Composio Python SDK
Composio gives your AI agents 1000+ pre-authenticated toolkits, per-user sessions, authentication, triggers, and a sandbox. This package is the Python SDK.
- Documentation
- Quickstart
- Changelog
- Dashboard (project keys: Settings > API Keys)
Install
Requires Python 3.11 through 3.15.
pip install composio
Configure your API key
Get a project API key from your project's Settings > API Keys in the dashboard. The quickstart shows the setup.
Set the key in the shell that starts your application:
export COMPOSIO_API_KEY="your_composio_api_key"
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.
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.
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. CLI login alone does not configure your application's API key; you still need to set COMPOSIO_API_KEY or pass api_key.
Quickstart
Create a session for one of your users and hand its tools to your agent:
from composio import Composio
composio = Composio() # reads COMPOSIO_API_KEY, or pass api_key=...
session = composio.create(user_id="user_123")
tools = session.tools() # OpenAI-format tool definitions by default
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:
session = composio.use(session_id)
See how Composio works for sessions and meta tools, and configuring sessions for restricting toolkits, tools, auth_configs, and connected_accounts on composio.create().
Execution results
Python session execution takes tool_slug, not the direct Tools API's slug:
result = session.execute(
tool_slug="COMPOSIO_SEARCH_TOOLS",
arguments={"queries": [{"use_case": "find recent emails"}]},
)
if result.result_type == "completed":
print(result.data)
else: # "failed" or "blocked", even if error is empty
print(result.result_type, result.error)
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.
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=...).
Provider helpers have provider-specific return contracts. The Python Anthropic helper 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.
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.
Error handling
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:
from composio import api_error_details
from composio_client import APIStatusError
try:
composio.tools.execute(
slug="GMAIL_SEND_EMAIL",
arguments={"to": "user@example.com", "subject": "Hi", "body": "Hello"},
user_id="user_123",
)
except APIStatusError as error:
details = api_error_details(error)
print(details.message) # 410 toolkit GMAIL version 20250114_00 is retired ...
print(details.status_code) # 410
print(details.api_error_code) # 1410
print(details.request_id) # req_...
print(details.possible_fixes) # ["Pin 20261101_00"] or status-specific guidance
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.
Use with an agent framework
Provider packages adapt session.tools() to your framework's native tool format. With OpenAI Agents:
pip install composio composio-openai-agents openai-agents
from composio import Composio
from composio_openai_agents import OpenAIAgentsProvider
from agents import Agent, Runner
composio = Composio(provider=OpenAIAgentsProvider())
session = composio.create(user_id="user_123")
tools = session.tools()
agent = Agent(
name="Personal Assistant",
instructions="You are a helpful assistant. Use Composio tools to take action.",
tools=tools,
)
result = Runner.run_sync(starting_agent=agent, input="Summarize my emails from today")
print(result.final_output)
Other Python providers: composio-openai, composio-anthropic, composio-claude-agent-sdk, composio-langchain, composio-langgraph, composio-llamaindex, composio-crewai, composio-autogen, composio-gemini, composio-google, composio-google-adk. Don't see yours? Build a custom provider.
MCP
Every session also exposes a hosted MCP endpoint. Pass mcp=True and point Claude, Cursor, or any MCP client at it:
from composio import Composio
composio = Composio()
session = composio.create(user_id="user_123", mcp=True)
print(session.mcp.url) # MCP endpoint for this session
print(session.mcp.headers) # auth headers for the endpoint
See sessions via MCP.
Authentication
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:
connection_request = session.authorize("gmail")
print(connection_request.redirect_url) # send the user here to approve access
connection_request.wait_for_connection()
See authentication for auth configs, custom OAuth apps, and connection lifecycle.
Triggers
Subscribe to events from connected apps (new email, new commit, and so on) and react to them:
from composio import Composio
composio = Composio()
trigger = composio.triggers.create(
slug="GITHUB_COMMIT_EVENT",
user_id="user_123",
trigger_config={"owner": "composiohq", "repo": "composio"},
)
subscription = composio.triggers.subscribe()
@subscription.handle(trigger_id=trigger.trigger_id)
def handle_event(data):
print("Event received:", data)
subscription.wait_forever()
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.
Development
This package lives in the Composio SDK monorepo under python/. See the contribution guidelines to get set up.
Support
Metadata
Release files for composio 0.33.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| composio-0.33.0.tar.gz | 483.5 kB | With provenance | Details for composio-0.33.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| composio-0.33.0-py3-none-any.whl | Python 3 | none | any | Details for composio-0.33.0-py3-none-any.whl |
Total release size: 742.9 kB
Release files / composio-0.33.0.tar.gz
| Download URL | composio-0.33.0.tar.gz |
|---|---|
| Size | 483.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
471f51d8f0560a7b1c6c37ac66dffa151dcb8eb6058a1f2f48244d2c3f036ad2
|
|
BLAKE2b-256 checksum How to use checksums |
c2783e4f7ea5b96aacf1753fc98d0a5d0912e1fe0edcebd14db68902e95cc9ff
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / composio-0.33.0-py3-none-any.whl
| Download URL | composio-0.33.0-py3-none-any.whl |
|---|---|
| Size | 259.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4ce82c3a88a6613ac82187c63aba73507db4154c0e36529c10b970cd24fa1447
|
|
BLAKE2b-256 checksum How to use checksums |
c5950f196077ba1a8c6dbc0062a57f267597c7cdd96911a9aa4a697e6798a3ae
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logSecurity for composio 0.33.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for composio-0.33.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.