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

next
md 207 lines 10.1 KB
Rendered Raw
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)