1
---
2
title: Quickstart
3
-description: Build a Python agent that discovers and runs Composio tools
4
-keywords: [tutorial, setup, first agent, python, openai agents, sessions, tool router]
3
+description: Build an agent that discovers and runs Composio tools
4
+keywords: [tutorial, setup, first agent, sessions, tool router]
5
---
6
7
Build an agent that chooses Composio tools at runtime. Type a task, connect an app if needed, and continue in the same conversation.
8
9
-This example uses Python and OpenAI Agents. A Composio session gives the agent tool discovery, account connections, and execution. It exposes only a small set of meta tools, so app schemas are loaded when needed. You can use the same pattern with any [supported provider or framework](/docs/providers).
9
+Pick your framework below. A Composio [session](/docs/how-composio-works) gives your agent tool discovery, account connections, and execution across [1000+ apps](/toolkits). It exposes only a small set of meta tools, so app schemas are loaded when the agent needs them.
10
11
-## Prerequisites
12
-
13
-You need:
11
+<Callout type="info">
12
+The TypeScript SDK is ESM-only and requires Node.js 22.22.3 or newer. Use `import` syntax rather than CommonJS `require()`.
13
+</Callout>
14
15
-- [`uv`](https://docs.astral.sh/uv/) to create the Python project and install its dependencies.
16
-- A `COMPOSIO_API_KEY` from [Composio Settings](https://dashboard.composio.dev/~/project/settings/api-keys?utm_source=docs&utm_medium=content&utm_campaign=docs-quickstart).
17
-- An `OPENAI_API_KEY` from [OpenAI](https://platform.openai.com/api-keys).
15
+<QuickstartFlow>
16
19
-## Build the agent
17
+<FrameworkOption id="openai-agents" name="OpenAI Agents" logo="/images/providers/openai-logo.svg" logoDark="/images/providers/openai-logo-dark.svg">
18
19
<Steps>
20
<Step>
23
-<StepTitle>Create the project</StepTitle>
24
-
25
-Create a Python 3.10 project and enter its directory:
26
-
27
-```bash
28
-uv init --app --python 3.10 composio-quickstart
29
-cd composio-quickstart
30
-```
31
-
21
+<StepTitle>Install</StepTitle>
22
+
23
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
24
+<Tab value="Python">
25
+The Composio Python SDK requires **Python 3.10 or newer**.
26
+
27
+<PackageInstall ecosystem="python" packages="python-dotenv composio composio-openai-agents openai-agents" />
28
+</Tab>
29
+<Tab value="TypeScript">
30
+<PackageInstall
31
+ packages="@composio/core @composio/openai-agents @openai/agents"
32
+ comment={[
33
+ '@composio/core ships its docs and TypeScript source in the package,',
34
+ 'so it is inspectable to coding agents.',
35
+ 'Use @composio/slim for a smaller install with the same API.',
36
+ ]}
37
+/>
38
+</Tab>
39
+</Tabs>
40
</Step>
33
-<Step>
34
-<StepTitle>Install the packages</StepTitle>
35
-
36
-```bash
37
-uv add python-dotenv composio composio-openai-agents openai-agents
38
-```
41
40
-</Step>
42
<Step>
42
-<StepTitle>Set your API keys</StepTitle>
43
+<StepTitle>Configure API Keys</StepTitle>
44
44
-Create a `.env` file in the project root:
45
+<Callout type="info">
46
+Get your `COMPOSIO_API_KEY` from [Settings](https://dashboard.composio.dev/~/project/settings/api-keys?utm_source=docs&utm_medium=content&utm_campaign=docs-quickstart) and `OPENAI_API_KEY` from [OpenAI](https://platform.openai.com/api-keys).
47
+</Callout>
48
49
```bash title=".env"
50
COMPOSIO_API_KEY=your_composio_api_key
51
OPENAI_API_KEY=your_openai_api_key
52
```
50
-
51
-Keep `.env` out of source control:
52
-
53
-```bash
54
-echo ".env" >> .gitignore
55
-```
56
-
53
</Step>
58
-<Step>
59
-<StepTitle>Add the agent</StepTitle>
60
-
61
-Replace `main.py` with this complete program:
54
63
-```python title="main.py"
64
-import sys
55
+<Step>
56
+<StepTitle>Create session and run agent</StepTitle>
57
66
-from agents import Agent, Runner, SQLiteSession
58
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
59
+<Tab value="Python">
60
+```python
61
+from dotenv import load_dotenv
62
from composio import Composio
63
+from agents import Agent, Runner, SQLiteSession
64
from composio_openai_agents import OpenAIAgentsProvider
69
-from dotenv import load_dotenv
65
66
load_dotenv()
67
68
+# Initialize Composio with OpenAI Agents provider
69
composio = Composio(provider=OpenAIAgentsProvider())
74
-session = composio.sessions.create(user_id="quickstart-user")
70
+
71
+# Create a session for your user
72
+user_id = "user_123"
73
+session = composio.sessions.create(user_id=user_id)
74
+tools = session.tools()
75
+
76
+# For multi-turn, store the session ID in your db and reuse instead of creating another session:
77
+# session_id = session.session_id
78
+# session = composio.use(session_id)
79
80
agent = Agent(
77
- name="Composio assistant",
81
+ name="Personal Assistant",
82
instructions=(
83
"Use Composio tools to complete the request. "
84
"If a connection is required, share its Connect Link and wait. "
85
"Ask for confirmation before creating, updating, or deleting data."
86
),
83
- tools=session.tools(),
87
+ model="gpt-5.2",
88
+ tools=tools,
89
)
90
86
-conversation = SQLiteSession("quickstart-conversation")
87
-
88
-def run_task(task: str) -> None:
89
- result = Runner.run_sync(
90
- starting_agent=agent,
91
- input=task,
92
- session=conversation,
93
- )
94
- print(f"Assistant: {result.final_output}\n")
95
-
96
-if len(sys.argv) > 1:
97
- run_task(" ".join(sys.argv[1:]))
98
-else:
99
- print("Ask me to work with your apps. Type 'exit' to quit.")
100
- while True:
101
- task = input("You: ").strip()
102
- if task.lower() == "exit":
103
- break
104
- if task:
105
- run_task(task)
91
+# Memory for multi-turn conversation
92
+memory = SQLiteSession("conversation")
93
+
94
+print("""
95
+What task would you like me to help you with?
96
+I can use tools like Gmail, GitHub, Linear, Notion, and more.
97
+(Type 'exit' to exit)
98
+Example tasks:
99
+ - 'Summarize my emails from today'
100
+ - 'List all open issues on the composio github repository'
101
+""")
102
+
103
+while True:
104
+ user_input = input("You: ").strip()
105
+ if user_input.lower() == "exit":
106
+ break
107
+
108
+ print("Assistant: ", end="", flush=True)
109
+ result = Runner.run_sync(starting_agent=agent, input=user_input, session=memory)
110
+ print(f"{result.final_output}\n")
111
```
112
+</Tab>
113
+<Tab value="TypeScript">
114
+```typescript
115
+import "dotenv/config";
116
+import { Composio } from "@composio/core";
117
+import { Agent, run, MemorySession } from "@openai/agents";
118
+import { OpenAIAgentsProvider } from "@composio/openai-agents";
119
+import { createInterface } from "readline/promises";
120
+
121
+// Initialize Composio with OpenAI Agents provider
122
+const composio = new Composio({ provider: new OpenAIAgentsProvider() });
123
+
124
+// Create a session for your user
125
+const userId = "user_123";
126
+const session = await composio.create(userId);
127
+const tools = await session.tools();
128
+
129
+// For multi-turn, store the session ID in your db and reuse instead of calling create() again:
130
+// const sessionId = session.sessionId;
131
+// const session = await composio.use(sessionId);
132
+
133
+const agent = new Agent({
134
+ name: "Personal Assistant",
135
+ instructions:
136
+ "Use Composio tools to complete the request. " +
137
+ "If a connection is required, share its Connect Link and wait. " +
138
+ "Ask for confirmation before creating, updating, or deleting data.",
139
+ model: "gpt-5.2",
140
+ tools,
141
+});
142
+
143
+const memory = new MemorySession();
144
+const readline = createInterface({ input: process.stdin, output: process.stdout });
145
+
146
+console.log(`
147
+What task would you like me to help you with?
148
+I can use tools like Gmail, GitHub, Linear, Notion, and more.
149
+(Type 'exit' to exit)
150
+Example tasks:
151
+ - 'Summarize my emails from today'
152
+ - 'List all open issues on the composio github repository'
153
+`);
154
+
155
+while (true) {
156
+ const input = (await readline.question("You: ")).trim();
157
+ if (input.toLowerCase() === "exit") break;
158
+
159
+ process.stdout.write("Assistant: ");
160
+ const result = await run(agent, input, { session: memory });
161
+ process.stdout.write(`${result.finalOutput}\n`);
162
+}
163
+readline.close();
164
+```
165
+</Tab>
166
+</Tabs>
167
+</Step>
168
+</Steps>
169
+
170
+</FrameworkOption>
171
172
+<FrameworkOption id="claude-agents" name="Claude Agent SDK" logo="/images/providers/anthropic-logo.svg" logoDark="/images/providers/anthropic-logo-dark.svg">
173
+
174
+<Steps>
175
+<Step>
176
+<StepTitle>Install</StepTitle>
177
+
178
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
179
+<Tab value="Python">
180
+<PackageInstall ecosystem="python" packages="python-dotenv composio composio-claude-agent-sdk claude-agent-sdk" />
181
+</Tab>
182
+<Tab value="TypeScript">
183
+<PackageInstall
184
+ packages="dotenv @composio/core @composio/claude-agent-sdk @anthropic-ai/claude-agent-sdk"
185
+ comment={[
186
+ '@composio/core ships its docs and TypeScript source in the package,',
187
+ 'so it is inspectable to coding agents.',
188
+ 'Use @composio/slim for a smaller install with the same API.',
189
+ ]}
190
+/>
191
+</Tab>
192
+</Tabs>
193
</Step>
194
+
195
<Step>
110
-<StepTitle>Run it</StepTitle>
196
+<StepTitle>Configure API Keys</StepTitle>
197
112
-```bash
113
-uv run main.py
198
+<Callout type="info">
199
+Get your `COMPOSIO_API_KEY` from [Settings](https://dashboard.composio.dev/~/project/settings/api-keys?utm_source=docs&utm_medium=content&utm_campaign=docs-quickstart) and `ANTHROPIC_API_KEY` from [Anthropic](https://console.anthropic.com/settings/keys).
200
+</Callout>
201
+
202
+```bash title=".env"
203
+COMPOSIO_API_KEY=your_composio_api_key
204
+ANTHROPIC_API_KEY=your_anthropic_api_key
205
```
206
+</Step>
207
116
-To run one task without an interactive prompt, pass it as an argument:
208
+<Step>
209
+<StepTitle>Create session and run agent</StepTitle>
210
+
211
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
212
+<Tab value="Python">
213
+```python
214
+import asyncio
215
+from dotenv import load_dotenv
216
+from composio import Composio
217
+from composio_claude_agent_sdk import ClaudeAgentSDKProvider
218
+from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, create_sdk_mcp_server, AssistantMessage, TextBlock
219
118
-```bash
119
-uv run main.py "Find the three most recent open issues in composiohq/composio"
220
+load_dotenv()
221
+
222
+# Initialize Composio with Claude Agent SDK provider
223
+composio = Composio(provider=ClaudeAgentSDKProvider())
224
+
225
+# Create a session for your user
226
+user_id = "user_123"
227
+session = composio.sessions.create(user_id=user_id)
228
+tools = session.tools()
229
+
230
+# For multi-turn, store the session ID in your db and reuse instead of creating another session:
231
+# session_id = session.session_id
232
+# session = composio.use(session_id)
233
+
234
+custom_server = create_sdk_mcp_server(name="composio", version="1.0.0", tools=tools)
235
+
236
+async def main():
237
+ options = ClaudeAgentOptions(
238
+ system_prompt=(
239
+ "Use Composio tools to complete the request. "
240
+ "If a connection is required, share its Connect Link and wait. "
241
+ "Ask for confirmation before creating, updating, or deleting data."
242
+ ),
243
+ permission_mode="bypassPermissions",
244
+ mcp_servers={"composio": custom_server},
245
+ )
246
+
247
+ async with ClaudeSDKClient(options=options) as client:
248
+ print("""
249
+What task would you like me to help you with?
250
+I can use tools like Gmail, GitHub, Linear, Notion, and more.
251
+(Type 'exit' to exit)
252
+Example tasks:
253
+ - 'Summarize my emails from today'
254
+ - 'List all open issues on the composio github repository'
255
+""")
256
+
257
+ while True:
258
+ user_input = input("You: ").strip()
259
+ if user_input.lower() == "exit":
260
+ break
261
+
262
+ await client.query(user_input)
263
+ print("Claude: ", end="", flush=True)
264
+ async for message in client.receive_response():
265
+ if isinstance(message, AssistantMessage):
266
+ for block in message.content:
267
+ if isinstance(block, TextBlock):
268
+ print(block.text, end="", flush=True)
269
+ print()
270
+
271
+asyncio.run(main())
272
```
273
+</Tab>
274
+<Tab value="TypeScript">
275
+```typescript
276
+import "dotenv/config";
277
+import { Composio } from "@composio/core";
278
+import { ClaudeAgentSDKProvider } from "@composio/claude-agent-sdk";
279
+import { createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
280
+import { createInterface } from "readline/promises";
281
+
282
+// Initialize Composio with Claude Agent SDK provider
283
+const composio = new Composio({ provider: new ClaudeAgentSDKProvider() });
284
+
285
+// Create a session for your user
286
+const userId = "user_123";
287
+const session = await composio.create(userId);
288
+const tools = await session.tools();
289
+
290
+// For multi-turn, store the session ID in your db and reuse instead of calling create() again:
291
+// const sessionId = session.sessionId;
292
+// const session = await composio.use(sessionId);
293
+
294
+const customServer = createSdkMcpServer({
295
+ name: "composio",
296
+ version: "1.0.0",
297
+ tools: tools,
298
+});
299
+
300
+const readline = createInterface({ input: process.stdin, output: process.stdout });
301
+
302
+console.log(`
303
+What task would you like me to help you with?
304
+I can use tools like Gmail, GitHub, Linear, Notion, and more.
305
+(Type 'exit' to exit)
306
+Example tasks:
307
+ - 'Summarize my emails from today'
308
+ - 'List all open issues on the composio github repository and create a Google Sheet with the issues'
309
+`);
310
+
311
+let isFirstQuery = true;
312
+const options = {
313
+ systemPrompt:
314
+ "Use Composio tools to complete the request. " +
315
+ "If a connection is required, share its Connect Link and wait. " +
316
+ "Ask for confirmation before creating, updating, or deleting data.",
317
+ mcpServers: { composio: customServer },
318
+ permissionMode: "bypassPermissions" as const,
319
+};
320
+
321
+while (true) {
322
+ const input = (await readline.question("You: ")).trim();
323
+ if (input.toLowerCase() === "exit") break;
324
+
325
+ const queryOptions = isFirstQuery ? options : { ...options, continue: true };
326
+ isFirstQuery = false;
327
+
328
+ process.stdout.write("Claude: ");
329
+ for await (const stream of query({ prompt: input, options: queryOptions })) {
330
+ if (stream.type === "assistant") {
331
+ for (const block of stream.message.content) {
332
+ if (block.type === "text") {
333
+ process.stdout.write(block.text);
334
+ }
335
+ }
336
+ }
337
+ }
338
+ console.log();
339
+}
340
+
341
+readline.close();
342
+```
343
+</Tab>
344
+</Tabs>
345
+</Step>
346
+</Steps>
347
122
-Enter any task that needs an app tool. For example:
348
+</FrameworkOption>
349
124
-- `Find the three most recent open issues in a public GitHub repository.`
125
-- `Summarize my unread emails from today.`
126
-- `Turn these release notes into a Linear issue: ...`
350
+<FrameworkOption id="vercel-ai" name="Vercel AI SDK" logo="/images/providers/vercel-logo.svg" logoDark="/images/providers/vercel-logo-dark.svg">
351
128
-These are examples, not a sequence. If a task needs access to an account, the agent gives you a Connect Link. Open it, approve the connection, and tell the agent to continue.
352
+<Steps>
353
+<Step>
354
+<StepTitle>Install</StepTitle>
355
+
356
+<PackageInstall
357
+ packages="@composio/core @composio/vercel ai @ai-sdk/anthropic"
358
+ comment={[
359
+ '@composio/core ships its docs and TypeScript source in the package,',
360
+ 'so it is inspectable to coding agents.',
361
+ 'Use @composio/slim for a smaller install with the same API.',
362
+ ]}
363
+/>
364
+</Step>
365
+
366
+<Step>
367
+<StepTitle>Configure API Keys</StepTitle>
368
+
369
+<Callout type="info">
370
+Get your `COMPOSIO_API_KEY` from [Settings](https://dashboard.composio.dev/~/project/settings/api-keys?utm_source=docs&utm_medium=content&utm_campaign=docs-quickstart) and `ANTHROPIC_API_KEY` from [Anthropic](https://console.anthropic.com/settings/keys).
371
+</Callout>
372
+
373
+```bash title=".env"
374
+COMPOSIO_API_KEY=your_composio_api_key
375
+ANTHROPIC_API_KEY=your_anthropic_api_key
376
+```
377
+</Step>
378
379
+<Step>
380
+<StepTitle>Create session and run agent</StepTitle>
381
+
382
+```typescript
383
+import "dotenv/config";
384
+import { anthropic } from "@ai-sdk/anthropic";
385
+import { Composio } from "@composio/core";
386
+import { VercelProvider } from "@composio/vercel";
387
+import { streamText, stepCountIs, type ModelMessage } from "ai";
388
+import { createInterface } from "readline/promises";
389
+
390
+// Initialize Composio with Vercel provider
391
+const composio = new Composio({ provider: new VercelProvider() });
392
+
393
+// Create a session for your user
394
+const userId = "user_123";
395
+const session = await composio.create(userId);
396
+const tools = await session.tools();
397
+
398
+// For multi-turn, store the session ID in your db and reuse instead of calling create() again:
399
+// const sessionId = session.sessionId;
400
+// const session = await composio.use(sessionId);
401
+
402
+const readline = createInterface({ input: process.stdin, output: process.stdout });
403
+
404
+console.log(`
405
+What task would you like me to help you with?
406
+I can use tools like Gmail, GitHub, Linear, Notion, and more.
407
+(Type 'exit' to exit)
408
+Example tasks:
409
+ - 'Summarize my emails from today'
410
+ - 'List all open issues on the composio github repository'
411
+`);
412
+
413
+const messages: ModelMessage[] = [];
414
+
415
+while (true) {
416
+ const input = (await readline.question("You: ")).trim();
417
+ if (input.toLowerCase() === "exit") break;
418
+
419
+ messages.push({ role: "user", content: input });
420
+ process.stdout.write("Assistant: ");
421
+
422
+ const result = await streamText({
423
+ system:
424
+ "Use Composio tools to complete the request. " +
425
+ "If a connection is required, share its Connect Link and wait. " +
426
+ "Ask for confirmation before creating, updating, or deleting data.",
427
+ model: anthropic("claude-sonnet-4-6"),
428
+ messages,
429
+ stopWhen: stepCountIs(10),
430
+ onStepFinish: (step) => {
431
+ for (const toolCall of step.toolCalls) {
432
+ process.stdout.write(`\n[Using tool: ${toolCall.toolName}]`);
433
+ }
434
+ },
435
+ tools,
436
+ });
437
+
438
+ for await (const textPart of result.textStream) {
439
+ process.stdout.write(textPart);
440
+ }
441
+ console.log();
442
+
443
+ messages.push(...(await result.response).messages);
444
+}
445
+
446
+readline.close();
447
+```
448
</Step>
449
</Steps>
450
451
+</FrameworkOption>
452
+
453
+</QuickstartFlow>
454
+
455
+Ask for any task that needs an app tool: `Summarize my unread emails from today`, or `List all open issues on the composio github repository`. If a task needs access to an account, the agent gives you a Connect Link. Open it, approve the connection, and tell the agent to continue.
456
+
457
## What just happened?
458
135
-- `OpenAIAgentsProvider` formats Composio tools for OpenAI Agents.
136
-- `composio.sessions.create()` creates a Composio session for `quickstart-user`. The session scopes connections and tool calls to that ID.
137
-- Composio sessions persist. In an application, store `session.session_id` and restore it with `composio.use(session_id)` instead of creating a new session for every turn. See [Reusing a session](/docs/how-composio-works#how-sessions-behave).
459
+- The provider you picked formats Composio tools for your framework and wires in execution.
460
+- `composio.sessions.create()` creates a Composio session for `user_123`. The session scopes connections and tool calls to that ID.
461
+- Composio sessions persist. In an application, store the session ID (`session.session_id` in Python, `session.sessionId` in TypeScript) and restore it with `composio.use(session_id)` instead of creating a new session for every turn. See [Reusing a session](/docs/how-composio-works#how-sessions-behave).
462
- `session.tools()` gives the agent a small set of meta tools for finding, connecting, and running app tools. It does not load thousands of tool schemas into the model context.
139
-- `SQLiteSession` stores the OpenAI conversation history on disk. It is separate from the Composio session.
463
464
<Callout type="warn" title="Use your application's user ID in production">
142
-`quickstart-user` is only for this local example. Replace it with a stable ID from your database. Each ID gets separate connections and tool calls.
465
+`user_123` is only for this local example. Replace it with a stable ID from your database. Each ID gets separate connections and tool calls.
466
</Callout>
467
468
You can inspect the selected tools, inputs, responses, and timing with the [Logs API](/reference/api-reference/logs).