Skip to content

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

docs: restore quickstart framework picker with TypeScript, keep intent-rewrite improvements

Rahul Tarak205329c3d2f2
diff --git a/docs/content/docs/quickstart.mdx b/docs/content/docs/quickstart.mdx
index 8cb42840f..321c48d1c 100644
--- a/docs/content/docs/quickstart.mdx
+++ b/docs/content/docs/quickstart.mdx
@@ -1,145 +1,468 @@
---
title: Quickstart
-description: Build a Python agent that discovers and runs Composio tools
-keywords: [tutorial, setup, first agent, python, openai agents, sessions, tool router]
+description: Build an agent that discovers and runs Composio tools
+keywords: [tutorial, setup, first agent, sessions, tool router]
---
Build an agent that chooses Composio tools at runtime. Type a task, connect an app if needed, and continue in the same conversation.
-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).
+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.
-## Prerequisites
-
-You need:
+<Callout type="info">
+The TypeScript SDK is ESM-only and requires Node.js 22.22.3 or newer. Use `import` syntax rather than CommonJS `require()`.
+</Callout>
-- [`uv`](https://docs.astral.sh/uv/) to create the Python project and install its dependencies.
-- 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).
-- An `OPENAI_API_KEY` from [OpenAI](https://platform.openai.com/api-keys).
+<QuickstartFlow>
-## Build the agent
+<FrameworkOption id="openai-agents" name="OpenAI Agents" logo="/images/providers/openai-logo.svg" logoDark="/images/providers/openai-logo-dark.svg">
<Steps>
<Step>
-<StepTitle>Create the project</StepTitle>
-
-Create a Python 3.10 project and enter its directory:
-
-```bash
-uv init --app --python 3.10 composio-quickstart
-cd composio-quickstart
-```
-
+<StepTitle>Install</StepTitle>
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+The Composio Python SDK requires **Python 3.10 or newer**.
+
+<PackageInstall ecosystem="python" packages="python-dotenv composio composio-openai-agents openai-agents" />
+</Tab>
+<Tab value="TypeScript">
+<PackageInstall
+ packages="@composio/core @composio/openai-agents @openai/agents"
+ comment={[
+ '@composio/core ships its docs and TypeScript source in the package,',
+ 'so it is inspectable to coding agents.',
+ 'Use @composio/slim for a smaller install with the same API.',
+ ]}
+/>
+</Tab>
+</Tabs>
</Step>
-<Step>
-<StepTitle>Install the packages</StepTitle>
-
-```bash
-uv add python-dotenv composio composio-openai-agents openai-agents
-```
-</Step>
<Step>
-<StepTitle>Set your API keys</StepTitle>
+<StepTitle>Configure API Keys</StepTitle>
-Create a `.env` file in the project root:
+<Callout type="info">
+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).
+</Callout>
```bash title=".env"
COMPOSIO_API_KEY=your_composio_api_key
OPENAI_API_KEY=your_openai_api_key
```
-
-Keep `.env` out of source control:
-
-```bash
-echo ".env" >> .gitignore
-```
-
</Step>
-<Step>
-<StepTitle>Add the agent</StepTitle>
-
-Replace `main.py` with this complete program:
-```python title="main.py"
-import sys
+<Step>
+<StepTitle>Create session and run agent</StepTitle>
-from agents import Agent, Runner, SQLiteSession
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+from dotenv import load_dotenv
from composio import Composio
+from agents import Agent, Runner, SQLiteSession
from composio_openai_agents import OpenAIAgentsProvider
-from dotenv import load_dotenv
load_dotenv()
+# Initialize Composio with OpenAI Agents provider
composio = Composio(provider=OpenAIAgentsProvider())
-session = composio.sessions.create(user_id="quickstart-user")
+
+# Create a session for your user
+user_id = "user_123"
+session = composio.sessions.create(user_id=user_id)
+tools = session.tools()
+
+# For multi-turn, store the session ID in your db and reuse instead of creating another session:
+# session_id = session.session_id
+# session = composio.use(session_id)
agent = Agent(
- name="Composio assistant",
+ name="Personal Assistant",
instructions=(
"Use Composio tools to complete the request. "
"If a connection is required, share its Connect Link and wait. "
"Ask for confirmation before creating, updating, or deleting data."
),
- tools=session.tools(),
+ model="gpt-5.2",
+ tools=tools,
)
-conversation = SQLiteSession("quickstart-conversation")
-
-def run_task(task: str) -> None:
- result = Runner.run_sync(
- starting_agent=agent,
- input=task,
- session=conversation,
- )
- print(f"Assistant: {result.final_output}\n")
-
-if len(sys.argv) > 1:
- run_task(" ".join(sys.argv[1:]))
-else:
- print("Ask me to work with your apps. Type 'exit' to quit.")
- while True:
- task = input("You: ").strip()
- if task.lower() == "exit":
- break
- if task:
- run_task(task)
+# Memory for multi-turn conversation
+memory = SQLiteSession("conversation")
+
+print("""
+What task would you like me to help you with?
+I can use tools like Gmail, GitHub, Linear, Notion, and more.
+(Type 'exit' to exit)
+Example tasks:
+ - 'Summarize my emails from today'
+ - 'List all open issues on the composio github repository'
+""")
+
+while True:
+ user_input = input("You: ").strip()
+ if user_input.lower() == "exit":
+ break
+
+ print("Assistant: ", end="", flush=True)
+ result = Runner.run_sync(starting_agent=agent, input=user_input, session=memory)
+ print(f"{result.final_output}\n")
```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import "dotenv/config";
+import { Composio } from "@composio/core";
+import { Agent, run, MemorySession } from "@openai/agents";
+import { OpenAIAgentsProvider } from "@composio/openai-agents";
+import { createInterface } from "readline/promises";
+
+// Initialize Composio with OpenAI Agents provider
+const composio = new Composio({ provider: new OpenAIAgentsProvider() });
+
+// Create a session for your user
+const userId = "user_123";
+const session = await composio.create(userId);
+const tools = await session.tools();
+
+// For multi-turn, store the session ID in your db and reuse instead of calling create() again:
+// const sessionId = session.sessionId;
+// const session = await composio.use(sessionId);
+
+const agent = new Agent({
+ name: "Personal Assistant",
+ instructions:
+ "Use Composio tools to complete the request. " +
+ "If a connection is required, share its Connect Link and wait. " +
+ "Ask for confirmation before creating, updating, or deleting data.",
+ model: "gpt-5.2",
+ tools,
+});
+
+const memory = new MemorySession();
+const readline = createInterface({ input: process.stdin, output: process.stdout });
+
+console.log(`
+What task would you like me to help you with?
+I can use tools like Gmail, GitHub, Linear, Notion, and more.
+(Type 'exit' to exit)
+Example tasks:
+ - 'Summarize my emails from today'
+ - 'List all open issues on the composio github repository'
+`);
+
+while (true) {
+ const input = (await readline.question("You: ")).trim();
+ if (input.toLowerCase() === "exit") break;
+
+ process.stdout.write("Assistant: ");
+ const result = await run(agent, input, { session: memory });
+ process.stdout.write(`${result.finalOutput}\n`);
+}
+readline.close();
+```
+</Tab>
+</Tabs>
+</Step>
+</Steps>
+
+</FrameworkOption>
+<FrameworkOption id="claude-agents" name="Claude Agent SDK" logo="/images/providers/anthropic-logo.svg" logoDark="/images/providers/anthropic-logo-dark.svg">
+
+<Steps>
+<Step>
+<StepTitle>Install</StepTitle>
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+<PackageInstall ecosystem="python" packages="python-dotenv composio composio-claude-agent-sdk claude-agent-sdk" />
+</Tab>
+<Tab value="TypeScript">
+<PackageInstall
+ packages="dotenv @composio/core @composio/claude-agent-sdk @anthropic-ai/claude-agent-sdk"
+ comment={[
+ '@composio/core ships its docs and TypeScript source in the package,',
+ 'so it is inspectable to coding agents.',
+ 'Use @composio/slim for a smaller install with the same API.',
+ ]}
+/>
+</Tab>
+</Tabs>
</Step>
+
<Step>
-<StepTitle>Run it</StepTitle>
+<StepTitle>Configure API Keys</StepTitle>
-```bash
-uv run main.py
+<Callout type="info">
+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).
+</Callout>
+
+```bash title=".env"
+COMPOSIO_API_KEY=your_composio_api_key
+ANTHROPIC_API_KEY=your_anthropic_api_key
```
+</Step>
-To run one task without an interactive prompt, pass it as an argument:
+<Step>
+<StepTitle>Create session and run agent</StepTitle>
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+import asyncio
+from dotenv import load_dotenv
+from composio import Composio
+from composio_claude_agent_sdk import ClaudeAgentSDKProvider
+from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, create_sdk_mcp_server, AssistantMessage, TextBlock
-```bash
-uv run main.py "Find the three most recent open issues in composiohq/composio"
+load_dotenv()
+
+# Initialize Composio with Claude Agent SDK provider
+composio = Composio(provider=ClaudeAgentSDKProvider())
+
+# Create a session for your user
+user_id = "user_123"
+session = composio.sessions.create(user_id=user_id)
+tools = session.tools()
+
+# For multi-turn, store the session ID in your db and reuse instead of creating another session:
+# session_id = session.session_id
+# session = composio.use(session_id)
+
+custom_server = create_sdk_mcp_server(name="composio", version="1.0.0", tools=tools)
+
+async def main():
+ options = ClaudeAgentOptions(
+ system_prompt=(
+ "Use Composio tools to complete the request. "
+ "If a connection is required, share its Connect Link and wait. "
+ "Ask for confirmation before creating, updating, or deleting data."
+ ),
+ permission_mode="bypassPermissions",
+ mcp_servers={"composio": custom_server},
+ )
+
+ async with ClaudeSDKClient(options=options) as client:
+ print("""
+What task would you like me to help you with?
+I can use tools like Gmail, GitHub, Linear, Notion, and more.
+(Type 'exit' to exit)
+Example tasks:
+ - 'Summarize my emails from today'
+ - 'List all open issues on the composio github repository'
+""")
+
+ while True:
+ user_input = input("You: ").strip()
+ if user_input.lower() == "exit":
+ break
+
+ await client.query(user_input)
+ print("Claude: ", end="", flush=True)
+ async for message in client.receive_response():
+ if isinstance(message, AssistantMessage):
+ for block in message.content:
+ if isinstance(block, TextBlock):
+ print(block.text, end="", flush=True)
+ print()
+
+asyncio.run(main())
```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import "dotenv/config";
+import { Composio } from "@composio/core";
+import { ClaudeAgentSDKProvider } from "@composio/claude-agent-sdk";
+import { createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
+import { createInterface } from "readline/promises";
+
+// Initialize Composio with Claude Agent SDK provider
+const composio = new Composio({ provider: new ClaudeAgentSDKProvider() });
+
+// Create a session for your user
+const userId = "user_123";
+const session = await composio.create(userId);
+const tools = await session.tools();
+
+// For multi-turn, store the session ID in your db and reuse instead of calling create() again:
+// const sessionId = session.sessionId;
+// const session = await composio.use(sessionId);
+
+const customServer = createSdkMcpServer({
+ name: "composio",
+ version: "1.0.0",
+ tools: tools,
+});
+
+const readline = createInterface({ input: process.stdin, output: process.stdout });
+
+console.log(`
+What task would you like me to help you with?
+I can use tools like Gmail, GitHub, Linear, Notion, and more.
+(Type 'exit' to exit)
+Example tasks:
+ - 'Summarize my emails from today'
+ - 'List all open issues on the composio github repository and create a Google Sheet with the issues'
+`);
+
+let isFirstQuery = true;
+const options = {
+ systemPrompt:
+ "Use Composio tools to complete the request. " +
+ "If a connection is required, share its Connect Link and wait. " +
+ "Ask for confirmation before creating, updating, or deleting data.",
+ mcpServers: { composio: customServer },
+ permissionMode: "bypassPermissions" as const,
+};
+
+while (true) {
+ const input = (await readline.question("You: ")).trim();
+ if (input.toLowerCase() === "exit") break;
+
+ const queryOptions = isFirstQuery ? options : { ...options, continue: true };
+ isFirstQuery = false;
+
+ process.stdout.write("Claude: ");
+ for await (const stream of query({ prompt: input, options: queryOptions })) {
+ if (stream.type === "assistant") {
+ for (const block of stream.message.content) {
+ if (block.type === "text") {
+ process.stdout.write(block.text);
+ }
+ }
+ }
+ }
+ console.log();
+}
+
+readline.close();
+```
+</Tab>
+</Tabs>
+</Step>
+</Steps>
-Enter any task that needs an app tool. For example:
+</FrameworkOption>
-- `Find the three most recent open issues in a public GitHub repository.`
-- `Summarize my unread emails from today.`
-- `Turn these release notes into a Linear issue: ...`
+<FrameworkOption id="vercel-ai" name="Vercel AI SDK" logo="/images/providers/vercel-logo.svg" logoDark="/images/providers/vercel-logo-dark.svg">
-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.
+<Steps>
+<Step>
+<StepTitle>Install</StepTitle>
+
+<PackageInstall
+ packages="@composio/core @composio/vercel ai @ai-sdk/anthropic"
+ comment={[
+ '@composio/core ships its docs and TypeScript source in the package,',
+ 'so it is inspectable to coding agents.',
+ 'Use @composio/slim for a smaller install with the same API.',
+ ]}
+/>
+</Step>
+
+<Step>
+<StepTitle>Configure API Keys</StepTitle>
+
+<Callout type="info">
+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).
+</Callout>
+
+```bash title=".env"
+COMPOSIO_API_KEY=your_composio_api_key
+ANTHROPIC_API_KEY=your_anthropic_api_key
+```
+</Step>
+<Step>
+<StepTitle>Create session and run agent</StepTitle>
+
+```typescript
+import "dotenv/config";
+import { anthropic } from "@ai-sdk/anthropic";
+import { Composio } from "@composio/core";
+import { VercelProvider } from "@composio/vercel";
+import { streamText, stepCountIs, type ModelMessage } from "ai";
+import { createInterface } from "readline/promises";
+
+// Initialize Composio with Vercel provider
+const composio = new Composio({ provider: new VercelProvider() });
+
+// Create a session for your user
+const userId = "user_123";
+const session = await composio.create(userId);
+const tools = await session.tools();
+
+// For multi-turn, store the session ID in your db and reuse instead of calling create() again:
+// const sessionId = session.sessionId;
+// const session = await composio.use(sessionId);
+
+const readline = createInterface({ input: process.stdin, output: process.stdout });
+
+console.log(`
+What task would you like me to help you with?
+I can use tools like Gmail, GitHub, Linear, Notion, and more.
+(Type 'exit' to exit)
+Example tasks:
+ - 'Summarize my emails from today'
+ - 'List all open issues on the composio github repository'
+`);
+
+const messages: ModelMessage[] = [];
+
+while (true) {
+ const input = (await readline.question("You: ")).trim();
+ if (input.toLowerCase() === "exit") break;
+
+ messages.push({ role: "user", content: input });
+ process.stdout.write("Assistant: ");
+
+ const result = await streamText({
+ system:
+ "Use Composio tools to complete the request. " +
+ "If a connection is required, share its Connect Link and wait. " +
+ "Ask for confirmation before creating, updating, or deleting data.",
+ model: anthropic("claude-sonnet-4-6"),
+ messages,
+ stopWhen: stepCountIs(10),
+ onStepFinish: (step) => {
+ for (const toolCall of step.toolCalls) {
+ process.stdout.write(`\n[Using tool: ${toolCall.toolName}]`);
+ }
+ },
+ tools,
+ });
+
+ for await (const textPart of result.textStream) {
+ process.stdout.write(textPart);
+ }
+ console.log();
+
+ messages.push(...(await result.response).messages);
+}
+
+readline.close();
+```
</Step>
</Steps>
+</FrameworkOption>
+
+</QuickstartFlow>
+
+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.
+
## What just happened?
-- `OpenAIAgentsProvider` formats Composio tools for OpenAI Agents.
-- `composio.sessions.create()` creates a Composio session for `quickstart-user`. The session scopes connections and tool calls to that ID.
-- 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).
+- The provider you picked formats Composio tools for your framework and wires in execution.
+- `composio.sessions.create()` creates a Composio session for `user_123`. The session scopes connections and tool calls to that ID.
+- 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).
- `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.
-- `SQLiteSession` stores the OpenAI conversation history on disk. It is separate from the Composio session.
<Callout type="warn" title="Use your application's user ID in production">
-`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.
+`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.
</Callout>
You can inspect the selected tools, inputs, responses, and timing with the [Logs API](/reference/api-reference/logs).
diff --git a/docs/tests/static/quickstart.test.ts b/docs/tests/static/quickstart.test.ts
deleted file mode 100644
index 02877a15d..000000000
--- a/docs/tests/static/quickstart.test.ts
+++ /dev/null
@@ -1,45 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { readFile } from 'fs/promises';
-import { join } from 'path';
-
-const QUICKSTART_PATH = join(import.meta.dir, '../../content/docs/quickstart.mdx');
-
-describe('Quickstart default path', () => {
- test('presents one linear OpenAI Agents and Python flow before adaptations', async () => {
- const content = await readFile(QUICKSTART_PATH, 'utf-8');
- const milestones = [
- '<StepTitle>Create the project</StepTitle>',
- '<StepTitle>Install the packages</StepTitle>',
- '<StepTitle>Set your API keys</StepTitle>',
- '<StepTitle>Add the agent</StepTitle>',
- '<StepTitle>Run it</StepTitle>',
- '## What just happened?',
- '## Adapt the example',
- ];
- const positions = milestones.map(milestone => content.indexOf(milestone));
-
- expect(positions.every(position => position >= 0)).toBe(true);
- expect([...positions].sort((a, b) => a - b)).toEqual(positions);
- expect(content).not.toContain('<QuickstartFlow>');
- expect(content).not.toContain('<FrameworkOption');
- expect(content).not.toContain('Finish this path');
- expect(content).not.toContain('respond exactly');
- });
-
- test('supports interactive and one-shot tasks', async () => {
- const content = await readFile(QUICKSTART_PATH, 'utf-8');
-
- expect(content).toContain('uv init --app --python 3.10 composio-quickstart');
- expect(content).toContain(
- 'uv add python-dotenv composio composio-openai-agents openai-agents'
- );
- expect(content).toContain('session = composio.sessions.create(user_id="quickstart-user")');
- expect(content).toContain('if len(sys.argv) > 1:');
- expect(content).toContain('run_task(" ".join(sys.argv[1:]))');
- expect(content).toContain('task = input("You: ").strip()');
- expect(content).toContain('uv run main.py "Find the three most recent open issues');
- expect(content).toContain('the agent gives you a Connect Link');
- expect(content).toContain('a small set of meta tools for finding, connecting, and running app tools');
- expect(content).toContain('composio.use(session_id)');
- });
-});