How Composio works

Composio connects AI agents to external services like GitHub, Gmail, and Slack. Your agent gets a small set of meta tools that can discover, authenticate, and execute tools across hundreds of apps at runtime.

This page is a high-level overview. Each concept has a dedicated page with full details:

1. Users & Sessions: how users and sessions scope tools and connections
2. Authentication: Connect Links, OAuth, API keys, and auth configs
3. Tools and toolkits: meta tools, discovery, and execution
4. Workbench: persistent Python sandbox for bulk operations
5. Triggers: event-driven payloads from connected apps

For hands-on setup, see the quickstart.

Sessions

When your app calls composio.create(), it creates a session scoped to a user.

composio = Composio()
session = composio.create(user_id="user_123")

# Get tools formatted for your provider
tools = session.tools()

# Or get the MCP endpoint for MCP-compatible frameworks
mcp_url = session.mcp.url
mcp_headers = session.mcp.headers

A session ties together:

• A user: whose credentials and connections to use
• Available toolkits: all by default, or a specific set you configure
• Auth configuration: which authentication method and connected accounts to use

Sessions are immutable. Their configuration is fixed at creation. If the context changes (different toolkits, different connected account), create a new session. You don't need to cache or manage session IDs.

Meta tools

Rather than loading hundreds of tool definitions into your agent's context, a session provides 5 meta tools:

The agent searches for relevant tools, authenticates if needed, and executes them, all through these 5 meta tools. For large responses or bulk operations, the agent offloads work to the workbench sandbox. Meta tool calls share context through a session_id, so the agent can search in one call and execute in the next without losing state.

Composio also surfaces learned plans from past executions: step-by-step workflows that have worked before for similar tasks, guiding the agent without starting from scratch.

Authentication

When a tool requires authentication and the user hasn't connected yet, the agent uses COMPOSIO_MANAGE_CONNECTIONS to generate a Connect Link, a hosted page where the user authorizes access.

In a conversation, this looks like:

You: Create a GitHub issue for the login bug

Agent: You'll need to connect your GitHub account. Please authorize here: <Connect Link>

You: Done

Agent: Created issue #42 on your-org/your-repo.

Composio manages the OAuth flow end to end: redirects, token exchange, and automatic refresh. Connections persist across sessions. A user who connects GitHub once can use it in every future session without re-authenticating.

Remote workbench

Large responses from COMPOSIO_MULTI_EXECUTE_TOOL are automatically synced to a secure remote workbench. Instead of stuffing thousands of lines into the context window, the agent can work with the data inside the workbench:

• Reading files and tool responses
• Searching across large outputs
• Writing and executing Python code to transform, filter, or aggregate data
• Calling Composio tools via the run_composio_tool helper for bulk orchestration

This keeps the agent's context window lean while still letting it handle operations like labeling hundreds of emails, processing CSV exports, or summarizing long API responses.

What to read next

Start with the concepts in order, or jump to the quickstart if you want to build right away: