Composio Client

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[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

Access to toolkit operations. See Toolkits API for details.

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

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

AuthConfigs

Manage authentication configurations. See Auth Configs API for details.

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

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

Model Context Protocol operations. See MCP API for details.

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

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

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

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

Overview

Core API

Providers

Advanced

Initialization

Basic Usage

With Provider

Constructor

Complete Configuration Example

Properties

tools

toolkits

connected_accounts

auth_configs

triggers

mcp

tool_router

provider

client

Generic Type System

Shorthand Methods

create

use

Environment Variables

Error Handling

Examples

Basic Tool Execution

With Custom Provider

Next Steps

Tools

Connected Accounts

Providers

Tool Router

Build docs developers (and LLMs) love

Overview

Core API

Providers

Advanced

​Initialization

​Basic Usage

​With Provider

​Constructor

​Complete Configuration Example

​Properties

​tools

​toolkits

​connected_accounts

​auth_configs

​triggers

​mcp

​tool_router

​provider

​client

​Generic Type System

​Shorthand Methods

​create

​use

​Environment Variables

​Error Handling

​Examples

​Basic Tool Execution

​With Custom Provider

​Next Steps

Tools

Connected Accounts

Providers

Tool Router

Build docs developers (and LLMs) love

Initialization

Basic Usage

With Provider

Constructor

Complete Configuration Example

Properties

tools

toolkits

connected_accounts

auth_configs

triggers

mcp

tool_router

provider

client

Generic Type System

Shorthand Methods

create

use

Environment Variables

Error Handling

Examples

Basic Tool Execution

With Custom Provider

Next Steps