> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Build an agent that discovers and runs Composio tools

Build an agent that chooses Composio tools at runtime. Type a task, connect an app if needed, and continue in the same conversation.

Pick your framework below. A Composio [session](https://composio-preview.mintlify.site/docs/how-composio-works.md) gives your agent tool discovery, account connections, and execution across [1000+ apps](https://composio-preview.mintlify.site/toolkits.md). It exposes only a small set of meta tools, so app schemas are loaded when the agent needs them.

[Agent setup](https://composio-preview.mintlify.site/docs/agent-setup)

Help me add Composio to this project. First, inspect the codebase to understand its framework, agent architecture, authentication, and user or tenant identity model.

Check whether the official `composio` Agent Skill is installed. If it is missing, install it for this project with:

`npx skills add ComposioHQ/composio --skill composio`

Then load and follow the skill. If installation requires approval, ask for it. If the host does not support skills or installation fails, use the current documentation at [https://docs.composio.dev](https://docs.composio.dev) and report that fallback.

Default to Composio Platform for application codebases. Use Composio For You only when the project clearly configures a personal agent or automation for the developer’s own accounts.

Based on the codebase, explain briefly where Composio would fit. Then ask what I want my users or agent to accomplish with connected apps. If the project suggests likely use cases, offer a few relevant options. If it is not clear whether I want to build Composio into the application or connect it to my coding agent, ask me before making changes.

> [!NOTE]
>
> **Running as an unattended coding agent?**
>
> If no human is available to log in, use `composio login --agent` to obtain a Composio credential. Follow [Authenticate an unattended agent](https://composio-preview.mintlify.site/docs/agent-setup/unattended-authentication.md) to configure `COMPOSIO_API_KEY` and verify a live tool call.

> [tab] OpenAI Agents
>
> **1. Install**
>
> > [tab] Python
> >
> > The Composio Python SDK requires **Python 3.11 through 3.15**.
> >
> > ```bash uv theme={null}
> > uv add python-dotenv composio composio-openai-agents openai-agents
> > ```
> >
> > ```bash pip theme={null}
> > pip install python-dotenv composio composio-openai-agents openai-agents
> > ```
> >
> > > [!WARNING]
> > >
> > > **Do not install composio-core**
> > >
> > > The current Python package is `composio`. The package `composio-core` is the legacy v1 SDK — it calls deprecated APIs and does not work with sessions. If an older tutorial or an AI coding assistant suggests it, install `composio` instead. See the [migration guide](https://composio-preview.mintlify.site/docs/migration-guide/new-sdk.md).
>
> > [tab] TypeScript
> >
> > The TypeScript SDK is ESM-only and requires **Node.js 22.22.3 or newer**. Use `import` syntax rather than CommonJS `require()`.
> >
> > ```bash npm theme={null}
> > # @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.
> > npm install @composio/core @composio/openai-agents @openai/agents
> > ```
> >
> > ```bash pnpm theme={null}
> > # @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.
> > pnpm add @composio/core @composio/openai-agents @openai/agents
> > ```
> >
> > ```bash yarn theme={null}
> > # @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.
> > yarn add @composio/core @composio/openai-agents @openai/agents
> > ```
> >
> > ```bash bun theme={null}
> > # @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.
> > bun add @composio/core @composio/openai-agents @openai/agents
> > ```
>
> **2. Configure API Keys**
>
> > [!NOTE]
> >
> > 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).
>
> ```bash .env theme={null}
> COMPOSIO_API_KEY=your_composio_api_key
> OPENAI_API_KEY=your_openai_api_key
> ```
>
> **3. Create session and run agent**
>
> > [tab] Python
> >
> > ```python theme={null}
> > from dotenv import load_dotenv
> > from composio import Composio
> > from agents import Agent, Runner, SQLiteSession
> > from composio_openai_agents import OpenAIAgentsProvider
> >
> > load_dotenv()
> >
> > # Initialize Composio with OpenAI Agents provider
> > composio = Composio(provider=OpenAIAgentsProvider())
> >
> > # 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="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=tools,
> > )
> >
> > # 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] TypeScript
> >
> > ```typescript theme={null}
> > 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] Claude Agent SDK
>
> **1. Install**
>
> > [tab] Python
> >
> > ```bash uv theme={null}
> > uv add python-dotenv composio composio-claude-agent-sdk claude-agent-sdk
> > ```
> >
> > ```bash pip theme={null}
> > pip install python-dotenv composio composio-claude-agent-sdk claude-agent-sdk
> > ```
> >
> > > [!WARNING]
> > >
> > > **Do not install composio-core**
> > >
> > > The current Python package is `composio`. The package `composio-core` is the legacy v1 SDK — it calls deprecated APIs and does not work with sessions. If an older tutorial or an AI coding assistant suggests it, install `composio` instead. See the [migration guide](https://composio-preview.mintlify.site/docs/migration-guide/new-sdk.md).
>
> > [tab] TypeScript
> >
> > ```bash npm theme={null}
> > # @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.
> > npm install dotenv @composio/core @composio/claude-agent-sdk @anthropic-ai/claude-agent-sdk
> > ```
> >
> > ```bash pnpm theme={null}
> > # @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.
> > pnpm add dotenv @composio/core @composio/claude-agent-sdk @anthropic-ai/claude-agent-sdk
> > ```
> >
> > ```bash yarn theme={null}
> > # @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.
> > yarn add dotenv @composio/core @composio/claude-agent-sdk @anthropic-ai/claude-agent-sdk
> > ```
> >
> > ```bash bun theme={null}
> > # @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.
> > bun add dotenv @composio/core @composio/claude-agent-sdk @anthropic-ai/claude-agent-sdk
> > ```
>
> **2. Configure API Keys**
>
> > [!NOTE]
> >
> > 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).
>
> ```bash .env theme={null}
> COMPOSIO_API_KEY=your_composio_api_key
> ANTHROPIC_API_KEY=your_anthropic_api_key
> ```
>
> **3. Create session and run agent**
>
> > [tab] Python
> >
> > ```python theme={null}
> > 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
> >
> > 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] TypeScript
> >
> > ```typescript theme={null}
> > 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'
> > `);
> >
> > 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] Vercel AI SDK
>
> **1. Install**
>
> ```bash npm theme={null}
> # @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.
> npm install @composio/core @composio/vercel ai @ai-sdk/anthropic
> ```
>
> ```bash pnpm theme={null}
> # @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.
> pnpm add @composio/core @composio/vercel ai @ai-sdk/anthropic
> ```
>
> ```bash yarn theme={null}
> # @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.
> yarn add @composio/core @composio/vercel ai @ai-sdk/anthropic
> ```
>
> ```bash bun theme={null}
> # @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.
> bun add @composio/core @composio/vercel ai @ai-sdk/anthropic
> ```
>
> **2. Configure API Keys**
>
> > [!NOTE]
> >
> > 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).
>
> ```bash .env theme={null}
> COMPOSIO_API_KEY=your_composio_api_key
> ANTHROPIC_API_KEY=your_anthropic_api_key
> ```
>
> **3. Create session and run agent**
>
> ```typescript theme={null}
> 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();
> ```

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?

* The provider you picked formats Composio tools for your framework and wires in execution.
* `composio.sessions.create()` creates a [Composio session](https://composio-preview.mintlify.site/docs/how-composio-works.md) 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](https://composio-preview.mintlify.site/docs/how-composio-works.md#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.

> [!WARNING]
>
> **Use your application's user ID in production**
>
> `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.

Note: Sessions are recommended for new integrations. If you maintain a legacy direct-execution integration, see [Sessions vs direct execution](https://composio-preview.mintlify.site/docs/sessions-vs-direct-execution.md) and the [migration guide](https://composio-preview.mintlify.site/docs/migration-guide/direct-to-sessions.md). You can inspect the selected tools, inputs, responses, and timing with the [Logs API](https://composio-preview.mintlify.site/reference/api-reference/logs).

## Adapt the example

> [card] [Use another framework](https://composio-preview.mintlify.site/docs/providers)
>
> Choose OpenAI, Anthropic, Vercel AI SDK, LangChain, CrewAI, or another supported provider.

> [card] [Configure the session](https://composio-preview.mintlify.site/docs/configuring-sessions.md)
>
> Restrict toolkits, preload tools, or select connected accounts.

> [card] [Design authentication](https://composio-preview.mintlify.site/docs/authentication)
>
> Add Connect Links and per-user connections to your application.

> [card] [Expose an MCP endpoint](https://composio-preview.mintlify.site/docs/sessions-via-mcp.md)
>
> Use the same Composio session from an MCP-compatible application.

> [card] [Browse SDK examples](https://composio-preview.mintlify.site/examples/sdk-examples.md)
>
> Find TypeScript and Python source code, deploy a Worker, or try TypeSafe and Python MCP integrations.

## Plan your application

> [card] [Consumer agent architecture](https://composio-preview.mintlify.site/docs/consumer-agents.md)
>
> Map individual users to isolated connections and reusable sessions.

> [card] [B2B agent architecture](https://composio-preview.mintlify.site/docs/b2b-agents.md)
>
> Choose member-owned or workspace-owned connections for a multi-tenant product.

> [card] [Production readiness](https://composio-preview.mintlify.site/docs/production-readiness.md)
>
> Review identity, auth, security, logging, and trigger decisions before launch.
