6
7
Build your first AI agent with Composio Tools. You'll create a [session](/docs/users-and-sessions) for a user, give your agent access to [tools](/docs/tools-and-toolkits), and let it take action across 1000+ apps.
8
9
-<Callout type="info">
10
-If you are an AI agent setting up Composio for yourself, you can [sign up as an agent](/docs/signing-up-as-an-agent) without a human-created account first.
11
-</Callout>
12
-
9
<QuickstartFlow>
10
11
<FrameworkOption id="openai-agents" name="OpenAI Agents" logo="/images/providers/openai-logo.svg" logoDark="/images/providers/openai-logo-dark.svg">
13
<IntegrationTabs>
14
<IntegrationContent value="native">
15
20
-<PromptBanner>
21
-**Add Composio tools to an OpenAI Agents app (Native Tools)**
22
-
23
-Give your OpenAI Agent access to 1000+ tools (Gmail, GitHub, Slack, Notion, etc.) via Composio. Composio handles authentication, tool discovery, and execution. You create a **session** for a user, get tools from that session, and pass them to your Agent.
24
-
25
-**Key concepts**
26
-
27
-- **Session**: Scoped environment for a user. Created with `composio.create(userId)`, reused with `composio.use(sessionId)`. Each `create()` returns a new session ID — store it and reuse for multi-turn conversations. Sessions have access to all toolkits by default.
28
-- **Provider**: Translates Composio tools into the framework's tool format. For OpenAI Agents, use `OpenAIAgentsProvider`.
29
-- **Authentication**: When a tool requires auth (e.g., GitHub OAuth), Composio returns an auth URL. The user authenticates once; Composio manages tokens.
30
-
31
-**Rules**
32
-
33
-ALWAYS:
34
-- Initialize with `OpenAIAgentsProvider` as the provider
35
-- Create a session with a user ID before getting tools
36
-- Use `session.tools()` to get tools — this returns framework-ready tools
37
-- Store API keys in .env, load with dotenv
38
-
39
-NEVER:
40
-- Hardcode API keys in source code
41
-- Call tools directly without a session
42
-- Import from `composio-core` (the package is `composio` for Python, `@composio/core` for TS)
43
-- Use `composio.tools.get()` or `composio.tools.execute()` — these are deprecated direct execution patterns
44
-
45
-**Deprecated (DO NOT use)**
46
-
47
-Python:
48
-```
49
-# WRONG — old direct execution pattern
50
-tools = composio.tools.get(user_id, { toolkits: ['github'] })
51
-result = composio.tools.execute('GITHUB_STAR_REPO', {...})
52
-
53
-# WRONG — old package name
54
-from composio_core import Composio
55
-```
56
-
57
-TypeScript:
58
-```
59
-// WRONG — old direct execution pattern
60
-const tools = composio.tools.get(userId, { toolkits: ['github'] });
61
-const result = composio.tools.execute('GITHUB_STAR_REPO', {...});
62
-```
63
-
64
-**Verify before responding**
65
-
66
-1. Is `OpenAIAgentsProvider` passed to `Composio()`?
67
-2. Is a session created with `composio.create(user_id)`?
68
-3. Are tools retrieved from `session.tools()`, not `composio.tools.get()`?
69
-4. Are API keys in .env, not hardcoded?
70
-5. Are imports from `composio` (Python) or `@composio/core` (TS)?
71
-
72
-</PromptBanner>
73
-
16
<Steps>
17
<Step>
18
<StepTitle>Install</StepTitle>
155
</IntegrationContent>
156
<IntegrationContent value="mcp">
157
216
-<PromptBanner>
217
-**Add Composio tools to an OpenAI Agents app (MCP)**
218
-
219
-Give your OpenAI Agent access to 1000+ tools (Gmail, GitHub, Slack, Notion, etc.) via Composio's hosted MCP server. No provider package needed — you connect directly to Composio's MCP endpoint. Composio handles authentication, tool discovery, and execution. You create a **session** for a user and pass the MCP connection to your Agent.
220
-
221
-**Key concepts**
222
-
223
-- **Session**: Scoped environment for a user. Created with `composio.create(userId)`, reused with `composio.use(sessionId)`. Each `create()` returns a new session ID — store it and reuse for multi-turn conversations. Sessions have access to all toolkits by default.
224
-- **MCP mode**: Instead of using a provider package, you connect to Composio's hosted MCP server using `session.mcp.url` and `session.mcp.headers`. No `@composio/openai-agents` package needed.
225
-- **Authentication**: When a tool requires auth (e.g., GitHub OAuth), Composio returns an auth URL. The user authenticates once; Composio manages tokens.
226
-
227
-**Rules**
228
-
229
-ALWAYS:
230
-- Use `session.mcp.url` and `session.mcp.headers` from the session — these are unique per session
231
-- In Python, set `require_approval` to `"never"` in the tool_config
232
-- Create a session with a user ID before accessing `session.mcp`
233
-- Store API keys in .env, load with dotenv
234
-
235
-NEVER:
236
-- Hardcode MCP URLs or headers — they come from the session
237
-- Pass a provider to `Composio()` when using MCP mode (no provider needed)
238
-- Import from `composio-core` (the package is `composio` for Python, `@composio/core` for TS)
239
-- Use `composio.tools.get()` or `composio.tools.execute()` — these are deprecated direct execution patterns
240
-
241
-**Deprecated (DO NOT use)**
242
-
243
-Python:
244
-```
245
-# WRONG — old direct execution pattern
246
-tools = composio.tools.get(user_id, { toolkits: ['github'] })
247
-result = composio.tools.execute('GITHUB_STAR_REPO', {...})
248
-
249
-# WRONG — using a provider with MCP (not needed)
250
-composio = Composio(provider=OpenAIAgentsProvider())
251
-
252
-# WRONG — old package name
253
-from composio_core import Composio
254
-```
255
-
256
-TypeScript:
257
-```
258
-// WRONG — old direct execution pattern
259
-const tools = composio.tools.get(userId, { toolkits: ['github'] });
260
-
261
-// WRONG — using a provider with MCP (not needed)
262
-const composio = new Composio({ provider: new OpenAIAgentsProvider() });
263
-```
264
-
265
-**Verify before responding**
266
-
267
-1. Is `Composio()` initialized WITHOUT a provider?
268
-2. Is a session created with `composio.create(user_id)`?
269
-3. Are `session.mcp.url` and `session.mcp.headers` used for the MCP connection?
270
-4. In Python, is `require_approval` set to `"never"`?
271
-5. Are API keys in .env, not hardcoded?
272
-
273
-</PromptBanner>
274
-
158
<Steps>
159
<Step>
160
<StepTitle>Install</StepTitle>
315
<IntegrationTabs>
316
<IntegrationContent value="native">
317
435
-<PromptBanner>
436
-**Add Composio tools to a Claude Agent SDK app (Native Tools)**
437
-
438
-Give your Claude agent access to 1000+ tools (Gmail, GitHub, Slack, Notion, etc.) via Composio. Composio handles authentication, tool discovery, and execution. You create a **session** for a user, get tools, wrap them in an SDK MCP server, and pass that server to ClaudeAgentOptions.
439
-
440
-**Key concepts**
441
-
442
-- **Session**: Scoped environment for a user. Created with `composio.create(userId)`, reused with `composio.use(sessionId)`. Each `create()` returns a new session ID — store it and reuse for multi-turn conversations. Sessions have access to all toolkits by default.
443
-- **Provider**: Translates Composio tools into the framework's tool format. For Claude Agent SDK, use `ClaudeAgentSDKProvider`.
444
-- **SDK MCP server**: Tools must be wrapped in an SDK MCP server via `create_sdk_mcp_server` / `createSdkMcpServer` before passing to `ClaudeAgentOptions.mcp_servers`. Do NOT pass tools directly.
445
-- **Authentication**: When a tool requires auth (e.g., GitHub OAuth), Composio returns an auth URL. The user authenticates once; Composio manages tokens.
446
-
447
-**Rules**
448
-
449
-ALWAYS:
450
-- Initialize with `ClaudeAgentSDKProvider` as the provider
451
-- Create a session with a user ID before getting tools
452
-- Wrap tools in an SDK MCP server before passing to ClaudeAgentOptions
453
-- Use `async/await` — Claude Agent SDK is fully async
454
-- Store API keys in .env, load with dotenv
455
-
456
-NEVER:
457
-- Pass tools directly to ClaudeAgentOptions (must wrap in MCP server first)
458
-- Hardcode API keys in source code
459
-- Import from `composio-core` (the package is `composio` for Python, `@composio/core` for TS)
460
-- Use `composio.tools.get()` or `composio.tools.execute()` — these are deprecated direct execution patterns
461
-
462
-**Deprecated (DO NOT use)**
463
-
464
-Python:
465
-```
466
-# WRONG — old direct execution pattern
467
-tools = composio.tools.get(user_id, { toolkits: ['github'] })
468
-result = composio.tools.execute('GITHUB_STAR_REPO', {...})
469
-
470
-# WRONG — passing tools directly without MCP server wrapper
471
-options = ClaudeAgentOptions(tools=tools)
472
-
473
-# WRONG — old package name
474
-from composio_core import Composio
475
-```
476
-
477
-TypeScript:
478
-```
479
-// WRONG — old direct execution pattern
480
-const tools = composio.tools.get(userId, { toolkits: ['github'] });
481
-
482
-// WRONG — passing tools directly without MCP server wrapper
483
-const options = new ClaudeAgentOptions({ tools });
484
-```
485
-
486
-**Verify before responding**
487
-
488
-1. Is `ClaudeAgentSDKProvider` passed to `Composio()`?
489
-2. Is a session created with `composio.create(user_id)`?
490
-3. Are tools wrapped in `create_sdk_mcp_server` / `createSdkMcpServer` before passing to options?
491
-4. Is the code using `async/await`?
492
-5. Are API keys in .env, not hardcoded?
493
-
494
-</PromptBanner>
495
-
318
<Steps>
319
<Step>
320
<StepTitle>Install</StepTitle>
481
</IntegrationContent>
482
<IntegrationContent value="mcp">
483
662
-<PromptBanner>
663
-**Add Composio tools to a Claude Agent SDK app (MCP)**
664
-
665
-Give your Claude agent access to 1000+ tools (Gmail, GitHub, Slack, Notion, etc.) via Composio's hosted MCP server. No provider package needed — you connect directly to Composio's MCP endpoint. Composio handles authentication, tool discovery, and execution. You create a **session** for a user and pass the MCP connection to ClaudeAgentOptions.
666
-
667
-**Key concepts**
668
-
669
-- **Session**: Scoped environment for a user. Created with `composio.create(userId)`, reused with `composio.use(sessionId)`. Each `create()` returns a new session ID — store it and reuse for multi-turn conversations. Sessions have access to all toolkits by default.
670
-- **MCP mode**: Instead of using a provider package, you connect to Composio's hosted MCP server using `session.mcp.url` and `session.mcp.headers`. No `@composio/claude-agent-sdk` package needed.
671
-- **Authentication**: When a tool requires auth (e.g., GitHub OAuth), Composio returns an auth URL. The user authenticates once; Composio manages tokens.
672
-
673
-**Rules**
674
-
675
-ALWAYS:
676
-- Use `session.mcp.url` and `session.mcp.headers` from the session — these are unique per session
677
-- Set MCP server type to `"http"` in the mcp_servers config
678
-- In Python, set `permission_mode` to `"bypassPermissions"` in the mcp_servers config
679
-- Use `async/await` — Claude Agent SDK is fully async
680
-- Store API keys in .env, load with dotenv
681
-
682
-NEVER:
683
-- Hardcode MCP URLs or headers — they come from the session
684
-- Pass a provider to `Composio()` when using MCP mode (no provider needed)
685
-- Import from `composio-core` (the package is `composio` for Python, `@composio/core` for TS)
686
-- Use `composio.tools.get()` or `composio.tools.execute()` — these are deprecated direct execution patterns
687
-
688
-**Deprecated (DO NOT use)**
689
-
690
-Python:
691
-```
692
-# WRONG — old direct execution pattern
693
-tools = composio.tools.get(user_id, { toolkits: ['github'] })
694
-result = composio.tools.execute('GITHUB_STAR_REPO', {...})
695
-
696
-# WRONG — using a provider with MCP (not needed)
697
-composio = Composio(provider=ClaudeAgentSDKProvider())
698
-
699
-# WRONG — old package name
700
-from composio_core import Composio
701
-```
702
-
703
-TypeScript:
704
-```
705
-// WRONG — old direct execution pattern
706
-const tools = composio.tools.get(userId, { toolkits: ['github'] });
707
-
708
-// WRONG — using a provider with MCP (not needed)
709
-const composio = new Composio({ provider: new ClaudeAgentSDKProvider() });
710
-```
711
-
712
-**Verify before responding**
713
-
714
-1. Is `Composio()` initialized WITHOUT a provider?
715
-2. Is a session created with `composio.create(user_id)`?
716
-3. Are `session.mcp.url` and `session.mcp.headers` used in the `mcp_servers` config?
717
-4. Is the MCP server type set to `"http"`?
718
-5. Is the code using `async/await`?
719
-6. Are API keys in .env, not hardcoded?
720
-
721
-</PromptBanner>
722
-
484
<Steps>
485
<Step>
486
<StepTitle>Install</StepTitle>
664
<IntegrationTabs>
665
<IntegrationContent value="native">
666
906
-<PromptBanner>
907
-**Add Composio tools to a Vercel AI SDK app (Native Tools)**
908
-
909
-Give your Vercel AI agent access to 1000+ tools (Gmail, GitHub, Slack, Notion, etc.) via Composio. Composio handles authentication, tool discovery, and execution. You create a **session** for a user, get tools from that session, and pass them to `streamText` or `generateText`. TypeScript only.
910
-
911
-**Key concepts**
912
-
913
-- **Session**: Scoped environment for a user. Created with `composio.create(userId)`, reused with `composio.use(sessionId)`. Each `create()` returns a new session ID — store it and reuse for multi-turn conversations. Sessions have access to all toolkits by default.
914
-- **Provider**: Translates Composio tools into the framework's tool format. For Vercel AI, use `VercelProvider`.
915
-- **streamText vs generateText**: Use `streamText` for streaming responses, `generateText` for single responses. Both accept Composio tools via the `tools` parameter.
916
-- **Authentication**: When a tool requires auth (e.g., GitHub OAuth), Composio returns an auth URL. The user authenticates once; Composio manages tokens.
917
-
918
-**Rules**
919
-
920
-ALWAYS:
921
-- Initialize with `VercelProvider` as the provider
922
-- Create a session with a user ID before getting tools
923
-- Use `session.tools()` to get tools — this returns Vercel AI-compatible tools
924
-- Use `streamText` or `generateText` from the `ai` package
925
-- Set `maxSteps` to allow multi-step tool use (e.g., `maxSteps: 10`)
926
-- Store API keys in .env, load with dotenv
927
-
928
-NEVER:
929
-- Hardcode API keys in source code
930
-- Call tools directly without a session
931
-- Import from `composio-core` (the package is `@composio/core`)
932
-- Use `composio.tools.get()` or `composio.tools.execute()` — these are deprecated direct execution patterns
933
-- Forget `maxSteps` — without it, the model won't execute tool calls
934
-
935
-**Deprecated (DO NOT use)**
936
-
937
-```
938
-// WRONG — old direct execution pattern
939
-const tools = composio.tools.get(userId, { toolkits: ['github'] });
940
-const result = composio.tools.execute('GITHUB_STAR_REPO', {...});
941
-
942
-// WRONG — missing maxSteps (model won't execute tool calls)
943
-const result = await generateText({ model, tools, prompt });
944
-```
945
-
946
-**Verify before responding**
947
-
948
-1. Is `VercelProvider` passed to `Composio()`?
949
-2. Is a session created with `composio.create(userId)`?
950
-3. Are tools retrieved from `session.tools()`, not `composio.tools.get()`?
951
-4. Is `maxSteps` set in `streamText` / `generateText`?
952
-5. Are API keys in .env, not hardcoded?
953
-
954
-</PromptBanner>
955
-
667
<Steps>
668
<Step>
669
<StepTitle>Install</StepTitle>
758
</IntegrationContent>
759
<IntegrationContent value="mcp">
760
1050
-<PromptBanner>
1051
-**Add Composio tools to a Vercel AI SDK app (MCP)**
1052
-
1053
-Give your Vercel AI agent access to 1000+ tools (Gmail, GitHub, Slack, Notion, etc.) via Composio's hosted MCP server. No provider package needed — you connect directly to Composio's MCP endpoint using `@ai-sdk/mcp`. Composio handles authentication, tool discovery, and execution. TypeScript only.
1054
-
1055
-**Key concepts**
1056
-
1057
-- **Session**: Scoped environment for a user. Created with `composio.create(userId)`, reused with `composio.use(sessionId)`. Each `create()` returns a new session ID — store it and reuse for multi-turn conversations. Sessions have access to all toolkits by default.
1058
-- **MCP mode**: Instead of using a provider package, you connect to Composio's hosted MCP server using `session.mcp.url` and `session.mcp.headers` via `@ai-sdk/mcp`. No `@composio/vercel` package needed.
1059
-- **Client lifecycle**: Always close the MCP client with `await client.close()` when done.
1060
-- **Authentication**: When a tool requires auth (e.g., GitHub OAuth), Composio returns an auth URL. The user authenticates once; Composio manages tokens.
1061
-
1062
-**Rules**
1063
-
1064
-ALWAYS:
1065
-- Use `mcp.url` and `mcp.headers` from the session object returned by `composio.create(userId)`
1066
-- Set transport type to `"http"` in createMCPClient
1067
-- Set `maxSteps` to allow multi-step tool use (e.g., `maxSteps: 10`)
1068
-- Close the MCP client when done: `await client.close()`
1069
-- Store API keys in .env, load with dotenv
1070
-
1071
-NEVER:
1072
-- Hardcode MCP URLs or headers — they come from the session
1073
-- Pass a provider to `Composio()` when using MCP mode (no provider needed)
1074
-- Import from `composio-core` (the package is `@composio/core`)
1075
-- Use `composio.tools.get()` or `composio.tools.execute()` — these are deprecated direct execution patterns
1076
-- Forget `maxSteps` — without it, the model won't execute tool calls
1077
-- Forget `await client.close()` — this leaks the MCP connection
1078
-
1079
-**Deprecated (DO NOT use)**
1080
-
1081
-```
1082
-// WRONG — old direct execution pattern
1083
-const tools = composio.tools.get(userId, { toolkits: ['github'] });
1084
-const result = composio.tools.execute('GITHUB_STAR_REPO', {...});
1085
-
1086
-// WRONG — using a provider with MCP (not needed)
1087
-const composio = new Composio({ provider: new VercelProvider() });
1088
-
1089
-// WRONG — missing maxSteps (model won't execute tool calls)
1090
-const result = await generateText({ model, tools, prompt });
1091
-```
1092
-
1093
-**Verify before responding**
1094
-
1095
-1. Is `Composio()` initialized WITHOUT a provider?
1096
-2. Are `mcp.url` and `mcp.headers` taken from the session returned by `composio.create(userId)`?
1097
-3. Is transport type `"http"` in `createMCPClient`?
1098
-4. Is `maxSteps` set in `streamText` / `generateText`?
1099
-5. Is `client.close()` called when done?
1100
-6. Are API keys in .env, not hardcoded?
1101
-
1102
-</PromptBanner>
1103
-
761
<Steps>
762
<Step>
763
<StepTitle>Install</StepTitle>
867
868
</QuickstartFlow>
869
1213
-<Callout type="info">
1214
-By default, sessions have access to **all available toolkits** in the Composio catalog. Your agent can discover and use any of them through `COMPOSIO_SEARCH_TOOLS`. To restrict which toolkits are available, see [Enable and disable toolkits](/docs/toolkits/enable-and-disable-toolkits).
1215
-</Callout>
1216
-
1217
-<Callout>
1218
-Every `composio.create()` call returns a new session ID. For multi-turn conversations or web apps, store the session ID and call `composio.use(sessionId)` on subsequent requests instead of creating a new session each time. See [Reusing a session](/docs/users-and-sessions#reusing-a-session).
1219
-</Callout>
870
+By default, each `composio.create()` call returns a new session with access to all toolkits. Sessions are highly configurable beyond that: [Reusing a session](/docs/users-and-sessions#reusing-a-session) covers storing a session ID and calling `composio.use()` across multi-turn requests, while [Configuring Sessions](/docs/configuring-sessions) covers restricting toolkits, auth configs, and connected accounts.
871
872
## Next steps
873