Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
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.mdxindex 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_keyOPENAI_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_dotenvfrom composio import Composio+from agents import Agent, Runner, SQLiteSessionfrom composio_openai_agents import OpenAIAgentsProvider-from dotenv import load_dotenvload_dotenv()+# Initialize Composio with OpenAI Agents providercomposio = 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.tsdeleted file mode 100644index 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)');- });-});