@devries-cameron20 / composio-1 / commits / fef7a1517
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

native tools

Sushmithamallesh committed Dec 15, 2025 at 18:20 UTC fef7a1517d0456ad0b4112d4593a3e055f3bb2f0
12 files changed +526 -19
fern/docs.yml
+3
@@ -317,6 +317,9 @@ navigation:
317 - page: Using with MCP Clients
318 path: pages/dist/tool-router/using-with-mcp-clients.mdx
319 slug: using-with-mcp-clients
320 + - page: Using as a native tool
321 + path: pages/dist/tool-router/using-as-a-native-tool.mdx
322 + slug: using-as-a-native-tool
323 - tab: providers
324 layout:
325 - section: Supported Providers
fern/pages/src/tool-router/overview.mdx
+2 -2
@@ -20,5 +20,5 @@ This is what powers complex agentic products like [Rube](https://rube.app).
20 ## Quick links
21
22 - [Quickstart](/tool-router/quickstart): Build your first AI agent with Tool Router.
23 -- [Using with MCP clients](/tool-router/using-with-mcp-clients): Guides on how to use Tool Router MCP with popular MCP clients.
24 -{/* - [Using as native tools](/tool-router/using-as-native-tools): Guides on how to use Tool router as a tool with popular Agentic Providers. */}
23 +- [Using with MCP clients](/tool-router/using-with-mcp-clients): Guides on how to use Tool Router MCP with popular MCP clients.
24 +- [Using as a native tool](/tool-router/using-as-a-native-tool): Guide on how to use Tool Router as a native tool with any AI framework.
fern/pages/src/tool-router/quickstart.mdx
+84 -7
@@ -6,7 +6,10 @@ keywords: "tool router quickstart, quickstart"
6 hide-nav-links: false
7 ---
8
9 -Build an interactive agent with access to 1000+ tools.
9 +Choose how you want to integrate Tool Router:
10 +
11 +<AccordionGroup>
12 +<Accordion title="Using Tool Router MCP">
13
14 <Tabs>
15 <Tab title="Claude Agent SDK">
@@ -105,15 +108,86 @@ When the agent needs authentication, it will prompt the user with a link to conn
108 </Tab>
109 </Tabs>
110
108 -## What just happened?
111 +### What just happened?
112 +
113 +When you run this agent, Tool Router:
114 +1. **Creates an MCP server** with your session configuration
115 +2. **Searches** for the right tools based on your request
116 +3. **Handles authentication** if needed
117 +4. **Executes tools** and uses a workbench for processing large responses
118 +
119 +</Accordion>
120 +
121 +<Accordion title="Using Tool router as a native tool">
122 +
123 +<Tabs>
124 +<Tab title="OpenAI">
125 +
126 +<Steps>
127 +<Step title="Install">
128 +<CodeGroup>
129 +```bash title="Python" for="python"
130 +pip install composio openai
131 +```
132 +```bash title="TypeScript" for="typescript"
133 +npm install @composio/core openai
134 +```
135 +</CodeGroup>
136 +</Step>
137
110 -When you ran this agent, Tool Router handled everything behind the scenes:
138 +<Step title="Create session and use as native tool">
139 +Tool Router can be added as a single native tool to your agent. This provides a meta-tool that handles search, authentication, and execution across all 1000+ Composio tools.
140
112 -1. **[Search](/tool-router/tool-search)** - Found the right Gmail tools from 1000+ available tools
113 -2. **[Authentication](/tool-router/authentication)** - Prompted you to connect your Gmail account
114 -3. **[Execution](/tool-router/tool-execution)** - Fetched your emails and processed results efficiently
141 +<Info>
142 +- Set your `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
143 +- Set your `OPENAI_API_KEY` environment variable with your [OpenAI API key](https://platform.openai.com/api-keys).
144 +- `userId` is your user's unique identifier. See [User Management](/docs/user-management) for details.
145 +</Info>
146
116 -All you wrote was a prompt. Tool Router handled the rest!
147 +<CodeGroup>
148 +<SnippetCode src="fern/snippets/tool-router/python/quickstart-native-openai.py" title="Python" for="python" />
149 +<SnippetCode src="fern/snippets/tool-router/typescript/quickstart-native-openai.ts" title="TypeScript" for="typescript" />
150 +</CodeGroup>
151 +</Step>
152 +</Steps>
153 +
154 +</Tab>
155 +
156 +<Tab title="Vercel AI SDK">
157 +
158 +<Steps>
159 +<Step title="Install">
160 +```bash title="TypeScript"
161 +npm install @composio/core ai @ai-sdk/openai
162 +```
163 +</Step>
164 +
165 +<Step title="Create session and use as native tool">
166 +Tool Router can be added as a single native tool to your agent. This provides a meta-tool that handles search, authentication, and execution across all 1000+ Composio tools.
167 +
168 +<Info>
169 +- Set your `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
170 +- Set your `OPENAI_API_KEY` environment variable with your [OpenAI API key](https://platform.openai.com/api-keys).
171 +- `userId` is your user's unique identifier. See [User Management](/docs/user-management) for details.
172 +</Info>
173 +
174 +<SnippetCode src="fern/snippets/tool-router/typescript/quickstart-native-vercel.ts" title="TypeScript" />
175 +</Step>
176 +</Steps>
177 +
178 +</Tab>
179 +</Tabs>
180 +
181 +### What just happened?
182 +
183 +When you run this agent, Tool Router:
184 +1. **Provides a single tool** to your agent framework
185 +2. **Interprets requests** and **searches** for the right tools internally
186 +3. **Handles authentication** if needed
187 +4. **Executes tools** and uses a workbench for processing large responses
188 +
189 +</Accordion>
190 +</AccordionGroup>
191
192 ## Next steps
193
@@ -130,4 +204,7 @@ All you wrote was a prompt. Tool Router handled the rest!
204 <Card title="Using MCP" href="/tool-router/using-with-mcp-clients">
205 Connect Tool Router to any MCP-compatible client.
206 </Card>
207 + <Card title="Using as a native tool" href="/tool-router/using-as-a-native-tool">
208 + Use Tool Router as a native tool with any AI framework.
209 + </Card>
210 </CardGroup>
fern/pages/src/tool-router/users-and-sessions.mdx
+16 -3
@@ -33,16 +33,29 @@ Restrict the session to specific toolkits:
33
34 <CodeGroup>
35 ```python Python
36 +# Using array format
37 session = composio.create(
38 user_id="user_123",
39 toolkits=["github", "gmail", "slack"]
40 )
41 +
42 +# Using object format with enable key
43 +session = composio.create(
44 + user_id="user_123",
45 + toolkits={"enable": ["github", "gmail", "slack"]}
46 +)
47 ```
48
49 ```typescript TypeScript
50 +// Using array format
51 const session = await composio.create("user_123", {
52 toolkits: ["github", "gmail", "slack"],
53 });
54 +
55 +// Using object format with enable key
56 +const session = await composio.create("user_123", {
57 + toolkits: { enable: ["github", "gmail", "slack"] },
58 +});
59 ```
60 </CodeGroup>
61
@@ -54,13 +67,13 @@ Keep all toolkits enabled except specific ones:
67 ```python Python
68 session = composio.create(
69 user_id="user_123",
57 - toolkits={"disabled": ["exa", "firecrawl"]}
70 + toolkits={"disable": ["exa", "firecrawl"]}
71 )
72 ```
73
74 ```typescript TypeScript
75 const session = await composio.create("user_123", {
63 - toolkits: { disabled: ["exa", "firecrawl"] },
76 + toolkits: { disable: ["exa", "firecrawl"] },
77 });
78 ```
79 </CodeGroup>
@@ -150,7 +163,7 @@ console.log(mcp.url);
163 ```
164 </CodeGroup>
165
153 -For framework examples, see [Using with MCP clients](/tool-router/using-with-mcp-clients).
166 +For framework examples, see [Using with MCP clients](/tool-router/using-with-mcp-clients) or [Using as a native tool](/tool-router/using-as-a-native-tool).
167
168 ### authorize()
169
fern/pages/src/tool-router/using-as-a-native-tool.mdx new
+77
@@ -0,0 +1,77 @@
1 +---
2 +title: Using as a native tool
3 +image: "https://og.composio.dev/api/og?title=Using%20as%20a%20Native%20Tool"
4 +description: "Use Tool Router as a native tool with any AI framework"
5 +keywords: "native tool, tool router, meta-tool"
6 +---
7 +
8 +Tool Router can be used as a single native tool with any AI framework. The tool handles search, authentication, and execution internally.
9 +
10 +## Examples for popular frameworks
11 +
12 +Jump to examples for:
13 +- [OpenAI](#openai) - Python, TypeScript
14 +- [Vercel AI SDK](#vercel-ai-sdk) - TypeScript
15 +
16 +## OpenAI
17 +
18 +### Installation
19 +
20 +<CodeGroup>
21 +```bash title="Python" for="python"
22 +pip install composio openai
23 +```
24 +```bash title="TypeScript" for="typescript"
25 +npm install @composio/core openai
26 +```
27 +</CodeGroup>
28 +
29 +### Usage
30 +
31 +Create a Tool Router session and use it as a native tool:
32 +
33 +<Info>
34 +- Set your `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
35 +- Set your `OPENAI_API_KEY` environment variable with your [OpenAI API key](https://platform.openai.com/api-keys).
36 +</Info>
37 +
38 +<CodeGroup>
39 +<SnippetCode src="fern/snippets/tool-router/python/native-tools-openai.py" title="Python" />
40 +<SnippetCode src="fern/snippets/tool-router/typescript/native-tools-openai.ts" title="TypeScript" />
41 +</CodeGroup>
42 +
43 +## Vercel AI SDK
44 +
45 +### Installation
46 +
47 +```bash
48 +npm install @composio/core ai @ai-sdk/openai
49 +```
50 +
51 +### Usage
52 +
53 +Create a Tool Router session and use it as a native tool:
54 +
55 +<Info>
56 +- Set your `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
57 +- Set your `OPENAI_API_KEY` environment variable with your [OpenAI API key](https://platform.openai.com/api-keys).
58 +</Info>
59 +
60 +<SnippetCode src="fern/snippets/tool-router/typescript/native-tools-vercel.ts" />
61 +
62 +## Next steps
63 +
64 +<CardGroup cols={2}>
65 + <Card title="Quickstart" href="/tool-router/quickstart">
66 + See both MCP and native tool in action
67 + </Card>
68 + <Card title="Using with MCP" href="/tool-router/using-with-mcp-clients">
69 + Use Tool Router with MCP-compatible clients
70 + </Card>
71 + <Card title="Authentication" href="/tool-router/authentication">
72 + Learn about authentication options
73 + </Card>
74 + <Card title="Session management" href="/tool-router/users-and-sessions">
75 + Configure sessions for your users
76 + </Card>
77 +</CardGroup>
\ No newline at end of file
fern/pages/src/tool-router/using-as-native-tools.mdx deleted
-7
@@ -1,7 +0,0 @@
1 ----
2 -title: Using as Native Tools
3 -image: "https://og.composio.dev/api/og?title=Using%20as%20Native%20Tools"
4 -description: "Use Tool Router tools directly with any agent framework"
5 -keywords: "tool router"
6 ----
7 -
fern/snippets/tool-router/python/native-tools-openai.py new
+74
@@ -0,0 +1,74 @@
1 +import os
2 +import json
3 +from dotenv import load_dotenv
4 +from composio import Composio
5 +from openai import OpenAI
6 +
7 +# Load environment variables from .env file
8 +load_dotenv()
9 +
10 +composio_api_key = os.environ["COMPOSIO_API_KEY"]
11 +user_id = "user_123" # Your user's unique identifier
12 +
13 +# Initialize Composio and create a Tool Router session
14 +composio = Composio(api_key=composio_api_key)
15 +session = composio.create(user_id=user_id)
16 +
17 +# Initialize OpenAI client
18 +client = OpenAI(
19 + api_key=os.environ["OPENAI_API_KEY"]
20 +)
21 +
22 +# Get Tool Router as a native tool
23 +tool_router = session.get_tool_router()
24 +
25 +# Create a chat completion with the tool
26 +response = client.chat.completions.create(
27 + model="gpt-4-turbo-preview",
28 + messages=[
29 + {
30 + "role": "user",
31 + "content": (
32 + "Fetch all open issues from the composio/composio GitHub repository "
33 + "and create a summary of the top 5 by priority"
34 + )
35 + }
36 + ],
37 + tools=[tool_router.tool],
38 + tool_choice="auto"
39 +)
40 +
41 +print("Assistant:", response.choices[0].message.content)
42 +
43 +# Handle tool calls if the assistant wants to use Tool Router
44 +tool_calls = response.choices[0].message.tool_calls
45 +if tool_calls:
46 + tool_call = tool_calls[0]
47 +
48 + if tool_call.function.name == "composio_tool_router":
49 + # Execute the tool with Tool Router
50 + args = json.loads(tool_call.function.arguments)
51 + result = tool_router.execute(args)
52 +
53 + # Send the result back to OpenAI
54 + final_response = client.chat.completions.create(
55 + model="gpt-4-turbo-preview",
56 + messages=[
57 + {
58 + "role": "user",
59 + "content": (
60 + "Fetch all open issues from the composio/composio GitHub repository "
61 + "and create a summary of the top 5 by priority"
62 + )
63 + },
64 + response.choices[0].message,
65 + {
66 + "role": "tool",
67 + "tool_call_id": tool_call.id,
68 + "content": json.dumps(result)
69 + }
70 + ],
71 + tools=[tool_router.tool]
72 + )
73 +
74 + print("Assistant:", final_response.choices[0].message.content)
\ No newline at end of file
fern/snippets/tool-router/python/quickstart-native-openai.py new
+74
@@ -0,0 +1,74 @@
1 +import os
2 +import json
3 +from dotenv import load_dotenv
4 +from composio import Composio
5 +from openai import OpenAI
6 +
7 +# Load environment variables from .env file
8 +load_dotenv()
9 +
10 +composio_api_key = os.environ["COMPOSIO_API_KEY"]
11 +user_id = "user_123" # Your user's unique identifier
12 +
13 +# Initialize Composio and create a Tool Router session
14 +composio = Composio(api_key=composio_api_key)
15 +session = composio.create(user_id=user_id)
16 +
17 +# Initialize OpenAI client
18 +client = OpenAI(
19 + api_key=os.environ["OPENAI_API_KEY"]
20 +)
21 +
22 +# Get Tool Router as a native tool
23 +tool_router = session.get_tool_router()
24 +
25 +# Create a chat completion with the tool
26 +response = client.chat.completions.create(
27 + model="gpt-4-turbo-preview",
28 + messages=[
29 + {
30 + "role": "user",
31 + "content": (
32 + "Fetch all open issues from the composio/composio GitHub repository "
33 + "and create a summary of the top 5 by priority"
34 + )
35 + }
36 + ],
37 + tools=[tool_router.tool],
38 + tool_choice="auto"
39 +)
40 +
41 +print("Assistant:", response.choices[0].message.content)
42 +
43 +# Handle tool calls if the assistant wants to use Tool Router
44 +tool_calls = response.choices[0].message.tool_calls
45 +if tool_calls:
46 + tool_call = tool_calls[0]
47 +
48 + if tool_call.function.name == "composio_tool_router":
49 + # Execute the tool with Tool Router
50 + args = json.loads(tool_call.function.arguments)
51 + result = tool_router.execute(args)
52 +
53 + # Send the result back to OpenAI
54 + final_response = client.chat.completions.create(
55 + model="gpt-4-turbo-preview",
56 + messages=[
57 + {
58 + "role": "user",
59 + "content": (
60 + "Fetch all open issues from the composio/composio GitHub repository "
61 + "and create a summary of the top 5 by priority"
62 + )
63 + },
64 + response.choices[0].message,
65 + {
66 + "role": "tool",
67 + "tool_call_id": tool_call.id,
68 + "content": json.dumps(result)
69 + }
70 + ],
71 + tools=[tool_router.tool]
72 + )
73 +
74 + print("Assistant:", final_response.choices[0].message.content)
\ No newline at end of file
fern/snippets/tool-router/typescript/native-tools-openai.ts new
+67
@@ -0,0 +1,67 @@
1 +import "dotenv/config"; // Load environment variables from .env file
2 +import { Composio } from "@composio/core";
3 +import OpenAI from "openai";
4 +
5 +const composioApiKey = process.env.COMPOSIO_API_KEY;
6 +const userId = "user_123"; // Your user's unique identifier
7 +
8 +// Initialize Composio and create a Tool Router session
9 +const composio = new Composio({ apiKey: composioApiKey });
10 +const session = await composio.create(userId);
11 +
12 +// Initialize OpenAI client
13 +const openai = new OpenAI({
14 + apiKey: process.env.OPENAI_API_KEY,
15 +});
16 +
17 +// Get Tool Router as a native tool
18 +const toolRouter = await session.getToolRouter();
19 +
20 +// Create a chat completion with the tool
21 +const response = await openai.chat.completions.create({
22 + model: "gpt-4-turbo-preview",
23 + messages: [
24 + {
25 + role: "user",
26 + content: "Fetch all open issues from the composio/composio GitHub repository " +
27 + "and create a summary of the top 5 by priority",
28 + },
29 + ],
30 + tools: [toolRouter.tool],
31 + tool_choice: "auto",
32 +});
33 +
34 +console.log("Assistant:", response.choices[0].message.content);
35 +
36 +// Handle tool calls if the assistant wants to use Tool Router
37 +const toolCalls = response.choices[0].message.tool_calls;
38 +if (toolCalls && toolCalls.length > 0) {
39 + const toolCall = toolCalls[0];
40 +
41 + if (toolCall.function.name === "composio_tool_router") {
42 + // Execute the tool with Tool Router
43 + const args = JSON.parse(toolCall.function.arguments);
44 + const result = await toolRouter.execute(args);
45 +
46 + // Send the result back to OpenAI
47 + const finalResponse = await openai.chat.completions.create({
48 + model: "gpt-4-turbo-preview",
49 + messages: [
50 + {
51 + role: "user",
52 + content: "Fetch all open issues from the composio/composio GitHub repository " +
53 + "and create a summary of the top 5 by priority",
54 + },
55 + response.choices[0].message,
56 + {
57 + role: "tool",
58 + tool_call_id: toolCall.id,
59 + content: JSON.stringify(result),
60 + },
61 + ],
62 + tools: [toolRouter.tool],
63 + });
64 +
65 + console.log("Assistant:", finalResponse.choices[0].message.content);
66 + }
67 +}
\ No newline at end of file
fern/snippets/tool-router/typescript/native-tools-vercel.ts new
+31
@@ -0,0 +1,31 @@
1 +import "dotenv/config"; // Load environment variables from .env file
2 +import { Composio } from "@composio/core";
3 +import { openai } from "@ai-sdk/openai";
4 +import { generateText } from "ai";
5 +
6 +const composioApiKey = process.env.COMPOSIO_API_KEY;
7 +const userId = "user_123"; // Your user's unique identifier
8 +
9 +// Initialize Composio and create a Tool Router session
10 +const composio = new Composio({ apiKey: composioApiKey });
11 +const session = await composio.create(userId);
12 +
13 +// Get Tool Router as a native tool
14 +const toolRouter = await session.getToolRouter();
15 +
16 +// Use with Vercel AI SDK
17 +const { text, toolCalls, toolResults } = await generateText({
18 + model: openai("gpt-4-turbo"),
19 + prompt: "Fetch all open issues from the composio/composio GitHub repository " +
20 + "and create a summary of the top 5 by priority",
21 + tools: {
22 + composio_tool_router: toolRouter.tool,
23 + },
24 +});
25 +
26 +console.log("Result:", text);
27 +
28 +// If there were tool calls, they've already been executed
29 +if (toolResults && toolResults.length > 0) {
30 + console.log("Tool was called and executed successfully");
31 +}
\ No newline at end of file
fern/snippets/tool-router/typescript/quickstart-native-openai.ts new
+67
@@ -0,0 +1,67 @@
1 +import "dotenv/config"; // Load environment variables from .env file
2 +import { Composio } from "@composio/core";
3 +import OpenAI from "openai";
4 +
5 +const composioApiKey = process.env.COMPOSIO_API_KEY;
6 +const userId = "user_123"; // Your user's unique identifier
7 +
8 +// Initialize Composio and create a Tool Router session
9 +const composio = new Composio({ apiKey: composioApiKey });
10 +const session = await composio.create(userId);
11 +
12 +// Initialize OpenAI client
13 +const openai = new OpenAI({
14 + apiKey: process.env.OPENAI_API_KEY,
15 +});
16 +
17 +// Get Tool Router as a native tool
18 +const toolRouter = await session.getToolRouter();
19 +
20 +// Create a chat completion with the tool
21 +const response = await openai.chat.completions.create({
22 + model: "gpt-4-turbo-preview",
23 + messages: [
24 + {
25 + role: "user",
26 + content: "Fetch all open issues from the composio/composio GitHub repository " +
27 + "and create a summary of the top 5 by priority",
28 + },
29 + ],
30 + tools: [toolRouter.tool],
31 + tool_choice: "auto",
32 +});
33 +
34 +console.log("Assistant:", response.choices[0].message.content);
35 +
36 +// Handle tool calls if the assistant wants to use Tool Router
37 +const toolCalls = response.choices[0].message.tool_calls;
38 +if (toolCalls && toolCalls.length > 0) {
39 + const toolCall = toolCalls[0];
40 +
41 + if (toolCall.function.name === "composio_tool_router") {
42 + // Execute the tool with Tool Router
43 + const args = JSON.parse(toolCall.function.arguments);
44 + const result = await toolRouter.execute(args);
45 +
46 + // Send the result back to OpenAI
47 + const finalResponse = await openai.chat.completions.create({
48 + model: "gpt-4-turbo-preview",
49 + messages: [
50 + {
51 + role: "user",
52 + content: "Fetch all open issues from the composio/composio GitHub repository " +
53 + "and create a summary of the top 5 by priority",
54 + },
55 + response.choices[0].message,
56 + {
57 + role: "tool",
58 + tool_call_id: toolCall.id,
59 + content: JSON.stringify(result),
60 + },
61 + ],
62 + tools: [toolRouter.tool],
63 + });
64 +
65 + console.log("Assistant:", finalResponse.choices[0].message.content);
66 + }
67 +}
\ No newline at end of file
fern/snippets/tool-router/typescript/quickstart-native-vercel.ts new
+31
@@ -0,0 +1,31 @@
1 +import "dotenv/config"; // Load environment variables from .env file
2 +import { Composio } from "@composio/core";
3 +import { openai } from "@ai-sdk/openai";
4 +import { generateText } from "ai";
5 +
6 +const composioApiKey = process.env.COMPOSIO_API_KEY;
7 +const userId = "user_123"; // Your user's unique identifier
8 +
9 +// Initialize Composio and create a Tool Router session
10 +const composio = new Composio({ apiKey: composioApiKey });
11 +const session = await composio.create(userId);
12 +
13 +// Get Tool Router as a native tool
14 +const toolRouter = await session.getToolRouter();
15 +
16 +// Use with Vercel AI SDK
17 +const { text, toolCalls, toolResults } = await generateText({
18 + model: openai("gpt-4-turbo"),
19 + prompt: "Fetch all open issues from the composio/composio GitHub repository " +
20 + "and create a summary of the top 5 by priority",
21 + tools: {
22 + composio_tool_router: toolRouter.tool,
23 + },
24 +});
25 +
26 +console.log("Result:", text);
27 +
28 +// If there were tool calls, they've already been executed
29 +if (toolResults && toolResults.length > 0) {
30 + console.log("Tool was called and executed successfully");
31 +}
\ No newline at end of file