Executing Tools

Once you have fetched or defined your tools (Fetching Tools), the next step is to execute them. This means triggering the actual API call or function execution that the tool represents.

There are two primary ways to execute Composio tools:

1. Automatic execution: Your chosen LLM decides which tool to call, and a framework (like Vercel AI SDK, LangChain) handles triggering the execution logic provided by Composio.
2. Direct execution: Your LLM/agent decides to call a tool and the code explicitly invokes the specific Composio tool using the execute_action method, often used for testing or simple automation.

Automatic execution

Frameworks like the Vercel AI, LangGraph often have features to automatically execute the tools. The framework will handle the execution logic provided by Composio.

Here’s an example of how Vercel AI SDK automatically executes tools

1
// Conceptual illustration within Vercel AI SDK context
2
import { VercelAIToolSet } from "composio-core";
3
import { generateText } from 'ai';
4
import { openai } from '@ai-sdk/openai';
5
6
const toolset = new VercelAIToolSet(); // Gets API key from env
7
8
async function runVercelExample() {
9
  const { tool } = await import('ai'); // Vercel AI SDK tool definition type
10
11
  // 1. Fetch tool - Composio formats it for Vercel, including an 'execute' function
12
  const tools = await toolset.getTools({ actions: ["GITHUB_GET_THE_AUTHENTICATED_USER"] });
13
14
  // 2. Use the tool with the framework's function (e.g., generateText)
15
  const { text, toolResults } = await generateText({
16
    model: openai('gpt-4o-mini'),
17
    prompt: 'Get my GitHub username',
18
    tools: tools // Provide the Composio-generated tool definitions
19
  });
20
21
  // 3. Framework internally calls the 'execute' method on the chosen tool.
22
  //    Composio's wrapper inside 'execute' handles the actual API call.
23
  console.log("Tool Results:", toolResults);
24
  console.log("Final Text:", text);
25
}

Key Takeaway: When using a framework integration, you typically fetch tools using the corresponding Composio ToolSet (e.g., VercelAIToolSet) and then use the framework’s standard way to handle tool calls. Composio’s ToolSet ensures the execution logic is correctly wired behind the scenes.

Direct execution

For scenarios where you want to run a specific tool programmatically without an LLM making the decision, use the execute_action method. This is available on the base ComposioToolSet and framework-specific ToolSets.

Let’s create a GitHub issue using Composio.

1
# Example: Create a GitHub Issue Directly
2
from composio_openai import ComposioToolSet, Action
3
# Assumes toolset is initialized and authenticated
4
5
toolset = ComposioToolSet()
6
7
print("Creating GitHub issue directly...")
8
try:
9
    result = toolset.execute_action(
10
        action=Action.GITHUB_CREATE_AN_ISSUE,
11
        params={
12
            "owner": "composiohq",  # Replace with actual owner
13
            "repo": "agi",  # Replace with actual repo
14
            "title": "New Issue via Composio execute_action",
15
            "body": "This issue was created directly using the Composio SDK.",
16
            # Other optional params like 'assignees', 'labels' can be added here
17
        },
18
        # entity_id="your-user-id" # Optional: Specify if not 'default'
19
    )
20
21
    if result.get("successful"):
22
        print("Successfully created issue!")
23
        # Issue details are often in result['data']
24
        print("Issue URL:", result.get("data", {}).get("html_url"))
25
    else:
26
        print("Failed to create issue:", result.get("error"))
27
28
except Exception as e:
29
    print(f"An error occurred: {e}")

This directly triggers the specified Composio action using the associated user’s credentials.

Specifying Users

By using entity_id

Composio needs to know which user’s connection/credentials to use when executing an authenticated action. You provide this context using entity_id and sometimes connected_account_id.

By default it uses the default entity ID "default".

For multi-tenant applications (multi-user apps), you need to provide the entity_id.

1
# Direct Execution with entity_id
2
toolset.execute_action(
3
    action=Action.GITHUB_CREATE_AN_ISSUE,
4
    params={...},
5
    entity_id="user-from-my-db-123"
6
)

By using connected_account_id

connected_account_id offers more precision by identifying a specific instance of a connection (e.g., a user’s work Gmail vs. personal Gmail).

You typically only need this if an entity_id has multiple active connections for the same app.

If connected_account_id is not provided, Composio generally uses the most recently added active connection matching the entity_id and the app being used. You can pass it when needed, primarily with execute_action:

1
# Direct Execution targeting a specific connection
2
toolset.execute_action(
3
    action=Action.GMAIL_SEND_EMAIL,
4
    params={...},
5
    connected_account_id="conn_abc123xyz" # The specific Gmail connection
6
)