Metadata-Version: 2.4
Name: composio
Version: 0.33.0
Summary: SDK for integrating Composio with your applications.
Home-page: https://github.com/composiohq/composio
Author: Composio
Author-email: tech@composio.dev
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11,<3.16
Description-Content-Type: text/markdown
Requires-Dist: pysher==1.0.8
Requires-Dist: websocket-client<2
Requires-Dist: pydantic<3,>=2.11.9
Requires-Dist: composio-client==2.1.33
Requires-Dist: typing-extensions<5,>=4.16.0
Requires-Dist: openai<4,>=2.48.0
Requires-Dist: json-schema-to-pydantic<1,>=0.4.11
Requires-Dist: jsonschema<5,>=4.23.0
Requires-Dist: requests<3,>=2.32.4
Requires-Dist: urllib3<3,>=2.7.0
Requires-Dist: certifi>=2026.10.19
Dynamic: author
Dynamic: author-email
Dynamic: home-page
Dynamic: requires-python

<p align="center">
  <a href="https://composio.dev">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://brand.composio.dev/logos/Logomark-White.svg">
      <img alt="Composio logo" src="https://brand.composio.dev/logos/Logomark-Black.svg" width="96">
    </picture>
  </a>
</p>

# 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](https://docs.composio.dev)
- [Quickstart](https://docs.composio.dev/docs/quickstart)
- [Changelog](https://docs.composio.dev/reference/changelog)
- [Dashboard](https://dashboard.composio.dev) (project keys: Settings > API Keys)

## Install

Requires Python 3.11 through 3.15.

```bash
pip install composio
```

## Configure your API key

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.

Set the key in the shell that starts your application:

```bash
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](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`.

## Quickstart

Create a session for one of your users and hand its tools to your agent:

```python
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:

```python
session = composio.use(session_id)
```

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()`.

## Execution results

Python session execution takes `tool_slug`, not the direct Tools API's `slug`:

```python
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](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.

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:

```python
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](https://github.com/ComposioHQ/composio/tree/next/python/providers/openai_agents):

```bash
pip install composio composio-openai-agents openai-agents
```

```python
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`](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).

## MCP

Every session also exposes a hosted MCP endpoint. Pass `mcp=True` and point Claude, Cursor, or any MCP client at it:

```python
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](https://docs.composio.dev/docs/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:

```python
connection_request = session.authorize("gmail")
print(connection_request.redirect_url)  # send the user here to approve access
connection_request.wait_for_connection()
```

See [authentication](https://docs.composio.dev/docs/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:

```python
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](https://docs.composio.dev/docs/setting-up-triggers/creating-triggers).

## Development

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.

## Support

- [Documentation](https://docs.composio.dev)
- [Python SDK reference](https://docs.composio.dev/reference/sdk-reference/python)
- [Changelog](https://docs.composio.dev/reference/changelog)
- [Discord community](https://discord.gg/composio)
- [Open an issue](https://github.com/ComposioHQ/composio/issues)
- [support@composio.dev](mailto:support@composio.dev)
