Skip to content

README.md

Latest commit

 

History

History
182 lines (122 loc) · 8.87 KB

README.md

File metadata and controls

182 lines (122 loc) · 8.87 KB
Raw

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.

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