composio-client for Python

composio-client replaces the Stainless-generated package without requiring you to rewrite existing 1.43.x calls.

from composio_client import Composio

client = Composio(api_key="ak_...")

session = client.tool_router.session.create(user_id="user@example.com")
result = client.tool_router.session.execute(
    session.session_id,
    tool_slug="GITHUB_CREATE_ISSUE",
    arguments={"owner": "composiohq", "repo": "composio", "title": "Example"},
)

The owned client preserves the public Python contract from composio-client==1.43.0 and adds the rest of the v3.1 API. You get all 113 operations, including the 64 operations published by Stainless and 49 additive operations generated from the checked-in OpenAPI document.

The September 2026 schema adds client.session_configs.list() and client.session_configs.retrieve(id), premium usage settings, workbench tool-execution controls, and trigger egress overrides. Generated public request and response types include new fields while retaining existing Stainless declarations.

Install the client

pip install composio-client

With uv:

uv add composio-client

Set COMPOSIO_API_KEY or pass api_key when you construct the client.

Use from_env when configuration must come from a specific mapping instead of os.environ:

client = Composio.from_env(config, environment="staging")

Explicit keyword arguments replace mapped values. The factory recognizes COMPOSIO_API_KEY, COMPOSIO_USER_API_KEY, COMPOSIO_ORG_API_KEY, COMPOSIO_BASE_URL, and COMPOSIO_CUSTOM_HEADERS. Clients created with with_options() keep using the resolved mapping and do not fall back to ambient values.

Identify the calling product

A product built on the client passes a ClientIdentity instead of setting headers by hand:

from composio_client import ClientIdentity, Composio

client = Composio(
    identity=ClientIdentity(product="composio", version="0.9.0", source="PYTHON_SDK", framework="openai"),
)

product and version are sent as x-client-provenance and x-client-version (version also as x-sdk-version); source, framework and runtime as x-source, x-framework and x-runtime. The library headers (x-client-library, x-client-library-version, x-client-language) are the package's own and are refused in default_headers, COMPOSIO_CUSTOM_HEADERS and request_options headers; once identity is set, so is every identity header. A refused name raises ComposioError. ClientIdentity is frozen and validates that every value is non-empty printable ASCII.

Use the async client

import asyncio

from composio_client import AsyncComposio


async def main() -> None:
    async with AsyncComposio(api_key="ak_...") as client:
        session = await client.tool_router.session.create(user_id="user@example.com")
        print(session.session_id)


asyncio.run(main())

Read raw response metadata

Every released resource keeps the Stainless raw and streaming accessors:

from composio_client import Composio

client = Composio(api_key="ak_...")

response = client.tool_router.session.with_raw_response.retrieve("sess_123")
print(response.status_code)
session = response.parse()

with client.tool_router.session.with_streaming_response.retrieve("sess_123") as response:
    print(response.headers)

The async resource exposes the corresponding async response objects and context managers.

Handle API errors

The exception hierarchy matches the Stainless package. Existing except blocks keep working:

from composio_client import Composio, NotFoundError

client = Composio(api_key="ak_...")

try:
    client.tool_router.session.retrieve("missing")
except NotFoundError as error:
    print(error.status_code)

Migrate pre-release owned-client calls

Earlier owned-client builds accepted aggregate body, query, and headers values. Those calls remain valid during the transition:

client.tool_router.session.create({"user_id": "user@example.com"})
client.tool_router.session.config_history("sess_123", query={"limit": 25})

Prefer the flat Stainless form in new code:

client.tool_router.session.create(user_id="user@example.com")
client.tool_router.session.config_history("sess_123", limit=25)

See the Python migration guide for compatibility details and the stricter credential transport rules.

Develop the Python package

Generate from the repository root:

pnpm generate:python
pnpm codegen:check

Run Python checks from python/:

uv run ruff check
uv run ruff format --check
uv run mypy src scripts
uv run pytest
uv run python scripts/check_stainless_compatibility.py
uv build
uv run python scripts/check_stainless_compatibility.py --wheel dist/*.whl

The normal compatibility check is offline. It reads the committed 1.43.0 fixture and does not install or call the Stainless client.