Skip to main content

Composio logo

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.

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)

Source distribution for composio 0.33.0
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)

Table of built distributions (wheels) for composio 0.33.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.33.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page