diff --git a/docs/introduction/foundations/basic.mdx b/docs/introduction/foundations/basic.mdx index 24a3f9a257f..cda4a14b307 100644 --- a/docs/introduction/foundations/basic.mdx +++ b/docs/introduction/foundations/basic.mdx @@ -10,8 +10,8 @@ description: "Core Platform Modules" Learn how to manage users and authentication, integrations! - -Learn how to use, execute, process and even create actions! + +Learn how to use, execute, process and even create tools! diff --git a/docs/introduction/foundations/components/actions/action-guide.mdx b/docs/introduction/foundations/components/actions/action-guide.mdx deleted file mode 100644 index 523ce851b27..00000000000 --- a/docs/introduction/foundations/components/actions/action-guide.mdx +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: "๐Ÿ› ๏ธ What can I do with Actions?" -sidebarTitle: "Actions" -icon: "wand-magic-sparkles" -description: "Understand more about Actions & Using Them" ---- - -### Introduction to Actions -Actions are **interfaces for interacting** with **external world** via - -1. **Tool API calls** (e.g., gmail API to send an email) -2. **System Code execution** (e.g., Python code to generate a report) - - -```python Python Fetching an Action -tools = tool_set.get_tools(actions=[Action.GITHUB_ACTIVITY_STAR_REPO_FOR_AUTHENTICATED_USER]) -``` - -```javascript JavaScript Fetching an Action -const tools = await composioToolset.getTools({ - actions: ["github_star_a_repository_for_the_authenticated_user"] -}); -``` - - - -Actions are function calling compatible which means they can be used via Agentic Frameworks or any other LLMs. - - -### Action Types - -1. **Actions to Manage External Tools**: These are actions that are pre-configured for specific tools like **Asana tool** has actions for creating tasks, adding comments, etc. -2. **Actions to Manage System**: Actions that **interact with the execution environment**, including **file systems, shell commands, and browser automation**. -3. **Custom Actions**: These are custom code actions that you write in Python, JavaScript. It can also **extend the capabilities of Composio to interact with any existing/new tools**. - -### Quick Starts - - - How to use Actions with Agentic Frameworks - - - How to use Actions without Agents - - - - How to create and use Custom Actions for existing & new tools - - - Filter actions on the basis of natural language - - - - -### Action Limits - - - Giving LLM's too many actions can lead to significant performance issues. - - ```python python - tools = tool_set.get_tools(apps=[App.ASANA]) - # Asana has 100+ actions - ``` - ```javascript javascript - const tools = toolset.getTools({ - apps: ["github"] - }) // Github has 100+ actions - ``` - - - -Empirical evidence indicates that agents perform optimally when limited to fewer than 20 actions. - -To optimize agent performance, it's essential to limit the number of actions available. This can be achieved through effective action filtering strategies. - -Here are some recommended approaches: -1. Use specific actions from a tool -2. Implement custom filtering logic - -By carefully curating the action set, you can significantly improve agent efficiency and response quality. diff --git a/docs/introduction/foundations/components/actions/processing.mdx b/docs/introduction/foundations/components/actions/processing.mdx deleted file mode 100644 index f7c3dc58e67..00000000000 --- a/docs/introduction/foundations/components/actions/processing.mdx +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: "๐Ÿ› ๏ธ Enhancing Action Inputs, Outputs & Schemas" -sidebarTitle: "Processing Actions" -icon: "wand-magic-sparkles" -description: "Master the art of preprocessing, postprocessing, and schema processing for optimal results." ---- - -## Refining Action Inputs, Outputs & Schemas - -In many scenarios, the raw inputs, outputs, or schemas of actions may benefit from additional processing. This refinement step can significantly improve the quality and usability of your data. Here are three key use cases: - -- **Preprocessing**: Generate or modify inputs dynamically at runtime, handling scenarios that may be challenging for the LLM to produce directly. -- **Postprocessing**: Streamline large action responses by filtering or formatting the data before it reaches the Language Model (LLM). -- **Schema Processing**: Modify the request schema to include additional fields or alter existing ones. - -Composio empowers you with the ability to define **custom Python functions** as preprocessors, postprocessors, or schema processors. - -These can be applied at two levels: - -1. **Tool-level**: Affects all actions within a specific tool. -2. **Action-level**: Tailored processing for individual actions. - -Here's how you can implement these processors: - - - -```python Define the Preprocessor, Postprocessor, and Schema Processor Functions -def tool_schema_processor(schema): - # Modify schema as needed - return modified_schema - -def tool_preprocessor(input_data): - # Modify input_data as needed - return modified_input_data - -def tool_postprocessor(output_data): - # Process output_data as needed - return processed_output_data - -def action_schema_processor(schema): - # Modify schema as needed - return modified_schema - -def action_preprocessor(input_data): - # Modify input_data as needed - return modified_input_data - -def action_postprocessor(output_data): - # Process output_data as needed - return processed_output_data -``` - - - - -```python Set the schema, pre, and post processors while creating the toolset -# While defining the toolset, you can define the schema, pre, and post processors -composio_toolset = ComposioToolSet( - processors={ - "schema": { - App.GITHUB: tool_schema_processor, - Action.GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER: action_schema_processor, - }, - "pre": { - App.GITHUB: tool_preprocessor, - Action.GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER: action_preprocessor, - }, - "post": { - App.GITHUB: tool_postprocessor, - Action.GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER: action_postprocessor, - }, - }, -) - -tools = composio_toolset.get_tools(apps=[App.GITHUB]) -``` - - - - - - Ensure that your schema processing, preprocessing, and postprocessing functions are efficient and don't introduce significant latency. - diff --git a/docs/introduction/foundations/components/custom_actions.mdx b/docs/introduction/foundations/components/custom_actions.mdx deleted file mode 100644 index 6c066baa319..00000000000 --- a/docs/introduction/foundations/components/custom_actions.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: "Creating a Custom Action" -sidebarTitle: "Custom Actions" -icon: "gear" -description: "Complete customisation by creating your own actions" ---- - -## Overview - -**Custom Actions** in Composio allow users to execute actions locally, enhancing privacy and customization. - -Composio supports two action types: - -1. **Composio-Managed Actions:** Available on the [dashboard](https://app.composio.dev/). -2. **Custom Actions:** Defined and executed locally or in the tool [workspace](/introduction/foundations/components/workspace). - -**Custom actions** can be defined for **existing tools (gmail, google_calendar, etc.) or for your own tools.** - -```python Python Defining Custom Action -from composio import action - -@action(toolname="cow", requires=["cowsay"]) -def say(message: str) -> str: - """ - Cow will say whatever you want it to say. - - :param message: Message string - :return greeting: Formatted message. - """ - # A Description needs to be added to each Custom Action function - # The format is: - # """ - # description line - # :param input_param_1: input_param_description - # :param input_param_2: input_param_2_description - # :return output_variable: output_variable_description - # """ - import cowsay - - return cowsay.get_output_string("cow", message) -``` -```javascript Javascript Defining Custom Action -import { z } from "zod"; -import { ComposioToolSet } from "composio-core"; - -const toolset = new ComposioToolSet({}); - -(async () => { - await toolset.createAction({ - actionName: "sayHello", - toolName: "greetings", - description: "A simple action that says hello to someone", - inputParams: z.object({ - name: z.string().describe("Name of the person to greet") - }), - callback: async (inputParams) => { - return { - message: `Hello ${inputParams.name}!` - }; - } - }); - - const result = await toolset.executeAction("sayHello", { name: "World" }); - console.log("Action result:", result); // Will print: { message: "Hello World!" } -})(); -``` - -In this example, we **create a custom tool called "cow"** that uses the **`cowsay` library** to **output a message**. - -### Quick Starts - - - Learn more about creating a custom action for existing tools (gmail, google_calendar, etc.) & using it in your agent - diff --git a/docs/introduction/intro/quickstart.mdx b/docs/introduction/intro/quickstart.mdx index 4c71808bd34..2265be99771 100644 --- a/docs/introduction/intro/quickstart.mdx +++ b/docs/introduction/intro/quickstart.mdx @@ -99,7 +99,7 @@ Turn natural language into GitHub actions in minutes. Follow these 5 steps to st ``` - Composio also supports action executions without LLMs or agents. [Learn more](/patterns/actions/). + Composio also supports action executions without LLMs or agents. [Learn more](../../patterns/tools/use-tools/action-guide-without-agents). @@ -205,7 +205,7 @@ Turn natural language into GitHub actions in minutes. Follow these 5 steps to st ``` - Composio also supports action executions without LLMs or agents. [Learn more](/patterns/actions/). + Composio also supports action executions without LLMs or agents. [Learn more](../../patterns/tools/use-tools/action-guide-without-agents). diff --git a/docs/introduction/intro/quickstart_3.mdx b/docs/introduction/intro/quickstart_3.mdx index 1ece7a855c7..451e15b1dd2 100644 --- a/docs/introduction/intro/quickstart_3.mdx +++ b/docs/introduction/intro/quickstart_3.mdx @@ -285,7 +285,7 @@ Integrate with popular agentic frameworks Authorize a user's account to perform actions and subscribe to triggers - + Execute actions on behalf of a user diff --git a/docs/introduction/intro/quickstart_3_backup.mdx b/docs/introduction/intro/quickstart_3_backup.mdx index a2bc1acf652..453a01bc358 100644 --- a/docs/introduction/intro/quickstart_3_backup.mdx +++ b/docs/introduction/intro/quickstart_3_backup.mdx @@ -278,7 +278,7 @@ Congratulations! You've just: Authorize a user's account to perform actions and subscribe to triggers - + Execute actions on behalf of a user diff --git a/docs/mint.json b/docs/mint.json index 359e7a1aaa2..879af9e2d51 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -12,7 +12,7 @@ "colors": { "primary": "#343434", "light": "#fff", - "dark": "#9a4dff", + "dark": "#343434", "ultraLight": "#9a4dff", "ultraDark": "#9a4dff", "background": { @@ -91,12 +91,8 @@ "pages":[ "introduction/foundations/basic", "introduction/foundations/components/entity/entity-guide", - "introduction/foundations/components/actions/action-guide", - "introduction/foundations/components/custom_actions", "introduction/foundations/components/triggers/trigger-guide", - "introduction/foundations/components/integrations/custom-integration", "introduction/foundations/components/integrations/integration-guide", - "introduction/foundations/components/actions/processing", "introduction/foundations/components/workspace", "introduction/foundations/components/list_local_tools" ] @@ -112,17 +108,6 @@ "patterns/Auth/examples/shopify_example" ] }, - { - "group":"Actions", - "icon":"shuttle-space" , - "pages":[ - "patterns/actions/action-guide-with-agents", - "patterns/actions/action-guide-without-agents", - "patterns/actions/custom_actions", - "patterns/actions/usecase", - "patterns/actions/action-guide-faqs" - ] - }, { "group": "Triggers", "icon":"bolt", @@ -145,6 +130,33 @@ } ] }, + { + "group": "Tools", + "pages": [ + "patterns/tools/what-are-tools", + { + "group": "Use Tools", + "icon": "shuttle-space", + "pages": [ + "patterns/tools/use-tools/action-guide-with-agents", + "patterns/tools/use-tools/use-specific-actions", + "patterns/tools/use-tools/get-action-inputs", + "patterns/tools/use-tools/processing-actions", + "patterns/tools/use-tools/configure-tools", + "patterns/tools/use-tools/action-guide-without-agents" + ] + }, + { + "group": "Build Tools", + "icon": "hammer", + "pages": [ + "patterns/tools/build-tools/custom-action-for-new-tool", + "patterns/tools/build-tools/custom-action-for-existing-tool" + ] + }, + "patterns/tools/custom-integration" + ] + }, { "group":"Supported Frameworks", "pages":[ @@ -175,7 +187,7 @@ ] }, { - "group": "SweKit", + "group": "SWE Kit", "pages": [ "swekit-tools/introduction", "swekit-js/introduction", diff --git a/docs/patterns/actions/action-guide-faqs.mdx b/docs/patterns/actions/action-guide-faqs.mdx deleted file mode 100644 index ab1a56dba2d..00000000000 --- a/docs/patterns/actions/action-guide-faqs.mdx +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: "๐Ÿ› ๏ธ What else can I do with Actions?" -sidebarTitle: "Actions - FAQs" -icon: "wand-magic-sparkles" -description: "Understand more about Actions" ---- - - - - -```python Python Selecting Actions via Name -tool_set = ComposioToolSet() - -tools = tool_set.get_tools(actions=[Action.GITHUB_CREATE_AN_ISSUE,Action.GITHUB_COMMIT_EVENT]) -# can pass multiple actions -``` - -```javascript Javascript Selecting Actions via Name -const toolset = new OpenAIToolSet(); - -const tools = await toolset.getTools({actions: ['github_issues_create','github_commit_event']}); -// can pass multiple actions -``` - - - - - - - - -```Python Python Selecting Actions -use_case="Star a repo on github" - -action_enums=tool_set.find_actions_by_use_case(App.GITHUB,use_case=use_case) - -tools = tool_set.get_tools(actions=action_enums) - -# use tools as per your framework -``` - -```Javascript Javascript Selecting Actions -import { LangchainToolSet } from "composio-core"; - -const toolset = new LangchainToolSet({ - entityId: "default", -}); - -const actionsList = await toolset.client.actions.list({ - useCase: "create github issues", - apps: "github", -}); -``` - -```bash CLI Selecting Actions -composio actions --use-case 'get channel messages' --app 'slack' -``` - - - - - - - - - - -```python Selecting Actions via Apps & Tags -tools = tool_set.get_tools(apps=[App.GITHUB]) - -# Filter by tags -tag = "users" - -action_enums = toolset.find_actions_by_tags( - App.GITHUB, - tags=[tag], -) - -tools = tool_set.get_tools(actions=action_enums) -``` - - - - - -```javascript Selecting Actions via Apps -import { LangchainToolSet } from "composio-core"; - -const toolset = new LangchainToolSet({ - apiKey: process.env.COMPOSIO_API_KEY, - entityId: "default" -}); - -const actionsList = await toolset.client.actions.list({ - apps: "github" -}); - -const actions = await toolset.getTools({ - actions: actionsList.items.map((action) => { - return action.name; - }) -}) -``` - - - - - -```bash Selecting Actions via Apps -composio actions --app 'github' --tag 'code' -# Don't use tag if you want all actions -``` - - - - - - - - - -```curl curl -curl --request GET \ - --url https://backend.composio.dev/api/v2/actions \ - --header 'X-API-Key: ' -``` - - - - diff --git a/docs/patterns/actions/action-guide-with-agents.mdx b/docs/patterns/actions/action-guide-with-agents.mdx deleted file mode 100644 index 8d1864f0566..00000000000 --- a/docs/patterns/actions/action-guide-with-agents.mdx +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: "๐Ÿ› ๏ธ How can I execute Actions with my AI Agent?" -sidebarTitle: "Execute Actions with Agents" -icon: "robot" -description: "Perform Actions with your account or on behalf of your users with Agents" ---- -## Using Actions - -Composio lets you perform actions with your account or on behalf of your users. Feel free to check all the [tools](https://app.composio.dev/apps) we support. - -### Execute Actions with Agents - -To execute actions with your account or on behalf of your users, you can use the following code. - - -```python Python -from langchain.agents import create_openai_functions_agent, AgentExecutor -from langchain import hub -from langchain_openai import ChatOpenAI -from composio_langchain import ComposioToolSet, Action, App -import os - - -llm = ChatOpenAI(model="gpt-4o") - -prompt = hub.pull("hwchase17/openai-functions-agent") - -# Get All the tools -tool_set = ComposioToolSet() -tools = tool_set.get_tools(actions=[Action.GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER], tags=[]) - -# Define task -task = "Star a repo composiohq/composio on GitHub" - -agent = create_openai_functions_agent(llm, tools, prompt) -agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True) - -# Execute using agent_executor -agent_executor.invoke({"input": task}) -``` - -```javascript JavaScript - import { LangchainToolSet } from "composio-core"; - import { ChatOpenAI } from "@langchain/openai"; - import { AgentExecutor, createOpenAIFunctionsAgent } from "langchain/agents"; - import { pull } from "langchain/hub"; - - - (async () => { - const llm = new ChatOpenAI({ model: "gpt-4-turbo" }); - const composioToolset = new LangchainToolSet({ apiKey: process.env.COMPOSIO_API_KEY }); - const tools = await composioToolset.getTools({ actions: ["github_issues_create"] }); - const prompt = await pull("hwchase17/openai-functions-agent"); - - const agent = await createOpenAIFunctionsAgent({ llm, tools, prompt }); - const agentExecutor = new AgentExecutor({ agent, tools, verbose: true }); - const issueDetails = { - TITLE: "Sample issue", - DESCRIPTION: "Sample issue for the repo - himanshu-dixit/custom-repo-breaking" - }; - - const result = await agentExecutor.invoke({ - input: `Create a GitHub issue with the following details: ${JSON.stringify(issueDetails)}` - }); - return result.output; - })(); - ``` - - -This code demonstrates how to use LLMs to execute an action. -Composio supports multiple frameworks for creating Agents including LlamaIndex, CrewAI, Letta, Langchain, you can see it in the **Supported Frameworks** section. diff --git a/docs/patterns/actions/usecase.mdx b/docs/patterns/actions/usecase.mdx deleted file mode 100644 index 538d8b61d59..00000000000 --- a/docs/patterns/actions/usecase.mdx +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: "Finding Actions by Use Case" -sidebarTitle: "Actions by Use Case" -icon: "magnifying-glass" -description: "This documentation will guide you through the process of use case-based action finding in Composio." ---- - -Find relevant actions for your use case by describing what you want to accomplish in natural language. - -This approach is crucial because AI agents typically perform best with a limited set of actions. - - - -```Python Python Fetch Actions using use-case -use_case="Star a repo on github" - -action_enums=toolset.find_actions_by_use_case(App.GITHUB, use_case=use_case) -tools = toolset.get_tools(actions=action_enums) # use tools as per your framework -``` - -```Javascript Javascript Fetch Actions using use-case -import { LangchainToolSet } from "composio-core"; - -const toolset = new LangchainToolSet({ - entityId: "default", -}); - -const actionsList = await toolset.client.actions.list({ - useCase: "create github issues", - apps: "github", -}); -``` - -```bash CLI Fetch Actions using use-case -composio actions --use-case 'get channel messages' --app 'slack' -``` - \ No newline at end of file diff --git a/docs/patterns/actions/custom_actions.mdx b/docs/patterns/tools/build-tools/custom-action-for-existing-tool.mdx similarity index 52% rename from docs/patterns/actions/custom_actions.mdx rename to docs/patterns/tools/build-tools/custom-action-for-existing-tool.mdx index c1705a2781c..dcd5e6b8ff8 100644 --- a/docs/patterns/actions/custom_actions.mdx +++ b/docs/patterns/tools/build-tools/custom-action-for-existing-tool.mdx @@ -1,21 +1,15 @@ --- -title: "Custom Actions" -sidebarTitle: "Building Custom Actions" -icon: "hammer" -description: "Guide to creating Custom Actions for existing tool or new tool" +title: "Build Tools with Auth" +sidebarTitle: "Build Tools with Auth" +icon: "toolbox" +description: "Create custom actions that leverage existing tool authentication to extend functionality." --- -## What are Custom Actions? - -- Extend the functionality of existing tools by creating a custom action which utilises the existing authentication. (Fetch emails from Gmail) -- Write a custom action code snippet to execute the custom action (Check if number is even or odd) - - -Custom Actions can be created for any existing tool in Composio, allowing you to tailor the functionality to your specific needs while leveraging the existing authentication. +Custom Actions are powerful building blocks that enable you to create custom functionality while leveraging existing tool authentication. They can handle everything from simple data processing to complex third-party integrations, either using pre-configured tool authentication or running independently. -## Creating a Custom Action +## Creating a Custom Action with Authentication @@ -34,14 +28,15 @@ const toolset = new OpenAIToolSet({}) ``` + - - +Below is an example of creating a custom action called `my_custom_action` that integrates with the `gmail` tool. This action demonstrates how to fetch emails from the last 24 hours while utilizing Composio's built-in Gmail authentication. + -As `gmail` toolname is already registered in Composio, `auth` dictionary will be automatically provided! +Since `gmail` is a registered tool in Composio, the `auth` credentials are automatically injected into your custom action! -```python Custom Action - Gmail (python) +```python Python @action(toolname="gmail", requires=["example-pypi-package"]) # supports any package def my_custom_action(auth: dict, account_id: str) -> str: # Uses existing gmail auth """ @@ -81,7 +76,7 @@ def my_custom_action(auth: dict, account_id: str) -> str: # Uses existing gmail return str(response) ``` -```javascript Custom Action - Gmail (javascript) +```javascript Javascript await toolset.createAction({ actionName: "myCustomAction", toolName: "gmail", @@ -112,51 +107,12 @@ await toolset.createAction({ }); ``` - - - - -```python Python -@action(toolname="cow", requires=["cowsay"]) -def my_custom_action(account_id: str) -> str: - """ - Cow will say whatever you want it to say. - - :param account_id: Account ID, pass 'me' for default account - :return greeting: Formatted message. - """ - import cowsay - - return cowsay.get_output_string("cow", account_id) -``` -```javascript JavaScript -await toolset.createAction({ - actionName: "myCustomAction", - description: "Cow will say whatever you want it to say. This can be used to print text in cow style", - inputParams: z.object({ - accountId: z.string() - }), - callback: async (inputParams) => { - const accountId = inputParams.accountId; - const cowMessage = `Cow says: ${accountId}`; - return cowMessage; - } -}); -``` - - - -We can execute the custom action without Agents as well - - +Executing the custom action without Agents (it can be used with agents too) ```python Python -from composio import ComposioToolSet - -toolset = ComposioToolSet() toolset.execute_action( action=my_custom_action, params={ @@ -174,83 +130,11 @@ console.log( ) ``` - - - -```python Python Executing Custom Action with Agent -from openai import OpenAI -from composio_openai import ComposioToolSet - -openai_client = OpenAI() -# Initialise the Composio Tool Set -composio_toolset = ComposioToolSet() - -# Get GitHub tools that are pre-configured -# Retrieve actions -actions = composio_toolset.get_tools(actions=[my_custom_action]) - -my_task = "Fetch emails from Gmail account for last 24 hours" - -# Setup openai assistant -assistant_instruction = "You are a super intelligent personal assistant" - -# Prepare assistant -assistant = openai_client.beta.assistants.create( - name="Personal Assistant", - instructions=assistant_instruction, - model="gpt-4-turbo-preview", - tools=actions, # type: ignore -) - -# create a thread -thread = openai_client.beta.threads.create() -message = openai_client.beta.threads.messages.create( - thread_id=thread.id, role="user", content=my_task -) - -# Execute Agent with integrations - -run = openai_client.beta.threads.runs.create( - thread_id=thread.id, assistant_id=assistant.id -) - -# Execute function calls -response_after_tool_calls = composio_toolset.wait_and_handle_assistant_tool_calls( - client=openai_client, - run=run, - thread=thread, -) - -url = f"https://platform.openai.com/playground/assistants?assistant={assistant.id}&thread={thread.id}" - -print("Visit this URL to view the thread: ", url) -``` - -```javascript Javascript Custom Action with Agent -const tools = await toolset.getTools({ actions: ["myCustomAction"] }); -const instruction = "Fetch emails from Gmail account for last 24 hours" - -const client = new OpenAI({ apiKey: process.env.OPEN_AI_API_KEY }) -const response = await client.chat.completions.create({ - model: "gpt-4-turbo", - messages: [{ - role: "user", - content: instruction, - }], - tools: tools, - tool_choice: "auto", -}) - -console.log("Result", await toolset.handleToolCall(response)); -``` - - - -Output from executing Custom Action without Agents +Output from executing Custom Action -```shell Output from executing Custom Action without Agents +```shell Output [INFO] Logging is set to INFO, use `logging_level` argument or `COMPOSIO_LOGGING_LEVEL` change this [INFO] Executing `GMAIL_MY_CUSTOM_ACTION` with params={'query': 'test_query'} and metadata=None connected_account_id=None [INFO] Got response={'data': {'info': {'headers': {'Authorization': 'Bearer KEY', 'x-request-id': '2c65e8b'}, 'base_url': 'https://api.github.com', 'query_params': {}}}, 'error': None, 'successful'... diff --git a/docs/patterns/tools/build-tools/custom-action-for-new-tool.mdx b/docs/patterns/tools/build-tools/custom-action-for-new-tool.mdx new file mode 100644 index 00000000000..89656052646 --- /dev/null +++ b/docs/patterns/tools/build-tools/custom-action-for-new-tool.mdx @@ -0,0 +1,112 @@ +--- +title: "Build Tools without Auth" +sidebarTitle: "Build Tools without Auth" +icon: "plus" +description: "Create standalone custom tools and actions for any functionality you need (e.g., data processing, calculations, or integrations with other services)" +--- + + +Custom Actions are powerful building blocks that enable you to create custom functionality while running independently. They can handle everything from simple data processing to complex third-party integrations. + + +## Creating a Custom Tool without Authentication + + + + + +```python Python +from composio import ComposioToolSet, App, action + +toolset = ComposioToolSet() +``` +```javascript Javascript +import { OpenAIToolSet } from "composio-core" +import { z } from "zod" + +const toolset = new OpenAIToolSet({}) +``` + + + + +```python Python +@action(toolname="cow", requires=["cowsay"]) +def my_custom_action(message: str) -> str: + """ + Cow will say whatever you want it to say. + + :param message: Message to be displayed + :return greeting: Formatted message. + """ + import cowsay + + return cowsay.get_output_string("cow", message) +``` +```javascript JavaScript +await toolset.createAction({ + actionName: "myCustomAction", + description: "Cow will say whatever you want it to say", + inputParams: z.object({ + message: z.string() + }), + callback: async (inputParams) => { + const message = inputParams.message; + const cowMessage = `Cow says: ${message}`; + return cowMessage; + } +}); +``` + + + +Executing the custom action without Agents (it can be used with agents too) + +```python Python +toolset.execute_action( + action=my_custom_action, + params={"message": "AI is the future"} +) + +print(result['data']['greeting']) +``` + +```javascript JavaScript +console.log( + await toolset.executeAction( + "myCustomAction", + { message: "AI is the future" } + ) +) +``` + + +Output from executing Custom Action + +```shell Output (Python) + ________________ +| AI is the future | + ================ + \ + \ + ^__^ + (oo)\_______ + (__)\ )\/\ + ||----w | + || || +``` +```shell Output (Javascript) +Cow says: AI is the future +``` + + + + + +### Why Use Custom Tools or Actions? + +Custom Tools or Actions provide several advantages: + +- **Data privacy:** Execution happens on the userโ€™s machine, ensuring sensitive data doesnโ€™t leave the local environment. +- **Flexibility:** Users can create and customize as many tools and actions as needed. +- **Compatibility:** Custom actions can be integrated seamlessly across various Composio-supported platforms. diff --git a/docs/introduction/foundations/components/integrations/custom-integration.mdx b/docs/patterns/tools/custom-integration.mdx similarity index 93% rename from docs/introduction/foundations/components/integrations/custom-integration.mdx rename to docs/patterns/tools/custom-integration.mdx index f84d5708dbf..e6f53dd8cf5 100644 --- a/docs/introduction/foundations/components/integrations/custom-integration.mdx +++ b/docs/patterns/tools/custom-integration.mdx @@ -1,13 +1,13 @@ --- -title: "๐Ÿ”ง Adding Custom Tools" -sidebarTitle: "Custom Tools" +title: "๐Ÿ”ง How to add your own App?" +sidebarTitle: "Add Your Own App" icon: "puzzle-piece" -description: "Explore the process of creating custom tools with external Apps using OpenAPI Spec" +description: "Learn how to add your own App to Composio" --- -Creating custom tools on Composio is straightforward and can be done via an [OpenAPI Spec](https://swagger.io/specification/). +Creating your own App on Composio is straightforward and can be done via an [OpenAPI Spec](https://swagger.io/specification/). -Here's a tutorial showing how to create a Custom Tool for Notion +Here's a tutorial showing how to add Notion as an App on Composio + +1. Navigate to the [API Section](/api-reference/actions/get-action) of our documentation +2. Click on **Get Action** under the **Actions** category +3. Enter your Composio API key and the Action ID +4. The **parameters** attribute in the response contains the required parameters for executing the action + + + \ No newline at end of file diff --git a/docs/patterns/tools/use-tools/processing-actions.mdx b/docs/patterns/tools/use-tools/processing-actions.mdx new file mode 100644 index 00000000000..7df57eeba7c --- /dev/null +++ b/docs/patterns/tools/use-tools/processing-actions.mdx @@ -0,0 +1,163 @@ +--- +title: "๐Ÿ› ๏ธ How to modify Actions?" +sidebarTitle: "Modify Actions" +icon: "wand-magic-sparkles" +description: "Learn how to modify Tools & Actions to refine schemas, inputs, and outputs for optimal results." +--- + + +## Refining Tool Schemas, Inputs, & Outputs + +In many scenarios, the schemas, inputs, or outputs of tools may benefit from additional processing. This refinement step can significantly improve the quality and usability of your data. Here are three key use cases: + +- **Modifying Schema**: Modify the tool schema like the description of the parameters or the default values. For example, if you're manually providing certain values in input (like project_id), you can mark these fields as "not required" in the schema so the LLM knows it doesn't need to ask for them. +- **Modifying Inputs**: Add values as inputs to avoid specifying them in the prompt. e.g., passing `project_id` & `team_id` to the `LINEAR_CREATE_LINEAR_ISSUE` action. +- **Modifying Outputs**: Modify outputs to get the desired data. e.g., extracting `execution_id` & `issue_id` from the response of `LINEAR_CREATE_LINEAR_ISSUE` action. Doing this can help keep the LLM context clean. + +Composio empowers you with the ability to define **custom functions** as schema modifiers, input modifiers, or output modifiers. + +These can be applied at two levels: + +1. **App-level**: Affects all actions within a specific tool. +2. **Action-level**: Tailored processing for individual actions. + + + + + +```python Python +from langchain.agents import create_openai_functions_agent, AgentExecutor +from langchain import hub +from langchain_openai import ChatOpenAI +from composio_langchain import ComposioToolSet, Action, App +``` +```javascript JavaScript +Coming Soon +``` + + + + +```python Python +prompt = hub.pull("hwchase17/openai-functions-agent") + +llm = ChatOpenAI() +composio_toolset = ComposioToolSet() +``` +```javascript JavaScript +Coming Soon +``` + + + +This function will be used to modify the schema of the `LINEAR_CREATE_LINEAR_ISSUE` action, here we are modifying the description for the parameters `project_id` & `team_id` to not required, later in the program we will pass these values as inputs to the action. The technical term for this is **Action-level Schema Processing**. + +```python Python +def linear_schema_processor(schema: dict) -> dict: + schema['project_id']['description'] = schema['project_id']['description'].replace('is required', 'not required') + schema['team_id']['description'] = schema['team_id']['description'].replace('is required', 'not required') + return schema +``` +```javascript JavaScript +Coming Soon +``` + + +This function will be used to modify the input data for the `LINEAR_CREATE_LINEAR_ISSUE` action. here we have added the values for `project_id` and `team_id` parameters to the input data, by doing this can can avoid specifying these values in the prompt and be sure that agent uses the correct values. The technical term for this is **Action-level Pre-Processing**. + +```python Python +def linear_pre_processor(input_data: dict) -> dict: + input_data['project_id'] = 'e708162b-9b1a-4901-ab93-0f0149f9d805' + input_data['team_id'] = '249ee4cc-7bbb-4ff1-adbe-d3ef2f3df94e' + return input_data +``` +```javascript JavaScript +Coming Soon +``` + + + +This function will be used to modify the output data for the `LINEAR_CREATE_LINEAR_ISSUE` action. here we are modifying the output to just return the action execution status `successful` & the `issue_id`, by doing this can keep the LLM context clean. The technical term for this is **Action-level Post-Processing**. + +```python Python +def linear_post_processor(output_data: dict) -> dict: + output_data = { + 'success': output_data['successfull'], + 'issue_id': output_data['data']['id'] + } + return output_data +``` +```javascript JavaScript +Coming Soon +``` + + + +When getting tools using the `get_tools()` method, we need to pass the `processors` parameter to specify the schema, pre-processing, and post-processing functions. In this example, we're setting up an Action-level preprocessor by mapping the `LINEAR_CREATE_LINEAR_ISSUE` action to our `linear_schema_processor`, `linear_pre_processor` and `linear_post_processor` functions defined above respectively in schema, pre, and post processors. + + +```python Python {2-12} +tools = composio_toolset.get_tools( + processors={ + "schema": { + Action.LINEAR_CREATE_LINEAR_ISSUE: linear_schema_processor, + }, + "pre": { + Action.LINEAR_CREATE_LINEAR_ISSUE: linear_pre_processor, + }, + "post": { + Action.LINEAR_CREATE_LINEAR_ISSUE: linear_post_processor, + } + }, + actions=[Action.LINEAR_CREATE_LINEAR_ISSUE] +) +``` +```javascript JavaScript +Coming Soon +``` + + + + +```python Python +task = "Create a Linear Issue with to update the frontend" + +agent = create_openai_functions_agent(llm, tools, prompt) +agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True) + +agent_executor.invoke({"input": task}) +``` +```javascript JavaScript +Coming Soon +``` + + + + +### How to use processors at App-level? +Above we saw how to use processors at the Action-level, below is an example of how to use them at the App-level. + +```python Python {2-12} +tools = composio_toolset.get_tools( + processors={ + "pre": { + App.: processor_function, + }, + "post": { + App.: processor_function, + }, + "schema": { + App.: processor_function, + }, + }, + apps=[App.] +) +``` +```javascript JavaScript +Coming Soon +``` + + + + Ensure that your schema processing, preprocessing, and postprocessing functions are efficient and don't introduce significant latency. + diff --git a/docs/patterns/tools/use-tools/use-specific-actions.mdx b/docs/patterns/tools/use-tools/use-specific-actions.mdx new file mode 100644 index 00000000000..c6af346e619 --- /dev/null +++ b/docs/patterns/tools/use-tools/use-specific-actions.mdx @@ -0,0 +1,115 @@ +--- +title: "How can I get and use specific actions from a Tool?" +sidebarTitle: "Use Specific Actions" +icon: "pickaxe" +description: "Each Tool (like GitHub, Slack, etc.) comes with many Actions. You can explore all available Tools & Actions [here](https://app.composio.dev/apps). Each Action has an associated action ID which you can use to call the action." +--- + + + Filtering actions is crucial for optimizing AI agent performance. Providing too many actions can overwhelm the LLM's decision-making process, making it harder to choose the most appropriate action. It's best to narrow down the action set to only the most relevant ones for your specific use case. + + +### Specifying Actions +`GITHUB_CREATE_AN_ISSUE` and `GITHUB_COMMIT_EVENT` are action IDs for actions in the Github Tool + +```python Python +from composio import ComposioToolSet, App, action + +toolset = ComposioToolSet() + +# can pass multiple actions +tools = toolset.get_tools(actions=[Action.GITHUB_CREATE_AN_ISSUE,Action.GITHUB_COMMIT_EVENT]) +``` + +```javascript Javascript +import { LangchainToolSet } from "composio-core"; + +const toolset = new LangchainToolSet(); + +// can pass multiple actions +const tools = await toolset.getTools({actions: ['github_issues_create','github_commit_event']}); +``` + + +### Filtering Actions +Actions can be filtered by tags or use case. + + +Filter the Actions in an App based on tags. +For example, you can: +- Filter all user-related Actions using the "users" tag +- Retrieve metadata-related Actions using the "meta" tag + + +```python Python +from composio_langchain import ComposioToolSet, Action, App + +tools = tool_set.get_tools(apps=[App.GITHUB]) + +# Filter by tags +tag = "users" + +action_enums = toolset.find_actions_by_tags( + App.GITHUB, + tags=[tag], +) + +tools = tool_set.get_tools(actions=action_enums) +``` + +```javascript Javascript +import { OpenAIToolSet } from "composio-core"; + +const composio_toolset = new OpenAIToolSet(); + +// Filter by tags +const tag = "meta"; + +const actions = await composio_toolset.getTools({ + apps: ["github"], + tags: [tag], +}); + +console.log(actions); +``` + +```bash CLI +composio actions --app 'github' --tag 'code' +``` + + + +Find relevant actions for your use case by describing your use case in natural language. + +```Python Python +from composio import ComposioToolSet, App, action + +toolset = ComposioToolSet() + +# Specify the use case +use_case="Star a repo on github" + +action_enums=toolset.find_actions_by_use_case(App.GITHUB, use_case=use_case) +tools = toolset.get_tools(actions=action_enums) +``` + +```Javascript Javascript +import { LangchainToolSet } from "composio-core"; + +const toolset = new LangchainToolSet(); + +// Specify the use case +const useCase = "Star a repo on github"; + +const actionsList = await toolset.client.actions.list({ + useCase: useCase, + apps: "github", +}); +``` + +```bash CLI +composio actions --use-case 'star a repo on github' --app 'github' +``` + + + diff --git a/docs/patterns/tools/what-are-tools.mdx b/docs/patterns/tools/what-are-tools.mdx new file mode 100644 index 00000000000..de7e285a14c --- /dev/null +++ b/docs/patterns/tools/what-are-tools.mdx @@ -0,0 +1,79 @@ +--- +title: "๐Ÿ› ๏ธ What are Tools & Actions?" +sidebarTitle: "What are Tools?" +icon: "question" +description: "Learn about tools in Composio" +--- +### What are tools? + +Large Language Models (LLMs) are like a highly intelligent person who can understand and reason about almost anything but is sitting in an empty room with no ability to interact with the outside world. They can think and talk about sending emails, creating a ticket on Jira, or cloning a repository from github, but can't actually DO these things. + +This is where tools come in. Tools give this intelligent being specific abilities to interact with the real world. Many AI models support tool calling (also called function calling). + + +The term **tools** and **actions** are used interchangeably in the documentation + + +### How tool calling works +AI models with tool calling capabilities decide when and how to use specific tools to meet user requests. Developers create and provide these tools, equipping the AI with a toolbox to select the best tool for each task + +For example, if a user asks an LLM to send an email to `john@example.com` with subject `Meeting Tomorrow`, the LLM can use the [Gmail](https://app.composio.dev/app/gmail) tool's `GMAIL_SEND_EMAIL` action to send the email. + +LLM's thinking process: +1. Recognizes this requires email sending capability +2. Identifies the appropriate tool ([Gmail](https://app.composio.dev/app/gmail)) & action (`GMAIL_SEND_EMAIL`) +3. Structures the necessary parameters: + - recipient: john@example.com + - subject: "Meeting Tomorrow" + - body: [drafts appropriate content] +4. Calls the action with these parameters + + +### Tool calling with Composio + +At Composio, we offer tools for multiple platforms, accessible via Python and JavaScript SDKs. These platforms, referred to as **Apps** or **Tools**, include popular services like GitHub, Twitter, Salesforce, Jira, and Notion. Within each of these Apps, we provide **Actions**, which are essentially functions that can be executed. For example, you can send an email on Gmail, star a repository on GitHub, or create an issue on Jira. These tools can also be used directly, similar to function calls, without needing agents. + + +```python Python +from composio_langchain import ComposioToolSet, Action, App + +tool_set = ComposioToolSet() + +# Get all actions from a tool +tools = tool_set.get_tools(apps=[App.GITHUB]) + +# Get specific actions +tools = tool_set.get_tools(actions=[Action.GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER]) +``` + +```javascript JavaScript +import { LangchainToolSet } from "composio-core"; + +const composioToolset = new LangchainToolSet(); + +// Get all actions from a tool +const tools = await composioToolset.getTools({ apps: ["github"] }); + +// Get specific actions +const tools = await composioToolset.getTools({ actions: ["github_star_a_repository_for_the_authenticated_user"] }); +``` + + +### Action Types + +1. **External Tool Actions**: Pre-configured actions for specific tools, such as creating issues or changing issue status in Jira. +2. **System Management Actions**: Actions that interact with the execution environment, like file system operations, shell commands, and browser automation. +3. **Custom Actions**: User-defined actions in Python or JavaScript that extend Composio's capabilities to interact with new or existing tools. + +### Action Limits + +Empirical evidence indicates that agents perform optimally when limited to **fewer than 20 actions**. Providing LLMs with too many actions can lead to significant performance issues, such as **increased response time** and **decreased accuracy**. + +To optimize agent performance, it's essential to limit the number of actions available. This can be achieved through effective action filtering strategies. Here are some recommended approaches: + +1. Use specific actions from a tool +2. Use tags to filter actions +3. Use use cases to filter actions +4. Implement custom filtering logic + +By carefully curating the action set, you can significantly improve agent efficiency and response quality. diff --git a/docs/swekit/benchmarks.mdx b/docs/swekit/benchmarks.mdx index 53ee5d606d4..3a693b46877 100644 --- a/docs/swekit/benchmarks.mdx +++ b/docs/swekit/benchmarks.mdx @@ -1,6 +1,6 @@ --- title: "Benchmarks" -sidebarTitle: "SweKit Benchmarks" +sidebarTitle: "SWE Kit Benchmarks" icon: "chart-line" description: "Learn how to run and evaluate your SWE agents using benchmarks" ---