Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | <p align="center"> |
| 2 | <a href="https://composio.dev"> |
| 3 | <picture> |
| 4 | <source media="(prefers-color-scheme: dark)" srcset="https://brand.composio.dev/logos/Logomark-White.svg"> |
| 5 | <img alt="Composio logo" src="https://brand.composio.dev/logos/Logomark-Black.svg" width="96"> |
| 6 | </picture> |
| 7 | </a> |
| 8 | </p> |
| 9 | |
| 10 | # Composio Python SDK |
| 11 | |
| 12 | Composio gives your AI agents 1000+ pre-authenticated toolkits, per-user sessions, authentication, triggers, and a sandbox. This package is the Python SDK. |
| 13 | |
| 14 | - [Documentation](https://docs.composio.dev) |
| 15 | - [Quickstart](https://docs.composio.dev/docs/quickstart) |
| 16 | - [Changelog](https://docs.composio.dev/reference/changelog) |
| 17 | - [Dashboard](https://dashboard.composio.dev) (project keys: Settings > API Keys) |
| 18 | |
| 19 | ## Install |
| 20 | |
| 21 | Requires Python 3.11 through 3.15. |
| 22 | |
| 23 | ```bash |
| 24 | pip install composio |
| 25 | ``` |
| 26 | |
| 27 | ## Configure your API key |
| 28 | |
| 29 | Get a project API key from your project's **Settings > API Keys** in the dashboard. The [quickstart](https://docs.composio.dev/docs/quickstart) shows the setup. |
| 30 | |
| 31 | Set the key in the shell that starts your application: |
| 32 | |
| 33 | ```bash |
| 34 | export COMPOSIO_API_KEY="your_composio_api_key" |
| 35 | ``` |
| 36 | |
| 37 | `Composio()` reads `COMPOSIO_API_KEY`. You can instead load the key from your secret store and pass it with `Composio(api_key=project_api_key)`. Keep keys out of source control and logs. |
| 38 | |
| 39 | Without a project key, `Composio()` raises `ApiKeyNotProvidedError` before making API requests. Passing `api_key=None` or `api_key=""` explicitly does not fall back to the environment. |
| 40 | |
| 41 | The CLI is optional and installed separately. `pip install composio` provides neither a `composio` executable nor a `python -m composio` entry point. If you want to use `composio login`, follow the [CLI installation instructions](https://docs.composio.dev/docs/cli#install). CLI login alone does not configure your application's API key; you still need to set `COMPOSIO_API_KEY` or pass `api_key`. |
| 42 | |
| 43 | ## Quickstart |
| 44 | |
| 45 | Create a session for one of your users and hand its tools to your agent: |
| 46 | |
| 47 | ```python |
| 48 | from composio import Composio |
| 49 | |
| 50 | composio = Composio() # reads COMPOSIO_API_KEY, or pass api_key=... |
| 51 | |
| 52 | session = composio.create(user_id="user_123") |
| 53 | tools = session.tools() # OpenAI-format tool definitions by default |
| 54 | ``` |
| 55 | |
| 56 | By default a session gets meta tools that discover, authenticate, and execute app tools at runtime, so you don't load hundreds of tool definitions into context. Store `session.session_id` and reuse the session across turns: |
| 57 | |
| 58 | ```python |
| 59 | session = composio.use(session_id) |
| 60 | ``` |
| 61 | |
| 62 | See [how Composio works](https://docs.composio.dev/docs/how-composio-works) for sessions and meta tools, and [configuring sessions](https://docs.composio.dev/docs/configuring-sessions) for restricting `toolkits`, `tools`, `auth_configs`, and `connected_accounts` on `composio.create()`. |
| 63 | |
| 64 | ## Execution results |
| 65 | |
| 66 | Python session execution takes `tool_slug`, not the direct Tools API's `slug`: |
| 67 | |
| 68 | ```python |
| 69 | result = session.execute( |
| 70 | tool_slug="COMPOSIO_SEARCH_TOOLS", |
| 71 | arguments={"queries": [{"use_case": "find recent emails"}]}, |
| 72 | ) |
| 73 | if result.result_type == "completed": |
| 74 | print(result.data) |
| 75 | else: # "failed" or "blocked", even if error is empty |
| 76 | print(result.result_type, result.error) |
| 77 | ``` |
| 78 | |
| 79 | `session.execute` returns a Pydantic `ToolRouterSessionExecuteResponse` with `data`, `error`, `log_id`, and `result_type` attributes. Serialize it with `result.model_dump(mode="json")` or `result.model_dump_json()`. It has no `successful` key or model tool-call ID. |
| 80 | |
| 81 | In contrast, `composio.tools.execute(slug=..., arguments=..., user_id=...)` and `after_execute` modifiers use `ToolExecutionResponse` dictionaries: check `response["successful"]` and serialize with `json.dumps(response)`. Provider adapters for session execution derive that flag from `result_type == "completed"` and retain `result_type`, `log_id`, and any returned `instant_charge`. Modifiers receive `(tool, toolkit, response)` and must return the dictionary. Calling `session.execute` directly doesn't invoke callbacks supplied to `session.tools(modifiers=...)`. |
| 82 | |
| 83 | Provider helpers have provider-specific return contracts. The [Python Anthropic helper](providers/anthropic) returns execution dictionaries with `tool_use_id`; you still build and serialize Anthropic `tool_result` blocks yourself. Don't assume Python returns TypeScript-native message blocks. |
| 84 | |
| 85 | Transport/authentication errors and requests for user input can raise instead of returning a result. Keep authentication recovery separate from returned tool failures. A non-throwing call, empty `error`, or execution-log ID isn't proof of a provider-side action. Check the explicit outcome and tool-specific `data`; your application owns retry and idempotency decisions. |
| 86 | |
| 87 | ## Error handling |
| 88 | |
| 89 | API rejections raise a `composio_client` status error, which is also a `ComposioError`. The message carries the server's explanation, and the error exposes the HTTP status, request id, numeric API error code, and a suggested fix: |
| 90 | |
| 91 | ```python |
| 92 | from composio import api_error_details |
| 93 | from composio_client import APIStatusError |
| 94 | |
| 95 | try: |
| 96 | composio.tools.execute( |
| 97 | slug="GMAIL_SEND_EMAIL", |
| 98 | arguments={"to": "user@example.com", "subject": "Hi", "body": "Hello"}, |
| 99 | user_id="user_123", |
| 100 | ) |
| 101 | except APIStatusError as error: |
| 102 | details = api_error_details(error) |
| 103 | print(details.message) # 410 toolkit GMAIL version 20250114_00 is retired ... |
| 104 | print(details.status_code) # 410 |
| 105 | print(details.api_error_code) # 1410 |
| 106 | print(details.request_id) # req_... |
| 107 | print(details.possible_fixes) # ["Pin 20261101_00"] or status-specific guidance |
| 108 | ``` |
| 109 | |
| 110 | `api_error_details()` returns the typed view of the same exception, so type checkers see these fields. `details.possible_fixes` uses the server's `suggested_fix` when present. Without one, it returns a fix chosen for the HTTP status, so a 401, 402, 403, 410, or 5xx doesn't tell you to check the tool slug and arguments. `details.details` still exposes the validated error envelope. |
| 111 | |
| 112 | ## Use with an agent framework |
| 113 | |
| 114 | Provider packages adapt `session.tools()` to your framework's native tool format. With [OpenAI Agents](https://github.com/ComposioHQ/composio/tree/next/python/providers/openai_agents): |
| 115 | |
| 116 | ```bash |
| 117 | pip install composio composio-openai-agents openai-agents |
| 118 | ``` |
| 119 | |
| 120 | ```python |
| 121 | from composio import Composio |
| 122 | from composio_openai_agents import OpenAIAgentsProvider |
| 123 | from agents import Agent, Runner |
| 124 | |
| 125 | composio = Composio(provider=OpenAIAgentsProvider()) |
| 126 | |
| 127 | session = composio.create(user_id="user_123") |
| 128 | tools = session.tools() |
| 129 | |
| 130 | agent = Agent( |
| 131 | name="Personal Assistant", |
| 132 | instructions="You are a helpful assistant. Use Composio tools to take action.", |
| 133 | tools=tools, |
| 134 | ) |
| 135 | |
| 136 | result = Runner.run_sync(starting_agent=agent, input="Summarize my emails from today") |
| 137 | print(result.final_output) |
| 138 | ``` |
| 139 | |
| 140 | Other Python providers: [`composio-openai`](https://github.com/ComposioHQ/composio/tree/next/python/providers/openai), [`composio-anthropic`](https://github.com/ComposioHQ/composio/tree/next/python/providers/anthropic), [`composio-claude-agent-sdk`](https://github.com/ComposioHQ/composio/tree/next/python/providers/claude_agent_sdk), [`composio-langchain`](https://github.com/ComposioHQ/composio/tree/next/python/providers/langchain), [`composio-langgraph`](https://github.com/ComposioHQ/composio/tree/next/python/providers/langgraph), [`composio-llamaindex`](https://github.com/ComposioHQ/composio/tree/next/python/providers/llamaindex), [`composio-crewai`](https://github.com/ComposioHQ/composio/tree/next/python/providers/crewai), [`composio-autogen`](https://github.com/ComposioHQ/composio/tree/next/python/providers/autogen), [`composio-gemini`](https://github.com/ComposioHQ/composio/tree/next/python/providers/gemini), [`composio-google`](https://github.com/ComposioHQ/composio/tree/next/python/providers/google), [`composio-google-adk`](https://github.com/ComposioHQ/composio/tree/next/python/providers/google_adk). Don't see yours? [Build a custom provider](https://docs.composio.dev/docs/providers/custom-providers). |
| 141 | |
| 142 | ## MCP |
| 143 | |
| 144 | Every session also exposes a hosted MCP endpoint. Pass `mcp=True` and point Claude, Cursor, or any MCP client at it: |
| 145 | |
| 146 | ```python |
| 147 | from composio import Composio |
| 148 | |
| 149 | composio = Composio() |
| 150 | |
| 151 | session = composio.create(user_id="user_123", mcp=True) |
| 152 | print(session.mcp.url) # MCP endpoint for this session |
| 153 | print(session.mcp.headers) # auth headers for the endpoint |
| 154 | ``` |
| 155 | |
| 156 | See [sessions via MCP](https://docs.composio.dev/docs/sessions-via-mcp). |
| 157 | |
| 158 | ## Authentication |
| 159 | |
| 160 | Sessions manage connections for you by default; the agent walks the user through OAuth with the session's meta tools. To drive the flow yourself, authorize a toolkit from the session: |
| 161 | |
| 162 | ```python |
| 163 | connection_request = session.authorize("gmail") |
| 164 | print(connection_request.redirect_url) # send the user here to approve access |
| 165 | connection_request.wait_for_connection() |
| 166 | ``` |
| 167 | |
| 168 | See [authentication](https://docs.composio.dev/docs/authentication) for auth configs, custom OAuth apps, and connection lifecycle. |
| 169 | |
| 170 | ## Triggers |
| 171 | |
| 172 | Subscribe to events from connected apps (new email, new commit, and so on) and react to them: |
| 173 | |
| 174 | ```python |
| 175 | from composio import Composio |
| 176 | |
| 177 | composio = Composio() |
| 178 | |
| 179 | trigger = composio.triggers.create( |
| 180 | slug="GITHUB_COMMIT_EVENT", |
| 181 | user_id="user_123", |
| 182 | trigger_config={"owner": "composiohq", "repo": "composio"}, |
| 183 | ) |
| 184 | |
| 185 | subscription = composio.triggers.subscribe() |
| 186 | |
| 187 | @subscription.handle(trigger_id=trigger.trigger_id) |
| 188 | def handle_event(data): |
| 189 | print("Event received:", data) |
| 190 | |
| 191 | subscription.wait_forever() |
| 192 | ``` |
| 193 | |
| 194 | `subscribe()` streams events over a WebSocket for local development. In production, register a webhook URL and parse deliveries with `composio.triggers.parse()`. See [setting up triggers](https://docs.composio.dev/docs/setting-up-triggers/creating-triggers). |
| 195 | |
| 196 | ## Development |
| 197 | |
| 198 | This package lives in the [Composio SDK monorepo](https://github.com/ComposioHQ/composio) under `python/`. See the [contribution guidelines](https://github.com/ComposioHQ/composio/blob/next/CONTRIBUTING.md) to get set up. |
| 199 | |
| 200 | ## Support |
| 201 | |
| 202 | - [Documentation](https://docs.composio.dev) |
| 203 | - [Python SDK reference](https://docs.composio.dev/reference/sdk-reference/python) |
| 204 | - [Changelog](https://docs.composio.dev/reference/changelog) |
| 205 | - [Discord community](https://discord.gg/composio) |
| 206 | - [Open an issue](https://github.com/ComposioHQ/composio/issues) |
| 207 | - [support@composio.dev](mailto:support@composio.dev) |