Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
quickstart changes
Sushmithamallesh committed
Dec 3, 2025 at 20:03 UTC
1648d300cbf58d0c78584d7d07f3e05a097ae501
1 file changed
+195
-152
fern/pages/src/tool-router/quickstart.mdx
+195
-152
@@ -9,264 +9,304 @@ hide-nav-links: false
9
Build an agent that summarizes your Gmail inbox.
10
11
<Tabs>
12
-<Tab title="OpenAI (Python)">
12
+<Tab title="OpenAI (TypeScript)">
13
14
<Steps>
15
<Step title="Install Composio SDK">
16
```bash
17
-pip install composio openai-agents composio-openai-agents
17
+npm install @composio/core @openai/agents
18
```
19
</Step>
20
21
-<Step title="Create session for user">
22
-Sessions are ephemeral, user-scoped and manage connections and tools for that user. See [Session Management](/docs/user-management) and [Configuring Toolkits](/tool-router/configuring-toolkits).
21
+<Step title="Create session and run agent">
22
+[Sessions](/tool-router/users-and-sessions) are ephemeral, user-scoped and manage connections and tools for that user.
23
24
<Info>
25
-`your-api-key`: Your Composio API key from the [dashboard](https://platform.composio.dev/?next_page=/settings).
26
-`pg-user-550e8400-e29b-41d4`: The [ID of the user](/docs/user-management) in your system.
25
+Replace `your-composio-api-key` with your Composio API key from the [settings](https://platform.composio.dev/?next_page=/settings) page.
26
</Info>
28
-```python
29
-from composio import Composio
30
-from composio_openai_agents import OpenAIAgentsProvider
27
32
-composio = Composio(
33
- api_key="your-api-key",
34
- provider=OpenAIAgentsProvider()
35
-)
28
+When the agent needs authentication, it will prompt the user with a link to connect their account. If you want to customise the authentication flow and have more control over the user experience, see [Manual Authentication](/tool-router/manually-authenticating-users).
29
37
-# Create a session for a user
38
-session = composio.create(user_id="pg-user-550e8400-e29b-41d4")
39
-```
40
-</Step>
30
+```typescript
31
+import { Composio } from "@composio/core";
32
+import { Agent, run, hostedMcpTool } from "@openai/agents";
33
42
-<Step title="Run agent">
43
-When the agent needs authentication, it will prompt the user to connect. To pre-authenticate users, see [Manual Authentication](/tool-router/manual-authentication).
44
-```python
45
-from agents import Agent, Runner
34
+const composio = new Composio({ apiKey: "your-composio-api-key" });
35
47
-agent = Agent(
48
- name="Personal Assistant",
49
- instructions="You are a helpful personal assistant.",
50
- tools=session.tools()
51
-)
36
+console.log("Creating Tool Router session...");
37
+const { mcp } = await composio.create("pg-user-550e8400-e29b-41d4");
38
+console.log(`Tool Router session created: ${mcp.url}`);
39
53
-result = Runner.run_sync(
54
- agent,
55
- "Summarize all the emails in my Gmail inbox today"
56
-)
57
-print(result.final_output)
40
+const agent = new Agent({
41
+ name: "Personal Assistant",
42
+ instructions: "You are a helpful personal assistant.",
43
+ tools: [
44
+ hostedMcpTool({
45
+ serverLabel: "composio",
46
+ serverUrl: mcp.url,
47
+ headers: {
48
+ "x-api-key": "your-composio-api-key",
49
+ },
50
+ }),
51
+ ],
52
+});
53
+
54
+console.log("Running the Open AI agent to fetch gmail inbox")
55
+const result = await run(
56
+ agent,
57
+ "Summarize all the emails in my Gmail inbox today"
58
+);
59
+console.log(result.finalOutput);
60
```
61
60
-To use OpenAI Agents SDK with Tool Router MCP instead, see [Using with MCP Clients](/tool-router/using-with-mcp-clients#openai).
62
+<Info>
63
+`pg-user-550e8400-e29b-41d4` is a placeholder for your user's ID. See [User Management](/docs/user-management) for details.
64
+</Info>
65
+
66
+To use OpenAI Agents SDK with Tool Router as native tools instead, see [Using as Native Tools](/tool-router/using-as-native-tools#openai).
67
</Step>
68
</Steps>
69
70
</Tab>
71
66
-<Tab title="OpenAI (TypeScript)">
72
+<Tab title="Vercel AI SDK">
73
74
<Steps>
75
<Step title="Install Composio SDK">
76
```bash
71
-npm install @composio/core @composio/openai-agents @openai/agents
77
+npm install @composio/core ai @ai-sdk/openai @ai-sdk/mcp
78
```
79
</Step>
80
75
-<Step title="Create session for user">
76
-Sessions are ephemeral, user-scoped and manage connections and tools for that user. See [Session Management](/docs/user-management) and [Configuring Toolkits](/tool-router/configuring-toolkits).
81
+<Step title="Create session and run agent">
82
+[Sessions](/tool-router/users-and-sessions) are ephemeral, user-scoped and manage connections and tools for that user.
83
84
<Info>
79
-`your-api-key`: Your Composio API key from the [dashboard](https://platform.composio.dev/?next_page=/settings).
80
-`pg-user-550e8400-e29b-41d4`: The [ID of the user](/docs/user-management) in your system.
85
+Replace `your-composio-api-key` with your Composio API key from the [settings](https://platform.composio.dev/?next_page=/settings) page.
86
</Info>
87
+
88
+When the agent needs authentication, it will prompt the user with a link to connect their account. If you want to customise the authentication flow and have more control over the user experience, see [Manual Authentication](/tool-router/manually-authenticating-users).
89
+
90
```typescript
91
+import { openai } from "@ai-sdk/openai";
92
+import { experimental_createMCPClient as createMCPClient } from "@ai-sdk/mcp";
93
import { Composio } from "@composio/core";
84
-import { OpenAIAgentsProvider } from "@composio/openai-agents";
94
+import { stepCountIs, streamText } from "ai";
95
86
-const composio = new Composio({
87
- apiKey: "your-api-key",
88
- provider: new OpenAIAgentsProvider(),
89
-});
96
+const composio = new Composio({ apiKey: "your-composio-api-key" });
97
91
-// Create a session for a user
92
-const { tools } = await composio.create("pg-user-550e8400-e29b-41d4");
93
-```
94
-</Step>
98
+console.log("Creating Tool Router session...");
99
+const { mcp } = await composio.create("pg-user-550e8400-e29b-41d4");
100
+console.log(`Tool Router session created: ${mcp.url}`);
101
+
102
+const client = await createMCPClient({
103
+ transport: {
104
+ type: "http",
105
+ url: mcp.url,
106
+ headers: {
107
+ "x-api-key": "your-composio-api-key",
108
+ },
109
+ },
110
+});
111
96
-<Step title="Run agent">
97
-When the agent needs authentication, it will prompt the user to connect. To pre-authenticate users, see [Manual Authentication](/tool-router/manual-authentication).
98
-```typescript
99
-import { Agent, run } from "@openai/agents";
112
+const tools = await client.tools();
113
101
-const agent = new Agent({
102
- name: "Personal Assistant",
103
- instructions: "You are a helpful personal assistant.",
104
- tools: await tools(),
114
+const stream = await streamText({
115
+ model: openai("gpt-5"),
116
+ prompt: "Summarize all the emails in my Gmail inbox today",
117
+ stopWhen: stepCountIs(10),
118
+ onStepFinish: (step) => {
119
+ if (step.toolCalls.length > 0) {
120
+ for (const toolCall of step.toolCalls) {
121
+ console.log(`Executed ${toolCall.toolName}`);
122
+ }
123
+ }
124
+ },
125
+ tools,
126
});
127
107
-const result = await run(
108
- agent,
109
- "Summarize all the emails in my Gmail inbox today"
110
-);
111
-console.log(result.finalOutput);
128
+for await (const textPart of stream.textStream) {
129
+ process.stdout.write(textPart);
130
+}
131
```
132
114
-To use OpenAI Agents SDK with Tool Router MCP instead, see [Using with MCP Clients](/tool-router/using-with-mcp-clients#openai).
133
+<Info>
134
+`pg-user-550e8400-e29b-41d4` is a placeholder for your user's ID. See [User Management](/docs/user-management) for details.
135
+</Info>
136
+
137
+To use Vercel AI SDK with Tool Router as native tools instead, see [Using as Native Tools](/tool-router/using-as-native-tools#vercel).
138
</Step>
139
</Steps>
140
141
</Tab>
142
120
-<Tab title="Anthropic (Python)">
143
+{/* <Tab title="Anthropic (TypeScript)">
144
145
<Steps>
146
<Step title="Install Composio SDK">
147
```bash
125
-pip install composio anthropic-agents
148
+npm install @composio/core @anthropic-ai/claude-agent-sdk
149
```
150
</Step>
151
129
-<Step title="Create session for user">
130
-Sessions are ephemeral, user-scoped and manage connections and tools for that user. See [Session Management](/docs/user-management) and [Configuring Toolkits](/tool-router/configuring-toolkits).
152
+<Step title="Create session and run agent">
153
+[Sessions](/tool-router/users-and-sessions) are ephemeral, user-scoped and manage connections and tools for that user.
154
155
<Info>
133
-`your-api-key`: Your Composio API key from the [dashboard](https://platform.composio.dev/?next_page=/settings).
134
-`pg-user-550e8400-e29b-41d4`: The [ID of the user](/docs/user-management) in your system.
156
+Replace `your-composio-api-key` with your Composio API key from the [settings](https://platform.composio.dev/?next_page=/settings) page.
157
</Info>
136
-```python
137
-from composio import Composio
158
139
-composio = Composio(api_key="your-api-key")
159
+When the agent needs authentication, it will prompt the user with a link to connect their account. If you want to customise the authentication flow and have more control over the user experience, see [Manual Authentication](/tool-router/manually-authenticating-users).
160
141
-# Create a session for a user
142
-session = composio.create(user_id="pg-user-550e8400-e29b-41d4")
143
-```
144
-</Step>
161
+```typescript
162
+import { Composio } from "@composio/core";
163
+import { query } from "@anthropic-ai/claude-agent-sdk";
164
146
-<Step title="Run agent">
147
-When the agent needs authentication, it will prompt the user to connect. To pre-authenticate users, see [Manual Authentication](/tool-router/manual-authentication).
148
-```python
149
-from anthropic_agents import Agent, run
165
+const composio = new Composio({ apiKey: "your-composio-api-key" });
166
151
-agent = Agent(
152
- name="Personal Assistant",
153
- instructions="You are a helpful personal assistant.",
154
- mcp_servers=[session.mcp.url]
155
-)
167
+console.log("Creating Tool Router session...");
168
+const { mcp } = await composio.create("pg-user-550e8400-e29b-41d4");
169
+console.log(`Tool Router session created: ${mcp.url}`);
170
157
-result = run(
158
- agent,
159
- "Summarize all the emails in my Gmail inbox today"
160
-)
161
-print(result.final_output)
171
+console.log("Waiting for agent response...");
172
+for await (const message of query({
173
+ prompt: "Summarize all the emails in my Gmail inbox today",
174
+ options: {
175
+ systemPrompt: "You are a helpful personal assistant.",
176
+ mcpServers: {
177
+ composio: {
178
+ type: "http",
179
+ url: mcp.url,
180
+ headers: { "x-api-key": "your-composio-api-key" },
181
+ },
182
+ },
183
+ },
184
+})) {
185
+ if (message.type === "result" && message.subtype === "success") {
186
+ console.log(message.result);
187
+ }
188
+}
189
```
190
191
+<Info>
192
+`pg-user-550e8400-e29b-41d4` is a placeholder for your user's ID. See [User Management](/docs/user-management) for details.
193
+</Info>
194
+
195
To use Anthropic Agents SDK with Tool Router as native tools instead, see [Using as Native Tools](/tool-router/using-as-native-tools#anthropic).
196
</Step>
197
</Steps>
198
199
</Tab>
200
170
-<Tab title="Anthropic (TypeScript)">
201
+<Tab title="OpenAI (Python)">
202
203
<Steps>
204
<Step title="Install Composio SDK">
205
```bash
175
-npm install @composio/core @anthropic-ai/agent
206
+pip install composio openai-agents
207
```
208
</Step>
209
179
-<Step title="Create session for user">
180
-Sessions are ephemeral, user-scoped and manage connections and tools for that user. See [Session Management](/docs/user-management) and [Configuring Toolkits](/tool-router/configuring-toolkits).
210
+<Step title="Create session and run agent">
211
+[Sessions](/tool-router/users-and-sessions) are ephemeral, user-scoped and manage connections and tools for that user.
212
213
<Info>
183
-`your-api-key`: Your Composio API key from the [dashboard](https://platform.composio.dev/?next_page=/settings).
184
-`pg-user-550e8400-e29b-41d4`: The [ID of the user](/docs/user-management) in your system.
214
+Replace `your-composio-api-key` with your Composio API key from the [settings](https://platform.composio.dev/?next_page=/settings) page.
215
</Info>
186
-```typescript
187
-import { Composio } from "@composio/core";
216
189
-const composio = new Composio({ apiKey: "your-api-key" });
217
+When the agent needs authentication, it will prompt the user with a link to connect their account. If you want to customise the authentication flow and have more control over the user experience, see [Manual Authentication](/tool-router/manually-authenticating-users).
218
191
-// Create a session for a user
192
-const { mcp } = await composio.create("pg-user-550e8400-e29b-41d4");
193
-```
194
-</Step>
219
+```python
220
+from composio import Composio
221
+from agents import Agent, Runner, HostedMCPTool
222
196
-<Step title="Run agent">
197
-When the agent needs authentication, it will prompt the user to connect. To pre-authenticate users, see [Manual Authentication](/tool-router/manual-authentication).
198
-```typescript
199
-import { Agent, run } from "@anthropic-ai/agent";
223
+composio = Composio(api_key="your-composio-api-key")
224
201
-const agent = new Agent({
202
- name: "Personal Assistant",
203
- instructions: "You are a helpful personal assistant.",
204
- mcpServers: [mcp.url],
205
-});
225
+session = composio.create(user_id="pg-user-550e8400-e29b-41d4")
226
207
-const result = await run(
208
- agent,
209
- "Summarize all the emails in my Gmail inbox today"
210
-);
211
-console.log(result.finalOutput);
227
+agent = Agent(
228
+ name="Personal Assistant",
229
+ instructions="You are a helpful personal assistant.",
230
+ tools=[
231
+ HostedMCPTool(
232
+ tool_config={
233
+ "type": "mcp",
234
+ "server_label": "composio",
235
+ "server_url": session.mcp.url,
236
+ "require_approval": "never",
237
+ "headers": {
238
+ "x-api-key": "your-composio-api-key",
239
+ },
240
+ }
241
+ )
242
+ ],
243
+)
244
+
245
+result = Runner.run_sync(
246
+ agent,
247
+ "Summarize all the emails in my Gmail inbox today"
248
+)
249
+print(result.final_output)
250
```
251
214
-To use Anthropic Agents SDK with Tool Router as native tools instead, see [Using as Native Tools](/tool-router/using-as-native-tools#anthropic).
252
+<Info>
253
+`pg-user-550e8400-e29b-41d4` is a placeholder for your user's ID. See [User Management](/docs/user-management) for details.
254
+</Info>
255
+
256
+To use OpenAI Agents SDK with Tool Router as native tools instead, see [Using as Native Tools](/tool-router/using-as-native-tools#openai).
257
</Step>
258
</Steps>
259
260
</Tab>
261
220
-<Tab title="Vercel AI SDK">
262
+<Tab title="Anthropic (Python)">
263
264
<Steps>
265
<Step title="Install Composio SDK">
266
```bash
225
-npm install @composio/core @composio/vercel ai @ai-sdk/openai
267
+pip install composio anthropic-agents
268
```
269
</Step>
270
229
-<Step title="Create session for user">
230
-Sessions are ephemeral, user-scoped and manage connections and tools for that user. See [Session Management](/docs/user-management) and [Configuring Toolkits](/tool-router/configuring-toolkits).
271
+<Step title="Create session and run agent">
272
+[Sessions](/tool-router/users-and-sessions) are ephemeral, user-scoped and manage connections and tools for that user.
273
274
<Info>
233
-`your-api-key`: Your Composio API key from the [dashboard](https://platform.composio.dev/?next_page=/settings).
234
-`pg-user-550e8400-e29b-41d4`: The [ID of the user](/docs/user-management) in your system.
275
+Replace `your-composio-api-key` with your Composio API key from the [settings](https://platform.composio.dev/?next_page=/settings) page.
276
</Info>
236
-```typescript
237
-import { Composio } from "@composio/core";
238
-import { VercelProvider } from "@composio/vercel";
277
240
-const composio = new Composio({
241
- apiKey: "your-api-key",
242
- provider: new VercelProvider(),
243
-});
278
+When the agent needs authentication, it will prompt the user with a link to connect their account. If you want to customise the authentication flow and have more control over the user experience, see [Manual Authentication](/tool-router/manually-authenticating-users).
279
245
-// Create a session for a user
246
-const { tools } = await composio.create("pg-user-550e8400-e29b-41d4");
247
-```
248
-</Step>
280
+```python
281
+from composio import Composio
282
+from anthropic_agents import Agent, run
283
250
-<Step title="Run agent">
251
-When the agent needs authentication, it will prompt the user to connect. To pre-authenticate users, see [Manual Authentication](/tool-router/manual-authentication).
252
-```typescript
253
-import { generateText } from "ai";
254
-import { openai } from "@ai-sdk/openai";
284
+composio = Composio(api_key="your-composio-api-key")
285
256
-const result = await generateText({
257
- model: openai("gpt-4o"),
258
- tools: await tools(),
259
- prompt: "Summarize all the emails in my Gmail inbox today",
260
-});
286
+session = composio.create(user_id="pg-user-550e8400-e29b-41d4")
287
262
-console.log(result.text);
288
+agent = Agent(
289
+ name="Personal Assistant",
290
+ instructions="You are a helpful personal assistant.",
291
+ mcp_servers=[session.mcp.url]
292
+)
293
+
294
+result = run(
295
+ agent,
296
+ "Summarize all the emails in my Gmail inbox today"
297
+)
298
+print(result.final_output)
299
```
300
265
-To use Vercel AI SDK with Tool Router MCP instead, see [Using with MCP Clients](/tool-router/using-with-mcp-clients#vercel).
301
+<Info>
302
+`pg-user-550e8400-e29b-41d4` is a placeholder for your user's ID. See [User Management](/docs/user-management) for details.
303
+</Info>
304
+
305
+To use Anthropic Agents SDK with Tool Router as native tools instead, see [Using as Native Tools](/tool-router/using-as-native-tools#anthropic).
306
</Step>
307
</Steps>
308
269
-</Tab>
309
+</Tab> */}
310
</Tabs>
311
312
## What just happened?
@@ -277,16 +317,19 @@ When you ran this agent, Tool Router handled everything behind the scenes:
317
2. **[Authentication](/tool-router/authentication)** - Prompted you to connect your Gmail account
318
3. **[Execution](/tool-router/tool-execution)** - Fetched your emails and processed results efficiently
319
280
-All you wrote was a prompt. Tool Router figured out the rest.
320
+All you wrote was a prompt. Tool Router handled the rest!
321
322
## Next steps
323
284
-<CardGroup cols={3}>
285
- <Card title="Configure toolkits" href="/tool-router/configuring-toolkits">
286
- Enable or disable specific apps for your session.
324
+<CardGroup cols={2}>
325
+ <Card title="Session management" href="/tool-router/users-and-sessions">
326
+ Learn about users, sessions, and how they work.
327
+ </Card>
328
+ <Card title="Tools and toolkits" href="/tool-router/tools-and-toolkits">
329
+ Learn about tools, toolkits, and how to configure them.
330
</Card>
288
- <Card title="Manual authentication" href="/tool-router/manual-authentication">
289
- Pre-authenticate users before running the agent.
331
+ <Card title="Manual authentication" href="/tool-router/manually-authenticating-users">
332
+ Customise the authentication flow for your users.
333
</Card>
334
<Card title="Using MCP" href="/tool-router/using-with-mcp-clients">
335
Connect Tool Router to any MCP-compatible client.