Composio Client

Main SDK client for initializing and configuring Composio

The Composio class is the main entry point for the Python SDK. It provides access to all SDK features including tools, toolkits, connected accounts, triggers, and more.

Initialization

Basic Usage

from composio import Composio
import os

# Initialize with API key from environment
composio = Composio(api_key=os.getenv("COMPOSIO_API_KEY"))

# Or let it auto-detect from COMPOSIO_API_KEY env var
composio = Composio()

With Provider

from composio import Composio
from composio_openai import OpenAIProvider
from composio_anthropic import AnthropicProvider

# Initialize with OpenAI provider
composio = Composio(provider=OpenAIProvider())

# Initialize with Anthropic provider
composio = Composio(provider=AnthropicProvider())

Constructor

provider · BaseProvider[TTool, TToolCollection] | None · default: "OpenAIProvider()"

The provider to use for tool wrapping. Defaults to OpenAI format. The generic types (TTool, TToolCollection) are automatically inferred from the provider.

api_key · str · required

Your Composio API key. Can be obtained from the Composio dashboard. If not provided, will read from COMPOSIO_API_KEY environment variable.

base_url · str · default: "https://api.composio.dev"

Custom API base URL for enterprise or development environments.

timeout · int · default: "60"

Request timeout in seconds.

max_retries · int · default: "3"

Maximum number of retries for failed requests.

allow_tracking · bool · default: "True"

Enable or disable telemetry tracking.

file_download_dir · str · default: "./downloads"

Directory path for downloading files from tool executions.

toolkit_versions · dict[str, str] | str | None · default: "None"

Specify toolkit versions to use:

• Dictionary mapping toolkit names to versions: {"github": "20250906_01"}
• String for same version across all toolkits: "20250906_01"
• None or "latest" for latest versions (default)

Can also be set via environment variables: COMPOSIO_TOOLKIT_VERSION_GITHUB=20250906_01

auto_upload_download_files · bool · default: "True"

Automatically handle file uploads and downloads in tool executions.

Complete Configuration Example

from composio import Composio
from composio_openai import OpenAIProvider

composio = Composio(
    api_key="your-api-key",
    base_url="https://api.composio.dev",
    timeout=90,
    max_retries=5,
    allow_tracking=True,
    file_download_dir="./my-downloads",
    provider=OpenAIProvider(),
    toolkit_versions={
        "github": "20250906_01",
        "slack": "latest"
    },
    auto_upload_download_files=True
)

Properties

The Composio client exposes the following properties for accessing SDK functionality:

tools

tools · Tools[TTool, TToolCollection]

Access to tool operations. See Tools API for details.

tools = composio.tools.get(user_id="default", toolkits=["github"])
result = composio.tools.execute("GITHUB_CREATE_ISSUE", {...})

toolkits

toolkits · Toolkits

Access to toolkit operations. See Toolkits API for details.

toolkit = composio.toolkits.get("github")
all_toolkits = composio.toolkits.list()

connected_accounts

connected_accounts · ConnectedAccounts

Manage third-party service connections. See Connected Accounts API for details.

connection = composio.connected_accounts.initiate(
    user_id="user_123",
    auth_config_id="ac_xxx"
)

auth_configs

auth_configs · AuthConfigs

Manage authentication configurations. See Auth Configs API for details.

config = composio.auth_configs.create("github", {...})

triggers

triggers · Triggers

Manage event triggers and webhooks. See Triggers API for details.

subscription = composio.triggers.subscribe()

@subscription.handle(trigger_slug="GITHUB_COMMIT_EVENT")
def on_commit(event):
    print(f"New commit: {event['payload']}")

mcp

mcp · MCP

Model Context Protocol operations. See MCP API for details.

server = composio.mcp.create(
    "my-server",
    toolkits=["github", "gmail"]
)

tool_router

tool_router · ToolRouter[TTool, TToolCollection]

Advanced tool routing with session management. See Tool Router API for details.

session = composio.tool_router.create(
    user_id="user_123",
    toolkits=["github"]
)

provider

provider · BaseProvider[TTool, TToolCollection]

The current provider instance used for tool wrapping.

# Access provider-specific functionality
result = composio.provider.handle_tool_calls(
    response=openai_response,
    user_id="default"
)

client

client · HttpClient

The underlying HTTP client for direct API access (advanced usage).

Generic Type System

The Composio class uses Python generics to provide type safety:

from composio import Composio
from composio_openai import OpenAIProvider
from composio_anthropic import AnthropicProvider

# With OpenAI provider
composio_openai: Composio[OpenAITool, list[OpenAITool]] = Composio(
    provider=OpenAIProvider()
)

# With Anthropic provider  
composio_anthropic: Composio[ToolParam, list[ToolParam]] = Composio(
    provider=AnthropicProvider()
)

# Default (OpenAI)
composio_default: Composio[OpenAITool, list[OpenAITool]] = Composio()

The generic parameters:

• TTool: Individual tool type (e.g., OpenAITool, ToolParam)
• TToolCollection: Collection type returned by get() (e.g., list[OpenAITool])

Shorthand Methods

The Composio client provides shorthand methods for common operations:

create

# Shorthand for tool_router.create()
session = composio.create(
    user_id="user_123",
    toolkits=["github"]
)

Equivalent to:

session = composio.tool_router.create(
    user_id="user_123",
    toolkits=["github"]
)

use

# Shorthand for tool_router.use()
session = composio.use(session_id="session_123")

Equivalent to:

session = composio.tool_router.use(session_id="session_123")

Environment Variables

The Composio SDK respects these environment variables:

# Required
COMPOSIO_API_KEY=your-api-key

# Optional
COMPOSIO_BASE_URL=https://api.composio.dev
COMPOSIO_LOGGING_LEVEL=info  # silent, error, warn, info, debug
DEVELOPMENT=false
CI=false

# Toolkit versions (per toolkit)
COMPOSIO_TOOLKIT_VERSION_GITHUB=20250906_01
COMPOSIO_TOOLKIT_VERSION_SLACK=latest

Error Handling

from composio import Composio
from composio.exceptions import (
    ApiKeyNotProvidedError,
    ComposioError,
    InvalidParams
)

try:
    composio = Composio()  # Will raise if no API key
except ApiKeyNotProvidedError:
    print("Please set COMPOSIO_API_KEY environment variable")
except ComposioError as e:
    print(f"Composio error: {e}")

Examples

Basic Tool Execution

from composio import Composio
import os

composio = Composio(api_key=os.getenv("COMPOSIO_API_KEY"))

# Get tools
tools = composio.tools.get(
    user_id="default",
    toolkits=["github"]
)

# Execute a tool
result = composio.tools.execute(
    slug="GITHUB_GET_REPO",
    arguments={"owner": "composiohq", "repo": "composio"},
    user_id="default"
)

print(result)

With Custom Provider

from composio import Composio
from composio_anthropic import AnthropicProvider
from anthropic import Anthropic

composio = Composio(provider=AnthropicProvider())
anthropic = Anthropic()

tools = composio.tools.get(
    user_id="default",
    toolkits=["github"]
)

response = anthropic.messages.create(
    model="claude-3-opus-20240229",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "Star the composio repo"}]
)

if response.stop_reason == "tool_use":
    result = composio.provider.handle_tool_calls(
        response=response,
        user_id="default"
    )

Next Steps

Tools

Learn about tool operations

Connected Accounts

Manage user authentication

Providers

Explore AI framework integrations

Tool Router

Advanced routing features