# Documentation


---

# Authenticating Tools (/docs/authenticating-tools)

The first step in authenticating your users is to create an **Auth Config**. Every toolkit has its own authentication method such as `OAuth`, `API key`, `Basic Auth`, or custom schemes.

An **Auth Config** is a blueprint that defines how authentication works for a toolkit across all your users. It defines:

1. **Authentication method** - `OAuth2`, `Bearer token`, `API key`, or `Basic Auth`
2. **Scopes** - what actions your tools can perform
3. **Credentials** - whether you'll use your own app credentials or Composio's managed auth

## Creating an auth config

### Using the Dashboard

### Step: Selecting a toolkit

Navigate to [Auth Configs](https://platform.composio.dev?next_page=%2Fauth-configs) tab in your dashboard and click "**Create Auth Config**". Find and select the toolkit you want to integrate (e.g., **Gmail**, **Slack**, **GitHub**).

### Step: Selecting the Authentication method

Each toolkit supports different authentication methods such as **OAuth**, **API Key**, **Bearer Token**. Select from the available options for your toolkit.

### Step: Configure scopes

Depending on your authentication method, you may need to configure scopes:
- **OAuth2**: Configure scopes for what data and actions your integration can access.
- **API Key/Bearer Token**: Permissions are typically fixed based on the key's access level.

### Step: Authentication Management

**For OAuth toolkits:**
- **Development/Testing**: Use Composio's managed authentication (no setup required)
- **Production**: Generate your own OAuth credentials from the toolkit's developer portal

**For custom authentication schemes:**

You must provide your own credentials regardless of environment.

> 
Want to remove Composio branding from OAuth screens? See [Custom Auth Configs](/docs/custom-auth-configs#white-labeling-the-oauth-consent-screen) for white-labeling options.

### Step: You are all set!

Click "**Create Auth Configuration**" button and you have completed your first step! Now you can move ahead to authenticating your users by [Connecting an Account](#connecting-an-account).

> **Auth configs are reusable**: 
Auth configs contain your developer credentials and app-level settings (*scopes*, *authentication method*, etc.). Once created, you can reuse the same auth config for all your users.

### When to create multiple auth configs?

You should create multiple auth configs for the same toolkit when you need:

- **Different authentication methods** - One OAuth config and one API key config
- **Different scopes** - Separate configs for read-only vs full access
- **Different OAuth apps** - Using separate client credentials for different environments
- **Different permission levels** - Limiting actions for specific use cases

- [Programmatic creation](/docs/programmatic-auth-configs): 
    For managing auth configs across multiple projects, you can create them programmatically via the API
  
  - [Production white-labeling](/docs/custom-auth-configs#white-labeling-the-oauth-consent-screen): 
    Remove Composio branding from OAuth screens for a fully white-labeled authentication experience
  

## Connecting an account

With an auth config created, you're ready to authenticate your users!

You can either use [**Connect Link**](#hosted-authentication-connect-link) for a hosted authentication flow, or use [**Direct SDK Integration**](#direct-sdk-integration).

> 
User authentication requires a User ID - a unique identifier that groups connected accounts together. Learn more about [User Management](/docs/user-management) to understand how to structure User IDs for your application.

**Choose the section below that matches your toolkit's authentication method:**

### Hosted Authentication (Connect Link)

Redirect users to a Composio-hosted URL that handles the entire authentication process—OAuth flows, API key collection, or custom fields like subdomain. You can specify a callback URL to control where users return after authentication.

**Python:**

```python
from composio import Composio

composio = Composio(api_key="your_api_key")

# Use the "AUTH CONFIG ID" from your dashboard
auth_config_id = "your_auth_config_id"

# Use a unique identifier for each user in your application
user_id = 'user-1349-129-12'

connection_request = composio.connected_accounts.link(
    user_id=user_id,
    auth_config_id=auth_config_id,
    callback_url='https://your-app.com/callback'
)

redirect_url = connection_request.redirect_url
print(f"Visit: {redirect_url} to authenticate your account")
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';

const composio = new Composio({apiKey: "your_api_key"});

// Use the "AUTH CONFIG ID" from your dashboard
const authConfigId = 'your_auth_config_id';

// Use a unique identifier for each user in your application
const userId = 'user-1349-129-12';

const connectionRequest = await composio.connectedAccounts.link(userId, authConfigId, {
  callbackUrl: 'https://your-app.com/callback'
});
const redirectUrl = connectionRequest.redirectUrl;
console.log(`Visit: ${redirectUrl} to authenticate your account`);
```
  

#### Customizing Connect Link

By default, users will see a Composio-branded authentication experience when connecting their accounts. To customize this interface with your application's branding:

1. Navigate to your Project Settings and select [Auth Screen](https://platform.composio.dev?next_page=/settings/auth-screen)
2. Configure your **Logo** and **App Title**

These settings will apply to all authentication flows using Connect Link, providing a white-labeled experience that maintains your brand identity throughout the authentication process.

> 
For complete white-labeling including OAuth consent screens (removing Composio's domain), see [Custom Auth Configs - White-labeling](/docs/custom-auth-configs#white-labeling-the-oauth-consent-screen).

### Direct SDK Integration

**Choose the section below that matches your toolkit's authentication method:**

#### OAuth Connections

For OAuth flows, you'll redirect users to complete authorization. You can specify a callback URL to control where users return after authentication:

**Python:**

```python
from composio import Composio

composio = Composio(api_key="YOUR_COMPOSIO_API_KEY")

# Use the "AUTH CONFIG ID" from your dashboard
auth_config_id = "your_auth_config_id"

# Use a unique identifier for each user in your application
user_id = "user-1349-129-12"

connection_request = composio.connected_accounts.initiate(
  user_id=user_id,
  auth_config_id=auth_config_id,
  config={"auth_scheme": "OAUTH2"},
  callback_url="https://www.yourapp.com/callback"
)
print(f"Redirect URL: {connection_request.redirect_url}")

connected_account = connection_request.wait_for_connection()

# Alternative: if you only have the connection request ID
# connected_account = composio.connected_accounts.wait_for_connection(
#  connection_request.id)
# Recommended when the connection_request object is no longer available

print(f"Connection established: {connected_account.id}")
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';

const composio = new Composio({apiKey: "YOUR_COMPOSIO_API_KEY"});

// Use the "AUTH CONFIG ID" from your dashboard
const authConfigId = 'your_auth_config_id';
// Use a unique identifier for each user in your application
const userId = 'user_4567';

const connRequest = await composio.connectedAccounts.initiate(
  userId,
  authConfigId,

    callbackUrl: 'https://www.yourapp.com/callback',

);
console.log(`Redirect URL: ${connRequest.redirectUrl}`);

const connectedAccount = await connRequest.waitForConnection();

// Alternative: if you only have the connection request ID
// const connectedAccount = await composio.connectedAccounts
//   .waitForConnection(connRequest.id);
// Recommended when the connRequest object is no longer available

console.log(`Connection established: ${connectedAccount.id}`);
```
  

#### Services with Additional Parameters

Some services like Zendesk require additional parameters such as `subdomain`:

**Python:**

```python
# For Zendesk - include subdomain
connection_request = composio.connected_accounts.initiate(
  user_id=user_id,
  auth_config_id=auth_config_id,
  config=auth_scheme.oauth2(subdomain="mycompany")  # For mycompany.zendesk.com
)
```
  
  
**TypeScript:**

```typescript
import { Composio, AuthScheme } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const userId = 'user_123';
const authConfigId = 'ac_zendesk';
// ---cut---
// For Zendesk - include subdomain
const connRequest = await composio.connectedAccounts.initiate(userId, authConfigId, {
  config: AuthScheme.OAuth2({
    subdomain: 'mycompany',
  }),
});
```
  

#### API Key Connections

For API key authentication, you can either collect API keys from each user or use your own API key for all users. Popular toolkits that use API keys include Stripe, Perplexity, etc.

Here is how to initiate the flow:

**Python:**

```python
from composio import Composio

composio = Composio(api_key="your_api_key")

# Use the "AUTH CONFIG ID" from your dashboard
auth_config_id = "your_auth_config_id"

# Use a unique identifier for each user in your application
user_id = "user_12323"

# API key provided by the user (collected from your app's UI)
# or use your own key
user_api_key = "user_api_key_here"

connection_request = composio.connected_accounts.initiate(
  user_id=user_id,
  auth_config_id=auth_config_id,
  config={
    "auth_scheme": "API_KEY", "val": {"api_key": user_api_key}

)

print(f"Connection established: {connection_request.id}")
```
  
  
**TypeScript:**

```typescript
import { Composio, AuthScheme } from '@composio/core';

const composio = new Composio({ apiKey: 'your_api_key' });

// Use the "AUTH CONFIG ID" from your dashboard
const authConfigId = 'your_auth_config_id';
// Use a unique identifier for each user in your application
const userId = 'user12345678';
// API key provided by the user (collected from your app's UI)
const userApiKey = 'user_api_key_here';

const connectionRequest = await composio.connectedAccounts.initiate(userId, authConfigId, {
  config: AuthScheme.APIKey({
    api_key: userApiKey,
  }),
});

console.log(`Connection established: ${connectionRequest.id}`);
```
  

## Fetching the required config parameters for an Auth Config

When working with any toolkit, you can inspect an auth config to understand its authentication requirements and expected parameters.

Here is how you would fetch the authentication method and input fields:

**Python:**

```python
from composio import Composio

composio = Composio(api_key="your_api_key")

# Use the "AUTH CONFIG ID" from your dashboard
auth_config_id = "your_auth_config_id"

# Fetch the auth configuration details
auth_config = composio.auth_configs.get(auth_config_id)

# Check what authentication method this config uses
print(f"Authentication method: {auth_config.auth_scheme}")

# See what input fields are required
print(f"Required fields: {auth_config.expected_input_fields}")
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';

const composio = new Composio({ apiKey: 'your_api_key' });

// Use the "AUTH CONFIG ID" from your dashboard
const authConfigId = 'your_auth_config_id';

// Fetch the auth configuration details
const authConfig = await composio.authConfigs.get(authConfigId);

console.log(`Authentication method: ${authConfig.authScheme}`);
console.log(`Required fields:`, authConfig.expectedInputFields);
```
  

## Other Authentication Methods

Composio also supports a wide range of other auth schemas:

**Bearer Token** - Similar to API keys, provide the user's bearer token directly when creating the connection.

**Basic Auth** - Provide username and password credentials for services that use HTTP Basic Authentication.

**Custom Schemes** - Some toolkits use their own custom authentication methods. Follow the toolkit-specific requirements for such cases.

> **Fetching auth config**: 
For any of these methods, [fetch the config parameter](#fetching-the-required-config-parameters-for-an-auth-config) to determine the exact fields required. Every toolkit has its own requirements, and understanding these is essential for successfully creating connections.

Learn how to [Manage connected accounts](/docs/connected-accounts) after users authenticate.

## Connection Statuses

After creating a connection, it will have one of the following statuses that indicates its current state:

| Status | Description |
|--------|-------------|
| **ACTIVE** | Connection is established and working. You can execute tools with this connection. |
| **INACTIVE** | Connection is temporarily disabled. Re-enable it to use the connection again. |
| **PENDING** | Connection is being processed. Wait for it to become active. |
| **INITIATED** | Connection request has started but not yet completed. User may still need to complete authentication. |
| **EXPIRED** | Connection credentials have expired. Composio automatically attempts to refresh credentials before marking as expired. Re-authenticate to restore access. |
| **FAILED** | Connection attempt failed. Check error details and try creating a new connection. |

> 
When credentials expire for OAuth connections, Composio automatically attempts to refresh them using the refresh token. The connection is only marked as **EXPIRED** after multiple refresh attempts have failed.

### Waiting for Connection Establishment

The `waitForConnection` method allows you to poll for a connection to become active after initiating authentication. This is useful when you need to ensure a connection is ready before proceeding.

**Python:**

```python
# Wait for the connection to be established
connected_account = connection_request.wait_for_connection()
print(connected_account.id)

# Alternative: Wait with custom timeout
# connected_account = connection_request.wait_for_connection(120)  # 2 minute timeout

# Alternative: If you only have the connection request ID (e.g., stored in database)
# connection_id = connection_request.id  # You can store this ID in your database
# connected_account = composio.connected_accounts.wait_for_connection(connection_id, 60)
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const connectionRequest = await composio.connectedAccounts.initiate('user_123', 'ac_123', {});
// ---cut---
// Wait for the connection to be established
const connectedAccount = await connectionRequest.waitForConnection();
console.log(connectedAccount.id);

// Alternative: Wait with custom timeout
// const connectedAccount = await connectionRequest.waitForConnection(120000);  // 2 minutes

// Alternative: If you only have the connection request ID (e.g., stored in database)
// const connectionId = connectionRequest.id;  // You can store this ID in your database
// const connectedAccount = await composio.connectedAccounts.waitForConnection(connectionId, 60000);
```
  

The method continuously polls the Composio API until the connection:
- Becomes **ACTIVE** (returns the connected account)
- Enters a terminal state like **FAILED** or **EXPIRED** (throws an error)
- Exceeds the specified timeout (throws a timeout error)

### Checking Connection Status

You can check the status of a connected account programmatically:

**Python:**

```python
# Get a specific connected account
connected_account = composio.connected_accounts.get("your_connected_account_id")
print(f"Status: {connected_account.status}")

# Filter connections by user_id, auth_config_id, and status (only active accounts)
filtered_connections = composio.connected_accounts.list(
    user_ids=["user_123"],
    auth_config_ids=["your_auth_config_id"],
    statuses=["ACTIVE"]
)
for connection in filtered_connections.items:
    print(f"{connection.id}: {connection.status}")
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
// Get a specific connected account by its nanoid
const connectedAccount = await composio.connectedAccounts.get('your_connected_account_id');
console.log(`Status: ${connectedAccount.status}`);

// Filter connections by user_id, auth_config_id, and status (only active accounts)
const filteredConnections = await composio.connectedAccounts.list({
  userIds: ['user_123'],
  authConfigIds: ['your_auth_config_id'],
  statuses: ['ACTIVE']
});
filteredConnections.items.forEach(connection => {
  console.log(`${connection.id}: ${connection.status}`);
});
```
  

> 
Only connections with **ACTIVE** status can be used to execute tools. If a connection is in any other state, you'll need to take appropriate action (re-authenticate, wait for processing, etc.) before using it.

## Next Step

With authentication set up, you can now fetch and execute tools. See [Executing Tools](/docs/executing-tools) to get started.

---

# Capabilities (/docs/capabilities)

title="Tool Router"
    description="Search, authenticate, and execute across all tools from one interface. Built-in Workbench and CodeAct solves context window limitations!"
    href="/tool-router/overview"
  />

    title="Managed Authentication"
    description="OAuth, API keys, token refresh—handled automatically."
    href="/docs/authenticating-tools"
  />

    title="Tools"
    description="10,000+ actions across 250+ apps. GitHub, Slack, Gmail, and more."
    href="/docs/fetching-tools"
  />

    title="MCP"
    description="Works with Claude Desktop, Cursor, and any MCP-compatible client."
    href="/docs/mcp-quickstart"
  />

    title="Triggers"
    description="React to events in real-time. Webhooks, new emails, GitHub events."
    href="/docs/using-triggers"
  />

---

# CLI (/docs/cli)

The Composio CLI helps you generate type-safe code and manage your Composio workspace.

## Installation

Install the Composio CLI using the installation script:

```bash
curl -fsSL https://composio.dev/install | bash
```

Or using wget:
```bash
wget -qO- https://composio.dev/install | bash
```

## Authentication

Manage your Composio authentication directly from the terminal.

### Login

Authenticate with your Composio account:

```bash
composio login
```

This opens your browser to complete authentication and stores your API key locally.

To authenticate without opening a browser (useful for SSH/remote sessions):

```bash
composio login --no-browser
```

This displays a URL to manually open in your browser.

### Check authentication status

Verify your current authentication:

```bash
composio whoami
```

This displays your current API key or indicates if you're not authenticated.

### Logout

Remove stored authentication:

```bash
composio logout
```

## Generate type definitions

Generate TypeScript or Python type definitions for all Composio tools. These types provide type safety when using direct tool execution (`composio.tools.execute()`), helping you pass the correct parameters and catch errors early.

### Auto-detect and generate

The CLI auto-detects your project language.
In your project directory:

```bash
composio generate
```

For TypeScript projects only, include individual tool types:
```bash
composio generate --type-tools
```

The CLI automatically:
- Detects your project type (Python or TypeScript)
- Generates appropriate type definitions

### Specify output directory

```bash
composio generate --output-dir ./my-types
```

### Language-specific commands

For explicit control, use language-specific commands:

**TypeScript:**

    Basic generation:
    ```bash
    composio ts generate
    ```

    Generate as single file:
    ```bash
    composio ts generate --compact
    ```

    Include individual tool types:
    ```bash
    composio ts generate --type-tools
    ```

    Generate both .ts and .js files:
    ```bash
    composio ts generate --transpiled
    ```

    Custom output directory:
    ```bash
    composio ts generate --output-dir ./my-types
    ```
  
  
**Python:**

    Basic generation:
    ```bash
    composio py generate
    ```

    Custom output directory:
    ```bash
    composio py generate --output-dir ./my_types
    ```

---

# Connected Accounts (/docs/connected-accounts)

Connected accounts are authenticated connections between your users and toolkits. After users authenticate (see [Authenticating tools](/docs/authenticating-tools)), you can manage these accounts throughout their lifecycle.

Composio automatically handles token refresh and credential management. This guide covers manual operations: listing, retrieving, refreshing, enabling, disabling, and deleting accounts.

## List accounts

Retrieve all connected accounts with optional filters:

**Python:**

```python
# List all accounts for a user
accounts = composio.connected_accounts.list(
    user_ids=[user_id]
)

# Filter by status
active_accounts = composio.connected_accounts.list(
    user_ids=[user_id],
    statuses=["ACTIVE"]
)
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const userId = 'user_123';
// ---cut---
// List all accounts for a user
const accounts = await composio.connectedAccounts.list({
  userIds: [userId]
});

// Filter by status
const activeAccounts = await composio.connectedAccounts.list({
  userIds: [userId],
  statuses: ['ACTIVE']
});
```
  

## Get account details

Retrieve a connected account by ID:

**Python:**

```python
account = composio.connected_accounts.get(connected_account_id)

print(f"Status: {account.status}")
print(f"Toolkit: {account.toolkit.slug}")
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const connectedAccountId = 'ca_123';
// ---cut---
const account = await composio.connectedAccounts.get(connectedAccountId);

console.log('Status:', account.status);
console.log('Toolkit:', account.toolkit.slug);
```
  

### Get account credentials

Get account credentials for use with your own tools:

**Python:**

```python
# Get the connected account's authentication state
if account.state:
    # The state contains the auth scheme and credentials
    auth_scheme = account.state.auth_scheme
    credentials = account.state.val

    print(f"Auth scheme: {auth_scheme}")
    print(f"Credentials: {credentials}")
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const account = await composio.connectedAccounts.get('ca_123');
// ---cut---
// Get the connected account's authentication state
if (account.state) {
  // The state contains the auth scheme and credentials
  const authScheme = account.state.authScheme;
  const credentials = account.state.val;

  console.log('Auth scheme:', authScheme);
  console.log('Credentials:', credentials);

```
  

> 
If credentials return as `REDACTED` instead of actual values, the **Mask Connected Account Secrets** setting is enabled on your account. This setting redacts all sensitive credential data (tokens, secrets, API keys) for security purposes.

To view actual credentials, navigate to **Settings → Project Settings → Project Configuration** and disable "Mask Connected Account Secrets".

## Refresh credentials

Manually refresh credentials for a connected account:

**Python:**

```python
try:
    refreshed = composio.connected_accounts.refresh(connected_account_id)
    print(f"Redirect URL: {refreshed.redirect_url}")

    # Wait for the connection to be established
    composio.connected_accounts.wait_for_connection(refreshed.id)
except Exception as e:
    print(f"Failed to refresh tokens: {e}")
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const connectedAccountId = 'ca_123';
// ---cut---
try {
  const refreshed = await composio.connectedAccounts.refresh(connectedAccountId);
  console.log('Redirect URL:', refreshed.redirect_url);

  // Wait for the connection to be established
  await composio.connectedAccounts.waitForConnection(refreshed.id);
} catch (error) {
  console.error('Failed to refresh tokens:', error);

```
  

## Enable and disable accounts

Change account status without deleting. Set to INACTIVE to pause access, or ACTIVE to restore. Useful for:
- Pausing access during subscription lapses
- Temporary disconnection

**Python:**

```python
# Disable an account
disabled = composio.connected_accounts.disable(connected_account_id)
print(f"Account disabled status: {disabled.success}")

# Re-enable when needed
enabled = composio.connected_accounts.enable(connected_account_id)
print(f"Account enabled status: {enabled.success}")
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const connectedAccountId = 'ca_123';
// ---cut---
// Disable an account
const disabled = await composio.connectedAccounts.disable(connectedAccountId);
console.log('Account disabled status:', disabled.success);

// Re-enable when needed
const enabled = await composio.connectedAccounts.enable(connectedAccountId);
console.log('Account enabled status:', enabled.success);
```
  

> 
INACTIVE accounts cannot execute tools. Tool execution will fail until the status is changed.

## Delete accounts

Permanently remove a connected account and revoke all credentials:

**Python:**

```python
# Delete a connected account
composio.connected_accounts.delete(connected_account_id)
print("Account deleted successfully")
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const connectedAccountId = 'ca_123';
// ---cut---
// Delete a connected account
await composio.connectedAccounts.delete(connectedAccountId);
console.log('Account deleted successfully');
```
  

> 
Deletion is permanent. Users must re-authenticate to reconnect.

## Multiple accounts

Users can connect multiple accounts for the same toolkit (e.g., personal and work Gmail).

> 
Use `link()` for creating accounts, as it provides hosted authentication and allows multiple accounts by default. See [Connect Link authentication](/docs/authenticating-tools#hosted-authentication-connect-link).

**Python:**

```python
# First account
try:
    first_account = composio.connected_accounts.initiate(
        user_id=user_id,
        auth_config_id=auth_config_id
    )
    print(f"First account redirect URL: {first_account.redirect_url}")
    connected_first_account = first_account.wait_for_connection()
    print(f"First account status: {connected_first_account.status}")
except Exception as e:
    print(f"Error initiating first account: {e}")

# Second account - must explicitly allow multiple
try:
    second_account = composio.connected_accounts.initiate(
        user_id=user_id,
        auth_config_id=auth_config_id,
        allow_multiple=True  # Required for additional accounts
    )
    print(f"Second account redirect URL: {second_account.redirect_url}")
    connected_second_account = second_account.wait_for_connection()
    print(f"Second account status: {connected_second_account.status}")
except Exception as e:
    print(f"Error initiating second account: {e}")
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const userId = 'user_123';
const authConfigId = 'ac_123';
// ---cut---
// First account
try {
  const firstAccount = await composio.connectedAccounts.initiate(
    userId,
    authConfigId
  );
  console.log('First account redirect URL:', firstAccount.redirectUrl);
  const connectedFirstAccount = await firstAccount.waitForConnection();
  console.log('First account status:', connectedFirstAccount.status);
} catch (error) {
  console.error('Error initiating first account:', error);

// Second account - must explicitly allow multiple
try {
  const secondAccount = await composio.connectedAccounts.initiate(
    userId,
    authConfigId,

      allowMultiple: true  // Required for additional accounts

  );
  console.log('Second account redirect URL:', secondAccount.redirectUrl);
  const connectedSecondAccount = await secondAccount.waitForConnection();
  console.log('Second account status:', connectedSecondAccount.status);
} catch (error) {
  console.error('Error initiating second account:', error);

```
  

### Execute with a specific account

When you have multiple accounts, specify which one to use with `connected_account_id`:

**Python:**

```python
# Execute tool with a specific connected account
result = composio.tools.execute(
    "GMAIL_GET_PROFILE",
    user_id=user_id,
    connected_account_id=connected_account_id,  # Specify which account to use
    version="20251111_00",
    arguments={}
)
print(f"Tool executed: {result}")
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const userId = 'user_123';
const connectedAccountId = 'ca_123';
// ---cut---
// Execute tool with a specific connected account
const result = await composio.tools.execute('GMAIL_GET_PROFILE', {
  userId: userId,
  connectedAccountId: connectedAccountId,  // Specify which account to use
  version: '20251111_00',
  arguments: {}
});
console.log('Tool executed:', result);
```

---

# Custom Auth Configs (/docs/custom-auth-configs)

Many toolkits support a level of customization for the auth config, specifically OAuth applications.

This guide will walk you through the process of customizing the auth config for toolkits where you can configure your own developer app.

## Creating a custom auth config

To create a custom auth config, click **Create Auth Config** in your dashboard, then navigate to **Authentication management** → **Manage authentication with custom credentials**.

You'll need to customize the auth config when you want to use different values than the defaults - such as your own subdomain, base URL, client ID, client secret, etc.

**Example: PostHog:**

You may change the subdomain for the PostHog toolkit to match your own instance.

  
  
**Example: Hubspot:**

For Hubspot you may customize everything here. For each auth scheme there is a different set of fields.

If you choose to use your own developer app for the OAuth2 scheme, you will have to provide the client ID and client secret.

  

Toolkits that support OAuth2 allow using your own developer app. This is the recommended approach for most cases.

> **Use your own developer app!**: 
We recommend using your own developer app for the OAuth2 scheme as it is more suited for production usage with many users and more granular control over scopes.

However, getting OAuth approvals takes time, so Composio provides a default developer app!

## OAuth2 Auth Configs

### Step: Generate the OAuth Client ID and Client Secret

To set up a custom OAuth config, you'll need the OAuth Client ID and Client Secret.

You can generate the client ID and client secret from your provider's OAuth configuration page.

Examples for Google and GitHub:

**Google:**

  
  
**GitHub:**

  

### Step: Set the Authorized Redirect URI

When creating your OAuth app, make sure to configure the Authorized Redirect URI to point to the Composio callback URL below:

```
https://backend.composio.dev/api/v3/toolkits/auth/callback
```

### Step: Create the auth config

Once you have the OAuth credentials, you can add them to the auth config in the dashboard.

1. Select the OAuth2 scheme.
2. Select the scopes to request from users. Default scopes are pre-filled for most apps.
3. Add the OAuth client ID and client secret for your developer app. Keep the redirect URL as is for now!
4. Click Create!

This auth config is now ready to be used in your application!

**Python:**

```python
# Create a new connected account
connection_request = composio.connected_accounts.initiate(
    user_id="user_id",
    auth_config_id="ac_1234",
)
print(connection_request)

# Wait for the connection to be established
connected_account = connection_request.wait_for_connection()
print(connected_account)
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const userId = 'user_123';
// ---cut---
const connReq = await composio.connectedAccounts.initiate(userId, "ac_1234");

console.log(connReq.redirectUrl);

const connection = await composio.connectedAccounts.waitForConnection(
  connReq.id
);

console.log(connection);
```
  

### White-labeling the OAuth Consent Screen

By default the users will see an OAuth screen like the one below:

The OAuth redirect URL is surfaced in some OAuth providers' consent screens. This may cause confusion for some users as that URL is not of the same domain as the application.

To remediate this:

### Step: Set the Authorized Redirect URI

Specify the Authorized Redirect URI to your own domain in the OAuth configuration.
For example:
```
https://yourdomain.com/api/composio-redirect
```

### Step: Create a redirect logic

Create a redirect logic, either through your DNS or in your application to redirect that endpoint to `https://backend.composio.dev/api/v3/toolkits/auth/callback`

**Example: API Route for OAuth Redirect**

**Python:**

```python
from fastapi import FastAPI
from fastapi.responses import RedirectResponse

from composio import Composio

# Create a FastAPI app
app = FastAPI()

# Create a Composio client
composio = Composio()

@app.get("/authorize/{toolkit}")
def authorize_app(toolkit: str):
    # retrieve the user id from your app
    user_id = "<user_id>"

    # retrieve the auth config id from your app
    auth_config_id = "<auth_config_id>"

    # initiate the connection request
    connection_request = composio.connected_accounts.initiate(
        user_id=user_id,
        auth_config_id=auth_config_id,
    )
    return RedirectResponse(url=connection_request.redirect_url)
```
  
  
**TypeScript:**

```typescript
import type { NextApiRequest, NextApiResponse } from 'next';

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  // The target Composio endpoint that handles OAuth callbacks
  const composioEndpoint = 'https://backend.composio.dev/api/v3/toolkits/auth/callback';

  // Extract and preserve all query parameters
  const queryParams = new URLSearchParams();
  Object.entries(req.query).forEach(([key, value]) => {
    if (typeof value === 'string') {
      queryParams.append(key, value);

  });

  // Redirect to Composio with all query parameters intact
  const redirectUrl = `${composioEndpoint}?${queryParams.toString()}`;
  res.redirect(302, redirectUrl);

```
  

### Step: Create the auth config

Specify your custom redirect URI in the auth config settings!

With this setup, you can use `https://yourdomain.com/api/composio-redirect` as your OAuth redirect URI, which will create a better user experience by keeping users on your domain during the OAuth flow.

backend.composio.dev]
    C -->|Custom Domain| E[Provider redirects to<br/>yourdomain.com/api/composio-redirect]

    E --> F[Your endpoint forwards to<br/>backend.composio.dev]

    D --> G[Composio exchanges code for token]
    F --> G

    G --> H[Connection established]

    style E fill:#e1f5fe
    style F fill:#e1f5fe
    style C fill:#fff3e0
```

**Key Benefits:**

- **Custom Domain**: Users see your domain in OAuth consent screens, not Composio's
- **Same Security**: Your domain just forwards the OAuth callback - no token handling
- **Better UX**: Maintains brand consistency throughout the auth flow

The custom redirect endpoint is a simple passthrough that preserves all OAuth parameters while keeping users on your domain.

---

# Custom Auth Parameters (/docs/custom-auth-params)

In cases where Composio is not being used for managing the auth but only for the tools, it is possible to use the `beforeExecute` hook to inject custom auth headers or parameters for a toolkit.

## Setup and Initialization

First, initialize the Composio SDK with your API key:

**Python:**

```python
from composio import Composio

composio = Composio()
```
  
  
**TypeScript:**

```typescript
import { Composio } from "@composio/core";

const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
});
```
  

## Creating the Auth Modifier Function

Define a function that modifies authentication parameters for specific toolkits. This function checks the toolkit name and adds custom authentication headers when needed.

- [This is a Before Execute Modifier!](/docs/modify-tool-behavior/before-execution-modifiers): 
Before Execute Modifiers are a way to modify the parameters of a tool before it is executed. In this case, they are useful for adding custom authentication headers or parameters to a tool.

**Python:**

```python
from composio import before_execute
from composio.types import ToolExecuteParams

@before_execute(toolkits=["NOTION"])
def add_custom_auth(
    tool: str,
    toolkit: str,
    params: ToolExecuteParams,
) -> ToolExecuteParams:
    if params["custom_auth_params"] is None:
        params["custom_auth_params"] = {"parameters": []}

    params["custom_auth_params"]["parameters"].append(

            "name": "x-api-key",
            "value": os.getenv("NOTION_API_KEY"),
            "in": "header",

    )
    return params
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const authModifier = ({ toolSlug, toolkitSlug, params }: { toolSlug: string; toolkitSlug: string; params: any }) => {
  // Add authentication parameters for specific toolkits
  if (toolkitSlug === "NOTION") {
    if (!params.customAuthParams) {
      params.customAuthParams = {};

    if (!params.customAuthParams.parameters) {
      params.customAuthParams.parameters = [];

    // Add an API key to the headers
    params.customAuthParams.parameters.push({
      in: "header",
      name: "X-API-Key",
      value: process.env.CUSTOM_API_KEY,
    });

  return params;
};
```
  

## Executing Tools with Custom Auth

Execute the tool using the custom authentication modifier. The `beforeExecute` hook allows you to modify parameters before the tool runs.

Following is an example of how to execute a tool with a custom authentication modifier for Completion Providers.

For Agentic Providers, read about [Modifying tool inputs](/docs/modify-tool-behavior/before-execution-modifiers).

**Python:**

```python
result = composio.tools.execute(
    slug="NOTION_GET_DATABASE_ITEMS",
    user_id="default",
    arguments={},
    modifiers=[
        add_custom_auth,
    ],
)
print(result)
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const authModifier = ({ toolSlug, toolkitSlug, params }: { toolSlug: string; toolkitSlug: string; params: any }) => {
  if (toolkitSlug === 'NOTION' && !params.customAuthParams) {
    params.customAuthParams = { parameters: [{ in: 'header', name: 'X-API-Key', value: 'key' }] };

  return params;
};
// ---cut---
const result = await composio.tools.execute(
  "NOTION_GET_DATABASE_ITEMS",

    userId: "sid",
    arguments: {
      database_id: "1234567890",
    },
  },

    beforeExecute: authModifier,

);

console.log(JSON.stringify(result, null, 2));
```

---

# Creating Custom Tools (/docs/custom-tools)

Custom tools allow you to create your own tools that can be used with Composio.

1. **Standalone tools** - Simple tools that don't require any authentication
2. **Toolkit-based tools** - Tools that require authentication and can use toolkit credentials

## Creating a Custom Tool

### Standalone Tool

A standalone tool is the simplest form of custom tool. It only requires input parameters and an execute function:

**Python:**

```python
from pydantic import BaseModel, Field

from composio import Composio
from composio.types import ExecuteRequestFn

composio = Composio()

class AddTwoNumbersInput(BaseModel):
    a: int = Field(
        ...,
        description="The first number to add",
    )
    b: int = Field(
        ...,
        description="The second number to add",
    )

# function name will be used as slug
@composio.tools.custom_tool
def add_two_numbers(request: AddTwoNumbersInput) -> int:
    """Add two numbers."""
    return request.a + request.b
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
import { z } from 'zod/v3';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const tool = await composio.tools.createCustomTool({
  slug: 'CALCULATE_SQUARE',
  name: 'Calculate Square',
  description: 'Calculates the square of a number',
  inputParams: z.object({
    number: z.number().describe('The number to calculate the square of'),
  }),
  execute: async input => {
    const { number } = input;
    return {
      data: { result: number * number },
      error: null,
      successful: true,
    };
  },
});
```
  

### Toolkit-based Tool

A toolkit-based tool has access to two ways of making authenticated requests:

**1. Using `executeToolRequest`** - The recommended way to make authenticated requests to the toolkit's API endpoints. Composio automatically handles credential injection and baseURL resolution:

**Python:**

```python
class GetIssueInfoInput(BaseModel):
    issue_number: int = Field(
        ...,
        description="The number of the issue to get information about",
    )

# function name will be used as slug
@composio.tools.custom_tool(toolkit="github")
def get_issue_info(
    request: GetIssueInfoInput,
    execute_request: ExecuteRequestFn,
    auth_credentials: dict,
) -> dict:
    """Get information about a GitHub issue."""
    response = execute_request(
        endpoint=f"/repos/composiohq/composio/issues/{request.issue_number}",
        method="GET",
        parameters=[

                "name": "Accept",
                "value": "application/vnd.github.v3+json",
                "type": "header",
            },

                "name": "Authorization",
                "value": f"Bearer {auth_credentials['access_token']}",
                "type": "header",
            },
        ],
    )
    return {"data": response.data}
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
import { z } from 'zod/v3';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const tool = await composio.tools.createCustomTool({
  slug: 'GITHUB_STAR_COMPOSIOHQ_REPOSITORY',
  name: 'Github star composio repositories',
  toolkitSlug: 'github',
  description: 'Star any specified repo of `composiohq` user',
  inputParams: z.object({
    repository: z.string().describe('The repository to star'),
    page: z.number().optional().describe('Pagination page number'),
    customHeader: z.string().optional().describe('Custom header'),
  }),
  execute: async (input, connectionConfig, executeToolRequest) => {
    // This method makes authenticated requests to the relevant API
    // You can use relative paths!
    // Composio will automatically inject the baseURL
    const result = await executeToolRequest({
      endpoint: `/user/starred/composiohq/${input.repository}`,
      method: 'PUT',
      body: {},
      // Add custom headers or query parameters
      parameters: [
        // Add query parameters

          name: 'page',
          value: input.page?.toString() || '1',
          in: 'query',
        },
        // Add custom headers

          name: 'x-custom-header',
          value: input.customHeader || 'default-value',
          in: 'header',
        },
      ],
    });
    return result;
  },
});
```
  

**2. Using `connectionConfig`** - For making direct API calls when needed:

**Python:**

```python
import requests

@composio.tools.custom_tool(toolkit="github")
def get_issue_info_direct(
    request: GetIssueInfoInput,
    execute_request: ExecuteRequestFn,
    auth_credentials: dict,
) -> dict:
    """Get information about a GitHub issue."""
    response = requests.get(
        f"https://api.github.com/repos/composiohq/composio/issues/{request.issue_number}",
        headers={
            "Accept": "application/vnd.github.v3+json",
            "Authorization": f"Bearer {auth_credentials['access_token']}",
        },
    )
    return {"data": response.json()}
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
import { z } from 'zod/v3';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const tool = await composio.tools.createCustomTool({
  slug: 'GITHUB_DIRECT_API',
  name: 'Direct GitHub API Call',
  description: 'Makes direct calls to GitHub API',
  toolkitSlug: 'github',
  inputParams: z.object({
    repo: z.string().describe('Repository name'),
  }),
  execute: async (input, connectionConfig, executeToolRequest) => {
    // Use connectionConfig for direct API calls
    if (!connectionConfig || connectionConfig.authScheme !== 'OAUTH2') {
      throw new Error('OAuth2 connection required');

    const result = await fetch(`https://api.github.com/repos/${input.repo}`, {
      headers: {
        Authorization: `Bearer ${connectionConfig.val.access_token}`,
      },
    });

    return {
      data: await result.json(),
      error: null,
      successful: true,
    };
  },
});
```
  

### Using Custom Headers and Query Parameters

You can add custom headers and query parameters to your toolkit-based tools using the `parameters` option in `executeToolRequest`:

**Python:**

```python
@composio.tools.custom_tool(toolkit="github")
def get_issue_info(
    request: GetIssueInfoInput,
    execute_request: ExecuteRequestFn,
    auth_credentials: dict,
) -> dict:
    """Get information about a GitHub issue."""
    response = execute_request(
        endpoint=f"/repos/composiohq/composio/issues/{request.issue_number}",
        method="GET",
        parameters=[

                "name": "Accept",
                "value": "application/vnd.github.v3+json",
                "type": "header",
            },

                "name": "Authorization",
                "value": f"Bearer {auth_credentials['access_token']}",
                "type": "header",
            },

                "name": 'X-Custom-Header',
                "value": 'custom-value',
                "type": 'header',
            },
        ],
    )
    return {"data": response.data}
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
import { z } from 'zod/v3';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const tool = await composio.tools.createCustomTool({
  slug: 'GITHUB_SEARCH_REPOSITORIES',
  name: 'Search GitHub Repositories',
  description: 'Search for repositories with custom parameters',
  toolkitSlug: 'github',
  inputParams: z.object({
    query: z.string().describe('Search query'),
    perPage: z.number().optional().describe('Results per page'),
    acceptType: z.string().optional().describe('Custom accept header'),
  }),
  execute: async (input, connectionConfig, executeToolRequest) => {
    const result = await executeToolRequest({
      endpoint: '/search/repositories',
      method: 'GET',
      parameters: [
        // Add query parameters for pagination

          name: 'q',
          value: input.query,
          in: 'query',
        },

          name: 'per_page',
          value: (input.perPage || 30).toString(),
          in: 'query',
        },
        // Add custom headers

          name: 'Accept',
          value: input.acceptType || 'application/vnd.github.v3+json',
          in: 'header',
        },

          name: 'X-Custom-Header',
          value: 'custom-value',
          in: 'header',
        },
      ],
    });
    return result;
  },
});
```
  

## Executing Custom Tools

You can execute custom tools just like any other tool:

**Python:**

```python
response = composio.tools.execute(
    user_id="default",
    slug="TOOL_SLUG", # For the tool above you can use `get_issue_info.slug`
    arguments={"issue_number": 1},
)
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const result = await composio.tools.execute('TOOL_SLUG', {
  arguments: {
    // Tool input parameters
  },
  userId: 'user-id',
  connectedAccountId: 'optional-account-id', // Required for toolkit-based tools
});
```
  

## Best Practices

1. Use descriptive names and slugs for your tools
2. Always provide descriptions for input parameters using `describe()`
3. Handle errors gracefully in your execute function
4. For toolkit-based tools:
   - Prefer `executeToolRequest` over direct API calls when possible
   - Use relative paths with `executeToolRequest` - Composio will automatically inject the correct baseURL
   - Use the `parameters` option to add custom headers or query parameters:
     ```typescript
     parameters: [
       { name: 'page', value: '1', in: 'query' }, // Adds ?page=1 to URL
       { name: 'x-custom', value: 'value', in: 'header' }, // Adds header
     ];
     ```
   - Remember that `executeToolRequest` can only call tools from the same toolkit
   - Use `executeToolRequest` to leverage Composio's automatic credential handling
   - Only use `connectionConfig` when you need to make direct API calls or interact with different services
5. Chain multiple toolkit operations using `executeToolRequest` for better maintainability

## Limitations

1. Custom tools are stored in memory and are not persisted
2. They need to be recreated when the application restarts
3. Toolkit-based tools require a valid connected account with the specified toolkit
4. `executeToolRequest` can only execute tools from the same toolkit that the custom tool belongs to
5. Each toolkit-based tool can only use one connected account at a time

---

# Debugging Info (/docs/debugging-info)

Your debugging info is tied to your project and it helps us trace what happened and debug the issue faster.

## Finding Your Debugging Info

Navigate to your project settings to find your debugging information:

## What to Share

When reaching out for support, share these identifiers:

```
@project_id: pr_xxxxxxxxxxxxx
@org_id: ok_xxxxxxxxxxxxx
@org_member_email: your-email@example.com
```

The identifiers with `pr_` (project) and `ok_` (organization) prefixes let us quickly check your logs inside our internal tracing tools, helping us resolve issues faster.

## Getting Help

import { MessageCircle, Github, Bug, Mail } from 'lucide-react';

- [Join Discord](https://discord.gg/composio): }>
    Get basic support from the community and Composio team
  
  - [GitHub Discussions](https://github.com/ComposioHQ/composio/discussions): }>
    Request new tools and share feedback
  
  - [File an Issue](https://github.com/ComposioHQ/composio/issues): }>
    Report SDK issues and bugs
  
  - [Contact Support](mailto:support@composio.dev): }>
    Reach out for dedicated support channels on Growth and Enterprise plans

---

# Executing Tools (/docs/executing-tools)

LLMs on their own can only do generation. Tool calling changes that by letting them interact with external services. Instead of just drafting an email, the model can call `GMAIL_SEND_EMAIL` to actually send it. The tool's results feed back to the LLM, closing the loop so it can decide, act, observe, and adapt.

In Composio, every **tool** is a single API action—fully described with schema, parameters, and return type. Tools live inside **toolkits** like Gmail, Slack, or GitHub, and Composio handles authentication and user scoping.

> 
**User Scoping**: All tools are scoped to a specific user - that's why every example includes a `user_id`. Learn how to structure User IDs in [User Management](/docs/user-management). Each user must authenticate with their respective services (Gmail, Calendar, etc.) - see [Authentication](/docs/authenticating-tools).

## Using Chat Completions

Use the Composio SDK with providers like OpenAI, Anthropic, and Google AI. To learn how to set up these providers, see [Providers](/docs/providers/openai).

**Python:**

```python
from composio import Composio
from composio_openai import OpenAIProvider
from openai import OpenAI
from datetime import datetime

# Use a unique identifier for each user in your application
user_id = "user-k7334"

# Create composio client
composio = Composio(provider=OpenAIProvider(), api_key="your_composio_api_key")

# Create openai client
openai = OpenAI()

# Get calendar tools for this user
tools = composio.tools.get(
    user_id=user_id,
    tools=["GOOGLECALENDAR_EVENTS_LIST"]
)

# Ask the LLM to check calendar
result = openai.chat.completions.create(
    model="gpt-4o-mini",
    tools=tools,
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": f"What's on my calendar for the next 7 days?"}
    ]
)

# Handle tool calls
result = composio.provider.handle_tool_calls(user_id=user_id, response=result)
print(result)
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
import { AnthropicProvider } from '@composio/anthropic';
import { Anthropic } from '@anthropic-ai/sdk';

// Use a unique identifier for each user in your application
const userId = 'user-k7334';

// Create anthropic client
const anthropic = new Anthropic();

// Create Composio client
const composio = new Composio({
  apiKey: "your-composio-api-key",
  provider: new AnthropicProvider(),
});

// Get calendar tools for this user
const tools = await composio.tools.get(userId, {
  tools: ['GOOGLECALENDAR_EVENTS_LIST'],
});

// Ask the LLM to check calendar
const msg = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  tools: tools,
  messages: [

      role: 'user',
      content: `What's on my calendar for the next 7 days?`,
    },
  ],
  max_tokens: 1024,
});

// Handle tool calls
const result = await composio.provider.handleToolCalls(userId, msg);
console.log('Results:', JSON.stringify(result, null, 2));
```
  

## Using Agentic Frameworks

Agentic frameworks automatically handle the tool execution loop. Composio provides support for frameworks like this by making sure the tools are formatted into the correct objects for the agentic framework to execute.

**Python:**

```python
import asyncio
from agents import Agent, Runner
from composio import Composio
from composio_openai_agents import OpenAIAgentsProvider

# Use a unique identifier for each user in your application
user_id = "user-k7334"

# Initialize Composio toolset
composio = Composio(provider=OpenAIAgentsProvider(), api_key="your_composio_api_key")

# Get all tools for the user
tools = composio.tools.get(
    user_id=user_id,
    toolkits=["COMPOSIO_SEARCH"],
)

# Create an agent with the tools
agent = Agent(
    name="Deep Researcher",
    instructions="You are an investigative journalist.",
    tools=tools,
)

async def main():
    result = await Runner.run(
        starting_agent=agent,
        input=("Do a thorough DEEP research on Golden Gate Bridge"),
    )
    print(result.final_output)

# Run the agent
asyncio.run(main())
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
import { generateText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';
import { VercelProvider } from '@composio/vercel';

// Use a unique identifier for each user in your application
const userId = 'user-k7334';

// Initialize Composio toolset
const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
  provider: new VercelProvider(),
});

// Get all tools for the user
const tools = await composio.tools.get(userId, {
  toolkits: ['HACKERNEWS_GET_LATEST_POSTS'],
  limit: 10,
});

// Generate text with tool use
const { text } = await generateText({
  model: anthropic('claude-sonnet-4-20250514'),
  messages: [

      role: 'user',
      content: 'Do a thorough DEEP research on the top articles on Hacker News about Composio',
    },
  ],
  tools,
});

console.log(text);
```
  

## Direct Tool Execution

If you just want to call a tool without using any framework or LLM provider, you can use the `execute` method directly.

> 
**Finding tool parameters and types:**

**Platform UI**: [Auth Configs](https://platform.composio.dev?next_page=/auth-configs) → Select your toolkit → Tools & Triggers → Select the tool to see its required and optional parameters

**CLI**: For Python and TypeScript projects, run `composio generate` to generate types. [Learn more →](/docs/cli#generate-type-definitions)

**Python:**

```python
from composio import Composio

user_id = "user-k7334"
# Configure toolkit versions at SDK level
composio = Composio(
    api_key="your_composio_key",
    toolkit_versions={"github": "20251027_00"}
)

# Find available arguments for any tool in the Composio dashboard
result = composio.tools.execute(
    "GITHUB_LIST_STARGAZERS",
    user_id=user_id,
    arguments={"owner": "ComposioHQ", "repo": "composio", "page": 1, "per_page": 5}
)
print(result)
```
  
  
**TypeScript:**

```typescript
import { Composio } from "@composio/core";

const userId = "user-k7334";
// Configure toolkit versions at SDK level
const composio = new Composio({
    apiKey: "your_composio_key",
    toolkitVersions: { github: "20251027_00" }
});

// Find available arguments for any tool in the Composio dashboard
const result = await composio.tools.execute("GITHUB_LIST_STARGAZERS", {
  userId,
  arguments: {
    "owner": "ComposioHQ",
    "repo": "composio",
    "page": 1,
    "per_page": 5
  },
});
console.log('GitHub stargazers:', JSON.stringify(result, null, 2));
```
  

> 
The examples above configure toolkit versions at SDK initialization. You can also pass versions per-execution or use environment variables. See [toolkit versioning](/docs/toolkit-versioning) for all configuration options.

### Proxy Execute

You can proxy requests to any supported toolkit API and let Composio inject the authentication state. This is useful when you need an API endpoint that isn't available as a predefined tool.

The `endpoint` can be a relative path or absolute URL. Composio uses the `connected_account_id` to determine the toolkit and resolve relative paths against the appropriate base URL.

**Python:**

```python
# Send a proxy request to the endpoint
response = composio.tools.proxy(
    endpoint="/repos/composiohq/composio/issues/1",
    method="GET",
    connected_account_id="ca_jI6********",  # use connected account for github
    parameters=[

            "name": "Accept",
            "value": "application/vnd.github.v3+json",
            "type": "header",
        },
    ],
)

print(response)
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
// Send a proxy request to the endpoint
const { data } = await composio.tools.proxyExecute({
    endpoint:'/repos/composiohq/composio/issues/1',
    method: 'GET',
    connectedAccountId: 'ca_jI*****', // use connected account for github
    parameters:[

            "name": "Accept",
            "value": "application/vnd.github.v3+json",
            "in": "header",
        },
    ],
});

console.log(data);
```
  

> 
Need an API that isn't supported by any Composio toolkit, or want to extend an existing one? Learn how to [create custom tools](/docs/custom-tools).

## Automatic File Handling

Composio handles file operations automatically. Pass file paths to tools that need them, and get local file paths back from tools that return files.

### File Upload

Pass local file paths, URLs, or File objects to tools that accept files:

**Python:**

```python
# Upload a local file to Google Drive
result = composio.tools.execute(
    slug="GOOGLEDRIVE_UPLOAD_FILE",
    user_id="user-1235***",
    arguments={"file_to_upload": os.path.join(os.getcwd(), "document.pdf")},
)

print(result)  # Print Google Drive file details
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
import path from 'path';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
// Upload a local file to Google Drive
const result = await composio.tools.execute('GOOGLEDRIVE_UPLOAD_FILE', {
  userId: 'user-4235***',
  arguments: {
    file_to_upload: path.join(__dirname, 'document.pdf')

});

console.log(result.data);  // Contains Google Drive file details
```
  

### File Download

When tools return files, Composio downloads them to the local directory and provides the file path in the response:

**Python:**

```python
composio = Composio(
    api_key="your_composio_key",
    file_download_dir="./downloads"  # Optional: Specify download directory
)

result = composio.tools.execute(
    "GOOGLEDRIVE_DOWNLOAD_FILE",
    user_id="user-1235***",
    arguments={"file_id": "your_file_id"},
)

# Result includes local file path
print(result)
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
// Download a file from Google Drive
const result = await composio.tools.execute('GOOGLEDRIVE_DOWNLOAD_FILE', {
    userId: 'user-1235***',
    arguments: {
      file_id: 'your-file-id'

  });

// Result includes local file path
console.log(result);
```
  

### Disabling Auto File Handling

You can disable automatic file handling when initializing the TypeScript SDK. When disabled, handle file uploads and downloads manually using `files.upload` and `files.download`:

```typescript
import { Composio } from '@composio/core';
import path from 'path';
// ---cut---
const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
  autoUploadDownloadFiles: false
});

// Now you need to handle files manually using composio.files API
const fileData = await composio.files.upload({
  file: path.join(__dirname, 'document.pdf'),
  toolSlug: 'GOOGLEDRIVE_UPLOAD_FILE',
  toolkitSlug: 'googledrive'
});
```

---

# Fetching tools and schemas (/docs/fetching-tools)

Fetch specific tools, filter by permissions or search, and inspect schemas for type information. Tools are automatically formatted for your provider.

## Basic usage

**Python:**

```python
tools = composio.tools.get(
    user_id,
    toolkits=["GITHUB"]
)
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const userId = 'user-123';
// ---cut---
const tools = await composio.tools.get(userId, {
  toolkits: ["GITHUB"]
});
```
  

Returns top 20 tools by default. Tools require a `user_id` because they're scoped to authenticated accounts. See [User management](/docs/user-management) and [Authentication](/docs/authenticating-tools).

## Tool schemas

Inspect tool parameters and types without a user_id:

**Python:**

```python
tool = composio.tools.get_raw_composio_tool_by_slug("GMAIL_SEND_EMAIL")
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const tool = await composio.tools.getRawComposioToolBySlug("GMAIL_SEND_EMAIL");
```
  

Generate type-safe code for direct SDK execution with [`composio generate`](/docs/cli#generate-type-definitions). This creates TypeScript or Python types from tool schemas.

> 
View tool parameters and schemas visually in the [Composio platform](https://platform.composio.dev). Navigate to any toolkit and select a tool to see its input/output parameters.

## Filtering tools

### By toolkit

Get tools from specific apps. Returns top 20 tools by default.

**Python:**

```python
# Fetch with limit for a specific user
tools = composio.tools.get(
    user_id,
    toolkits=["GITHUB"],
    limit=5  # Get top 5 tools
)

# Same filter but without user_id (for schemas)
raw_tools = composio.tools.get_raw_composio_tools(
    toolkits=["GITHUB"],
    limit=5
)
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const userId = 'user-123';
// ---cut---
// Fetch with limit for a specific user
const limitedTools = await composio.tools.get(userId, {
  toolkits: ["GITHUB"],
  limit: 5  // Get top 5 tools
});

// Same filter but without userId (for schemas)
const rawTools = await composio.tools.getRawComposioTools({
  toolkits: ["GITHUB"],
  limit: 5
});
```
  

### By name

Fetch specific tools when you know their names.

**Python:**

```python
# Fetch specific tools by name
tools = composio.tools.get(
    user_id,
    tools=["GITHUB_CREATE_ISSUE", "GITHUB_CREATE_PULL_REQUEST"]
)

# Get schemas without user_id
raw_tools = composio.tools.get_raw_composio_tools(
    tools=["GITHUB_CREATE_ISSUE", "GITHUB_CREATE_PULL_REQUEST"]
)
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const userId = 'user-123';
// ---cut---
// Fetch specific tools by name
const specificTools = await composio.tools.get(userId, {
  tools: ["GITHUB_LIST_STARGAZERS", "GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER"]
});

// Get schemas without userId
const specificRawTools = await composio.tools.getRawComposioTools({
  tools: ["GITHUB_LIST_STARGAZERS", "GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER"]
});
```
  

### By scopes

Filter OAuth tools by permission level. Only works with a single toolkit.

**Python:**

```python
# Filter by OAuth scopes (single toolkit only)
tools = composio.tools.get(
    user_id,
    toolkits=["GITHUB"],
    scopes=["write:org"]
)
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const userId = 'user-123';
// ---cut---
// Filter by OAuth scopes (single toolkit only)
const scopedTools = await composio.tools.get(userId, {
  toolkits: ["GITHUB"],
  scopes: ["write:org"]
});
```
  

### By search (experimental)

Find tools semantically.

**Python:**

```python
# Search tools semantically
tools = composio.tools.get(
    user_id,
    search="create calendar event"
)

# Search schemas without user_id
raw_tools = composio.tools.get_raw_composio_tools(
    search="create calendar event"
)

# Search within a specific toolkit
tools = composio.tools.get(
    user_id,
    search="issues",
    toolkits=["GITHUB"],
)

# Search toolkit schemas without user_id
raw_tools = composio.tools.get_raw_composio_tools(
    search="issues",
    toolkits=["GITHUB"]
)
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const userId = 'user-123';
// ---cut---
// Search tools semantically
const searchResults = await composio.tools.get(userId, {
  search: "create google calendar event"
});

// Search schemas without userId
const searchRawTools = await composio.tools.getRawComposioTools({
  search: "create google calendar event"
});

// Search within a specific toolkit
const toolkitSearch = await composio.tools.get(userId, {
  search: "star a repository",
  toolkits: ["GITHUB"]
});

// Search toolkit schemas without userId
const toolkitSearchRaw = await composio.tools.getRawComposioTools({
  search: "star a repository",
  toolkits: ["GITHUB"]
});
```
  

> 
Use specific toolkit versions in production to prevent breaking changes. See [toolkit versioning](/docs/toolkit-versioning).

---

# Welcome (/docs)

> **New: Tool Router**: 
Single MCP server and Tool that can search, authenticate, and execute across all Composio tools. [Learn more →](/tool-router/overview)

- [Managed authentication](/docs/authenticating-tools): Handle OAuth, API keys, and custom auth flows automatically
  - [Tool execution](/docs/executing-tools): Execute actions across 500+ toolkits with support for most AI frameworks
  - [MCP server](/docs/mcp-quickstart): Hosted MCP servers for all 500+ toolkits
  - [Triggers](/docs/using-triggers): Subscribe to external events and trigger workflows automatically

## Get started

- [Quickstart](/docs/quickstart): Build your first agent

  
  
    
**python:**

      [Video: Composio Python Quickstart](https://youtube.com/watch?v=wkqlR8322F4)
    
    
**typescript:**

      [Video: Composio TypeScript Quickstart](https://youtube.com/watch?v=ZRGb4xGl-kc)
    
  

## Why Composio?

Composio is the fastest way to enable your AI agents to take real-world actions—without dealing with individual API integrations, authentication flows, or complex tool formatting.

- **Access 500+ toolkits** out of the box across popular apps like Slack, GitHub, Notion, and more. [Browse toolkits →](/toolkits/introduction)
- **Enforce strict access and data controls** with [fine-grained permissions](/docs/authenticating-tools) for each tool and user.
- **Trigger agents and workflows** using [external events](/docs/using-triggers) (e.g., new message in Slack, new issue in GitHub).
- **Use MCP servers** for all 500+ toolkits, compatible with any [MCP client](/docs/mcp-quickstart).
- **Search, plan and authenticate** across all tools with [Tool Router](/tool-router/overview).

## Providers

Composio works with any AI framework. Pick your preferred SDK:

  - [OpenAI](/docs/providers/openai) (Python, TypeScript)
  - [Anthropic](/docs/providers/anthropic) (Python, TypeScript)
  - [Google Gemini](/docs/providers/google) (Python, TypeScript)
  - [Vercel AI SDK](/docs/providers/vercel) (TypeScript)
  - [LangChain](/docs/providers/langchain) (Python, TypeScript)
  - [LlamaIndex](/docs/providers/llamaindex) (Python, TypeScript)
  - [OpenAI Agents](/docs/providers/openai-agents) (Python)
  - [CrewAI](/docs/providers/crewai) (Python)
  - [Mastra](/docs/providers/mastra) (TypeScript)
  - [Build your own](/docs/providers/custom-providers) (Python, TypeScript)

## For AI tools

Access Composio documentation in Markdown format for use with Cursor, Copilot, Claude, and other AI tools:

- [composio.dev/llms.txt](/llms.txt) - Documentation index with links
- [composio.dev/llms-full.txt](/llms-full.txt) - Complete documentation in one file

```
Documentation:
{paste documentation from composio.dev/llms-full.txt}
---
Based on the above documentation, answer the following:
{your question}
```

## Community

Join our [Discord](https://discord.gg/composio) community!

---

# Providers (/docs/mcp-providers)

Integrate your MCP servers with popular AI SDKs and frameworks.

> 
Composio MCP servers only support Streamable HTTP transport.

## Anthropic SDK

Use MCP servers with the Anthropic Claude API.

**Python:**

```python
from anthropic import Anthropic
from composio import Composio

# Initialize clients
composio = Composio()
anthropic = Anthropic(api_key="your-anthropic-api-key")

# Create MCP server with GitHub and Linear tools
server = composio.mcp.create(
    name="dev-workflow-server",
    toolkits=[
        {"toolkit": "github", "auth_config": "ac_github_id"},
        {"toolkit": "linear", "auth_config": "ac_linear_id"}
    ],
    allowed_tools=["GITHUB_LIST_PRS", "GITHUB_CREATE_COMMENT", "LINEAR_CREATE_ISSUE"]
)

# Generate MCP instance for user
instance = server.generate("user@example.com")

# Use MCP with Anthropic to manage development workflow
response = anthropic.beta.messages.create(
    model="claude-sonnet-4-5",
    system="You are a helpful assistant with access to GitHub and Linear tools. Use these tools to help manage development workflows. Do not ask for confirmation before using the tools.",
    max_tokens=1000,
    messages=[{
        "role": "user",
        "content": "Check my GitHub PRs for review comments, create Linear tasks for any requested changes, and update the PR descriptions with task links"
    }],
    mcp_servers=[{
        "type": "url",
        "url": instance['url'],
        "name": "composio-mcp-server"
    }],
    betas=["mcp-client-2025-04-04"]  # Enable MCP beta
)

print(response.content)
```
  
  
**TypeScript:**

```typescript
import Anthropic from '@anthropic-ai/sdk';
import { Composio } from '@composio/core';

// Initialize clients
const composio = new Composio();
const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

// Create MCP server with Google Sheets tools
const server = await composio.mcp.create(
  "analytics-server",

    toolkits: [
      { toolkit: "googlesheets", authConfigId: "ac_sheets_id" }
    ],
    allowedTools: ["GOOGLESHEETS_GET_DATA", "GOOGLESHEETS_UPDATE_DATA", "GOOGLESHEETS_CREATE_SHEET"]

);

// Generate MCP instance for user
const instance = await server.generate("user@example.com");

// Use MCP with Anthropic for spreadsheet operations
const response = await anthropic.beta.messages.create({
  model: "claude-sonnet-4-5",
  system: "You are a helpful assistant with access to Google Sheets tools. Use these tools to analyze and manage spreadsheet data. Do not ask for confirmation before using the tools.",
  max_tokens: 1000,
  messages: [{
    role: "user",
    content: "Analyze the sales data in my Google Sheets 'Q4 Revenue' spreadsheet, calculate month-over-month growth, and add a new summary sheet with visualizations"
  }],
  mcp_servers: [{
    type: "url",
    url: instance.url,
    name: "composio-mcp-server"
  }],
  betas: ["mcp-client-2025-04-04"]  // Enable MCP beta
});

console.log(response.content);
```
  

## OpenAI SDK

Integrate MCP servers with OpenAI GPT models.

**Python:**

```python
from openai import OpenAI
from composio import Composio

# Initialize clients
composio = Composio()
openai = OpenAI(api_key="your-openai-api-key")

# Create MCP server with Google Sheets and Notion tools
server = composio.mcp.create(
    name="data-docs-server",
    toolkits=[
        {"toolkit": "googlesheets", "auth_config": "ac_sheets_id"},
        {"toolkit": "notion", "auth_config": "ac_notion_id"}
    ],
    allowed_tools=["GOOGLESHEETS_GET_DATA", "GOOGLESHEETS_UPDATE_DATA", "NOTION_CREATE_PAGE"]
)

# Generate MCP instance for user
instance = server.generate("user@example.com")

# Use MCP with OpenAI for data management
response = openai.responses.create(
    model="gpt-5",
    tools=[

            "type": "mcp",
            "server_label": "composio-server",
            "server_description": "Composio MCP server with Google Sheets and Notion integrations",
            "server_url": instance['url'],
            "require_approval": "never",
        },
    ],
    input="Export the Q4 metrics from Google Sheets and create a comprehensive Notion page with charts and analysis",
)

print("OpenAI MCP Response:", response.output_text)
```
  
  
**TypeScript:**

```typescript
import OpenAI from 'openai';
import { Composio } from '@composio/core';

// Initialize clients
const composio = new Composio();
const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

// Create MCP server with Linear and Notion tools
const server = await composio.mcp.create(
  "project-docs-server",

    toolkits: [
      { toolkit: "linear", authConfigId: "ac_linear_id" },
      { toolkit: "notion", authConfigId: "ac_notion_id" }
    ],
    allowedTools: ["LINEAR_LIST_ISSUES", "LINEAR_GET_ISSUE", "NOTION_CREATE_PAGE"]

);

// Generate MCP instance for user
const instance = await server.generate("user@example.com");

// Use MCP with OpenAI for project documentation
const response = await openai.responses.create({
  model: "gpt-5",
  tools: [

      type: "mcp",
      server_label: "composio-server",
      server_description: "Composio MCP server with Linear and Notion integrations",
      server_url: instance.url,
      require_approval: "never",
    },
  ],
  input: "Find all completed Linear issues from this sprint and create a Notion page documenting the release notes",
});

console.log("OpenAI MCP Response:", response.output_text);
```
  

## Mastra

Use MCP servers with Mastra framework.

```typescript
import { MCPClient } from "@mastra/mcp";
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { Composio } from "@composio/core";

// Initialize Composio
const composio = new Composio();

// Create MCP server with GitHub, Linear, and Notion tools
const server = await composio.mcp.create(
  "dev-automation-server",

    toolkits: [
      { toolkit: "github", authConfigId: "ac_github_id" },
      { toolkit: "linear", authConfigId: "ac_linear_id" },
      { toolkit: "notion", authConfigId: "ac_notion_id" }
    ],
    allowedTools: [
      "GITHUB_LIST_ISSUES", "GITHUB_CREATE_ISSUE",
      "LINEAR_CREATE_ISSUE", "LINEAR_UPDATE_ISSUE",
      "NOTION_CREATE_PAGE", "NOTION_UPDATE_PAGE"
    ]

);

// Generate MCP instance for user
const instance = await server.generate("user@example.com");

// Create MCP client with Composio server
export const mcpClient = new MCPClient({
  id: "composio-mcp-client",
  servers: {
    composio: { url: new URL(instance.url) },

});

// Create a development workflow agent
export const devAgent = new Agent({
  id: "dev-assistant",
  name: "Dev Assistant",
  description: "AI assistant for development workflow automation",
  instructions: "Help manage GitHub repos, Linear issues, and Notion documentation.",
  model: openai("gpt-4-turbo"),
  tools: await mcpClient.getTools()
});

// Example: Automate development workflow
(async () => {
  const response = await devAgent.generate(
    "Review open GitHub issues, create Linear tasks for bugs labeled 'priority', and update the Notion roadmap page"
  );
  console.log(response.text);
})();
```

---

# Quickstart (/docs/mcp-quickstart)

[Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) is an open-source standard for connecting AI applications to external tools. All the 500+ tools available in Composio are also available as MCP servers.

Composio lets you create MCP servers that handle authentication (OAuth, API keys), generate unique URLs for each user, and control which tools are exposed. You can combine multiple toolkits in a single server.

> 
Composio MCP servers only support Streamable HTTP transport.

## Install the SDK

First, install the Composio SDK for your preferred language:

**Python:**

```bash
pip install composio
```
  
  
**TypeScript:**

```bash
npm install @composio/core
```
  

## Create an MCP server

  ### Step: Initialize Composio

    
**Python:**

```python
from composio import Composio

# Initialize Composio
composio = Composio(api_key="YOUR_API_KEY")
```
      
      
**TypeScript:**

```typescript
import { Composio } from '@composio/core';

// Initialize Composio
const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY
});
```
      
    
  

  ### Step: Create server configuration

    > 
    **Before you begin:** [Create an auth configuration](/docs/authenticating-tools#creating-an-auth-config) for your toolkit.
    

    Create an MCP server with your auth config. You can also set list of specific tools to enable across all toolkits.

    
**Python:**

```python
# Create MCP server with multiple toolkits
server = composio.mcp.create(
    name="mcp-config-73840", # Pick a unique name for your MCP server
    toolkits=[

            "toolkit": "gmail",
            "auth_config": "ac_xyz123"  # Your Gmail auth config ID
        },

            "toolkit": "googlecalendar",
            "auth_config": "ac_abc456"  # Your Google Calendar auth config ID

    ],
    allowed_tools=["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL", "GOOGLECALENDAR_EVENTS_LIST"]
)

print(f"Server created: {server.id}")
print(server.id)
```
      
      
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
// ---cut---
// Create MCP server with multiple toolkits
const server = await composio.mcp.create("mcp-config-73840", {  // Pick a unique name for your MCP server
  toolkits: [

      authConfigId: "ac_xyz123", // Your Gmail auth config ID
      toolkit: "gmail"
    },

      authConfigId: "ac_abc456", // Your Google Calendar auth config ID
      toolkit: "googlecalendar"

  ],
  allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL", "GOOGLECALENDAR_EVENTS_LIST"]
});

console.log(`Server created: ${server.id}`);
console.log(server.id);
```
      
    

    > 
    **Alternative:** You can also create and manage MCP configs directly from the [Composio dashboard → MCP Configs](https://platform.composio.dev?next_page=/mcp-configs).
    
  

  ### Step: Generate user URLs

    > 
    **Before generating URLs:** Users must authenticate with the toolkits configured in your MCP server. See [hosted authentication](/docs/authenticating-tools#hosted-authentication-connect-link) for how to connect user accounts.
    

    Get server URLs for your users to connect:

    
**Python:**

```python
# Generate server instance for user
instance = composio.mcp.generate(user_id="user-73840", mcp_config_id=server.id) # Use the user ID for which you created the connected account

print(f"MCP Server URL: {instance['url']}")
```
      
      
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
const server = { id: 'mcp-config-73840' };
// ---cut---
// Generate server instance for user
const instance = await composio.mcp.generate("user-73840", server.id);  // Use the user ID for which you created the connected account

console.log("MCP Server URL:", instance.url);
```
      
    

    > 
    If users haven't authenticated, the MCP server will still generate a URL but tools requiring authentication won't work until the user connects their accounts.
    
  

  ### Step: Use with AI providers

    Use the MCP server URL with your AI provider:

    
**OpenAI (Python):**

```python
from openai import OpenAI

# Initialize OpenAI client
client = OpenAI(api_key="your-openai-api-key")

# Use the MCP server URL you generated
mcp_server_url = "https://backend.composio.dev/v3/mcp/YOUR_SERVER_ID?include_composio_helper_actions=true&user_id=YOUR_USER_ID"

# Use MCP with OpenAI Responses API
response = client.responses.create(
    model="gpt-5",
    tools=[

            "type": "mcp",
            "server_label": "composio-server",
            "server_description": "Composio MCP server for Gmail and Calendar integrations",
            "server_url": mcp_server_url,
            "require_approval": "never",
        },
    ],
    input="What meetings do I have tomorrow? Also check if I have any urgent emails",
)

print("OpenAI MCP Response:", response.output_text)
```
      
      
**Anthropic (Python):**

```python
from anthropic import Anthropic

# Initialize Anthropic client
client = Anthropic(api_key="your-anthropic-api-key")

# Use the MCP server URL you generated
mcp_server_url = "https://backend.composio.dev/v3/mcp/YOUR_SERVER_ID?include_composio_helper_actions=true&user_id=YOUR_USER_ID"

# Use MCP with Anthropic (beta feature)
response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    system="You are a helpful assistant with access to various tools through MCP. Use these tools to help the user. Do not ask for confirmation before using the tools.",
    max_tokens=1000,
    messages=[{
        "role": "user",
        "content": "What meetings do I have tomorrow? Also check if I have any urgent emails"
    }],
    mcp_servers=[{
        "type": "url",
        "url": mcp_server_url,
        "name": "composio-gmail-calendar-mcp-server"
    }],
    betas=["mcp-client-2025-04-04"]  # Enable MCP beta
)

print(response.content)
```
      
      
**Mastra (TypeScript):**

```typescript
import { MCPClient } from "@mastra/mcp";
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";

// Use the MCP server URL you generated
const MCP_URL = "https://backend.composio.dev/v3/mcp/YOUR_SERVER_ID?include_composio_helper_actions=true&user_id=YOUR_USER_ID";

export const client = new MCPClient({
  id: "docs-mcp-client",
  servers: {
    composio: { url: new URL(MCP_URL) },

});

export const agent = new Agent({
  id: "assistant",
  name: "Assistant",
  description: "Helpful AI with MCP tools",
  instructions: "Use the MCP tools to answer.",
  model: openai("gpt-4-turbo"),
  tools: await client.getTools()
});

(async () => {
  const res = await agent.generate("What meetings do I have tomorrow? Also check if I have any urgent emails");
  console.log(res.text);
})();
```
      
    
  

## Next steps

- [Server management](/docs/mcp-server-management): 
    Create and manage MCP servers
  
  - [Providers](/docs/mcp-providers): 
    Use with Anthropic, OpenAI, and other frameworks
  

> 
Need help? Join our [Discord](https://discord.com/invite/composio) or [raise an issue on GitHub](https://github.com/ComposioHQ/composio/issues/new?labels=bug).

---

# Server management (/docs/mcp-server-management)

This guide covers all server management operations for MCP servers.

## Create a server

**Python:**

```python
server = composio.mcp.create(
    name="my-gmail-server",
    toolkits=[{
        "toolkit": "gmail",
        "auth_config": "ac_xyz123"
    }],
    allowed_tools=["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]
)

print(f"Created server: {server.id}")
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const server = await composio.mcp.create(
  "my-gmail-server",

    toolkits: [

        authConfigId: "ac_xyz123",
        toolkit: "gmail"

    ],
    allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"],
    manuallyManageConnections: false

);

console.log(`Created server: ${server.id}`);
```
  

## List servers

Find and filter your MCP servers.

**Python:**

```python
# List all servers
servers = composio.mcp.list()
print(f"Found {len(servers['items'])} servers")

# Filter by toolkit
gmail_servers = composio.mcp.list(
    toolkits="gmail",
    limit=20
)

# Filter by name
production_servers = composio.mcp.list(
    name="production"
)
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
// List all servers
const servers = await composio.mcp.list({
  limit: 10,
  page: 1,
  authConfigs: [],
  toolkits: []
});
console.log(`Found ${servers.items.length} servers`);

// Filter by toolkit
const gmailServers = await composio.mcp.list({
  limit: 20,
  page: 1,
  authConfigs: [],
  toolkits: ["gmail"]
});

// Filter by name
const productionServers = await composio.mcp.list({
  limit: 10,
  page: 1,
  authConfigs: [],
  toolkits: [],
  name: "production"
});
```
  

## Get server details

**Python:**

```python
# Get by ID
server = composio.mcp.get("mcp_server_id")
print(f"Server name: {server.name}")
print(f"Toolkits: {server.toolkits}")
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
// Get by ID
const server = await composio.mcp.get("mcp_server_id");

console.log(`Server: ${server.name}`);
console.log(`Toolkits: ${server.toolkits}`);
```
  

## Update a server

Modify server configuration, tools, or auth configs.

**Python:**

```python
updated = composio.mcp.update(
    server_id="mcp_server_id",
    name="updated-name",
    allowed_tools=["GMAIL_FETCH_EMAILS", "GMAIL_SEARCH_EMAILS"]
)
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const updated = await composio.mcp.update(
  "mcp_server_id",

    name: "updated-name",
    toolkits: [

        toolkit: "gmail",
        authConfigId: "ac_new_config"

    ],
    allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEARCH_EMAILS"],
    manuallyManageConnections: false

);

console.log(updated);
```
  

## Delete a server

**Python:**

```python
result = composio.mcp.delete("mcp_server_id")
if result['deleted']:
    print("Server deleted successfully")
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const result = await composio.mcp.delete("mcp_server_id");
if (result.deleted) {
  console.log("Server deleted successfully");

```
  

## Multi-toolkit servers

Combine multiple services in a single MCP server.

**Python:**

```python
server = composio.mcp.create(
    name="productivity-suite",
    toolkits=[
        {"toolkit": "gmail", "auth_config": "ac_gmail"},
        {"toolkit": "slack", "auth_config": "ac_slack"},
        {"toolkit": "github", "auth_config": "ac_github"}
    ],
    allowed_tools=[
        "GMAIL_FETCH_EMAILS",
        "SLACK_SEND_MESSAGE",
        "GITHUB_CREATE_ISSUE"
    ]
)
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const server = await composio.mcp.create(
  "productivity-suite",

    toolkits: [

        authConfigId: "ac_gmail",
        toolkit: "gmail"
      },

        authConfigId: "ac_slack",
        toolkit: "slack"
      },

        authConfigId: "ac_github",
        toolkit: "github"

    ],
    allowedTools: [
      "GMAIL_FETCH_EMAILS",
      "SLACK_SEND_MESSAGE",
      "GITHUB_CREATE_ISSUE"
    ],
    manuallyManageConnections: false

);
```
  

## Generate user URLs

After creating a server, generate unique URLs for each user.

**Python:**

```python
# Generate instance for user
instance = server.generate("user@example.com")

print(f"URL: {instance['url']}")
print(f"Tools: {instance['allowed_tools']}")

# Chat-based authentication is enabled by default
# Set manually_manage_connections=True to disable it:
instance_manual = server.generate(
    "user@example.com",
    manually_manage_connections=True
)
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
// Generate instance for user
const instance = await composio.mcp.generate(
  "user@example.com",
  "mcp_server_id"
);

console.log("URL:", instance.url);
console.log("Tools:", instance.allowedTools);

// Chat-based authentication is enabled by default
// Set manuallyManageConnections: true to disable it:
const instanceManual = await composio.mcp.generate(
  "user@example.com",
  "mcp_server_id",
  { manuallyManageConnections: true }
);
```
  

> 
**Chat-based authentication:**
- **TypeScript**: Enabled by default (set `manuallyManageConnections=false` or omit it)
- **Python**: Enabled by default (set `manually_manage_connections=False` or omit it)

When enabled, the agent can authenticate users dynamically during conversation if they're missing required connections. Set `manuallyManageConnections=true` (TypeScript) or `manually_manage_connections=True` (Python) to disable it.

## Best practices

- **Use descriptive names** - Makes servers easy to find
- **Limit tools appropriately** - Only include necessary tools
- **Reuse servers** - Don't create duplicates for same configuration
- **Store server IDs** - Keep track of created server IDs

---

# Programmatic Auth Configs (/docs/programmatic-auth-configs)

Auth configs are created once and reused many times. However, when managing multiple toolkits, you may want to create auth configs programmatically.

- When creating and destroying auth configs multiple times in your app's lifecycle.
- When creating auth configs for your users' users.

## OAuth2 based apps

### Using Composio Default Auth

Since OAuth2 is the most common authentication type for applications, Composio provides managed auth for most OAuth2 based applications. This is to speed up development and prototyping. This means you don't have to provide your own OAuth credentials.

**Python:**

```python
from composio import Composio

composio = Composio()

# Use composio managed auth
auth_config = composio.auth_configs.create(
    toolkit="github",
    options={
        "type": "use_composio_managed_auth",
    },
)
print(auth_config)
```
  
  
**TypeScript:**

```typescript
import { Composio } from "@composio/core";

const composio = new Composio();

const authConfig = await composio.authConfigs.create("GITHUB", {
  name: "GitHub",
  type: "use_composio_managed_auth",
});

console.log(authConfig);
```
  

The returned `auth_config_id` should be stored securely in your database for future use to be created and destroyed multiple times.

You can also provide your own authentication details. The required `credentials` and `authScheme` depend on the auth type.

### Using your own OAuth2 credentials

Setting up and using your own OAuth2 credentials is the recommended way when going to production or expecting high usage.

In this example, we're using our own OAuth2 client ID and secret to create the auth config for Notion.

**Python:**

```python
# Use custom auth
auth_config = composio.auth_configs.create(
    toolkit="notion",
    options={
        "name": "Notion Auth",
        "type": "use_custom_auth",
        "auth_scheme": "OAUTH2",
        "credentials": {
            "client_id": "1234567890",
            "client_secret": "1234567890",
            "oauth_redirect_uri": "https://backend.composio.dev/api/v3/toolkits/auth/callback",
        },
    },
)
print(auth_config)
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const authConfig = await composio.authConfigs.create("NOTION", {
    name: "Notion",
    type: "use_custom_auth",
    credentials: {
        client_id: "1234567890",
        client_secret: "1234567890",
        oauth_redirect_uri: "https://backend.composio.dev/api/v3/toolkits/auth/callback",
    },
    authScheme: "OAUTH2",
});

console.log(authConfig);
```
  

> 
You can specify a custom redirect URI by including the `oauth_redirect_uri` parameter in the credentials object. If not provided, Composio uses the default redirect URI.

**Specifying the authorized redirect URI**

The process of setting up your own OAuth2 credentials usually involves generating a client ID and secret and specifying the **authorized redirect URI** in the OAuth configuration.

> 
The **authorized redirect URI** is the URI that captures the OAuth code that is returned to the app.

While doing so, you must ensure to set the **authorized redirect URI** in the OAuth configuration to:

```
https://backend.composio.dev/api/v3/toolkits/auth/callback
```

**GitHub:**

  
  
**Google:**

  

### Specifying scopes

Composio requests a set of appropriate default OAuth2 scopes for each toolkit wherever possible. However, you can override or modify these scopes by passing a `scopes` field to the `credentials` object.

**Python:**

```python
from composio import Composio

composio = Composio()

response = composio.auth_configs.create(
    toolkit="HUBSPOT",
    options={
        "name": "HubspotConfig",
        "authScheme": "OAUTH2",
        "type": "use_composio_managed_auth",
        "credentials": {
            "scopes": "sales-email-read,tickets"

)

print(response.id)
```
  
  
**TypeScript:**

```typescript
import { Composio } from "@composio/core";

const composio = new Composio();

const authConfig = await composio.authConfigs.create("HUBSPOT", {
  name: "HubspotConfig",
  type: "use_composio_managed_auth",
  credentials: {
    scopes: "sales-email-read,tickets",
  },
});

console.log(authConfig);
```
  

## Other auth types

Composio supports many applications that use different authentication types like API keys, Bearer tokens, JWT and even no authentication at all.

Generating the auth config for other auth types only has minor differences:
- `use_custom_auth` is used instead of `use_composio_managed_auth`
- The `credentials` field is used to pass the authentication details
- The `authScheme` field is used to specify the auth type

**Python:**

```python
# Use custom auth
auth_config = composio.auth_configs.create(
    toolkit="perplexityai",
    options={
        "type": "use_custom_auth",
        "auth_scheme": "API_KEY",
        "credentials": {}
    },
)
print(auth_config)
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const authConfig = await composio.authConfigs.create('PERPLEXITYAI', {
  name: 'Perplexity AI',
  type: 'use_custom_auth',
  credentials: {},
  authScheme: 'API_KEY',
});

console.log(authConfig);
```
  

## Programmatically inspecting fields

In cases where you need to dynamically discover the exact field names and handle different auth schemes programmatically, you can inspect the auth config details first.

This works for all auth types.

**Python:**

```python
required_fields = composio.toolkits.get_auth_config_creation_fields(
    toolkit="NOTION",
    auth_scheme="OAUTH2",
    required_only=True,
)
print(required_fields)
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const toolkits = await composio.toolkits.get("NOTION");

// Extract field names from authConfigDetails
const authFields = await composio.toolkits.getAuthConfigCreationFields('NOTION', 'OAUTH2', {
  requiredOnly: true,
});

console.log("Required auth config fields:", authFields);
```
  

Then inspect the required fields and specify them in the `credentials` object.

---

# Quickstart (/docs/quickstart)

This guide walks you through **authenticated tool calling**—the foundation of how Composio connects your AI agents to real-world actions.

You'll learn how to:
1. **Discover and add tools** relevant to your use case (e.g., Slack, GitHub, Notion) to your AI agent
2. **Authenticate tools** securely on behalf of a specific user, with fine-grained access control
3. **Enable your LLM** (like OpenAI, Claude, or LangChain) to invoke these tools reliably using structured tool call formats

## Prerequisites

Before you begin, ensure you have:

1. **A Composio account** - [Sign up here](https://platform.composio.dev) if you haven't already
2. **Python 3.10+** or **Node.js 18+** installed on your system
3. **Your API key** - Get it from the [developer dashboard](https://platform.composio.dev?next_page=/settings) and set it as an environment variable:

```bash
export COMPOSIO_API_KEY=your_api_key
```

## Install the SDK

First, install the Composio SDK for your preferred language:

**Python:**

    ```bash
    pip install composio
    ```
  
  
**TypeScript:**

    ```bash
    npm install @composio/core
    ```
  

## Authorize Tools & Run Them with an Agent

Composio supports multiple LLM providers. Here's how to use Composio with some of the most popular ones:

**OpenAI Agents (Python):**

    Install the OpenAI Agents provider:

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

    ```python
    import asyncio
    from composio import Composio
    from agents import Agent, Runner
    from composio_openai_agents import OpenAIAgentsProvider

    composio = Composio(api_key="your-api-key", provider=OpenAIAgentsProvider())

    # Id of the user in your system
    externalUserId = "pg-test-6dadae77-9ae1-40ca-8e2e-ba2d1ad9ebc4"

    # Create an auth config for gmail from the dashboard or programmatically
    auth_config_id = "your-auth-config-id"
    connection_request = composio.connected_accounts.link(
        user_id=externalUserId,
        auth_config_id=auth_config_id,
    )

    # Redirect user to the OAuth flow
    redirect_url = connection_request.redirect_url

    print(
        f"Please authorize the app by visiting this URL: {redirect_url}"
    )  # Print the redirect url to the user

    # Wait for the connection to be established
    connected_account = connection_request.wait_for_connection()
    print(
        f"Connection established successfully! Connected account id: {connected_account.id}"
    )

    # Get Gmail tools that are pre-configured
    tools = composio.tools.get(user_id=externalUserId, tools=["GMAIL_SEND_EMAIL"])

    agent = Agent(
        name="Email Manager", instructions="You are a helpful assistant", tools=tools
    )

    # Run the agent
    async def main():
        result = await Runner.run(
            starting_agent=agent,
            input="Send an email to soham.g@composio.dev with the subject 'Hello from composio' and the body 'Congratulations on sending your first email using AI Agents and Composio!'",
        )
        print(result.final_output)

    asyncio.run(main())
    ```
  
  
**Anthropic (TypeScript):**

    Install the Composio Anthropic provider:

    ```bash
    npm i @composio/core @composio/anthropic @anthropic-ai/sdk
    ```

    ```typescript
    import { Composio } from "@composio/core";
    import { AnthropicProvider } from "@composio/anthropic";
    import Anthropic from "@anthropic-ai/sdk";

    // env: ANTHROPIC_API_KEY
    const anthropic = new Anthropic();

    const composio = new Composio({
      apiKey: "your-api-key",
      provider: new AnthropicProvider(),
      toolkitVersions: {
        "gmail": "20251111_00",

    });

    // Id of the user in your system
    const externalUserId = "pg-test-6dadae77-9ae1-40ca-8e2e-ba2d1ad9ebc4";

    // Create an auth config for gmail from the dashboard or programmatically
    const authConfigId = "your-auth-config-id";

    const connectionRequest = await composio.connectedAccounts.link(
        externalUserId,
        authConfigId
    );

    // redirect the user to the OAuth flow
    const redirectUrl = connectionRequest.redirectUrl;
    console.log(`Please authorize the app by visiting this URL: ${redirectUrl}`);

    // wait for connection to be established
    const connectedAccount = await connectionRequest.waitForConnection();
    console.log(
      `Connection established successfully! Connected account id: ${connectedAccount.id}`
    );

    // Fetch tools for your user and execute
    const tools = await composio.tools.get(externalUserId, {
        tools: ["GMAIL_SEND_EMAIL"],
    });

    console.log(tools);
    const msg = await anthropic.messages.create({
      model: "claude-sonnet-4-5",
      messages: [

          role: "user",
          content: `Send an email to soham.g@composio.dev with the subject 'Hello from composio' and the body 'Congratulations on sending your first email using AI Agents and Composio!'`,
          },
      ],
      tools: tools,
      max_tokens: 1000,
    });

    const res = await composio.provider.handleToolCalls(externalUserId, msg);
    console.log("Email sent successfully!");
    ```
  
  
**Vercel AI SDK (TypeScript):**

    Install the Composio Vercel Provider:

    ```bash
    npm i @composio/core @composio/vercel ai @ai-sdk/openai
    ```

    ```typescript
    import { Composio } from "@composio/core";
    import { VercelProvider } from "@composio/vercel";
    import { generateText } from "ai";
    import { openai } from "@ai-sdk/openai";

    const composio = new Composio({
      apiKey: "your-api-key",
      provider: new VercelProvider(),
    });

    // Id of the user in your system
    const externalUserId = "pg-test-6dadae77-9ae1-40ca-8e2e-ba2d1ac9ebc4";

    // Create an auth config for gmail from the dashboard or programmatically
    const authConfigId = "your-auth-config-id";

    const connectionRequest = await composio.connectedAccounts.link(
      externalUserId,
      authConfigId
    );

    // redirect the user to the OAuth flow
    const redirectUrl = connectionRequest.redirectUrl;
    console.log(`Please authorize the app by visiting this URL: ${redirectUrl}`);

    // wait for connection to be established
    const connectedAccount = await connectionRequest.waitForConnection();

    const tools = await composio.tools.get(externalUserId, "GMAIL_SEND_EMAIL");

    // env: OPENAI_API_KEY
    const { text } = await generateText({
      model: openai("gpt-5"),
      messages: [

          role: "user",
          content: `Send an email to soham.g@composio.dev with the subject 'Hello from composio' and the body 'Congratulations on sending your first email using AI Agents and Composio!'`,
        },
      ],
      tools: tools
    });

    console.log("Email sent successfully!", { text });
    ```
  

> **What just happened?**: 
You just:
1. Authorized a user account with Composio
2. Passed those tool permissions into an LLM framework
3. Let the LLM securely call real tools on the user's behalf

All OAuth flows and tool execution were automatically handled by Composio.

## Next steps

- [Use Providers](/docs/providers/openai): Learn how to use Composio with various agent SDK and frameworks.
  - [Work with tools](/docs/executing-tools): Learn how to work with tools and tool calling on a deeper level with Composio.
  - [Manage authentication](/docs/custom-auth-configs): Authorize tools for multiple users.
  - [Triggers](/docs/using-triggers): Listen for external events to trigger actions in your agents.

---

# Toolkit Versioning (/docs/toolkit-versioning)

Toolkit versioning ensures your tools behave consistently across deployments. You can pin specific versions in production, test new releases in development, and roll back when needed.

> 
Starting from Python SDK v0.9.0 and TypeScript SDK v0.2.0, specifying versions is required for manual tool execution.

## Configuration methods

Configure toolkit versions using one of three methods:

### SDK initialization

**Python:**

```python
from composio import Composio

# Pin specific versions for each toolkit
composio = Composio(
    api_key="YOUR_API_KEY",
    toolkit_versions={
        "github": "20251027_00",
        "slack": "20251027_00",
        "gmail": "20251027_00"

)
```
  
  
**TypeScript:**

```typescript
import { Composio } from "@composio/core";

// Pin specific versions for each toolkit
const composio = new Composio({
    apiKey: "YOUR_API_KEY",
    toolkitVersions: {
        github: "20251027_00",
        slack: "20251027_00",
        gmail: "20251027_00"

});
```
  

### Environment variables

```bash
# Set versions for specific toolkits
export COMPOSIO_TOOLKIT_VERSION_GITHUB="20251027_00"
export COMPOSIO_TOOLKIT_VERSION_SLACK="20251027_00"
export COMPOSIO_TOOLKIT_VERSION_GMAIL="20251027_00"
```

### Per-execution override

**Python:**

```python
from composio import Composio

composio = Composio(api_key="YOUR_API_KEY")

# Specify version directly in execute call
result = composio.tools.execute(
    "GITHUB_LIST_STARGAZERS",
    arguments={
        "owner": "ComposioHQ",
        "repo": "composio"
    },
    user_id="user-k7334",
    version="20251027_00"  # Override version for this execution
)
print(result)
```
  
  
**TypeScript:**

```typescript
import { Composio } from "@composio/core";

const composio = new Composio({ apiKey: "YOUR_API_KEY" });

// Specify version directly in execute call
const result = await composio.tools.execute("GITHUB_LIST_STARGAZERS", {
    userId: "user-k7334",
    arguments: {
        owner: "ComposioHQ",
        repo: "composio"
    },
    version: "20251027_00"  // Override version for this execution
});
console.log(result);
```
  

## Version format

Versions follow the format `YYYYMMDD_NN`:
- `YYYYMMDD`: Release date
- `NN`: Sequential release number

```python
# Production
toolkit_versions = {"github": "20251027_00"}

# Development
toolkit_versions = {"github": "latest"}
```

> 
Never use `latest` in production. It can introduce breaking changes.

## Version resolution order

1. Per-execution version (highest priority)
2. SDK initialization version
3. Environment variable (toolkit-specific)

## Managing versions

Check available versions using:

**Python:**

```python
# Get toolkit information including available versions
toolkit = composio.toolkits.get(slug="github")

# Extract and print version information
print(f"Toolkit: {toolkit.name}")
print(f"Current Version: {toolkit.meta.version}")
print(f"Available Versions: {toolkit.meta.available_versions}")
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
// Get toolkit information including available versions
const toolkit = await composio.toolkits.get("github");

// Extract and print version information
console.log("Toolkit:", toolkit.name);
console.log("Available Versions:", toolkit.meta.availableVersions);
console.log("Latest Version:", toolkit.meta.availableVersions?.[0]);
```

---

# User Management (/docs/user-management)

## What are User IDs?

User IDs determine whose connected accounts and data you're accessing in Composio. Every tool execution, connection authorization, and account operation requires a `userId` parameter that identifies which context to use.

User IDs act as containers that group connected accounts together across toolkits. Depending on your application, you can use User IDs to represent an individual user, a team, or an entire organization.

## Quick Decision Guide

**How do users access connected accounts in your app?**

- **Each user connects their own personal accounts?**
  Use User IDs
  *Use your database UUID or primary key (e.g., `user.id`)*
  *Example: Users connect their personal Gmail, GitHub*

- **Teams share the same connected accounts?**
  Use Organization IDs
  *Use your organization UUID or primary key (e.g., `organization.id`)*
  *Example: Company Slack workspace*

## Patterns

### User IDs (Individual Accounts)

In production applications with multiple users, where each user connects and manages their own accounts.

**Choosing User IDs:**

- Recommended: Database UUID or primary key (`user.id`)
- Acceptable: Unique username (`user.username`)
- Avoid: Email addresses (emails can change)

**Python:**

```python
# Use your database's user ID (UUID, primary key, etc.)
user_id = user.id; # e.g., "550e8400-e29b-41d4-a716-446655440000"

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

result = composio.tools.execute(
  "GITHUB_GET_REPO",
  user_id=user_id,
  arguments={
    "owner": 'example',
    "repo": 'repo'

)
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
declare const user: { id: string };
// ---cut---
// Use your database's user ID (UUID, primary key, etc.)
const userId = user.id; // e.g., "550e8400-e29b-41d4-a716-446655440000"

const tools = await composio.tools.get(userId, {
  toolkits: ['github'],
});

const result = await composio.tools.execute('GITHUB_GET_REPO', {
  userId: userId,
  arguments: { owner: 'example', repo: 'repo' },
});
```
  

> 
Never use 'default' as a User ID in production with users. This could expose other users' data.

### Organization IDs (Team Accounts)

For applications where teams share connections - one admin connects accounts, all team members use them.

**When to use:**
- Team tools: Slack, Microsoft Teams, Jira
- Shared accounts: support@company.com, company GitHub org
- Enterprise apps: IT manages connections for all employees

**Python:**

```python
# Use the organization ID as userId
user_id = organization.id # e.g., "org_550e8400"

# All users in the organization share the same connected accounts
tools = composio.tools.get(
  user_id=user_id,
  toolkits=["SLACK"],
)

# Execute tools in the organization context
result = composio.tools.execute(
  "SLACK_SEND_MESSAGE",
  user_id=user_id,
  arguments={
    "channel": '#general',
    "text": 'Hello from the team!'

)
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
declare const organization: { id: string };
// ---cut---
// Use the organization ID as userId
const userId = organization.id; // e.g., "org_550e8400"

// All users in the organization share the same connected accounts
const tools = await composio.tools.get(userId, {
  toolkits: ['slack'],
});

// Execute tools in the organization context
const result = await composio.tools.execute('SLACK_SEND_MESSAGE', {
  userId: userId,
  arguments: {
    channel: '#general',
    text: 'Hello from the team!',
  },
});
```
  

## Multiple Connected Accounts

A single User ID can have multiple connected accounts for the same toolkit. For example, a user might connect both their personal and work Gmail accounts.

**Key concepts:**
- Each connected account gets a unique Connected Account ID
- Multiple accounts can exist under the same User ID for any toolkit
- You can specify which account to use when executing tools

**Account selection:**
- **Explicit:** Specify the Connected Account ID to target a specific account
- **Default:** If no Connected Account ID is provided, the most recently connected account is used

## Examples

### Organization-Based Application

In B2B applications, typically an admin connects accounts once and all team members share access. Here's a complete implementation:

**Key concepts:**
- Admin performs the OAuth connection using organization ID
- All team members execute tools using the same organization ID
- Permission checks ensure users can only access their organization's connections

```typescript
import { ConnectionRequest } from '@composio/core';
declare function storeConnectionRequest(orgId: string, adminId: string, req: ConnectionRequest): Promise<void>;
declare function userCanSendMessages(userId: string, orgId: string): Promise<boolean>;
declare const app: { post: (path: string, handler: (req: any, res: any) => Promise<any>) => void };
// ---cut---
import { Composio } from '@composio/core';
const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
});

// 1. Admin connects Slack for the entire organization
async function connectOrganizationToSlack(organizationId: string, adminUserId: string) {
  // Use organization ID as userId in Composio
  const connectionRequest = await composio.toolkits.authorize(organizationId, 'slack');

  // Store the connection request for the admin to complete
  await storeConnectionRequest(organizationId, adminUserId, connectionRequest);

  return connectionRequest.redirectUrl;

// 2. Any user in the organization can use the connected tools
async function sendSlackMessage(organizationId: string, channel: string, message: string) {
  return await composio.tools.execute('SLACK_SEND_MESSAGE', {
    userId: organizationId, // organization ID, not individual user ID
    arguments: {
      channel: channel,
      text: message,
    },
  });

// 3. Check if organization has required connections
async function getOrganizationTools(organizationId: string) {
  return await composio.tools.get(organizationId, {
    toolkits: ['slack', 'github', 'jira'],
  });

// Usage in your API endpoint
app.post('/api/slack/message', async (req, res) => {
  const { channel, message } = req.body;
  const organizationId = req.user.organizationId; // Get from your auth system

  // Verify user has permission to send messages for this organization
  if (!(await userCanSendMessages(req.user.id, organizationId))) {
    return res.status(403).json({ error: 'Insufficient permissions' });

  try {
    const result = await sendSlackMessage(organizationId, channel, message);
    res.json(result.data);
  } catch (error) {
    res.status(500).json({ error: 'Failed to send message' });

});
```

### Multi-User Application

In B2C applications, each user connects and manages their own accounts. Every user goes through their own OAuth flow and their data remains completely isolated.

**Key concepts:**
- Each user authorizes their own accounts using their unique user ID
- Connections are isolated - users can only access their own connected accounts
- No permission checks needed since users only access their own data

```typescript
declare const app: { get: (path: string, handler: (req: any, res: any) => Promise<any>) => void };
// ---cut---
import { Composio } from '@composio/core';
const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
});

// 1. User initiates GitHub connection
async function connectUserToGitHub(userId: string) {
  const connectionRequest = await composio.toolkits.authorize(userId, 'github');
  return connectionRequest.redirectUrl;

// 2. Get user's connected GitHub tools
async function getUserGitHubTools(userId: string) {
  return await composio.tools.get(userId, {
    toolkits: ['github'],
  });

// 3. Execute tool for specific user
async function getUserRepos(userId: string) {
  return await composio.tools.execute('GITHUB_LIST_REPOS', {
    userId: userId,
    arguments: {
      per_page: 10,
    },
  });

// Usage in your API endpoint
app.get('/api/github/repos', async (req, res) => {
  const userId = req.user.id; // Get from your auth system

  try {
    const repos = await getUserRepos(userId);
    res.json(repos.data);
  } catch (error) {
    res.status(500).json({ error: 'Failed to fetch repos' });

});
```

**Data isolation**: Composio ensures each userId's connections and data are completely separate. User A can never access User B's repositories.

### Hybrid Pattern

Many applications need both personal and team resources. Users might connect their personal Gmail while sharing the company Slack workspace.

**Common scenarios:**
- Personal calendars + shared project management
- Individual GitHub accounts + organization repositories

**Python:**

```python
# Wrong: Using individual user ID for org-connected tool
user_tools = composio.tools.get(
    user_id="user_123",  # Individual user ID
    toolkits=["slack"]  # Fails - Slack is connected at org level
)

# Correct: Match the ID type to how the tool was connected
user_personal_tools = composio.tools.get(
    user_id="user_123",  # Individual user ID
    toolkits=["gmail"]  # User's personal Gmail
)

org_shared_tools = composio.tools.get(
    user_id="org_123",  # Organization ID
    toolkits=["slack", "jira"]  # Organization's shared tools
)
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
declare const req: { user: { id: string; organizationId: string } };
// ---cut---
// Wrong: Using individual user ID for org-connected tool
const userTools = await composio.tools.get(req.user.id, {
  toolkits: ['slack'], // Fails - Slack is connected at org level
});

// Correct: Match the ID type to how the tool was connected
const userPersonalTools = await composio.tools.get(req.user.id, {
  toolkits: ['gmail'], // User's personal Gmail
});

const orgSharedTools = await composio.tools.get(req.user.organizationId, {
  toolkits: ['slack', 'jira'], // Organization's shared tools
});
```
  

Remember: The userId must match how the account was connected. If admin connected Slack with org ID, all members must use org ID to access it.

## Best Practices

**Your responsibilities:**
- Pass the correct User ID for each user
- Verify user permissions before executing organization tools
- Never use 'default' in production with multiple users
- Keep User IDs consistent across your application and Composio
- Use stable identifiers that won't change over time

**Data isolation:** Composio ensures complete isolation between User IDs. Users cannot access another ID's connections or data.

---

# Using Triggers (/docs/using-triggers)

When events occur in connected apps (like new Slack messages or GitHub commits), triggers automatically send the event data to your application.

Each event is delivered as a structured payload to your webhook endpoint (via webhooks or WebSockets), enabling your applications or AI agents to respond proactively.

> **Prerequisites**: 
Before proceeding, ensure you've created an [auth config](/docs/authenticating-tools#creating-an-auth-config) and [established a connection](/docs/authenticating-tools#hosted-authentication-connect-link) to an app (e.g., Slack, GitHub). Triggers are scoped to specific users - learn about [User Management](/docs/user-management) for guidance on structuring User IDs.

## Creating a trigger

You can create triggers using either the Composio dashboard or programmatically via the SDK.

### Using Dashboard

To create triggers through the dashboard:

1. Navigate to the [Auth Configs](https://platform.composio.dev?next_page=%2Fauth-configs) page
2. Select the auth config
3. Click "Add Trigger" and navigate to "Active Triggers" tab to fetch the trigger ID

Some triggers require additional configuration. The dashboard will prompt you for any required fields during setup.

### Using SDK

Create triggers programmatically by providing the trigger type and any required configuration. The trigger instance will be created using the toolkit version configured during Composio initialization (defaults to `'latest'`).

**Python:**

```python
from composio import Composio

composio = Composio(api_key="your-api-key")
user_id = "user-id-123435"

# Check what configuration is required
trigger_type = composio.triggers.get_type("GITHUB_COMMIT_EVENT")
print(trigger_type.config)
# Returns: {"properties": {...}, "required": ["owner", "repo"], ...}

# Create trigger with the required config
trigger = composio.triggers.create(
    slug="GITHUB_COMMIT_EVENT",
    user_id=user_id,
    trigger_config={"owner": "your-repo-owner", "repo": "your-repo-name"},
)
print(f"Trigger created: {trigger.trigger_id}")
```
  
  
**TypeScript:**

```typescript
import { Composio } from '@composio/core';

const composio = new Composio({apiKey: "your-api-key"});
const userId = 'user-id-123435';

// Check what configuration is required
const triggerType = await composio.triggers.getType("GITHUB_COMMIT_EVENT");
console.log(triggerType.config);
// Returns: {"properties": {...}, "required": ["owner", "repo"], ...}

// Create trigger with the required config
const trigger = await composio.triggers.create(
    userId,
    'GITHUB_COMMIT_EVENT',

        triggerConfig: {
            owner: 'your-repo-owner',
            repo: 'your-repo-name'

);
console.log(`Trigger created: ${trigger.triggerId}`);
```
  

> 
To use a specific toolkit version when creating triggers, configure `toolkitVersions` during initialization. See [Toolkit Versioning](/docs/toolkit-versioning) for more details.

## Subscribing to triggers

### Webhooks

The recommended way to subscribe to triggers is through webhooks. Configure your webhook URL in the [Event & Trigger settings](https://platform.composio.dev?next_page=/settings/events).

Use a publicly accessible URL where Composio can send event payloads. This endpoint should be able to process incoming POST requests containing the trigger data.

> 
**Local development:** Use [ngrok](https://ngrok.com) or [webhook.site](https://webhook.site) to expose your local server to the internet for testing.

Webhook payloads contain:
- `type`: The trigger type identifier
- `data`: The actual event data
- `timestamp`: When the event occurred
- `log_id`: Unique identifier for this event

Below are examples of webhook handlers for FastAPI and Next.js applications:

**Python:**

```python
@app.post("/webhook")
async def webhook_handler(request: Request):
    payload = await request.json()

    trigger_type = payload.get("type")
    event_data = payload.get("data", {})

    if trigger_type == "github_star_added_event":
        repo_name = event_data.get("repository_name")
        starred_by = event_data.get("starred_by")
        print(f"Repository {repo_name} starred by {starred_by}")
        # Add your business logic here

    return {"status": "success", "message": "Webhook processed"}
```
  
  
**TypeScript:**

```typescript
import { TriggerEvent } from '@composio/core';
type NextApiRequest = { body: any };
type NextApiResponse = { status: (code: number) => { json: (data: any) => void }; json: (data: any) => void };
type GitHubStarEventData = { repository_name: string; starred_by: string };
// ---cut---
export default async function webhookHandler(req: NextApiRequest, res: NextApiResponse) {
  const payload = req.body;

  if (payload.type === 'github_star_added_event') {
    const event: TriggerEvent

## Troubleshooting

View detailed trigger logs and debug issues on the [Composio dashboard](https://platform.composio.dev?next_page=/logs/triggers).

---

# Migration guides (/docs/migration-guide)

## Available migration guides

  
    Migrate from the old Composio SDK to the new SDK, including breaking changes, new features, and updated APIs.

    [View SDK migration guide →](/docs/migration-guide/new-sdk)
  

  
    Migrate to use the toolkit versioning system.

    [View versioning migration guide →](/docs/migration-guide/toolkit-versioning)

---

# Our next generation SDKs (/docs/migration-guide/new-sdk)

In the last few months, we have experienced very rapid growth in usage of our platform. As such, our team has been working hard to radically improve the performance and developer experience of our platform.

A lot of these changes have happened in the background, but we are excited to finally share our new SDKs with you that complement our new infra.

The new API features improved usability, enhanced stability, and better scalability. The SDKs built on top of it simplify the developer experience, making it easier than ever to build useful agents.

## What's new?

A lot of the changes are on the infra side, but from the SDK point of view, here is what you can expect:
- Faster and more reliable tool execution
- A simpler but more opinionated SDK
- Much more intuitive and consistent naming conventions
- A vastly improved TypeScript SDK that is meaningfully more type-safe and has full feature parity with the Python SDK

There aren't too many new flashy features here (yet) mainly because we wanted to get the bones right — but we feel we have a solid foundation to ship incredible new experiences on top very quickly.

## State of the new SDK and what is happening with the old SDKs?

Currently, the new SDKs are in a preview release. These new SDKs come almost fully formed, we do not expect many breaking changes to them but are releasing them in a preview state to get feedback and make necessary changes before locking them in.

As we lock the new SDKs in place, we will deprecate support for the old SDKs. They will continue to work for the foreseeable future but are no longer actively maintained. We will continue to push security updates and fix any critical bugs but will not support any new functionality in them.

We urge you to upgrade to the new SDKs as soon as possible.

## Nomenclature

We have updated several key terms in the SDK and API to improve clarity and consistency. The following table summarizes these changes:

| Previous Term | Current Term       | Definition                                                                |
|---------------|--------------------|--------------------------------------------------------------------------|
| Actions       | Tools              | Individual operations or capabilities that can be performed by an LLM agent |
| Apps          | Toolkits           | A collection of tools grouped under a single application                |
| Integration   | Auth Config        | Configuration containing developer credentials and application-level settings such as scopes and API endpoints. Scoped to a toolkit. |
| Connection    | Connected accounts | User-linked accounts associated with a toolkit                          |
| Entity ID     | User ID            | The identifier of the user performing the action (UUID or email)        |
| Trigger       | Trigger            | An event that can be subscribed to                                      |
| Toolsets      | Providers          | LLM or agent framework that can be used with Composio to create agents |

## Switch to nano IDs from UUIDs

We have transitioned from UUIDs to nano IDs throughout the platform for the following reasons:

- **Improved readability**: UUIDs are lengthy and difficult to read
- **Better usability**: Easier to copy with a single double-click
- **Better organization**: Nano IDs allow us to distinguish between different resource types through prefixes

| Feature           | Nano ID Prefix | Example            |
|-------------------|----------------|--------------------|
| Connected Account | `ca_`          | `ca_8x9w2l3k5m`    |
| Auth Config       | `ac_`          | `ac_1234567890`    |
| Trigger           | `ti_`          | `ti_So9EQf8XnAcy`  |

> 
Nano IDs are short, unique, and prefixed to indicate the resource type.

## SDK Changes

Upgrade to the latest SDK version using the appropriate package manager:

**Python:**

```bash
pip install -U composio
```
  
  
**TypeScript:**

```bash
npm install @composio/core
```
  

Both SDKs now implement proper namespacing for each concept.

### User ID scoping

The concept of `entity_id` has been expanded and renamed to `user_id`.

All operations are now scoped to a user ID, including:
- Fetching tools
- Initiating connections
- Executing tools
- Managing triggers

This change provides explicit specification of the user for whom the action is being performed. When a user may have multiple accounts (such as work and personal Gmail connections), you can use the more specific connected account ID.

### Replacing ToolSets with Providers

We have deprecated "toolsets" in favor of "providers". This change allows Composio to provide deeper standardization for tool implementation across different frameworks.

Previously, you needed to import and use a framework-specific `ComposioToolSet` class:

**Python (previous):**

```python
from composio_openai import ComposioToolSet, Action, App
from openai import OpenAI

toolset = ComposioToolSet()
```
  
  
**TypeScript (previous):**

```typescript
// @noErrors
import { OpenAIToolSet } from 'composio-core';

const toolset = new OpenAIToolSet();
```
  

The SDK structure is now framework-agnostic and includes the OpenAI provider out of the box:

**Python (current):**

```python
from composio import Composio
# from composio_langchain import LangchainProvider

composio = Composio()
# composio = Composio(provider=LangchainProvider())

tools = composio.tools.get(
    user_id="0001",
    tools=["LINEAR_CREATE_LINEAR_ISSUE", "GITHUB_CREATE_COMMIT"]
)
# tools returned is formatted for the provider. by default, OpenAI.
```
  
  
**TypeScript (current):**

```typescript
// @noErrors
import { Composio } from '@composio/core';
// import { VercelProvider } from '@composio/vercel';

const composio = new Composio({
  // provider: new VercelProvider(),
});
// Can specify other providers too, like OpenAI, Anthropic, Vercel AI SDK.

const tools = await composio.tools.get('user@example.com', {
  tools: ['LINEAR_CREATE_LINEAR_ISSUE', 'GITHUB_CREATE_COMMIT'],
});
// tools returned is formatted for the provider. by default, OpenAI.
```
  

You can now use the same tools across any framework with our unified interface, or create custom toolsets for frameworks we don't yet support.

Read more about [providers in our documentation](/docs/providers/openai) and explore the [complete list of available providers](/docs/providers/openai).

### Fetching and filtering tools

Previously, you could filter tools by:
- Apps
- Action names (tool names)
- Tags

You could also specify an `important` flag to retrieve the most important tools:

**Python (previous):**

```python
from composio_openai import ComposioToolSet, Action, App
from openai import OpenAI

toolset = ComposioToolSet()
client = OpenAI()

tools = toolset.get_tools(
    actions=[Action.GITHUB_GET_THE_AUTHENTICATED_USER], check_connected_accounts=True
)

tools = toolset.get_tools(apps=[App.GITHUB, App.LINEAR, App.SLACK], check_connected_accounts=True)
```
  
  
**TypeScript (previous):**

```typescript
// @noErrors
import { OpenAIToolSet } from 'composio-core';

const toolset = new OpenAIToolSet();

const tools_1 = await toolset.getTools({ apps: ['GITHUB'] });
const tools_2 = await toolset.getTools({
  actions: ['GITHUB_GET_THE_AUTHENTICATED_USER', 'LINEAR_CREATE_LINEAR_ISSUE'],
});
```
  

You can now filter tools by:
- Toolkits
- Tool slugs
- Limit parameter
- Search query

The `important` flag has been removed. Instead, tools are returned in order of importance by default:

> 
Since `user_id` is now explicitly required, the `check_connected_accounts` flag is no longer necessary.

**Python (current):**

```python
from composio import Composio

composio = Composio()

user_id = "user@acme.org"

tools_1 = composio.tools.get(user_id=user_id, toolkits=["GITHUB", "LINEAR"])

tools_2 = composio.tools.get(user_id=user_id, toolkits=["SLACK"], limit=5)  # Default limit=20

tools_3 = composio.tools.get(
    user_id=user_id,
    tools=["GITHUB_CREATE_AN_ISSUE", "GITHUB_CREATE_AN_ISSUE_COMMENT", "GITHUB_CREATE_A_COMMIT"],
)

tools_4 = composio.tools.get(user_id="john", search="hackernews posts")
```
  
  
**TypeScript (current):**

```typescript
// @noErrors
import { Composio } from '@composio/core';

const userId = 'user@acme.org';

const composio = new Composio();

const tools_1 = await composio.tools.get(userId, {
  toolkits: ['GITHUB', 'LINEAR'],
});

const tools_2 = await composio.tools.get(userId, {
  toolkits: ['GITHUB'],
  limit: 5, // Default limit=20
});

const tools_3 = await composio.tools.get(userId, {
  tools: ['GITHUB_CREATE_AN_ISSUE', 'GITHUB_CREATE_AN_ISSUE_COMMENT', 'GITHUB_CREATE_A_COMMIT'],
});

const tools_4 = await composio.tools.get(userId, {
  search: 'hackernews posts',
});
```
  

### Fetching raw tool data

To examine the raw schema definition of a tool for understanding input/output parameters or building custom logic around tool definitions, use the following methods:

**Python (current):**

```python
from composio import Composio

composio = Composio()

tool = composio.tools.get_raw_composio_tool_by_slug("HACKERNEWS_GET_LATEST_POSTS")

print(tool.model_dump_json())
```
  
  
**TypeScript (current):**

```typescript
// @noErrors
import { Composio } from '@composio/core';

const composio = new Composio();

const tool = await composio.tools.getRawComposioToolBySlug('GITHUB_GET_OCTOCAT');

console.log(JSON.stringify(tool, null, 2));
```
  

### Executing tools

Tool execution remains largely unchanged, with `user_id` now explicitly required.

For agentic frameworks, the tool object returned from `tools.get` is now the respective framework's native tool object. Tool call execution is handled by the agentic framework itself.

> 
For non-agentic frameworks, Composio provides a helper function to execute tool calls.

**Python v3:**

```python
from composio import Composio
from openai import OpenAI

openai_client = OpenAI()
composio = Composio()

tools = composio.tools.get(user_id="user@acme.com", tools=["GITHUB_GET_THE_ZEN_OF_GITHUB"])
response = openai_client.chat.completions.create(
    model="gpt-4.1",
    messages=[{"role": "user", "content": "gimme some zen."}],
    tools=tools,
)

result = composio.provider.handle_tool_calls(user_id="user@acme.com", response=response)
print(result)
```
  
  
**TypeScript v3:**

```typescript
// @noErrors
import { Composio } from '@composio/core';
import { AnthropicProvider } from '@composio/anthropic';
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic();
const composio = new Composio({
  provider: new AnthropicProvider(),
});

const userId = 'user@example.com';
const tools = await composio.tools.get(userId, {
  toolkits: ['GMAIL'],
});

const msg = await anthropic.messages.create({
  model: 'claude-3-7-sonnet-latest',
  tools: tools,
  messages: [

      role: 'user',
      content: "Say hi to 'soham@composio.dev'",
    },
  ],
  max_tokens: 1024,
});

const result = await composio.provider.handleToolCalls(userId, msg);
console.log('Tool results:', result);
```
  

For more information on executing tools for different frameworks, see [Replacing ToolSets with Providers](#replacing-toolsets-with-providers).

### Tool Modifiers (formerly Tool Processors)

Tool processors have been renamed to *tool modifiers* and now provide an improved developer experience. The implementation is now available in TypeScript too! (previously Python-only).

```python title="Python (previous)"
from composio_openai import ComposioToolSet, Action

toolset = ComposioToolSet()

def my_schema_processor(schema: dict) -> dict: ...
def my_preprocessor(inputs: dict) -> dict: ...
def my_postprocessor(result: dict) -> dict: ...

# Get tools with the modified schema
processed_tools = toolset.get_tools(
    actions=[Action.GMAIL_SEND_EMAIL],
    processors={
        # Applied BEFORE the LLM sees the schema
        "schema": {Action.SOME_ACTION: my_schema_processor},
        # Applied BEFORE the tool executes
        "pre": {Action.SOME_ACTION: my_preprocessor},
        # Applied AFTER the tool executes, BEFORE the result is returned
        "post": {Action.SOME_ACTION: my_postprocessor},
    },
)
```

| Previous          | Current                 |
|-------------------|-------------------------|
| `pre` processor   | `beforeExecute` modifier |
| `post` processor  | `afterExecute` modifier  |
| `schema` processor| `schema` modifier        |

The modifiers now leverage language-specific features to provide a more natural developer experience.

While tool processors could previously be applied during SDK initialization, tool fetching, and tool execution, we have restructured them as follows:
- **Chat Completion providers**: Modifiers are specified and applied during tool execution
- **Agentic frameworks**: Modifiers are specified and applied during tool fetching

#### Schema Modifiers

The following example demonstrates schema modifier usage, applicable across all providers:

**Python (current):**

```python
from composio import Composio, schema_modifier
from composio.types import Tool

user_id = "your@email.com"

@schema_modifier(tools=["HACKERNEWS_GET_LATEST_POSTS"])
def modify_schema(
    tool: str,
    toolkit: str,
    schema: Tool,
) -> Tool:
    _ = schema.input_parameters["properties"].pop("page", None)
    schema.input_parameters["required"] = ["size"]
    return schema

tools = composio.tools.get(
    user_id=user_id,
    tools=["HACKERNEWS_GET_LATEST_POSTS", "HACKERNEWS_GET_USER"],
    modifiers=[
        modify_schema,
    ]
)
```
  
  
**TypeScript (current):**

```typescript
// @noErrors
import { Composio } from '@composio/core';
import { OpenAI } from 'openai';

const userId = 'your@email.com';
const composio = new Composio();

// Schema modifier to delete the `page` argument from the `HACKERNEWS_GET_LATEST_POSTS` tool
const tools = await composio.tools.get(
  userId,

    tools: ['HACKERNEWS_GET_LATEST_POSTS', 'HACKERNEWS_GET_USER'],
  },

    modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
      if (toolSlug === 'HACKERNEWS_GET_LATEST_POSTS') {
        const { inputParameters } = schema;
        if (inputParameters?.properties) {
          delete inputParameters.properties['page'];

        inputParameters.required = ['size'];

      return schema;
    },

);

console.log(JSON.stringify(tools, null, 2));
```
  

#### Before Modifiers

The following example shows creating and using a before modifier for a Chat Completion provider. For agentic frameworks, view the [complete before modifier documentation](/docs/modify-tool-behavior/before-execution-modifiers):

**Python (current):**

```python
@before_execute(tools=["HACKERNEWS_GET_LATEST_POSTS"])
def before_execute_modifier(
    tool: str,
    toolkit: str,
    params: ToolExecuteParams,
) -> ToolExecuteParams:
    params["arguments"]["size"] = 1
    return params

# Get tools
tools = composio.tools.get(user_id=user_id, slug="HACKERNEWS_GET_LATEST_POSTS")
```
  
  
**TypeScript (current):**

```typescript
// @noErrors
const result_1 = await composio.tools.execute(
  'HACKERNEWS_GET_LATEST_POSTS',

    userId,
    arguments: JSON.parse(toolArgs),
  },

    beforeExecute: ({ toolSlug, toolkitSlug, params }) => {
      if (toolSlug === 'HACKERNEWS_GET_LATEST_POSTS') {
        params.arguments.size = 1;

      console.log(params);
      return params;
    },

);
```
  

#### After Modifiers

The following example shows creating and using an after modifier for a Chat Completion provider. For agentic frameworks, view the [complete after modifier documentation](/docs/modify-tool-behavior/after-execution-modifiers):

**Python (current):**

```python
@after_execute(tools=["HACKERNEWS_GET_USER"])
def after_execute_modifier(
    tool: str,
    toolkit: str,
    response: ToolExecutionResponse,
) -> ToolExecutionResponse:
    return {
        **response,
        "data": {
            "karma": response["data"]["karma"],
        },

tools = composio.tools.get(user_id=user_id, slug="HACKERNEWS_GET_USER")
```
  
  
**TypeScript (current):**

```typescript
// @noErrors
const result_2 = await composio.tools.execute(
  'HACKERNEWS_GET_USER',

    userId,
    arguments: JSON.parse(toolArgs),
  },

    afterExecute: ({ toolSlug, toolkitSlug, result }) => {
      if (toolSlug === 'HACKERNEWS_GET_USER') {
        const { data } = result;
        const { karma } = data.response_data as { karma: number };
        return {
          ...result,
          data: { karma },
        };

      return result;
    },

);
```
  

### Custom Tools

The SDK continues to support custom tools. [Creating tools from your methods](/docs/custom-tools#creating-a-custom-tool) remains possible. We recommend reviewing the [detailed custom tools documentation](/docs/custom-tools#creating-a-custom-tool) for more information.

Due to changes in the SDK architecture, creating custom tools that use Composio's managed authentication has been modified. In the previous SDK, you could create a custom tool as follows:

**Python (previous):**

```python
# Python Example using execute_request
from composio import action, ComposioToolSet
import typing as t

toolset = ComposioToolSet()

@action(toolname="github") # Associate with GitHub app for auth
def get_github_repo_topics(
    owner: t.Annotated[str, "Repository owner username"],
    repo: t.Annotated[str, "Repository name"],
    execute_request: t.Callable # Injected by Composio
) -> dict:
    """Gets the topics associated with a specific GitHub repository."""
    response_data = execute_request(
        endpoint=f"/repos/{owner}/{repo}/topics", # API path relative to base URL
        method="GET"
    )
    if isinstance(response_data, dict):
        return {"topics": response_data.get("names", [])}
```
  
  
**TypeScript (previous):**

```typescript
// @noErrors
import { OpenAIToolSet, type ActionExecutionResDto } from "composio-core";
import { z } from "zod";

const toolset = new OpenAIToolSet();

await toolset.createAction({
    actionName: "get_github_repo_topics",
    toolName: "github",
    description: "Gets the topics associated with a specific GitHub repository.",
    inputParams: z.object({
        owner: z.string().describe("Repository owner username"),
        repo: z.string().describe("Repository name"),
    }),
    callback: async (inputParams, _authCredentials, executeRequest): Promise => {
         const { owner, repo } = inputParams as { owner: string, repo: string };
         const response = await executeRequest({
             endpoint: `/repos/${owner}/${repo}/topics`,
             method: "GET",
             parameters: [],
         });

         const topics = (response as any)?.names ?? [];
         return { successful: true, data: { topics: topics } };

});
```
  

The *execute tool request* method handles injection of the appropriate base URL and authentication credentials for the tool:

**Python (current):**

```python
from pydantic import BaseModel, Field
from composio import Composio
from composio.core.models.custom_tools import ExecuteRequestFn

composio = Composio()

class GetIssueInfoInput(BaseModel):
    issue_number: int = Field(
        ...,
        description="The number of the issue to get information about",
    )

# function name will be used as slug
@composio.tools.custom_tool(toolkit="github")
def get_issue_info(
    request: GetIssueInfoInput,
    execute_request: ExecuteRequestFn,
    auth_credentials: dict,
) -> dict:
    """Get information about a GitHub issue."""
    response = execute_request(
        endpoint=f"/repos/composiohq/composio/issues/{request.issue_number}",
        method="GET",
        parameters=[

                "name": "Accept",
                "value": "application/vnd.github.v3+json",
                "type": "header",
            },

                "name": "Authorization",
                "value": f"Bearer {auth_credentials['access_token']}",
                "type": "header",
            },
        ],
    )
    return {"data": response.data}
```
  
  
**TypeScript (current):**

```typescript
// @noErrors
import { Composio } from "@composio/core";
import z from "zod";

const composio = new Composio();

const tool = await composio.tools.createCustomTool({
    slug: 'GITHUB_STAR_COMPOSIOHQ_REPOSITORY',
    name: 'Github star composio repositories',
    toolkitSlug: 'github',
    description: 'Star any specificied repo of `composiohq` user',
    inputParams: z.object({
      repository: z.string().describe('The repository to star'),
      page: z.number().optional().describe('Pagination page number'),
      customHeader: z.string().optional().describe('Custom header'),
    }),
    execute: async (input, connectionConfig, executeToolRequest) => {
      const result = await executeToolRequest({
        endpoint: `/user/starred/composiohq/${input.repository}`,
        method: 'PUT',
        body: {},
        parameters: [

            name: 'page',
            value: input.page?.toString() || '1',
            in: 'query',
          },

            name: 'x-custom-header',
            value: input.customHeader || 'default-value',
            in: 'header',
          },
        ],
      });
      return result;
    },
  });
```
  

For more information, including executing custom tools and defining custom headers and query parameters, refer to the [Custom Tools](/docs/custom-tools) documentation.

### Auth configs (formerly integrations)

Integrations are now called *auth configs*. While the terminology has changed, the underlying concept remains the same.

Auth configs store the configuration required for authentication with a given toolkit, including OAuth developer credentials, configurable base URLs, and scopes.

Auth configs now use nano IDs instead of UUIDs:

| Previous (UUID) Example              | Current (Nano ID) Example |
| :----------------------------------- | :------------------------ |
| `b7a9c1e2-3f4d-4a6b-8c2e-1d2f3a4b5c6d` | `ac_8x9w2l3k5m`             |

We recommend storing auth config nano IDs in your database for connecting users to the appropriate auth configuration.

For most use cases, you will create auth configs through the dashboard, and this process remains unchanged. Read more about [creating auth configs](/docs/authenticating-tools#creating-an-auth-config) and [customizing auth configs](/docs/custom-auth-configs).

Creating auth configs programmatically in the previous SDK:

**Python (previous):**

```python
from composio_openai import App, ComposioToolSet

toolset = ComposioToolSet()

integration = toolset.create_integration(
    app=App.GITHUB,
    auth_mode="OAUTH2",
    use_composio_oauth_app=True,
    # For use_composio_oauth_app=False, you can provide your own OAuth app credentials here
    # auth_config={
    #     "client_id": "123456",
    #     "client_secret": "123456"
    # }

)
print(integration.id)
```
  
  
**TypeScript (previous):**

```typescript
// @noErrors
import { OpenAIToolSet } from "composio-core";

const composioToolset = new OpenAIToolSet();

const integration = await composioToolset.integrations.create({
    name: "gmail_integration",
    appUniqueKey: "gmail",
    forceNewIntegration: true,
    useComposioAuth: false,
    // For useComposioAuth: false, you can provide your own OAuth app credentials here
    // authScheme: "OAUTH2",
    // authConfig: {
    //     clientId: "123456",
    //     clientSecret: "123456"
    // }
})

console.log(integration.id)
```
  

Creating auth configs programmatically in the current SDK:

**Python (current):**

```python
from composio import Composio

composio = Composio()

# Use composio managed auth
auth_config = composio.auth_configs.create(
    toolkit="notion",
    options={
        "type": "use_composio_managed_auth",
        # "type": "use_custom_auth",
        # "auth_scheme": "OAUTH2",
        # "credentials": {
        #     "client_id": "1234567890",
        #     "client_secret": "1234567890",
        #     "oauth_redirect_uri": "https://backend.composio.dev/api/v3/toolkits/auth/callback",
        # },
    },
)
print(auth_config)
```
  
  
**TypeScript (current):**

```typescript
// @noErrors
import { Composio } from '@composio/core';

const composio = new Composio();

const authConfig = await composio.authConfigs.create('LINEAR', {
  name: 'Linear',
  type: 'use_composio_managed_auth',
  //   type: "use_custom_auth",
  //   credentials: {
  //     client_id: "1234567890",
  //     client_secret: "1234567890",
  //     oauth_redirect_uri: "https://backend.composio.dev/api/v3/toolkits/auth/callback",
  // },
});

console.log(authConfig);
```
  

For using custom authentication credentials, refer to the [Programmatic Auth Configs](/docs/programmatic-auth-configs) documentation.

> 
The callback URL for creating custom OAuth configs is now `https://backend.composio.dev/api/v3/toolkits/auth/callback`. The previous URL was `https://backend.composio.dev/api/v1/auth-apps/add`.

### Connected accounts / User IDs

The primary change in connected accounts and user IDs is that user IDs are now a more prominent concept compared to entities in previous versions.

We have simplified the process of connecting a user to a toolkit. Instead of multiple methods and parameters for initiating a connection, both the SDK and API now require only a `user_id` and `auth_config_id` to initiate a connection.

This approach is more explicit and works well with the ability for developers to have multiple auth configs for a given toolkit.

Connected accounts now use nano IDs instead of UUIDs:

| Previous (UUID) Example              | Current (Nano ID) Example |
| :----------------------------------- | :------------------------ |
| `b7a9c1e2-3f4d-4a6b-8c2e-1d2f3a4b5c6d` | `ca_8x9w2l3k5m`             |

Previously, you might have initiated a connection like this:

**Python (previous):**

```python
from composio_openai import ComposioToolSet

toolset = ComposioToolSet()
user_id = "your_user_unique_id"
google_integration_id = "0000-0000"

entity = toolset.get_entity(id=user_id)

try:
    print(f"Initiating OAuth connection for entity {entity.id}...")
    connection_request = toolset.initiate_connection(
        integration_id=google_integration_id,
        entity_id=user_id,
        # Optionally add: redirect_url="https://yourapp.com/final-destination"
        # if you want user sent somewhere specific *after* Composio finishes.
    )

    # Check if a redirect URL was provided (expected for OAuth)
    if connection_request.redirectUrl:
        print(f"Received redirect URL: {connection_request.redirectUrl}")
    else:
        print("Error: Expected a redirectUrl for OAuth flow but didn't receive one.")

except Exception as e:
    print(f"Error initiating connection: {e}")
```
  
  
**TypeScript (previous):**

```typescript
// @noErrors
import { OpenAIToolSet } from "composio-core";

const toolset = new OpenAIToolSet();
const userId = "your_user_unique_id";
const googleIntegrationId = "0000-0000";

console.log(`Initiating OAuth connection for entity ${userId}...`);
const connectionRequest = await toolset.connectedAccounts.initiate({
    integrationId: googleIntegrationId,
    entityId: userId,
    // Optionally add: redirectUri: "https://yourapp.com/final-destination"
    // if you want user sent somewhere specific *after* Composio finishes.
});

// Check if a redirect URL was provided (expected for OAuth)
if (connectionRequest?.redirectUrl) {
    console.log(`Received redirect URL: ${connectionRequest.redirectUrl}`);
    // Proceed to Step 2: Redirect the user
    // Return or pass connectionRequest to the next stage
} else {
    console.error("Error: Expected a redirectUrl for OAuth flow but didn't receive one.");

```
  

The current process for initiating a connection is as follows:

**Python (current):**

```python
from composio import Composio

linear_auth_config_id = "ac_1234"
user_id = "user@email.com"
composio = Composio()

# Create a new connected account
connection_request = composio.connected_accounts.initiate(
    user_id=user_id,
    auth_config_id=linear_auth_config_id,
)
print(connection_request.redirect_url)

# Wait for the connection to be established
connected_account = connection_request.wait_for_connection()
print(connected_account)
```
  
  
**TypeScript (current):**

```typescript
// @noErrors
import { Composio } from "@composio/core";

const composio = new Composio();
const linearAuthConfigId = "ac_1234";
const userId = "user@email.com";

// Initiate the OAuth connection request
const connRequest = await composio.connectedAccounts.initiate(userId, linearAuthConfigId);

const { redirectUrl, id } = connRequest;
console.log(redirectUrl);

// Wait for the connection to be established
await connRequest.waitForConnection();

// If you only have the connection request ID, you can also wait using:
await composio.connectedAccounts.waitForConnection(id);
```
  

### Triggers

Composio continues to support listening to application events using triggers through WebSockets and webhooks.

#### Creating triggers

The process for creating triggers and specifying their configuration has been redesigned for improved clarity and intuitiveness.

Some triggers require configuration, such as repository names for GitHub triggers or channel names for Slack triggers. The process usually follows the pattern of fetching the trigger type and then creating the trigger with the appropriate configuration.

**Python (current):**

```python
from composio import Composio

composio = Composio()

user_id = "user@example.com"
trigger_config = composio.triggers.get_type("GITHUB_COMMIT_EVENT")
print(trigger_config.config)
### Trigger Config
# {
#     "properties": {
#         "owner": {
#             "description": "Owner of the repository",
#             "title": "Owner",
#             "type": "string"
#         },
#         "repo": {
#             "description": "Repository name",
#             "title": "Repo",
#             "type": "string"
#         }
#     },
#     "required": ["owner", "repo"],
#     "title": "WebhookConfigSchema",
#     "type": "object"

trigger = composio.triggers.create(
    slug="GITHUB_COMMIT_EVENT",
    user_id=user_id,
    trigger_config={"repo": "composiohq", "owner": "composio"},
)
print(trigger)

# Managing triggers

composio.triggers.enable(id="ti_abcd123")
```
  
  
**TypeScript (current):**

```typescript
// @noErrors
import { Composio } from '@composio/core';

const composio = new Composio();

const userId = 'user@acme.com';
// Fetch the trigger details
const triggerType = await composio.triggers.getType('GITHUB_COMMIT_EVENT');
console.log(JSON.stringify(triggerType.config, null, 2));
/*--- Trigger config ---

  "properties": {
    "owner": {
      "description": "Owner of the repository",
      "title": "Owner",
      "type": "string"
    },
    "repo": {
      "description": "Repository name",
      "title": "Repo",
      "type": "string"

  },
  "required": ["owner", "repo"],
  "title": "WebhookConfigSchema",
  "type": "object"

*/

const createResponse = await composio.triggers.create(userId, 'GITHUB_COMMIT_EVENT', {
  triggerConfig: {
    owner: 'composiohq',
    repo: 'composio',
  },
});
console.log(createResponse);
```
  

#### Enabling/Disabling triggers

You can enable or disable triggers through either the SDK or the dashboard. The dashboard process remains unchanged.

Managing triggers with the SDK:

**Python:**

```python
# Disable a trigger instance
disabled_instance = composio.triggers.disable(trigger_id="ti_abcd123")
print(disabled_instance)
```
  
  
**TypeScript:**

```typescript
// @noErrors
await composio.triggers.disable("ti_abcd123");
```
  

If needed, the trigger can be enabled again.

**Python:**

```python
# Enable a trigger instance
enabled_instance = composio.triggers.enable(trigger_id="ti_abcd123")
print(enabled_instance)
```
  
  
**TypeScript:**

```typescript
// @noErrors
await composio.triggers.enable("ti_abcd123");
```
  

#### Listening to triggers

We recommend listening to triggers through webhooks. The following are example routes for Next.js and FastAPI.

For development, you can also [listen to triggers through the SDK](/docs/using-triggers#subscribing-to-triggers-using-the-sdk-for-development).

**FastAPI:**

```python title="app/route.py"
from fastapi import FastAPI, Request, HTTPException
from typing import Dict, Any
import uvicorn
import json
import hmac
import hashlib
import base64
import os

def verify_webhook_signature(request: Request, body: bytes) -> bool:
    """Verify Composio webhook signature"""
    webhook_signature = request.headers.get("webhook-signature")
    webhook_id = request.headers.get("webhook-id")
    webhook_timestamp = request.headers.get("webhook-timestamp")
    webhook_secret = os.getenv("COMPOSIO_WEBHOOK_SECRET")

    if not all([webhook_signature, webhook_id, webhook_timestamp, webhook_secret]):
        raise HTTPException(status_code=400, detail="Missing required webhook headers or secret")

    if not webhook_signature.startswith("v1,"):
        raise HTTPException(status_code=401, detail="Invalid signature format")

    received = webhook_signature[3:]
    signing_string = f"{webhook_id}.{webhook_timestamp}.{body.decode()}"
    expected = base64.b64encode(
        hmac.new(webhook_secret.encode(), signing_string.encode(), hashlib.sha256).digest()
    ).decode()

    if not hmac.compare_digest(received, expected):
        raise HTTPException(status_code=401, detail="Invalid webhook signature")

    return True

@app.post("/webhook")
async def webhook_handler(request: Request):
    payload = await request.json()

    trigger_type = payload.get("type")
    event_data = payload.get("data", {})

    if trigger_type == "github_star_added_event":
        repo_name = event_data.get("repository_name")
        starred_by = event_data.get("starred_by")
        print(f"Repository {repo_name} starred by {starred_by}")
        # Add your business logic here

    return {"status": "success", "message": "Webhook processed"}
```
  
  
**Next.js:**

```typescript title="app/api/webhook/route.ts"
// @noErrors
import type { NextApiRequest, NextApiResponse } from 'next';
import { TriggerEvent } from '@composio/core';
import crypto from 'crypto';

type GitHubStarEventData = {
  repository_name: string;
  repository_url: string;
  starred_by: string;
  starred_at: string;
};

function verifyWebhookSignature(
  req: NextApiRequest,
  body: string
): boolean {
  const signature = req.headers['webhook-signature'] as string | undefined;
  const msgId = req.headers['webhook-id'] as string | undefined;
  const timestamp = req.headers['webhook-timestamp'] as string | undefined;
  const secret = process.env.COMPOSIO_WEBHOOK_SECRET;

  if (!signature || !msgId || !timestamp || !secret) {
    throw new Error('Missing required webhook headers or secret');

  if (!signature.startsWith('v1,')) {
    throw new Error('Invalid signature format');

  const received = signature.slice(3);
  const signingString = `${msgId}.${timestamp}.${body}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signingString)
    .digest('base64');

  return crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));

export default async function webhookHandler(req: NextApiRequest, res: NextApiResponse) {
  const payload = req.body;

  if (payload.type === 'github_star_added_event') {
    const event: TriggerEvent = {
      type: payload.type,
      timestamp: payload.timestamp,
      data: payload.data
    };

    console.log(`Repository ${event.data.repository_name} starred by ${event.data.starred_by}`);
    // Add your business logic here

  res.status(200).json({
    status: 'success',
    message: 'Webhook processed'
  });

```
  

## Coming Soon

### Local tools

Previously, the Python SDK included *[local tools](https://github.com/ComposioHQ/composio/tree/master/python/composio/tools/local)*. These were tools defined within the SDK and consisted of local shell and code-related tools such as "clipboard", "sqltool", and "shelltool".

This feature is currently in development for both Python and TypeScript SDKs, with newly created tools built for improved agent accuracy.

This feature is currently in development for both Python and TypeScript SDKs.

## API Endpoints

The following table lists important API endpoints that have changed. You can use this reference to quickly find the new v3 API endpoint for migration:

> 
This list is not exhaustive. Please refer to the [API Reference](/reference) for the complete list of endpoints.

### Toolkits (formerly Apps)

| Previous Endpoint | Current Endpoint |
| :--- | :--- |
| `GET /api/v1/apps` | `GET /api/v3/toolkits` |
| `GET /api/v1/apps/list/categories` | `GET /api/v3/toolkits/categories` |
| `GET /api/v1/apps/{appName}` | `GET /api/v3/toolkits/{slug}` |

### Tools (formerly Actions)

| Previous Endpoint | Current Endpoint |
| :--- | :--- |
| `GET /api/v2/actions` | `GET /api/v3/tools` |
| `GET /api/v2/actions/list/enums` | `GET /api/v3/tools/enum` |
| `GET /api/v2/actions/{actionId}` | `GET /api/v3/tools/{tool_slug}` |
| `POST /api/v2/actions/{actionId}/execute` | `POST /api/v3/tools/execute/{tool_slug}` |
| `POST /api/v2/actions/{actionId}/execute/get.inputs` | `POST /api/v3/tools/execute/{tool_slug}/input` |
| `POST /api/v2/actions/proxy` | `POST /api/v3/tools/execute/proxy` |

### Auth Configs (formerly Integrations/Connectors)

| Previous Endpoint | Current Endpoint |
| :--- | :--- |
| `GET /api/v1/integrations` | `GET /api/v3/auth_configs` |
| `POST /api/v1/integrations` | `POST /api/v3/auth_configs` |
| `GET /api/v1/integrations/{integrationId}` | `GET /api/v3/auth_configs/{nanoid}` |
| `PATCH /api/v1/integrations/{integrationId}` | `PATCH /api/v3/auth_configs/{nanoid}` |
| `DELETE /api/v1/integrations/{integrationId}` | `DELETE /api/v3/auth_configs/{nanoid}` |
| `POST /api/v2/integrations/create` | `POST /api/v3/auth_configs` |

### Connected Accounts (formerly Connections)

| Previous Endpoint | Current Endpoint |
| :--- | :--- |
| `GET /api/v1/connectedAccounts` | `GET /api/v3/connected_accounts` |
| `POST /api/v1/connectedAccounts` | `POST /api/v3/connected_accounts` |
| `POST /api/v2/connectedAccounts/initiateConnection` | `POST /api/v3/connected_accounts` |
| `GET /api/v1/connectedAccounts/{connectedAccountId}` | `GET /api/v3/connected_accounts/{nanoid}` |
| `DELETE /api/v1/connectedAccounts/{connectedAccountId}` | `DELETE /api/v3/connected_accounts/{nanoid}` |
| `POST /api/v1/connectedAccounts/{connectedAccountId}/disable` | `PATCH /api/v3/connected_accounts/{nanoId}/status` |
| `POST /api/v1/connectedAccounts/{connectedAccountId}/enable` | `PATCH /api/v3/connected_accounts/{nanoId}/status` |
| `POST /api/v1/connectedAccounts/{connectedAccountId}/reinitiate` | `POST /api/v3/connected_accounts/{nanoid}/refresh` |

### Triggers

| Previous Endpoint | Current Endpoint |
| :--- | :--- |
| `GET /api/v1/triggers` | `GET /api/v3/triggers_types` |
| `GET /api/v1/triggers/list/enums` | `GET /api/v3/triggers_types/list/enum` |
| `GET /api/v2/triggers/{triggerName}` | `GET /api/v3/triggers_types/{slug}` |
| `GET /api/v1/triggers/active_triggers` | `GET /api/v3/trigger_instances/active` |
| `POST /api/v1/triggers/enable/{connectedAccountId}/{triggerName}` | `POST /api/v3/trigger_instances/{slug}/upsert` |
| `DELETE /api/v1/triggers/instance/{triggerInstanceId}` | `DELETE /api/v3/trigger_instances/manage/{triggerId}` |
| `PATCH /api/v1/triggers/instance/{triggerId}/status` | `PATCH /api/v3/trigger_instances/manage/{triggerId}` |

---

# Toolkit versioning migration (/docs/migration-guide/toolkit-versioning)

Starting with Python SDK v0.9.0 and TypeScript SDK v0.2.0, manual tool execution requires explicit version specification. This is a breaking change from earlier versions where toolkit versioning was optional.

## Breaking change

Manual tool execution now requires explicit version specification. The `tools.execute()` method will fail without a version.

### Before (will fail)

**Python:**

```python
# Raises ToolVersionRequiredError
result = composio.tools.execute(
    "GITHUB_CREATE_ISSUE",
    {"user_id": "user-123", "arguments": {...}}
)
```
  
  
**TypeScript:**

```typescript
// @noErrors
// Throws ComposioToolVersionRequiredError
const result = await composio.tools.execute({
    toolSlug: "GITHUB_CREATE_ISSUE",
    userId: "user-123",
    arguments: {...}
});
```
  

### After (required)

Choose one of three migration strategies:

#### Option 1: Configure version at SDK level

**Python:**

```python
from composio import Composio

# Pin specific versions for each toolkit
composio = Composio(
    api_key="YOUR_API_KEY",
    toolkit_versions={
        "github": "20251027_00",
        "slack": "20251027_00",
        "gmail": "20251027_00"

)
```
  
  
**TypeScript:**

```typescript
// @noErrors
import { Composio } from "@composio/core";

// Pin specific versions for each toolkit
const composio = new Composio({
    apiKey: "YOUR_API_KEY",
    toolkitVersions: {
        github: "20251027_00",
        slack: "20251027_00",
        gmail: "20251027_00"

});
```
  

#### Option 2: Pass version with each execution

**Python:**

```python
# Specify version directly in execute call
result = composio.tools.execute(
    "GITHUB_LIST_STARGAZERS",
    arguments={
        "owner": "ComposioHQ",
        "repo": "composio"
    },
    user_id="user-k7334",
    version="20251027_00"  # Override version for this execution
)
print(result)
```
  
  
**TypeScript:**

```typescript
// @noErrors
// Specify version directly in execute call
const result = await composio.tools.execute("GITHUB_LIST_STARGAZERS", {
    userId: "user-k7334",
    arguments: {
        owner: "ComposioHQ",
        repo: "composio"
    },
    version: "20251027_00"  // Override version for this execution
});
console.log(result);
```
  

#### Option 3: Use environment variables

```bash
export COMPOSIO_TOOLKIT_VERSION_GITHUB="20251027_00"
```

## Migration checklist

1. **Audit your code**: Find all `tools.execute()` calls in your codebase
2. **Choose a strategy**: Select one of the three options above based on your needs
3. **Test thoroughly**: Verify tools work correctly with pinned versions
4. **Deploy gradually**: Roll out changes incrementally to minimize risk

## Temporary workaround

During migration, you can temporarily skip version checks (not recommended for production):

**Python:**

```python
result = composio.tools.execute(
    "GITHUB_CREATE_ISSUE",

        "user_id": "user-123",
        "arguments": {...}
    },
    dangerously_skip_version_check=True
)
```
  
  
**TypeScript:**

```typescript
// @noErrors
const result = await composio.tools.execute({
    toolSlug: "GITHUB_CREATE_ISSUE",
    userId: "user-123",
    arguments: {...},
    dangerouslySkipVersionCheck: true
});
```
  

> 
The `dangerouslySkipVersionCheck` flag is only for migration or debugging. Never use in production.

## Next steps

For complete documentation on toolkit versioning, including best practices and advanced configuration, see [Toolkit versioning](/docs/toolkit-versioning).

---

# After Execution Modifiers (/docs/modify-tool-behavior/after-execution-modifiers)

After execution modifiers are part of Composio SDK's powerful middleware capabilities that allow you to customize and extend the behavior of tools.

These modifiers are called after the tool is executed. This allows you to modify the result of the tool before it is returned to the agent.

**Useful for:**
- Modifying or truncating the output of the tool
- Converting the output to a different format before returning it to the agent

> 
Below we use the `afterExecute` modifier to truncate the output of `HACKERNEWS_GET_USER` and only return the karma of the user.

## With Chat Completions

Since completion providers don't have a function execution step, Composio executes the tool call directly. The modifier is configured on the `tools.execute` method.

**Python:**

```python
from composio import Composio, after_execute
from composio.types import ToolExecutionResponse

@after_execute(tools=["HACKERNEWS_GET_USER"])
def after_execute_modifier(
    tool: str,
    toolkit: str,
    response: ToolExecutionResponse,
) -> ToolExecutionResponse:
    return {
        **response,
        "data": {
            "karma": response["data"]["karma"],
        },

tools = composio.tools.get(user_id=user_id, slug="HACKERNEWS_GET_USER")

# Get response from the LLM
response = openai_client.chat.completions.create(
    model="gpt-4o-mini",
    tools=tools,
    messages=messages,
)
print(response)

# Execute the function calls
result = composio.provider.handle_tool_calls(
  response=response,
  user_id="default",
  modifiers=[
     after_execute_modifier,
  ]
)
print(result)
```
  
  
**TypeScript:**

```typescript
// @noErrors
const response = await openai.chat.completions.create({
  model: "gpt-4o-mini",
  messages,
  tools,
  tool_choice: "auto",
});

const { tool_calls } = response.choices[0].message;
console.log(tool_calls);

if (tool_calls) {
  const {
    function: { arguments: toolArgs },
  } = tool_calls[0];

  const result = await composio.tools.execute(
    "HACKERNEWS_GET_USER",

      userId,
      arguments: JSON.parse(toolArgs),
    },

      afterExecute: ({ toolSlug, toolkitSlug, result }) => {
        if (toolSlug === "HACKERNEWS_GET_USER") {
          const { data } = result;
          const { karma } = data.response_data as { karma: number };
          return {
            ...result,
            data: { karma },
          };

        return result;
      },

  );
  console.log(JSON.stringify(result, null, 2));

```
  

## With Agentic Frameworks

Agentic providers have a function execution step. The modifier is configured on the `tools.get` method which modifies the execution logic within the framework.

**Python:**

```python
from composio import Composio, after_execute
from composio.types import ToolExecutionResponse
from composio_crewai import CrewAIProvider

composio = Composio(provider=CrewAIProvider())

@after_execute(tools=["HACKERNEWS_GET_USER"])
def after_execute_modifier(
    tool: str,
    toolkit: str,
    response: ToolExecutionResponse,
) -> ToolExecutionResponse:
    return {
        **response,
        "data": {
            "karma": response["data"]["karma"],
        },

tools = composio.tools.get(
    user_id="default",
    slug="HACKERNEWS_GET_USER",
    modifiers=[
        after_execute_modifier,
    ]
)
```
  
  
**TypeScript:**

```typescript
// @noErrors
import { Composio } from "@composio/core";
import { VercelProvider } from "@composio/vercel";
import { v4 as uuidv4 } from "uuid";

const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
  provider: new VercelProvider(),
});

const userId = uuidv4();

const agenticTools = await composio.tools.get(
  userId,

    tools: ["HACKERNEWS_GET_USER"],
  },

    afterExecute: ({ toolSlug, toolkitSlug, result }) => {
      if (toolSlug === "HACKERNEWS_GET_USER") {
        const {
          data: { response_data: { karma } = {} } = {},
        } = result;
        return {
          ...result,
          data: { karma },
        };

      return result;
    },

);
```

---

# Before Execution Modifiers (/docs/modify-tool-behavior/before-execution-modifiers)

Before execution modifiers are part of Composio SDK's powerful middleware capabilities that allow you to customize and extend the behavior of tools.

These modifiers are called before the tool is executed by the LLM. This allows you to modify the arguments called by the LLM before they are executed by Composio.

**Useful for:**
- Injecting an argument into the tool execution
- Overriding the arguments emitted by the LLM

> 
Below we use the `beforeExecute` modifier to modify the number of posts returned by `HACKERNEWS_GET_LATEST_POSTS`.

## With Chat Completions

Since completion providers don't have a function execution step, Composio executes the tool call directly. The modifier is configured on the `tools.execute` method.

**Python:**

```python
from openai import OpenAI
from composio import Composio, before_execute
from composio.types import ToolExecuteParams

composio = Composio()
openai_client = OpenAI()
user_id = "user@email.com"

@before_execute(tools=["HACKERNEWS_GET_LATEST_POSTS"])
def before_execute_modifier(
    tool: str,
    toolkit: str,
    params: ToolExecuteParams,
) -> ToolExecuteParams:
    params["arguments"]["size"] = 1
    return params

# Get tools
tools = composio.tools.get(user_id=user_id, slug="HACKERNEWS_GET_LATEST_POSTS")

# Get response from the LLM
response = openai_client.chat.completions.create(
    model="gpt-4o-mini",
    tools=tools,
    messages=[{"role": "user", "content": "Fetch latest posts from hackernews"}],
)
print(response)

# Execute the function calls
result = composio.provider.handle_tool_calls(
    response=response,
    user_id="default",
    modifiers=[
        before_execute_modifier,
    ],
)
print(result)
```
  
  
**TypeScript:**

```typescript
// @noErrors
const response = await openai.chat.completions.create({
  model: "gpt-4o-mini",
  messages,
  tools,
  tool_choice: "auto",
});

const { tool_calls } = response.choices[0].message;
console.log(tool_calls);

if (tool_calls) {
  const {
    function: { arguments: toolArgs },
  } = tool_calls[0];

  const result = await composio.tools.execute(
    "HACKERNEWS_GET_LATEST_POSTS",

      userId,
      arguments: JSON.parse(toolArgs),
    },

      beforeExecute: ({ toolSlug, toolkitSlug, params }) => {
        if (toolSlug === "HACKERNEWS_GET_LATEST_POSTS") {
          params.arguments.size = 1;

        console.log(params);
        return params;
      },

  );
  console.log(JSON.stringify(result, null, 2));

```
  

## With Agentic Frameworks

Agentic providers have a function execution step. The modifier is configured on the `tools.get` method which modifies the execution logic within the framework.

**Python:**

```python
from composio import Composio, before_execute
from composio.types import ToolExecuteParams
from composio_crewai import CrewAIProvider

composio = Composio(provider=CrewAIProvider())

@before_execute(tools=["LINEAR_CREATE_LINEAR_ISSUE"])
def modify_linear_project_id(
    tool: str,
    toolkit: str,
    params: ToolExecuteParams,
) -> ToolExecuteParams:
    params["arguments"]["project_id"] = "1234567890"
    return params

tools = composio.tools.get(
    user_id="default",
    tools=[
        "HACKERNEWS_GET_LATEST_POSTS",
        "HACKERNEWS_GET_USER",
        "LINEAR_CREATE_LINEAR_ISSUE",
    ],
    modifiers=[
        modify_linear_project_id,
    ]
)
```
  
  
**TypeScript:**

```typescript
// @noErrors
import { Composio } from "@composio/core";
import { MastraProvider } from "@composio/mastra";

const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
  provider: new MastraProvider(),
});

const userId = "user@acme.com";

const agenticTools = await composio.tools.get(
  userId,

    tools: [
      "HACKERNEWS_GET_LATEST_POSTS",
      "HACKERNEWS_GET_USER",
      "LINEAR_CREATE_LINEAR_ISSUE",
    ],
  },

    beforeExecute: ({toolSlug, toolkitSlug, params}) => {
      if (toolSlug === "LINEAR_CREATE_LINEAR_ISSUE") {
        params.arguments.project_id = "1234567890";

      return params;
    },

);
```

---

# Schema Modifiers (/docs/modify-tool-behavior/schema-modifiers)

Schema modifiers are part of Composio SDK's powerful middleware capabilities that allow you to customize and extend the behavior of tools.

Schema modifiers transform a tool's schema before the tool is seen by an agent.

**Useful for:**
- Modifying or rewriting the tool description to better fit your use case
- Adding arguments to the tool (e.g., adding a `thought` argument to prompt the agent to explain reasoning)
- Hiding arguments from the tool when they're irrelevant
- Adding extra arguments for custom use cases
- Adding default values to tool arguments

> 
Below we modify the schema of `HACKERNEWS_GET_LATEST_POSTS` to make the `size` argument required and remove the `page` argument.

**Python:**

```python
from composio import Composio, schema_modifier
from composio.types import Tool

user_id = "your@email.com"

@schema_modifier(tools=["HACKERNEWS_GET_LATEST_POSTS"])
def modify_schema(
    tool: str,
    toolkit: str,
    schema: Tool,
) -> Tool:
    _ = schema.input_parameters["properties"].pop("page", None)
    schema.input_parameters["required"] = ["size"]
    return schema

tools = composio.tools.get(
    user_id=user_id,
    tools=["HACKERNEWS_GET_LATEST_POSTS", "HACKERNEWS_GET_USER"],
    modifiers=[
        modify_schema,
    ]
)
```
  
  
**TypeScript:**

```typescript
// @noErrors
const userId = "your@email.com";

const tools = await composio.tools.get(
  userId,

    tools: ["HACKERNEWS_GET_LATEST_POSTS", "HACKERNEWS_GET_USER"],
  },

    modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
      if (toolSlug === "HACKERNEWS_GET_LATEST_POSTS") {
        const { inputParameters } = schema;
        if (inputParameters?.properties) {
          delete inputParameters.properties["page"];

        inputParameters.required = ["size"];

      return schema;
    },

);

console.log(JSON.stringify(tools, null, 2));
```
  

With the modified tool schema, the `page` argument is removed and `size` is required.

  

**Python:**

```python
from openai import OpenAI
from composio import Composio, schema_modifier
from composio.types import Tool
from composio_openai import OpenAIProvider

@schema_modifier(tools=["HACKERNEWS_GET_LATEST_POSTS"])
def modify_schema(
    tool: str,
    toolkit: str,
    schema: Tool,
) -> Tool:
    _ = schema.input_parameters["properties"].pop("page", None)
    schema.input_parameters["required"] = ["size"]
    return schema

# Initialize tools
openai_client = OpenAI()
composio = Composio(provider=OpenAIProvider())

# Define task
task = "Get the latest posts from Hacker News"

# Get tools with modifier
tools = composio.tools.get(
  user_id="default",
  tools=['HACKERNEWS_GET_LATEST_POSTS', 'HACKERNEWS_GET_USER'],
  modifiers=[
      modify_schema,
  ],
)

# Get response from the LLM
response = openai_client.chat.completions.create(
    model="gpt-4o-mini",
    tools=tools,
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": task},
    ],
)
print(response)

# Execute the function calls
result = composio.provider.handle_tool_calls(response=response, user_id="default")
print(result)
```
  
  
**TypeScript:**

```typescript
// @noErrors
import { Composio } from '@composio/core';
import { OpenAI } from 'openai';

const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
});
const openai = new OpenAI();

const userId = 'your@email.com';

const tools = await composio.tools.get(
  userId,

    tools: ['HACKERNEWS_GET_LATEST_POSTS', 'HACKERNEWS_GET_USER'],
  },

    modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
      if (toolSlug === 'HACKERNEWS_GET_LATEST_POSTS') {
        const { inputParameters } = schema;
        if (inputParameters?.properties) {
          delete inputParameters.properties['page'];

        inputParameters.required = ['size'];

      return schema;
    },

);

console.log(JSON.stringify(tools, null, 2));

const response = await openai.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [

      role: 'system',
      content: 'You are a helpful assistant that can help with tasks.',
    },
    { role: 'user', content: 'Get the latest posts from Hacker News' },
  ],
  tools: tools,
  tool_choice: 'auto',
});

console.log(response.choices[0].message.tool_calls);
```
  

  

## Example: Modifying the tool description

Sometimes you need to provide additional context to help the agent understand how to use a tool correctly. This example demonstrates modifying the description of `GITHUB_LIST_REPOSITORY_ISSUES` to specify a default repository.

> 
This approach is useful when you want to guide the agent's behavior without changing the tool's underlying functionality.

In this example:
- We append additional instructions to the tool's description
- The modified description tells the agent to use `composiohq/composio` as the default repository
- This helps prevent errors when the agent forgets to specify a repository parameter

**Python:**

```python
from composio import Composio, schema_modifier
from composio.types import Tool
from composio_google import GoogleProvider
from google import genai
from uuid import uuid4

composio = Composio(provider=GoogleProvider())
client = genai.Client()
user_id = uuid4()

@schema_modifier(tools=["GITHUB_LIST_REPOSITORY_ISSUES"])
def append_repository(
    tool: str,
    toolkit: str,
    schema: Tool,
) -> Tool:
    schema.description += " When not specified, use the `composiohq/composio` repository"
    return schema

tools = composio.tools.get(
    user_id=user_id,
    tools=["GITHUB_LIST_REPOSITORY_ISSUES"],
    modifiers=[append_repository]
)

print(tools)
```
  
  
**TypeScript:**

```typescript
// @noErrors
import { Composio } from '@composio/core';
import { VercelProvider } from '@composio/vercel';
import { v4 as uuidv4 } from 'uuid';

const userId = uuidv4();
const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
  provider: new VercelProvider(),
});

const addDescription = ({ toolSlug, toolkitSlug, schema }) => {
  if (toolSlug === 'GITHUB_LIST_REPOSITORY_ISSUES') {
    schema.description += 'If not specified, use the `composiohq/composio` repository';

  return schema;
};

const tools = await composio.tools.get(
  userId,

    tools: ['GITHUB_LIST_REPOSITORY_ISSUES'],
  },

    modifySchema: addDescription,

);

console.log(tools);
```

---

# Anthropic Provider (/docs/providers/anthropic)

The Anthropic Provider transforms Composio tools into a format compatible with Anthropic's function calling capabilities through its Messages API.

## Setup

The Anthropic provider can be installed for both SDKs.

**Python:**

```bash
pip install composio composio-anthropic
```

**TypeScript:**

```bash
npm install @composio/anthropic @anthropic-ai/sdk
```

You can specify the provider in the constructor. The constructor also takes in an optional `cacheTools` parameter.

**Python:**

```python
import anthropic

from composio import Composio
from composio_anthropic import AnthropicProvider

# Initialize tools.
anthropic_client = anthropic.Anthropic()
composio = Composio(provider=AnthropicProvider())
```

**TypeScript:**

```typescript
import { Composio } from "@composio/core";
import { AnthropicProvider } from "@composio/anthropic";
import Anthropic from '@anthropic-ai/sdk';

const composio = new Composio({
  provider: new AnthropicProvider({
    cacheTools: false,  // default
  }),
});

const anthropic = new Anthropic();
```

## Usage

**Python:**

```python
# Define your user ID
user_id = "your-user-id"

# Get GitHub tool for listing stargazers
tools = composio.tools.get(user_id=user_id, tools=["GITHUB_LIST_STARGAZERS"])

# Get response from the LLM
response = anthropic_client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=tools,
    messages=[
        {"role": "user", "content": "List my github stargazers. for the repo composiohq/composio"},
    ],
)

# Execute the function calls.
result = composio.provider.handle_tool_calls(user_id=user_id, response=response)
print(result)
```

**TypeScript:**

```typescript
import { Composio } from "@composio/core";
import { AnthropicProvider } from "@composio/anthropic";
import Anthropic from '@anthropic-ai/sdk';
const composio = new Composio({ provider: new AnthropicProvider() });
const anthropic = new Anthropic();
// ---cut---
const userId = "your-user-id";
const tools = await composio.tools.get(userId, {
  tools: ["GITHUB_LIST_STARGAZERS"]
})

const msg = await anthropic.messages.create({
  model: "claude-sonnet-4-5",
  messages: [

      role: "user",
      content: "List my github stargazers. for the repo composiohq/composio",
    },
  ],
  tools: tools,
  max_tokens: 1000,
});

const res = await composio.provider.handleToolCalls(userId, msg);

console.log(res[0].content);
```

## Modifiers

Modifiers are functions that can be used to intercept and optionally modify the schema, the tool call request and the response from the tool call.

Anthropic provider modifiers are the standard framework modifiers. Read more here: [Modifying tool schemas](/docs/modify-tool-behavior/modifying-tool-schemas).

---

# CrewAI Provider (/docs/providers/crewai)

The CrewAI Provider formats the Composio tools into an object compatible with CrewAI's tool calling capabilities. Agents and LLM workflows built with this can call and execute the Composio tools.

## Setup

The CrewAI provider is available for only the Python SDK.

```bash
pip install composio_crewai==0.8.0
```

## Usage

```python
from crewai import Agent, Crew, Task
from langchain_openai import ChatOpenAI

from composio import Composio
from composio_crewai import CrewAIProvider

# Initialize tools.
openai_client = ChatOpenAI()
composio = Composio(provider=CrewAIProvider())

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

# Define agent
crewai_agent = Agent(
    role="Github Agent",
    goal="""You take action on Github using Github APIs""",
    backstory=(
        "You are AI agent that is responsible for taking actions on Github "
        "on users' behalf. You need to take action on Github using Github APIs"
    ),
    verbose=True,
    tools=tools,
    llm=openai_client,
)

# Define task
task = Task(
    description=(
        "Star a repo composiohq/composio on GitHub, if the action is successful "
        "include Action executed successfully"
    ),
    agent=crewai_agent,
    expected_output="if the star happened",
)

my_crew = Crew(agents=[crewai_agent], tasks=[task])
result = my_crew.kickoff()
print(result)
```

---

# Google Gen AI Provider (/docs/providers/google)

The Google provider transforms Composio tools into a format compatible with Gemini's function calling capabilities through it's API

## Setup

**Python:**

```bash
pip install google-genai composio_google
```

**TypeScript:**

```bash
npm install @google/genai
npm i @composio/core @composio/gemini
```

**Python:**

```python
from composio import Composio
from composio_gemini import GeminiProvider
from google import genai
from google.genai import types

# Create composio client
composio = Composio(provider=GeminiProvider())
# Create google client
client = genai.Client()
```

**TypeScript:**

```typescript
import {Composio} from '@composio/core';
import {GoogleProvider} from '@composio/google'
import {GoogleGenAI} from '@google/genai'

const composio = new Composio({
    apiKey: "your-composio-api-key",
    provider: new GoogleProvider()
})

const ai = new GoogleGenAI({
    apiKey: "your-gemini-api-key"
})
```

## Usage

**Python:**

```python
user_id = "0000-1111-2222"
tools = composio.tools.get(user_id, tools=["COMPOSIO_SEARCH_DUCK_DUCK_GO_SEARCH"])

# Create genai client config
config = types.GenerateContentConfig(tools=tools)

# # Use the chat interface.
chat = client.chats.create(model="gemini-2.0-flash", config=config)
response = chat.send_message("search about the latest info on windsurf acquisition.")
print(response.text)
```

**TypeScript:**

```typescript
import {Composio} from '@composio/core';
import {GoogleProvider} from '@composio/google'
import {GoogleGenAI} from '@google/genai'
const composio = new Composio({ apiKey: "key", provider: new GoogleProvider() });
const ai = new GoogleGenAI({ apiKey: "key" });
// ---cut---
// Use a unique identifier for each user in your application
const user_id = "your-external-user-id"

// Get tools - this returns already wrapped tools when using GoogleProvider
const tools = await composio.tools.get(user_id, 'HACKERNEWS_GET_USER')

const response = await ai.models.generateContent({
    model: 'gemini-2.0-flash-001',
    contents: "Search for the user 'pg's",
    config: {
        tools: [{ functionDeclarations: tools }],
    },
});

if (response.functionCalls && response.functionCalls.length > 0) {
    console.log(`Calling tool ${response.functionCalls[0].name}`);
    const functionCall = {
        name: response.functionCalls[0].name || '',
        args: response.functionCalls[0].args || {},
    };
    const result = await composio.provider.executeToolCall(user_id, functionCall);
    console.log(`Result: ${result}`);
} else {
    console.log('No function calls in the response');
    console.log(response.text);

```

## Modifiers

Modifiers are functions that can be used to intercept and optionally **modify** the schema, the tool call request and the response from the tool call.

OpenAI provider modifiers are the standard framework modifiers.
Read more here: [Modifying tool schemas](/docs/modify-tool-behavior/modifying-tool-schemas)

---

# LangChain Provider (/docs/providers/langchain)

The LangChain Provider transforms Composio tools into a format compatible with LangChain's function calling capabilities.

## Setup

**Python:**

```bash
pip install composio_langchain==0.8.0 langchain
```

**TypeScript:**

```bash
npm install @composio/langchain
```

## Usage

**Python:**

```python
from composio import Composio
from composio_langchain import LangchainProvider
from langchain import hub  # type: ignore
from langchain.agents import AgentExecutor, create_openai_functions_agent
from langchain_openai import ChatOpenAI

# Pull relevant agent model.
prompt = hub.pull("hwchase17/openai-functions-agent")

# Initialize tools.
openai_client = ChatOpenAI(model="gpt-5")

composio = Composio(provider=LangchainProvider())

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

# Define task
task = "Star a repo composiohq/composio on GitHub"

# Define agent
agent = create_openai_functions_agent(openai_client, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

# Execute using agent_executor
agent_executor.invoke({"input": task})
```

**TypeScript:**

```typescript
import { ChatOpenAI } from '@langchain/openai';
import { HumanMessage, AIMessage } from '@langchain/core/messages';
import { ToolNode } from '@langchain/langgraph/prebuilt';
import { StateGraph, MessagesAnnotation } from '@langchain/langgraph';
import { Composio } from '@composio/core';
import { LangchainProvider } from '@composio/langchain';

// initiate composio
const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
  provider: new LangchainProvider(),
});

// fetch the tool
console.log(`🔄 Fetching the tool...`);
const tools = await composio.tools.get('default', 'HACKERNEWS_GET_USER');

// Define the tools for the agent to use
const toolNode = new ToolNode(tools);

// Create a model and give it access to the tools
const model = new ChatOpenAI({
  model: 'gpt-4o-mini',
  temperature: 0,
}).bindTools(tools);

// Define the function that determines whether to continue or not
function shouldContinue({ messages }: typeof MessagesAnnotation.State) {
  const lastMessage = messages[messages.length - 1] as AIMessage;

  // If the LLM makes a tool call, then we route to the "tools" node
  if (lastMessage.tool_calls?.length) {
    return 'tools';

  // Otherwise, we stop (reply to the user) using the special "__end__" node
  return '__end__';

// Define the function that calls the model
async function callModel(state: typeof MessagesAnnotation.State) {
  console.log(`🔄 Calling the model...`);
  const response = await model.invoke(state.messages);

  // We return a list, because this will get added to the existing list
  return { messages: [response] };

// Define a new graph
const workflow = new StateGraph(MessagesAnnotation)
  .addNode('agent', callModel)
  .addEdge('__start__', 'agent') // __start__ is a special name for the entrypoint
  .addNode('tools', toolNode)
  .addEdge('tools', 'agent')
  .addConditionalEdges('agent', shouldContinue);

// Finally, we compile it into a LangChain Runnable.
const app = workflow.compile();

// Use the agent
const finalState = await app.invoke({
  messages: [new HumanMessage('Find the details of the user `pg` on HackerNews')],
});
console.log(`✅ Message recieved from the model`);
console.log(finalState.messages[finalState.messages.length - 1].content);

const nextState = await app.invoke({
  // Including the messages from the previous run gives the LLM context.
  // This way it knows we're asking about the weather in NY
  messages: [...finalState.messages, new HumanMessage('what about haxzie')],
});
console.log(`✅ Message recieved from the model`);
console.log(nextState.messages[nextState.messages.length - 1].content);
```

---

# LlamaIndex Provider (/docs/providers/llamaindex)

The LlamaIndex Provider transforms Composio tools into a format compatible with LlamaIndex's function calling capabilities.

## Setup

**Python:**

```bash
pip install composio_llamaindex==0.8.0 llama-index
```

**TypeScript:**

```bash
npm install @composio/llamaindex @llamaindex/openai @llamaindex/workflow
```

## Usage

**Python:**

```python
import asyncio
import dotenv
from composio_llamaindex import LlamaIndexProvider
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI

from composio import Composio

# Load environment variables from .env
dotenv.load_dotenv()

# Setup client
llm = OpenAI(model="gpt-5")
composio = Composio(provider=LlamaIndexProvider())

tools = composio.tools.get(
    user_id="user@acme.com",
    tools=["GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER"],
)

workflow = FunctionAgent(
    tools=tools,
    llm=llm,
    system_prompt="You are an agent that performs github actions.",
)

async def main():
    result = await workflow.run(
        user_msg="Hello! I would like to star a repo composiohq/composio on GitHub"
    )
    print(result)

if __name__ == "__main__":
    asyncio.run(main())
```

**TypeScript:**

```typescript
import { Composio } from '@composio/core';
import { LlamaindexProvider } from '@composio/llamaindex';
import { openai } from '@llamaindex/openai';
import { agent } from '@llamaindex/workflow';
import 'dotenv/config';

// Initialize Composio with LlamaIndex provider
const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
  provider: new LlamaindexProvider(),
});

async function main() {
  // Get tools
  const tools = await composio.tools.get('user@acme.com', {
    tools: ['GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER'],
  });

  // Create LlamaIndex agent with Composio tools
  const githubAgent = agent({
    name: 'GitHub Agent',
    description: 'An agent that performs GitHub actions',
    llm: openai({ model: 'gpt-4o-mini' }),
    systemPrompt: 'You are an agent that performs github actions.',
    tools,
  });

  // Run the agent
  const result = await githubAgent.run(
    'Hello! I would like to star a repo composiohq/composio on GitHub'
  );

  console.log(result);

main().catch(console.error);
```

## Advanced Usage

### Streaming Agent with Multiple Toolkits

```typescript
import { Composio } from '@composio/core';
import { LlamaindexProvider } from '@composio/llamaindex';
import { openai } from '@llamaindex/openai';
import { agent, agentStreamEvent } from '@llamaindex/workflow';
import 'dotenv/config';

const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
  provider: new LlamaindexProvider(),
});

async function streamingExample() {
  // Get tools from multiple toolkits with execution modifiers
  const tools = await composio.tools.get(
    'default',

      toolkits: ['gmail', 'googlecalendar', 'slack'],
      limit: 20,
    },

      beforeExecute: ({ toolSlug, params }) => {
        console.log(`🔄 Executing ${toolSlug} with:`, params);
        return params;
      },
      afterExecute: ({ toolSlug, result }) => {
        console.log(`✅ ${toolSlug} completed:`, result);
        return result;
      },

  );

  // Create streaming agent
  const assistantAgent = agent({
    name: 'Personal Assistant',
    description: 'A helpful personal assistant',
    llm: openai({ model: 'gpt-4o-mini' }),
    systemPrompt: 'You are a helpful personal assistant that can manage emails, calendar events, and slack messages.',
    tools,
  });

  // Stream the response
  const stream = await assistantAgent.runStream(
    'Schedule a meeting for tomorrow at 2 PM and send a slack message about it'
  );

  for await (const event of stream) {
    if (agentStreamEvent.include(event)) {
      process.stdout.write(event.data.delta);

streamingExample().catch(console.error);
```

---

# Mastra Provider (/docs/providers/mastra)

Mastra is a TypeScript native framework for building agents with tools and MCPs. It expects tools to be in the following format:
- Inputs: What information the tool needs to run (defined with an `inputSchema`, often using Zod).
- Outputs: The structure of the data the tool returns (defined with an `outputSchema`).
- Execution Logic: The code that performs the tool's action.
- Description: Text that helps the agent understand what the tool does and when to use it.

More documentation [here](https://mastra.ai/en/docs/tools-mcp/overview#creating-tools)

The Mastra provider formats the Composio tools into this format along with the execution logic so that agents can call and execute the Composio tools.

## Setup

```bash
npm install @composio/mastra
```

You can specify the provider in the constructor.

```typescript
import { Composio } from "@composio/core";
import { MastraProvider } from "@composio/mastra";
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";

const composio = new Composio({
  provider: new MastraProvider(),
});
```

## Usage

The tools are passed to the agent as a parameter.

```typescript
import { Composio } from "@composio/core";
import { MastraProvider } from "@composio/mastra";
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
const composio = new Composio({ provider: new MastraProvider() });
// ---cut---
const userId = "john doe";

const tools = await composio.tools.get(
  userId,

    toolkits: ["SUPABASE"],

);

const agent = new Agent({
  id: "supabase-agent",
  name: "Supabase Agent",
  instructions: "You think therefore you are.",
  model: openai("gpt-4.1"),
  tools: tools,
});

const { text } = await agent.generate([
  { role: "user", content: "Tell me about my Supabase project" },
]);

console.log("\n🤖 Agent Response:\n");
console.log(text);
```

---

# OpenAI Agents Provider (/docs/providers/openai-agents)

The OpenAI Agents Provider is a provider that formats the Composio tools into an object compatible with OpenAI's Agents API.

OpenAI Agents SDK is different from the OpenAI SDK. It helps build agentic AI apps in a lightweight, easy-to-use package with very few abstractions.

**Python:**

## Setup

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

## Usage

```python
import asyncio
from composio import Composio
from agents import Agent, Runner
from composio_openai_agents import OpenAIAgentsProvider

composio = Composio(api_key="your-api-key", provider=OpenAIAgentsProvider())

# Create a connected account for the user for the gmail toolkit and replace with your own user id
externalUserId = "your-user-id"

# Get Gmail tools that are pre-configured
tools = composio.tools.get(user_id=externalUserId, tools=["GMAIL_SEND_EMAIL"])

agent = Agent(
    name="Email Manager", instructions="You are a helpful assistant", tools=tools
)

# Run the agent
async def main():
    result = await Runner.run(
        starting_agent=agent,
        input="Send an email to soham.g@composio.dev with the subject 'Hello from composio 👋🏻' and the body 'Congratulations on sending your first email using AI Agents and Composio!'",
    )
    print(result.final_output)

asyncio.run(main())
```

**TypeScript:**

## Setup

```bash
npm install @composio/core @openai/agents @composio/openai-agents
```

## Usage

```typescript
import { Composio } from "@composio/core";
import { Agent, run } from "@openai/agents";
import { OpenAIAgentsProvider } from "@composio/openai-agents";

// add OPENAI_API_KEY in your .env file
const composio = new Composio({
  apiKey: "your-api-key",
  provider: new OpenAIAgentsProvider(),
});

// Create a connected account for the user for the gmail toolkit and replace with your own user id
const externalUserId = "your-user-id";

// Fetch tools for GMAIL toolkit on behalf of the user
const tools = await composio.tools.get(externalUserId, {
    tools: ["GMAIL_SEND_EMAIL"],
  });

const agent = new Agent({
    name: "Email Manager",
    tools: tools,
});

console.log(`Running agent...`);
const result = await run(
    agent,
    "Send an email to soham.g@composio.dev with the subject 'Hello from composio' and the body 'Congratulations on sending your first email using AI Agents and Composio!'"
);

console.log(`Received response from agent`);
if (result.finalOutput) {
    console.log(JSON.stringify(result.finalOutput, null, 2));

```

---

# OpenAI Providers (/docs/providers/openai)

The OpenAI Provider is the default provider for the Composio SDK. It transforms Composio tools into a format compatible with OpenAI's function calling capabilities through both the Responses and Chat Completion APIs.

## Setup

By default, the OpenAI Provider is installed when you install the Composio SDK. You can also install it manually:

**Python:**

```bash
pip install composio_openai
```

**TypeScript:**

```bash
npm install @composio/openai
```

## Responses API

The Responses API is the recommended way to build more agentic flows with the OpenAI API.
Read more about it in the [OpenAI documentation](https://platform.openai.com/docs/api-reference/responses)

> 
Before executing any tools that require authentication (like Gmail), you'll need to:
1. [Create an Auth Configuration](/docs/authenticating-tools#creating-an-auth-config) for your integration
2. [Set up a Connected Account](/docs/authenticating-tools#connecting-an-account) for the user.

**Python:**

```python
from openai import OpenAI
from composio import Composio
from composio_openai import OpenAIResponsesProvider

# Initialize Composio client with OpenAI Provider
composio = Composio(provider=OpenAIResponsesProvider())
openai = OpenAI()

# Make sure to create an auth config and a connected account for the user with gmail toolkit
# Make sure to replace "your-user-id" with the actual user ID
user_id = "your-user-id"

tools = composio.tools.get(user_id=user_id, tools=["GMAIL_SEND_EMAIL"])

response = openai.responses.create(
    model="gpt-5",
    tools=tools,
    input=[

            "role": "user",
            "content": "Send an email to soham.g@composio.dev with the subject 'Running OpenAI Provider snippet' and body 'Hello from the code snippet in openai docs'"

    ]
)

# Execute the function calls
result = composio.provider.handle_tool_calls(response=response, user_id=user_id)
print(result)
```

**TypeScript:**

```typescript
import OpenAI from 'openai';
import { Composio } from '@composio/core';
import { OpenAIResponsesProvider } from '@composio/openai';

// Initialize Composio client with OpenAI Provider
const composio = new Composio({
    provider: new OpenAIResponsesProvider(),
});
const openai = new OpenAI({});

// Make sure to create an auth config and a connected account for the user with gmail toolkit
// Make sure to replace "your-user-id" with the actual user ID
const userId = "your-user-id";

async function main() {
    try {
        const tools = await composio.tools.get(userId, {tools: ["GMAIL_SEND_EMAIL"]});

        const response = await openai.responses.create({
            model: "gpt-5",
            tools: tools,
            input: [

                    role: "user",
                    content: "Send an email to soham.g@composio.dev with the subject 'Running OpenAI Provider snippet' and body 'Hello from the code snippet in openai docs'"
                },
            ],
        });

        // Execute the function calls
        const result = await composio.provider.handleToolCalls(userId, response.output);
        console.log(result);
    } catch (error) {
        console.error('Error:', error);

main();
```

## Chat Completion API

The Chat Completion API generates a model response from a list of messages. Read more about it in the [OpenAI documentation](https://platform.openai.com/docs/api-reference/chat).
The OpenAI Chat Provider is the default provider used by Composio SDK, but you can also explicitly initialise it.

> 
Before executing any tools that require authentication (like Gmail), you'll need to:
1. [Create an Auth Configuration](/docs/authenticating-tools#creating-an-auth-config) for your integration
2. [Set up a Connected Account](/docs/authenticating-tools#connecting-an-account) for the user.

**Python:**

```python
from openai import OpenAI
from composio import Composio
from composio_openai import OpenAIProvider

# Initialize Composio client with OpenAI Provider
composio = Composio(provider=OpenAIProvider())
openai = OpenAI()

# Make sure to create an auth config and a connected account for the user with gmail toolkit
# Make sure to replace "your-user-id" with the actual user ID
user_id = "your-user-id"

tools = composio.tools.get(user_id=user_id, tools=["GMAIL_SEND_EMAIL"])

response = openai.chat.completions.create(
    model="gpt-5",
    tools=tools,
    messages=[
        {"role": "user", "content": "Send an email to soham.g@composio.dev with the subject 'Running OpenAI Provider snippet' and body 'Hello from the code snippet in openai docs'"},
    ],
)

# Execute the function calls
result = composio.provider.handle_tool_calls(response=response, user_id=user_id)
print(result)
```

**TypeScript:**

```typescript
import OpenAI from 'openai';
import { Composio } from '@composio/core';
import { OpenAIProvider } from '@composio/openai';

// Initialize Composio client with OpenAI Provider
const composio = new Composio({
    provider: new OpenAIProvider(),
});

const openai = new OpenAI();

// Make sure to create an auth config and a connected account for the user with gmail toolkit
// Make sure to replace "your-user-id" with the actual user ID
const userId = "your-user-id";

async function main() {
    try {
        const tools = await composio.tools.get(userId, {tools: ["GMAIL_SEND_EMAIL"]});

        const response = await openai.chat.completions.create({
            model: "gpt-5",
            tools: tools,
            messages: [

                    role: "user",
                    content: "Send an email to soham.g@composio.dev with the subject 'Running OpenAI Provider snippet' and body 'Hello from the code snippet in openai docs'"
                },
            ],
        });

        // Execute the function calls
        const result = await composio.provider.handleToolCalls(userId, response);
        console.log(result);
    } catch (error) {
        console.error('Error:', error);

main();
```

## Modifiers

Modifiers are functions that can be used to intercept and optionally **modify** the schema, the tool call request and the response from the tool call.

OpenAI provider modifiers are the standard framework modifiers.
Read more here: [Modifying tool schemas](/docs/modify-tool-behavior/modifying-tool-schemas)

---

# Vercel AI SDK Provider (/docs/providers/vercel)

Vercel AI SDK allows you to configure an optional async `execute` function that the framework uses to execute the tool calls.

The Vercel provider for Composio formats the Composio tools and adds this `execute` function to the tool calls.

## Setup

Vercel AI SDK and the provider are only available for the TypeScript SDK.

```bash
npm install @composio/vercel
```

You can specify and import the provider in the constructor.

```typescript
import { Composio } from '@composio/core';
import { VercelProvider } from '@composio/vercel';
import { generateText } from 'ai';
import { openai } from "@ai-sdk/openai";

const composio = new Composio({
  provider: new VercelProvider(),
});
```

## Usage

```typescript
import { Composio } from '@composio/core';
import { VercelProvider } from '@composio/vercel';
import { generateText } from 'ai';
import { openai } from "@ai-sdk/openai";
const composio = new Composio({ provider: new VercelProvider() });
// ---cut---
// create an auth config for gmail
// then create a connected account with an external user id that identifies the user
const externalUserId = "your-external-user-id";
const tools = await composio.tools.get(externalUserId, "GMAIL_SEND_EMAIL");

// env: OPENAI_API_KEY
const { text } = await generateText({
  model: openai("gpt-5"),
  messages: [

      role: "user",
      content: `Send an email to soham.g@composio.dev with the subject 'Hello from composio 👋🏻' and the body 'Congratulations on sending your first email using AI Agents and Composio!'`,
    },
  ],
  tools,
});

console.log("Email sent successfully!", { text });
```

---

# API (/docs/troubleshooting/api)

## Reporting API issues

When reporting API issues to support, provide the following:

- **cURL command**: Include the exact cURL to reproduce the issue
- **Request ID**: Add `x-request-id: <uuid>` header to your request and share the UUID (generate at [uuidgenerator.net](https://www.uuidgenerator.net/))
- **Error details**: Share the complete error message
- **Reproduction steps**: Include any steps needed to reproduce the issue

## Getting help

- **Email**: support@composio.dev
- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)

---

# Authentication (/docs/troubleshooting/authentication)

## Using Composio's default OAuth app

When using our default OAuth configuration:

- **Don't add additional scopes** - They may not be approved in our OAuth app
- Use only the pre-configured scopes provided

## Using custom OAuth apps

Ensure your OAuth app is configured correctly:

- **Redirect URL**: Must match exactly what's configured in your OAuth provider
- **Scopes**: Auth config scopes must match your OAuth app configuration
- **Credentials**: Verify client ID and secret are correct

For setup guides by toolkit: [OAuth Configuration Guides](https://composio.dev/oauth)

## Common authentication issues

- **Invalid redirect URI**: Check the callback URL matches exactly
- **Scope mismatch**: Ensure requested scopes are configured in both auth config and OAuth app
- **Expired tokens**: Try refreshing the connection
- **Rate limits**: Some providers limit authentication attempts
- **Credentials showing as `REDACTED`**: The "Mask Connected Account Secrets" setting is enabled on your account, which redacts all sensitive credential data. Navigate to **Settings → Project Settings → Project Configuration** and disable "Mask Connected Account Secrets" to view actual values

## Reporting authentication issues

When reporting to support, provide:

- **Error message**: Complete error details and screenshots
- **Auth config ID**: The `authConfigId` being used
- **Connected account ID**: If a connection was already created
- **OAuth provider**: Which service you're trying to connect

## Getting help

- **Email**: support@composio.dev
- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)

---

# CLI (/docs/troubleshooting/cli)

## Command not found

Verify the CLI is installed and in your PATH:

```bash
which composio
```

If not found, reinstall:

```bash
curl -fsSL https://composio.dev/install | bash
```

Or add to PATH:

```bash
echo 'export PATH="$HOME/.composio:$PATH"' >> ~/.bashrc && source ~/.bashrc
```

## Authentication errors

Check current authentication:

```bash
composio whoami
```

Re-authenticate if needed:

```bash
composio logout
composio login
```

For CI/CD, use environment variable:

```bash
export COMPOSIO_API_KEY="your-api-key"
```

## Type generation issues

### Project type not detected

Use language-specific commands:

```bash
composio ts generate  # TypeScript
composio py generate  # Python
```

### Output directory missing

Specify output directory explicitly:

```bash
composio generate --output-dir ./my-types
```

## Debug CLI issues

Enable debug logging:

```bash
composio --log-level debug [command]
```

Check version compatibility:

```bash
composio version
```

## Common issues

- **API key not found**: Run `composio login`
- **Project type detection fails**: Use language-specific commands or ensure you're in project root
- **Network timeout**: Check internet connection and proxy settings
- **Permission denied**: Check directory write permissions

## Getting help

- **Email**: support@composio.dev
- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
- **GitHub**: [Create an issue](https://github.com/ComposioHQ/composio/issues/new?labels=bug)

---

# Dashboard (/docs/troubleshooting/dashboard)

## Reporting dashboard issues

When reporting dashboard issues to support, provide:

- **Screenshot or recording**: Visual evidence of the issue
- **Error details**: Complete error message shown in the UI
- **Network logs**: Check browser DevTools for failing API calls and share:
  - Error message
  - Request ID (`x-request-id` header)
  - Failed endpoint URL

## Getting help

- **Email**: support@composio.dev
- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)

---

# Troubleshooting (/docs/troubleshooting)

import { Bug, Brain, Sparkles, MessageCircle, MessageSquare, BookOpen } from 'lucide-react';

This section is designed to help you quickly identify and resolve common issues encountered with Composio.

Some quick links:

- [Report issues](https://github.com/ComposioHQ/composio/issues/new?labels=bug): }>
    Found a bug? Please create a Github issue!
  
  - [Ask AI](https://deepwiki.com/ComposioHQ/composio): }>
    Try to use Ask AI in the docs or deepwiki to get the fastest responses on features, types, and best practices.
  
  - [Feature requests](https://github.com/ComposioHQ/composio/issues/new?labels=enhancement): }>
    Have an idea for improving Composio? Share your feature suggestions with us and we will prioritise your requests
  
  - [Ask the community](https://github.com/ComposioHQ/composio/discussions): }>
    Join our GitHub discussions to get help from the community
  
  - [Discord community](https://discord.com/channels/1170785031560646836/1268871288156323901): }>
    Post support queries on our discord channel or reach out to support@composio.dev
  
  - [Migration guides](/docs/migration-guide): }>
    Check out our migration guides to help you upgrade to the latest version.

---

# MCP (/docs/troubleshooting/mcp)

## Connected account not found error

This error occurs when MCP cannot find a valid connected account for authentication:

- **Specify an account**: Provide either `connected_account_id` or `user_id` in your MCP configuration
- **Default behavior**: Without specification, MCP uses `user_id=default`. If multiple connections exist with the same user_id, the most recent is used
- **Verification checklist**:
  - Account status is `ACTIVE` (not deleted)
  - Account belongs to the same auth config used to create the MCP server

Learn more: [MCP Quickstart](/docs/mcp-quickstart)

## Getting 404 errors

Verify your URL format matches one of these patterns:

- `https://mcp.composio.dev/composio/server//mcp`
- `https://apollo-<randomID>-composio.vercel.app/v3/mcp/`
- `https://apollo.composio.dev/v3/mcp/`

## Testing and debugging

If experiencing issues, test your MCP server with:

- [Postman MCP Requests](https://learning.postman.com/docs/postman-ai-developer-tools/mcp-requests/create/)
- [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector)

This helps identify whether the issue is with your MCP client or the server.

## Reporting MCP issues

When reporting to support, provide:

- **Error message**: Complete error details
- **MCP server URL**: The exact URL you're connecting to
- **Testing results**: Whether issue reproduces in MCP Inspector/Postman or only in specific client
- **Connected account ID**: If facing connection issues
- **Reproduction steps**: Clear steps to reproduce the issue

## Getting help

- **Email**: support@composio.dev
- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)

---

# SDKs (/docs/troubleshooting/sdks)

## Debug network issues

Enable debug logging to see API calls and identify if issues are SDK or API related. Look for the `x-request-id` in logs to share with support.

**Python:**

```bash
# Set environment variable
COMPOSIO_LOGGING_LEVEL=debug
```
  
  
**TypeScript:**

```bash
// Set environment variable
COMPOSIO_LOG_LEVEL=debug
```
  

## Check SDK version

Ensure you're using the latest version:

**Python:**

```bash
pip install --upgrade composio
```
  
  
**TypeScript:**

```bash
npm install @composio/core@latest
```
  

Check current version:
- Python: [PyPI](https://pypi.org/project/composio/)
- TypeScript: [npm](https://www.npmjs.com/package/@composio/core)

## Common issues

- **Type errors or parameter confusion**: Search [DeepWiki](https://deepwiki.com/ComposioHQ/composio) or use the Ask AI assistant
- **Tool-specific issues**: Check the [specific tool's documentation](/toolkits/introduction)
- **Bug reporting**: Create a [GitHub issue](https://github.com/ComposioHQ/composio/issues/new?labels=bug) with debug logs and reproduction steps

## Getting help

- **Email**: support@composio.dev
- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)

---

# Tools & Toolkits (/docs/troubleshooting/tools)

## Tool execution failures (401/403 errors)

Authentication and permission errors typically occur due to:

### Missing scopes

Check if your connection has the required scopes using this API:

```bash
curl --location 'https://backend.composio.dev/api/v3/tools/get_scopes_required' \
--header 'x-api-key: YOUR_COMPOSIO_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "tools": [
        "SLACK_SENDS_A_MESSAGE_TO_A_SLACK_CHANNEL",
        "SLACK_CREATE_A_REMINDER"
    ]
}'
```

### Insufficient permissions

Verify the connected account has necessary permissions:

- **Admin requirements**: Some tools require admin-level access
- **Paid accounts**: Certain toolkits need paid subscriptions
  - Example: MS Teams requires Microsoft 365 account + Azure AD tenant

## Tool not working

- Check [tool-specific documentation](/toolkits/introduction) for requirements
- Verify the connected account is active and properly authenticated
- Test with the latest SDK version

## Reporting tool issues

When reporting to support, provide:

- **Error message**: Complete error details
- **Log ID**: From the error response
- **Tool name**: Exact tool slug being executed
- **Connected account ID**: Account used for execution

## Getting help

- **Email**: support@composio.dev
- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)

---

# Triggers (/docs/troubleshooting/triggers)

## Unable to create trigger

Check the error message - the account might not have sufficient permissions or required scopes.

## Type errors with trigger payloads

Having issues with trigger payload types? Search [DeepWiki](https://deepwiki.com/ComposioHQ/composio) or use the Ask AI assistant for type definitions and examples.

## Not receiving trigger payloads

Even if the action occurred (email received, Jira issue created, etc.), there may be delays:

- **Gmail triggers**: Uses polling with minimum 1-minute frequency - expect delays of up to a minute
- **Other services**: May have their own polling intervals or webhook delivery delays

## Reporting trigger issues

When reporting to support, provide:

- **Error message**: Complete error details
- **Connected account**: The account ID used for creating the trigger
- **cURL command**: To reproduce the issue
- **Reproduction steps**: Any additional steps needed

## Getting help

- **Email**: support@composio.dev
- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)

---

# Custom Providers (/docs/providers/custom-providers)

Providers transform Composio tools into the format your AI framework expects. If your framework isn't listed in our supported providers, you can build your own.

  />

  />

---

# Python Custom Provider (/docs/providers/custom-providers/python)

This guide shows how to create custom providers for the Composio Python SDK. Custom providers enable integration with different AI frameworks and platforms.

## Provider architecture

The Composio SDK uses a provider architecture to adapt tools for different AI frameworks. The provider handles:

1. **Tool format transformation**: Converting Composio tools into formats compatible with specific AI platforms
2. **Platform-specific integration**: Providing helper methods for seamless integration

## Types of providers

There are two types of providers:

1. **Non-agentic providers**: Transform tools for platforms that don't have their own agency (e.g., OpenAI, Anthropic)
2. **Agentic providers**: Transform tools for platforms that have their own agency (e.g., LangChain, CrewAI)

## Provider class hierarchy

```
BaseProvider (Abstract)
├── NonAgenticProvider (Abstract)
│   └── OpenAIProvider (Concrete)
│   └── AnthropicProvider (Concrete)
│   └── [Your Custom Non-Agentic Provider] (Concrete)
└── AgenticProvider (Abstract)
    └── LangchainProvider (Concrete)
    └── [Your Custom Agentic Provider] (Concrete)
```

## Quick start

The fastest way to create a new provider is using the provider scaffolding script:

```bash
# Create a non-agentic provider
make create-provider name=myprovider

# Create an agentic provider
make create-provider name=myagent agentic=true

# Create provider with custom output directory
make create-provider name=myprovider output=/path/to/custom/dir

# Combine options
make create-provider name=myagent agentic=true output=/my/custom/path
```

This will create a new provider in the specified directory (default: `python/providers/<provider-name>/`) with:
- Complete package structure with `pyproject.toml`
- Provider implementation template
- Demo script
- README with usage examples
- Type annotations and proper inheritance

> 
The scaffolding script creates a fully functional provider template. You just need to implement the tool transformation logic specific to your platform. You can maintain your provider implementation in your own repository.

### Generated structure

The create-provider script generates the following structure:

```
python/providers/<provider-name>/
├── README.md                    # Documentation and usage examples
├── pyproject.toml              # Project configuration
├── setup.py                    # Setup script for pip compatibility
├── <provider-name>_demo.py     # Demo script showing usage
└── composio_<provider-name>/   # Package directory
    ├── __init__.py             # Package initialization
    ├── provider.py             # Provider implementation
    └── py.typed                # PEP 561 type marker
```

After generation, you can:
1. Navigate to the provider directory: `cd python/providers/<provider-name>`
2. Install in development mode: `uv pip install -e .`
3. Implement your provider logic in `composio_<provider-name>/provider.py`
4. Test with the demo script: `python <provider-name>_demo.py`

## Creating a non-agentic provider

Non-agentic providers inherit from the `NonAgenticProvider` abstract class:

```python
from typing import List, Optional, Sequence, TypeAlias
from composio.core.provider import NonAgenticProvider
from composio.types import Tool, Modifiers, ToolExecutionResponse

# Define your tool format
class MyAITool:
    def __init__(self, name: str, description: str, parameters: dict):
        self.name = name
        self.description = description
        self.parameters = parameters

# Define your tool collection format
MyAIToolCollection: TypeAlias = List[MyAITool]

# Create your provider
class MyAIProvider(NonAgenticProvider[MyAITool, MyAIToolCollection], name="my-ai-platform"):
    """Custom provider for My AI Platform"""

    def wrap_tool(self, tool: Tool) -> MyAITool:
        """Transform a single tool to platform format"""
        return MyAITool(
            name=tool.slug,
            description=tool.description or "",
            parameters={
                "type": "object",
                "properties": tool.input_parameters.get("properties", {}),
                "required": tool.input_parameters.get("required", [])

        )

    def wrap_tools(self, tools: Sequence[Tool]) -> MyAIToolCollection:
        """Transform a collection of tools"""
        return [self.wrap_tool(tool) for tool in tools]

    # Optional: Custom helper methods for your AI platform
    def execute_my_ai_tool_call(
        self,
        user_id: str,
        tool_call: dict,
        modifiers: Optional[Modifiers] = None
    ) -> ToolExecutionResponse:
        """Execute a tool call in your platform's format

        Example usage:
        result = my_provider.execute_my_ai_tool_call(
            user_id="default",
            tool_call={"name": "GITHUB_STAR_REPO", "arguments": {"owner": "composiohq", "repo": "composio"}}
        )
        """
        # Use the built-in execute_tool method
        return self.execute_tool(
            slug=tool_call["name"],
            arguments=tool_call["arguments"],
            modifiers=modifiers,
            user_id=user_id
        )
```

## Creating an agentic provider

Agentic providers inherit from the `AgenticProvider` abstract class:

```python
from typing import Callable, Dict, List, Sequence
from composio.core.provider import AgenticProvider, AgenticProviderExecuteFn
from composio.types import Tool
from my_provider import AgentTool

# Import the Tool/Function class that represents a callable tool for your framework
# Optionally define your custom tool format below
# class AgentTool:
#     def __init__(self, name: str, description: str, execute: Callable, schema: dict):
#         self.name = name
#         self.description = description
#         self.execute = execute
#         self.schema = schema

# Define your tool collection format (typically a List)
AgentToolCollection: TypeAlias = List[AgentTool]

# Create your provider
class MyAgentProvider(AgenticProvider[AgentTool, List[AgentTool]], name="my-agent-platform"):
    """Custom provider for My Agent Platform"""

    def wrap_tool(self, tool: Tool, execute_tool: AgenticProviderExecuteFn) -> AgentTool:
        """Transform a single tool with execute function"""
        def execute_wrapper(**kwargs) -> Dict:
            result = execute_tool(tool.slug, kwargs)
            if not result.get("successful", False):
                raise Exception(result.get("error", "Tool execution failed"))
            return result.get("data", {})

        return AgentTool(
            name=tool.slug,
            description=tool.description or "",
            execute=execute_wrapper,
            schema=tool.input_parameters
        )

    def wrap_tools(
        self,
        tools: Sequence[Tool],
        execute_tool: AgenticProviderExecuteFn
    ) -> AgentToolCollection:
        """Transform a collection of tools with execute function"""
        return [self.wrap_tool(tool, execute_tool) for tool in tools]
```

## Using your custom provider

After creating your provider, use it with the Composio SDK:

### Non-agentic provider example

```python
from composio import Composio
from composio_myai import MyAIProvider
from myai import MyAIClient  # Your AI platform's client

# Initialize tools
myai_client = MyAIClient()
composio = Composio(provider=MyAIProvider())

# Define task
task = "Star a repo composiohq/composio on GitHub"

# Get GitHub tools that are pre-configured
tools = composio.tools.get(user_id="default", toolkits=["GITHUB"])

# Get response from your AI platform (example)
response = myai_client.chat.completions.create(
    model="your-model",
    tools=tools,  # These are in your platform's format
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": task},
    ],
)
print(response)

# Execute the function calls
result = composio.provider.handle_tool_calls(response=response, user_id="default")
print(result)
```

### Agentic provider example

```python
import asyncio
from agents import Agent, Runner
from composio_myagent import MyAgentProvider
from composio import Composio

# Initialize Composio toolset
composio = Composio(provider=MyAgentProvider())

# Get all the tools
tools = composio.tools.get(
    user_id="default",
    tools=["GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER"],
)

# Create an agent with the tools
agent = Agent(
    name="GitHub Agent",
    instructions="You are a helpful assistant that helps users with GitHub tasks.",
    tools=tools,
)

# Run the agent
async def main():
    result = await Runner.run(
        starting_agent=agent,
        input=(
            "Star the repository composiohq/composio on GitHub. If done "
            "successfully, respond with 'Action executed successfully'"
        ),
    )
    print(result.final_output)

asyncio.run(main())
```

## Best practices

1. **Keep providers focused**: Each provider should integrate with one specific platform
2. **Handle errors gracefully**: Catch and transform errors from tool execution
3. **Follow platform conventions**: Adopt naming and structural conventions of the target platform
4. **Use type annotations**: Leverage Python's typing system for better IDE support and documentation
5. **Cache transformed tools**: Store transformed tools when appropriate to improve performance
6. **Add helper methods**: Provide convenient methods for common platform-specific operations
7. **Document your provider**: Include docstrings and usage examples
8. **Set meaningful provider names**: Use the name parameter for telemetry and debugging

---

# TypeScript Custom Provider (/docs/providers/custom-providers/typescript)

This guide provides a comprehensive walkthrough of creating custom providers for the Composio TypeScript SDK, enabling integration with different AI frameworks and platforms.

## Provider Architecture

The Composio SDK uses a provider architecture to adapt tools for different AI frameworks. The provider handles:

1. **Tool Format Transformation**: Converting Composio tools into formats compatible with specific AI platforms
2. **Tool Execution**: Managing the flow of tool execution and results
3. **Platform-Specific Integration**: Providing helper methods for seamless integration

## Types of Providers

There are two types of providers:

1. **Non-Agentic Providers**: Transform tools for platforms that don't have their own agency (e.g., OpenAI)
2. **Agentic Providers**: Transform tools for platforms that have their own agency (e.g., LangChain, AutoGPT)

## Provider Class Hierarchy

```
BaseProvider (Abstract)
├── BaseNonAgenticProvider (Abstract)
│   └── OpenAIProvider (Concrete)
│   └── [Your Custom Non-Agentic Provider] (Concrete)
└── BaseAgenticProvider (Abstract)
    └── [Your Custom Agentic Provider] (Concrete)
```

## Creating a Non-Agentic Provider

Non-agentic providers implement the `BaseNonAgenticProvider` abstract class:

```typescript
import { BaseNonAgenticProvider, Tool } from '@composio/core';

// Define your tool format
interface MyAITool {
  name: string;
  description: string;
  parameters: {
    type: string;
    properties: Record<string, unknown>;
    required?: string[];
  };

// Define your tool collection format
type MyAIToolCollection = MyAITool[];

// Create your provider
export class MyAIProvider extends BaseNonAgenticProvider {
  // Required: Unique provider name for telemetry
  readonly name = 'my-ai-platform';

  // Required: Method to transform a single tool
  override wrapTool(tool: Tool): MyAITool {
    return {
      name: tool.slug,
      description: tool.description || '',
      parameters: {
        type: 'object',
        properties: tool.inputParameters?.properties || {},
        required: tool.inputParameters?.required || [],
      },
    };

  // Required: Method to transform a collection of tools
  override wrapTools(tools: Tool[]): MyAIToolCollection {
    return tools.map(tool => this.wrapTool(tool));

  // Optional: Custom helper methods for your AI platform
  async executeMyAIToolCall(
    userId: string,
    toolCall: {
      name: string;
      arguments: Record<string, unknown>;

  ): Promise<string> {
    // Use the built-in executeTool method
    const result = await this.executeTool(toolCall.name, {
      userId,
      arguments: toolCall.arguments,
    });

    return JSON.stringify(result.data);

```

## Creating an Agentic Provider

Agentic providers implement the `BaseAgenticProvider` abstract class:

```typescript
// @noErrors
import { BaseAgenticProvider, Tool, ExecuteToolFn } from '@composio/core';

// Define your tool format
interface AgentTool {
  name: string;
  description: string;
  execute: (args: Record<string, unknown>) => Promise<unknown>;
  schema: Record<string, unknown>;

// Define your tool collection format
interface AgentToolkit {
  tools: AgentTool[];
  createAgent: (config: Record<string, unknown>) => unknown;

// Create your provider
export class MyAgentProvider extends BaseAgenticProvider {
  // Required: Unique provider name for telemetry
  readonly name = 'my-agent-platform';

  // Required: Method to transform a single tool with execute function
  override wrapTool(tool: Tool, executeToolFn: ExecuteToolFn): AgentTool {
    return {
      name: tool.slug,
      description: tool.description || '',
      schema: tool.inputParameters || {},
      execute: async (args: Record<string, unknown>) => {
        const result = await executeToolFn(tool.slug, args);
        if (!result.successful) {
          throw new Error(result.error || 'Tool execution failed');

        return result.data;
      },
    };

  // Required: Method to transform a collection of tools with execute function
  override wrapTools(tools: Tool[], executeToolFn: ExecuteToolFn): AgentToolkit {
    const agentTools = tools.map(tool => this.wrapTool(tool, executeToolFn));

    return {
      tools: agentTools,
      createAgent: config => {
        // Create an agent using the tools
        return {
          run: async (prompt: string) => {
            // Implementation depends on your agent framework
            console.log(`Running agent with prompt: ${prompt}`);
            // The agent would use the tools.execute method to run tools
          },
        };
      },
    };

  // Optional: Custom helper methods for your agent platform
  async runAgent(agentToolkit: AgentToolkit, prompt: string): Promise<unknown> {
    const agent = agentToolkit.createAgent({});
    return await agent.run(prompt);

```

## Using Your Custom Provider

After creating your provider, use it with the Composio SDK:

```typescript
// @noErrors
import { Composio } from '@composio/core';
import { MyAIProvider } from './my-ai-provider';

// Create your provider instance
const myProvider = new MyAIProvider();

// Initialize Composio with your provider
const composio = new Composio({
  apiKey: 'your-composio-api-key',
  provider: myProvider,
});

// Get tools - they will be transformed by your provider
const tools = await composio.tools.get('default', {
  toolkits: ['github'],
});

// Use the tools with your AI platform
console.log(tools); // These will be in your custom format
```

## Provider State and Context

Your provider can maintain state and context:

```typescript
// @noErrors
export class StatefulProvider extends BaseNonAgenticProvider {
  readonly name = 'stateful-provider';

  // Provider state
  private requestCount = 0;
  private toolCache = new Map<string, any>();
  private config: ProviderConfig;

  constructor(config: ProviderConfig) {
    super();
    this.config = config;

  override wrapTool(tool: Tool): ProviderTool {
    this.requestCount++;

    // Use the provider state/config
    const enhancedTool = {
      // Transform the tool
      name: this.config.useUpperCase ? tool.slug.toUpperCase() : tool.slug,
      description: tool.description,
      schema: tool.inputParameters,
    };

    // Cache the transformed tool
    this.toolCache.set(tool.slug, enhancedTool);

    return enhancedTool;

  override wrapTools(tools: Tool[]): ProviderToolCollection {
    return tools.map(tool => this.wrapTool(tool));

  // Custom methods that use provider state
  getRequestCount(): number {
    return this.requestCount;

  getCachedTool(slug: string): ProviderTool | undefined {
    return this.toolCache.get(slug);

```

## Advanced: Provider Composition

You can compose functionality by extending existing providers:

```typescript
// @noErrors
import { OpenAIProvider } from '@composio/openai';

// Extend the OpenAI provider with custom functionality
export class EnhancedOpenAIProvider extends OpenAIProvider {
  // Add properties
  private analytics = {
    toolCalls: 0,
    errors: 0,
  };

  // Override methods to add functionality
  override async executeToolCall(userId, tool, options, modifiers) {
    this.analytics.toolCalls++;

    try {
      // Call the parent implementation
      const result = await super.executeToolCall(userId, tool, options, modifiers);
      return result;
    } catch (error) {
      this.analytics.errors++;
      throw error;

  // Add new methods
  getAnalytics() {
    return this.analytics;

  async executeWithRetry(userId, tool, options, modifiers, maxRetries = 3) {
    let attempts = 0;
    let lastError;

    while (attempts < maxRetries) {
      try {
        return await this.executeToolCall(userId, tool, options, modifiers);
      } catch (error) {
        lastError = error;
        attempts++;
        await new Promise(resolve => setTimeout(resolve, 1000 * attempts));

    throw lastError;

```

## Best Practices

1. **Keep providers focused**: Each provider should integrate with one specific platform
2. **Handle errors gracefully**: Catch and transform errors from tool execution
3. **Follow platform conventions**: Adopt naming and structural conventions of the target platform
4. **Optimize for performance**: Cache transformed tools when possible
5. **Add helper methods**: Provide convenient methods for common platform-specific operations
6. **Provide clear documentation**: Document your provider's unique features and usage
7. **Use telemetry**: Set a meaningful provider name for telemetry insights

---


# Tool Router


---

# Authentication (/tool-router/authentication)

Tool Router handles authentication through [Connect Links](/docs/authenticating-tools#hosted-authentication-connect-link), hosted pages where users complete OAuth or enter credentials.

## In-chat authentication

By default, when a tool requires authentication, the agent prompts the user with a Connect Link. The user authenticates and confirms in chat. The agent handles OAuth flows, token refresh, and credential management automatically.

Here's what this looks like in a conversation:

```
You: Star the composio repo on GitHub

Agent: I need you to connect your GitHub account first.
       Please click here to authorize: https://connect.composio.dev/link/ln_abc123

You: Done

Agent: Done! I've starred ComposioHQ/composio.
```

This flow works well for chat applications where users interact directly with the agent. See [Using in-chat authentication](/tool-router/using-in-chat-authentication).

## Manual authentication

For apps that manage auth outside of chat, use `session.authorize()` to generate Connect Links programmatically:

**Python:**

```python
connection_request = session.authorize("github")
print(connection_request.redirect_url)
# https://connect.composio.dev/link/ln_abc123
```

**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const session = await composio.toolRouter.create('user_123', { toolkits: ['github'] });
// ---cut---
const connectionRequest = await session.authorize("github");
console.log(connectionRequest.redirectUrl);
// https://connect.composio.dev/link/ln_abc123
```

Use this when you want users to connect accounts during onboarding, or when building a custom connections page. See [Manually authenticating users](/tool-router/manually-authenticating-users) for a detailed guide.

## How Tool Router manages auth configs

When executing a tool, Tool Router needs an auth config to find or create a connected account. It handles this automatically:

1. Uses your `authConfigs` override if provided
2. Otherwise, reuses an auth config it previously created for this toolkit
3. If none exists, creates one using Composio managed auth

You don't need to create auth configs manually for most toolkits.

## Supported auth methods

Tool Router supports **Composio managed OAuth** (GitHub, Gmail, Slack, and most toolkits) and **API key auth** (users enter their own keys via Connect Link).

> 
Toolkits without Composio managed auth require a custom auth config. See [Using custom auth configs](/tool-router/using-custom-auth-configs).

## White-labeling

Show your own branding on OAuth consent screens by creating your own OAuth app. See [White-labeling authentication](/tool-router/white-labeling-authentication).

---

# Overview (/tool-router)

Tool Router is a unified interface that lets an agent **search**, **plan**, **authenticate**, and **execute** actions across thousands of Composio tools.

Consider an agent that works across Gmail, Notion, Slack, Google Drive, and hundreds of other apps. The challenges:

- **Search**: Identifying the right tool for the task
- **Context Management**: Managing context for complex queries with large responses
- **Authentication**: Handling authentication across all of them

Tool Router exposes a set of meta-tools that handle all this complexity including search to discover the right tools, and a workbench to process results without flooding context.

This is what powers complex agentic products like [Rube](https://rube.app).

## Quick links

- [Quickstart](/tool-router/quickstart): Build your first AI agent with Tool Router.
- [Using with MCP clients](/tool-router/using-with-mcp-clients): Guides on how to use Tool Router MCP with popular MCP clients.
- [Using as a native tool](/tool-router/using-as-a-native-tool): Guide on how to use Tool Router as a native tool with any AI framework.

---

# Managing multiple accounts (/tool-router/managing-multiple-accounts)

Users can connect multiple accounts for the same toolkit (e.g., personal and work Gmail accounts). This is useful when users need to manage different email accounts, GitHub organizations, or separate work and personal contexts. This guide explains how to connect, select, and manage multiple accounts.

## Default account behavior

When multiple accounts are connected for the same toolkit:
- Each session can only use **one account per toolkit** at a time
- Tool Router uses the **most recently connected account** by default
- You can override this by explicitly selecting an account
- Each account maintains its own authentication and permissions

## Connecting multiple accounts

Call `session.authorize()` multiple times for the same toolkit. Each authorization creates a separate connected account with its own ID. The most recently connected account becomes the active one for that session. New sessions will also use the most recent account unless you [explicitly select a different one](#selecting-a-specific-account-for-a-session).

**Python:**

```python
session = composio.create(user_id="user_123")

# Connect first account (work)
work_auth = session.authorize("gmail")
print(f"Connect work Gmail: {work_auth.redirect_url}")
work_connection = work_auth.wait_for_connection()
print(f"Work account connected: {work_connection.id}")

# Connect second account (personal)
personal_auth = session.authorize("gmail")
print(f"Connect personal Gmail: {personal_auth.redirect_url}")
personal_connection = personal_auth.wait_for_connection()
print(f"Personal account connected: {personal_connection.id}")
```

**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const session = await composio.create("user_123");

// Connect first account (work)
const workAuth = await session.authorize("gmail");
console.log(`Connect work Gmail: ${workAuth.redirectUrl}`);
const workConnection = await workAuth.waitForConnection();
console.log(`Work account connected: ${workConnection.id}`);

// Connect second account (personal)
const personalAuth = await session.authorize("gmail");
console.log(`Connect personal Gmail: ${personalAuth.redirectUrl}`);
const personalConnection = await personalAuth.waitForConnection();
console.log(`Personal account connected: ${personalConnection.id}`);
```

> 
Store the account IDs returned after connection to explicitly select accounts later.

## Selecting a specific account for a session

Each Tool Router session can only use one account per toolkit at a time. To use a specific account in a session, pass it in the session config:

**Python:**

```python
# This session will use a specific Gmail account
session = composio.create(
    user_id="user_123",
    connected_accounts={
        "gmail": "ca_specific_account_id",  # Connected account ID
    },
)

# To switch accounts, create a new session with a different account ID
session2 = composio.create(
    user_id="user_123",
    connected_accounts={
        "gmail": "ca_different_account_id",  # Different account
    },
)
```

**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
// This session will use a specific Gmail account
const session = await composio.create("user_123", {
  connectedAccounts: {
    gmail: "ca_specific_account_id",  // Connected account ID
  },
});

// To switch accounts, create a new session with a different account ID
const session2 = await composio.create("user_123", {
  connectedAccounts: {
    gmail: "ca_different_account_id",  // Different account
  },
});
```

## Listing all user accounts

To list all accounts a user has connected (not just the active one), see [List accounts](/docs/connected-accounts#list-accounts).

## Viewing session's active account

Use `session.toolkits()` to see which account is currently active in the session:

**Python:**

```python
toolkits = session.toolkits()

for toolkit in toolkits.items:
    if toolkit.connection.connected_account:
        print(f"{toolkit.name}: {toolkit.connection.connected_account.id}")
```

**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const session = await composio.create("user_123");
// ---cut---
const toolkits = await session.toolkits();

for (const toolkit of toolkits.items) {
  if (toolkit.connection?.connectedAccount) {
    console.log(`${toolkit.name}: ${toolkit.connection.connectedAccount.id}`);

```

---

# Manually authenticating users (/tool-router/manually-authenticating-users)

Manual authentication lets you connect users to toolkits outside of the chat flow. Use this when you want to:
- Pre-authenticate users before they start chatting
- Build a custom connections UI in your app

## Authorize a toolkit

Use `session.authorize()` to generate a [Connect Link](/docs/authenticating-tools#hosted-authentication-connect-link) URL, redirect the user, and wait for them to complete:

**Python:**

```python
session = composio.create(user_id="user_123")

connection_request = session.authorize("gmail")

print(connection_request.redirect_url)
# https://connect.composio.dev/link/ln_abc123

connected_account = connection_request.wait_for_connection(60000)
print(f"Connected: {connected_account.id}")
```

**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const session = await composio.create("user_123");

const connectionRequest = await session.authorize("gmail");

console.log(connectionRequest.redirectUrl);
// https://connect.composio.dev/link/ln_abc123

const connectedAccount = await connectionRequest.waitForConnection(60000);
console.log(`Connected: ${connectedAccount.id}`);
```

Redirect the user to the redirect URL. After they authenticate, they'll return to your callback URL. The connection request polls until the user completes authentication (default timeout: 60 seconds).

> 
If the user closes the Connect Link without completing auth, the connection remains in `INITIATED` status until it expires.

## Check connection status

Use `session.toolkits()` to see all toolkits in the session and their connection status:

**Python:**

```python
toolkits = session.toolkits()

for toolkit in toolkits.items:
    status = toolkit.connection.connected_account.id if toolkit.connection.is_active else "Not connected"
    print(f"{toolkit.name}: {status}")
```

**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const session = await composio.create("user_123");
// ---cut---
const toolkits = await session.toolkits();

toolkits.items.forEach((toolkit) => {
  console.log(`${toolkit.name}: ${toolkit.connection?.connectedAccount?.id ?? "Not connected"}`);
});
```

## Disabling in-chat auth

By default, Tool Router includes the `COMPOSIO_MANAGE_CONNECTIONS` meta-tool that prompts users to authenticate during chat. To disable this and handle auth entirely in your UI:

**Python:**

```python
session = composio.create(
    user_id="user_123",
    manage_connections=False,
)
```

**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const session = await composio.create("user_123", {
  manageConnections: false,
});
```

## Putting it together

A common pattern is to verify all required connections before starting the agent:

**Python:**

```python
from composio import Composio

composio = Composio(api_key="your-api-key")

required_toolkits = ["gmail", "github"]

session = composio.create(
    user_id="user_123",
    manage_connections=False,  # Disable in-chat auth prompts
)

toolkits = session.toolkits()

connected = {t.slug for t in toolkits.items if t.connection.is_active}
pending = [slug for slug in required_toolkits if slug not in connected]

print(f"Connected: {connected}")
print(f"Pending: {pending}")

for slug in pending:
    connection_request = session.authorize(slug)
    print(f"Connect {slug}: {connection_request.redirect_url}")
    connection_request.wait_for_connection()

print(f"All toolkits connected! MCP URL: {session.mcp.url}")
```

**TypeScript:**

```typescript
import { Composio } from "@composio/core";

const composio = new Composio({ apiKey: "your-api-key" });

const requiredToolkits = ["gmail", "github"];

const session = await composio.create("user_123", {
  manageConnections: false, // Disable in-chat auth prompts
});

const toolkits = await session.toolkits();

const connected = toolkits.items
  .filter((t) => t.connection?.connectedAccount)
  .map((t) => t.slug);

const pending = requiredToolkits.filter((slug) => !connected.includes(slug));

console.log("Connected:", connected);
console.log("Pending:", pending);

for (const slug of pending) {
  const connectionRequest = await session.authorize(slug);
  console.log(`Connect ${slug}: ${connectionRequest.redirectUrl}`);
  await connectionRequest.waitForConnection();

console.log(`All toolkits connected! MCP URL: ${session.mcp.url}`);
```

---

# Quickstart (/tool-router/quickstart)

Choose how you want to integrate Tool Router:

**Claude Agent SDK:**

### Step: Install

```bash
pip install python-dotenv composio claude-agent-sdk
```

**TypeScript:**

```bash
npm install dotenv @composio/core @anthropic-ai/claude-agent-sdk
```

### Step: Create session and run agent

[Sessions](/tool-router/users-and-sessions) are ephemeral, user-scoped and manage connections and tools for that user.

> 
- Set `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
- Set `ANTHROPIC_API_KEY` environment variable with your [Anthropic API key](https://platform.claude.com/settings/keys).
- `userId` is your user's unique identifier. See [User Management](/docs/user-management) for details.

When the agent needs authentication, it will prompt the user with a link to connect their account. If you want to customise the authentication flow and have more control over the user experience, see [Manual Authentication](/tool-router/manually-authenticating-users).

**Python:**

```python
import asyncio
from dotenv import load_dotenv
from claude_agent_sdk.client import ClaudeSDKClient
from claude_agent_sdk.types import (
    ClaudeAgentOptions,
    AssistantMessage,
    TextBlock,
    ToolUseBlock,
)
from composio import Composio

load_dotenv()

# Initialize Composio (API key from env var COMPOSIO_API_KEY)
composio = Composio()

# Unique identifier of the user
user_id = "user_123"

# Create a tool router session for the user
session = composio.create(user_id=user_id)

# Configure Claude with Composio MCP server
options = ClaudeAgentOptions(
    system_prompt=(
        "You are a helpful assistant with access to external tools. "
        "Always use the available tools to complete user requests."
    ),
    mcp_servers={
        "composio": {
            "type": "http",
            "url": session.mcp.url,
            "headers": session.mcp.headers,

    },
    permission_mode="bypassPermissions",
)

async def main():
    print("""
What task would you like me to help you with?
I can use tools like Gmail, GitHub, Linear, Notion, and more.
(Type 'exit' to exit)
Example tasks:
  • 'Summarize my emails from today'
  • 'List all open issues on the composio github repository and create a notion page with the issues'
""")

    async with ClaudeSDKClient(options) as client:
        # Multi-turn conversation with agentic tool calling
        while True:
            user_input = input("You: ").strip()
            if user_input.lower() == "exit":
                break

            print("\nClaude: ", end="", flush=True)
            try:
                await client.query(user_input)
                async for msg in client.receive_response():
                    if isinstance(msg, AssistantMessage):
                        for block in msg.content:
                            if isinstance(block, ToolUseBlock):
                                print(f"\n[Using tool: {block.name}]", end="")
                            elif isinstance(block, TextBlock):
                                print(block.text, end="", flush=True)
                print()
            except Exception as e:
                print(f"\n[Error]: {e}")

if __name__ == "__main__":
    asyncio.run(main())
```

**TypeScript:**

```typescript
import "dotenv/config";
import { query, type Options } from "@anthropic-ai/claude-agent-sdk";
import { Composio } from "@composio/core";
import { createInterface } from "readline/promises";

// Initialize Composio (API key from env var COMPOSIO_API_KEY or pass explicitly: { apiKey: "your-key" })
const composio = new Composio();

// Unique identifier of the user
const userId = "user_123";

// Create a tool router session for the user
const session = await composio.create(userId);

const options: Options = {
  systemPrompt: `You are a helpful assistant with access to external tools. ` +
    `Always use the available tools to complete user requests.`,
  mcpServers: {
    composio: {
      type: "http",
      url: session.mcp.url,
      headers: session.mcp.headers // Authentication headers for the Composio MCP server
    },
  },
  permissionMode: "bypassPermissions", // Auto-approve tools (demo only - use "default" in production)
};

// Set up interactive terminal input/output for the conversation
const readline = createInterface({ input: process.stdin, output: process.stdout });

console.log(`
What task would you like me to help you with?
I can use tools like Gmail, GitHub, Linear, Notion, and more.
(Type 'exit' to exit)
Example tasks:
  • 'Summarize my emails from today'
  • 'List all open issues on the composio github repository and create a Google Sheet with the issues'
`);

let isFirstQuery = true;

// Multi-turn conversation with agentic tool calling
while (true) {
  const answer = await readline.question('You: ');
  const input = answer.trim();
  if (input.toLowerCase() === "exit") break;

  process.stdout.write("Claude: ");

  // Use `continue: true` to maintain conversation context
  const queryOptions = isFirstQuery ? options : { ...options, continue: true };
  isFirstQuery = false;

  try {
    for await (const stream of query({ prompt: input, options: queryOptions })) {
      // Only process assistant messages (the SDK also sends result/error messages)
      if (stream.type === "assistant") {
        const { content } = stream.message;
        for (const block of content) {
          if (block.type === "tool_use") {
            process.stdout.write(`\n[Using tool: ${block.name}]`);
          } else if (block.type === "text") {
            process.stdout.write(block.text);

  } catch (error) {
    console.error("\n[Error]:", error instanceof Error ? error.message : error);

  process.stdout.write("\n");

readline.close();
```

**OpenAI Agents SDK:**

### Step: Install

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

**TypeScript:**

```bash
npm install dotenv @composio/core @openai/agents zod@3
```

### Step: Create session and run agent

[Sessions](/tool-router/users-and-sessions) are ephemeral, user-scoped and manage connections and tools for that user.

> 
- Set `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
- Set `OPENAI_API_KEY` environment variable with your [OpenAI API key](https://platform.openai.com/api-keys).
- `userId` is your user's unique identifier. See [User Management](/docs/user-management) for details.

When the agent needs authentication, it will prompt the user with a link to connect their account. If you want to customise the authentication flow and have more control over the user experience, see [Manual Authentication](/tool-router/manually-authenticating-users).

**Python:**

```python
from dotenv import load_dotenv
from composio import Composio
from agents import Agent, Runner, HostedMCPTool, SQLiteSession

load_dotenv()

# Initialize Composio (API key from env var COMPOSIO_API_KEY)
composio = Composio()

# Unique identifier of the user
user_id = "user_123"

# Create a Tool Router session for the user
session = composio.create(user_id=user_id)

# Configure OpenAI agent with Composio MCP server
agent = Agent(
    name="Personal Assistant",
    instructions="You are a helpful personal assistant. Use Composio tools to take action.",
    model="gpt-5.2",
    tools=[
        HostedMCPTool(
            tool_config={
                "type": "mcp",
                "server_label": "composio",
                "server_url": session.mcp.url,
                "require_approval": "never",
                "headers": session.mcp.headers,

        )
    ],
)

# Memory for multi-turn conversation
memory = SQLiteSession(user_id)

print("""
What task would you like me to help you with?
I can use tools like Gmail, GitHub, Linear, Notion, and more.
(Type 'exit' to exit)
Example tasks:
  • 'Summarize my emails from today'
  • 'List all open issues on the composio github repository'
""")

while True:
    user_input = input("You: ").strip()
    if user_input.lower() == "exit":
        break

    print("Assistant: ", end="", flush=True)
    try:
        result = Runner.run_sync(starting_agent=agent, input=user_input, session=memory)
        print(f"{result.final_output}\n")
    except Exception as e:
        print(f"\n[Error]: {e}")
```

**TypeScript:**

```typescript
import "dotenv/config";
import { Composio } from "@composio/core";
import { Agent, run, hostedMcpTool, MemorySession } from "@openai/agents";
import { createInterface } from "readline/promises";

// Initialize Composio (API key from env var COMPOSIO_API_KEY or pass explicitly: { apiKey: "your-key" })
const composio = new Composio();

// Unique identifier of the user
const userId = "user_123";

// Create a tool router session for the user
const session = await composio.create(userId);

const agent = new Agent({
  name: "Personal Assistant",
  instructions: "You are a helpful personal assistant. Use Composio tools to take action.",
  model: "gpt-5.2",
  tools: [
    hostedMcpTool({
      serverLabel: "composio",
      serverUrl: session.mcp.url,
      headers: session.mcp.headers // Authentication headers for the Composio MCP server
    }),
  ],
});

// Create a memory session for persistent multi-turn conversation
const memory = new MemorySession();

// Set up interactive terminal input/output for the conversation
const readline = createInterface({ input: process.stdin, output: process.stdout });

console.log(`
What task would you like me to help you with?
I can use tools like Gmail, GitHub, Linear, Notion, and more.
(Type 'exit' to exit)
Example tasks:
  • 'Summarize my emails from today'
  • 'List all open issues on the composio github repository and create a Google Sheet with the issues'
`);

// Multi-turn conversation with agentic tool calling
while (true) {
  const input = (await readline.question("You: ")).trim();
  if (input.toLowerCase() === "exit") break;

  console.log("Assistant: ");

  try {
    // Multi-turn agentic loop: GPT calls tools and reasons until task is complete
    const result = await run(agent, input, { session: memory });
    console.log(`${result.finalOutput}`);
  } catch (error) {
    console.error("\n[Error]:", error instanceof Error ? error.message : error);

readline.close();
```

**Vercel AI SDK:**

### Step: Install Composio SDK

```bash
npm install dotenv @composio/core ai @ai-sdk/anthropic @ai-sdk/mcp
```

### Step: Create session and run agent

[Sessions](/tool-router/users-and-sessions) are ephemeral, user-scoped and manage connections and tools for that user.

> 
- Set `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
- Set `ANTHROPIC_API_KEY` environment variable with your [Anthropic API key](https://platform.claude.com/settings/keys).
- `userId` is your user's unique identifier. See [User Management](/docs/user-management) for details.

When the agent needs authentication, it will prompt the user with a link to connect their account. If you want to customise the authentication flow and have more control over the user experience, see [Manual Authentication](/tool-router/manually-authenticating-users).

```typescript
import "dotenv/config";
import { anthropic } from "@ai-sdk/anthropic";
import { experimental_createMCPClient as createMCPClient } from "@ai-sdk/mcp";
import { Composio } from "@composio/core";
import { stepCountIs, streamText } from "ai";

// Initialize Composio (API key from env var COMPOSIO_API_KEY or pass explicitly: { apiKey: "your-key" })
const composio = new Composio();

// Unique identifier of the user
const userId = "user_123";

// Create a tool router session for the user
const { mcp } = await composio.create(userId);

// Create an MCP client to connect to the Composio tool router
const client = await createMCPClient({
  transport: {
    type: "http",
    url: mcp.url,
    headers: mcp.headers, // Authentication headers for the Composio MCP server
  },
});
const tools = await client.tools();

console.log("Summarizing your emails from today");

const stream = await streamText({
  system: "You are a helpful personal assistant. Use Composio tools to take action.",
  model: anthropic("claude-sonnet-4-5"),
  prompt: "Summarize my emails from today",
  stopWhen: stepCountIs(10),
  onStepFinish: (step) => {
    for (const toolCall of step.toolCalls) {
      console.log(`[Using tool: ${toolCall.toolName}]`);

  },
  tools,
});

for await (const textPart of stream.textStream) {
  process.stdout.write(textPart);

console.log("\n\n---");
console.log("Tip: If prompted to authenticate, complete the auth flow and run again.");
```

### What just happened?

When you run this agent, Tool Router:
1. **Creates an MCP server** with your session configuration
2. **Searches** for the right tools based on your request
3. **Handles authentication** if needed
4. **Executes tools** and uses a workbench for processing large responses

**OpenAI:**

### Step: Install

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

**TypeScript:**

```bash
npm install @composio/core @composio/openai-agents @openai/agents
```

### Step: Create session and use as native tool

Tool Router can be added as a single native tool to your agent. This provides a meta-tool that handles search, authentication, and execution across all 1000+ Composio tools.

> 
- Set `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
- Set `OPENAI_API_KEY` environment variable with your [OpenAI API key](https://platform.openai.com/api-keys).
- `userId` is your user's unique identifier. See [User Management](/docs/user-management) for details.

**Python:**

```python
from dotenv import load_dotenv
from composio import Composio
from agents import Agent, Runner, SQLiteSession
from composio_openai_agents import OpenAIAgentsProvider

load_dotenv()

# Initialize Composio with OpenAI Agents provider (API key from env var COMPOSIO_API_KEY)
composio = Composio(provider=OpenAIAgentsProvider())

# Unique identifier of the user
user_id = "user_123"

# Create a session and get native tools for the user
session = composio.create(user_id=user_id)
tools = session.tools()

# Configure OpenAI agent with Composio tools
agent = Agent(
    name="Personal Assistant",
    instructions="You are a helpful personal assistant. Use Composio tools to take action.",
    model="gpt-5.2",
    tools=tools,
)

# Memory for multi-turn conversation
memory = SQLiteSession("conversation")

print("""
What task would you like me to help you with?
I can use tools like Gmail, GitHub, Linear, Notion, and more.
(Type 'exit' to exit)
Example tasks:
  • 'Summarize my emails from today'
  • 'List all open issues on the composio github repository'
""")

while True:
    user_input = input("You: ").strip()
    if user_input.lower() == "exit":
        break

    print("Assistant: ", end="", flush=True)
    try:
        result = Runner.run_sync(starting_agent=agent, input=user_input, session=memory)
        print(f"{result.final_output}\n")
    except Exception as e:
        print(f"\n[Error]: {e}")
```

**TypeScript:**

```typescript
import "dotenv/config";
import { Composio } from "@composio/core";
import { Agent, run, MemorySession } from "@openai/agents";
import { OpenAIAgentsProvider } from "@composio/openai-agents";
import { createInterface } from "readline/promises";

// Initialize Composio with OpenAI Agents provider (API key from env var COMPOSIO_API_KEY)
const composio = new Composio({ provider: new OpenAIAgentsProvider() });

// Unique identifier of the user
const userId = "user_123";
// Create a tool router session for the user
const session = await composio.create(userId);
const tools = await session.tools();

const agent = new Agent({
  name: "Personal Assistant",
  instructions: "You are a helpful personal assistant. Use Composio tools to take action.",
  model: "gpt-5.2",
  tools,
});

// Set up interactive terminal input/output for the conversation
const readline = createInterface({ input: process.stdin, output: process.stdout });
// Create a memory session for persistent multi-turn conversation
const memory = new MemorySession();

console.log(`
What task would you like me to help you with?
I can use tools like Gmail, GitHub, Linear, Notion, and more.
(Type 'exit' to exit)
Example tasks:
  • 'Summarize my emails from today'
  • 'List all open issues on the composio github repository and create a Google Sheet with the issues'
`);

// Multi-turn conversation with agentic tool calling
while (true) {
    const query = await readline.question("You: ");
    const input = query.trim();

    if (input.toLowerCase() === "exit") break;
    process.stdout.write("Assistant: ");

    try {
      const result = await run(agent, input, { session: memory });
      process.stdout.write(`${result.finalOutput}`);
    } catch (error) {
    console.error("\n[Error]:", error instanceof Error ? error.message : error);

readline.close();
```

**Vercel AI SDK:**

### Step: Install

```bash
npm install @composio/core @composio/vercel ai @ai-sdk/anthropic
```

### Step: Create session and use as native tool

Tool Router can be added as a single native tool to your agent. This provides a meta-tool that handles search, authentication, and execution across all 1000+ Composio tools.

> 
- Set `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
- Set `ANTHROPIC_API_KEY` environment variable with your [Anthropic API key](https://console.anthropic.com/settings/keys).
- `userId` is your user's unique identifier. See [User Management](/docs/user-management) for details.

```typescript
import "dotenv/config";
import { anthropic } from "@ai-sdk/anthropic";
import { Composio } from "@composio/core";
import { VercelProvider } from "@composio/vercel";
import { stepCountIs, streamText } from "ai";

// Initialize Composio with Vercel provider (API key from env var COMPOSIO_API_KEY)
const composio = new Composio({ provider: new VercelProvider() });

// Unique identifier of the user
const userId = "user_123";

// Create a session and get native tools for the user
const session = await composio.create(userId);
const tools = await session.tools();

process.stdout.write("Summarizing your emails from today");
process.stdout.write("\n");

const stream = await streamText({
  system: "You are a helpful personal assistant. Use Composio tools to take action.",
  model: anthropic("claude-sonnet-4-5"),
  prompt: "Summarize my emails from today",
  stopWhen: stepCountIs(10),
  onStepFinish: (step) => {
    for (const toolCall of step.toolCalls) {
      process.stdout.write(`[Using tool: ${toolCall.toolName}]`);
      process.stdout.write("\n");

  },
  tools,
});

for await (const textPart of stream.textStream) {
  process.stdout.write(textPart);

process.stdout.write("\n");
process.stdout.write("Tip: If prompted to authenticate, complete the auth flow and run again.");
```

### What just happened?

When you run this agent, Tool Router:
1. **Provides a single tool** to your agent framework
2. **Interprets requests** and **searches** for the right tools internally
3. **Handles authentication** if needed
4. **Executes tools** and uses a workbench for processing large responses

## Next steps

- [Session management](/tool-router/users-and-sessions): 
    Learn about users, sessions, and how they work.
  
  - [Tools and toolkits](/tool-router/tools-and-toolkits): 
    Learn about tools, toolkits, and how to configure them.
  
  - [Manual authentication](/tool-router/manually-authenticating-users): 
    Customise the authentication flow for your users.
  
  - [Using MCP](/tool-router/using-with-mcp-clients): 
    Connect Tool Router to any MCP-compatible client.
  
  - [Using as a native tool](/tool-router/using-as-a-native-tool): 
    Use Tool Router as a native tool with any AI framework.

---

# Tools and toolkits (/tool-router/tools-and-toolkits)

Tool Router gives your agent access to most Composio toolkits by default. For details on configuring which toolkits are available in a session, see [Users and sessions](/tool-router/users-and-sessions#enabling-toolkits).

## Toolkits and tools

A **toolkit** is a collection of related tools for a service and a **tool** is an individual action your agent can execute.

| Toolkit | Tools |
|---------|-------|
| `github` | `GITHUB_CREATE_A_COMMIT`, `GITHUB_ACTIVITY_LIST_STARGAZERS_FOR_REPO`, `GITHUB_SEARCH_REPO_S`, ... |
| `gmail` | `GMAIL_SEND_EMAIL`, `GMAIL_FETCH_EMAILS`, `GMAIL_CREATE_EMAIL_DRAFT`, ... |
| `linear` | `LINEAR_CREATE_LINEAR_ISSUE`, `LINEAR_UPDATE_ISSUE`, `LINEAR_CREATE_LINEAR_LABEL`, ... |

## Available toolkits

Browse all available toolkits in the [Composio platform](https://platform.composio.dev) under "All Toolkits". Each toolkit page shows its tools (with input and output parameters) and authentication methods supported for that toolkit.

You can also list toolkits programmatically:

**Python:**

```python
# Returns top 20 toolkits by default
toolkits = composio.toolkits.get()

for toolkit in toolkits:
    print(toolkit.name)
```

**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
// Returns top 20 toolkits by default
const toolkits = await composio.toolkits.get();

for (const toolkit of toolkits) {
  console.log(toolkit.name);

```

For details on browsing tools within toolkits and inspecting schemas, see [Fetching tools and schemas](/docs/fetching-tools).

> 
Some toolkits require you to provide your own credentials. See [Using custom auth configs](/tool-router/using-custom-auth-configs).

> 
Need a toolkit that doesn't exist? [Request it here](https://request.composio.dev/boards/tool-requests).

## Default session behavior

When you create a session, all toolkits are available:

**Python:**

```python
session = composio.create(user_id="user_123")
```

**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const session = await composio.create("user_123");
```

Your agent can search and use tools from any toolkit. To restrict or configure which toolkits are available, see [Users and sessions](/tool-router/users-and-sessions#enabling-toolkits).

> 
Triggers can be used alongside Tool Router to respond to events in connected apps. See [Using triggers](/docs/using-triggers) for setup instructions.

---

# Users and sessions (/tool-router/users-and-sessions)

A **user ID** is an identifier from your system (database ID, UUID, or any unique string) that scopes connected accounts and tool access to a specific user. User IDs can represent individuals, teams, or organizations. See [User Management](/docs/user-management) for patterns.

A **session** is an ephemeral configuration that combines:
- Which user's connected accounts to use
- Which toolkits are available
- Which auth configs to use

Tool Router's meta-tools are the same for everyone. The session determines the context they operate within.

## Creating a session

**Python:**

```python
session = composio.create(user_id="user_123")
```

**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const session = await composio.create("user_123");
```

### Enabling toolkits

Restrict the session to specific toolkits:

**Python:**

```python
# Using array format
session = composio.create(
    user_id="user_123",
    toolkits=["github", "gmail", "slack"]
)

# Using object format with enable key
session = composio.create(
    user_id="user_123",
    toolkits={"enable": ["github", "gmail", "slack"]}
)
```

**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
// Using array format
const session = await composio.create("user_123", {
  toolkits: ["github", "gmail", "slack"],
});

// Using object format with enable key
const session2 = await composio.create("user_123", {
  toolkits: { enable: ["github", "gmail", "slack"] },
});
```

### Disabling toolkits

Keep all toolkits enabled except specific ones:

**Python:**

```python
session = composio.create(
    user_id="user_123",
    toolkits={"disable": ["exa", "firecrawl"]}
)
```

**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const session = await composio.create("user_123", {
  toolkits: { disable: ["exa", "firecrawl"] },
});
```

### Custom auth configs

Use your own OAuth credentials instead of Composio's defaults:

**Python:**

```python
session = composio.create(
    user_id="user_123",
    auth_configs={
        "github": "ac_your_github_config",
        "slack": "ac_your_slack_config"

)
```

**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const session = await composio.create("user_123", {
  authConfigs: {
    github: "ac_your_github_config",
    slack: "ac_your_slack_config",
  },
});
```

See [White-labeling authentication](/tool-router/white-labeling-authentication) for branding, or [Using custom auth configs](/tool-router/using-custom-auth-configs) for toolkits that require your own credentials.

## Connected accounts

Connected accounts are stored in Composio and persist across sessions. When a user connects their GitHub account in one session, it remains available in future sessions. Sessions configure *which* connections to use, but don't own the connections themselves.

### Account selection

If a user has multiple connected accounts for the same toolkit, you can specify which one to use:

**Python:**

```python
session = composio.create(
    user_id="user_123",
    connected_accounts={
        "gmail": "ca_work_gmail",
        "github": "ca_personal_github"

)
```

**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const session = await composio.create("user_123", {
  connectedAccounts: {
    gmail: "ca_work_gmail",
    github: "ca_personal_github",
  },
});
```

### Precedence

When executing a tool, Tool Router selects the connected account in this order:

1. `connectedAccounts` override if provided in session config
2. `authConfigs` override - finds or creates connection on that config
3. Auth config previously created by Tool Router for this toolkit
4. Creates new auth config using Composio managed auth (tagged as Tool Router created)
5. Error if no Composio managed auth scheme exists for the toolkit

If a user has multiple connected accounts for a toolkit, the most recently connected one is used.

## Session methods

### mcp

Get the MCP server URL to use with any MCP-compatible client.

**Python:**

```python
mcp_url = session.mcp.url
```

**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const session = await composio.create("user_123");
// ---cut---
const { mcp } = session;
console.log(mcp.url);
```

For framework examples, see [Using with MCP clients](/tool-router/using-with-mcp-clients) or [Using as a native tool](/tool-router/using-as-a-native-tool).

### tools()

Get native tools from the session for use with AI frameworks.

**Python:**

```python
tools = session.tools()
```

**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const session = await composio.create("user_123");
// ---cut---
const tools = await session.tools();
```

### authorize()

Manually authenticate a user to a toolkit outside of the chat flow.

**Python:**

```python
connection_request = session.authorize("github")

print(connection_request.redirect_url)

connected_account = connection_request.wait_for_connection()
```

**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const session = await composio.create("user_123");
// ---cut---
const connectionRequest = await session.authorize("github", {
  callbackUrl: "https://myapp.com/callback",
});

console.log(connectionRequest.redirectUrl);

const connectedAccount = await connectionRequest.waitForConnection();
```

For more details, see [Manually authenticating users](/tool-router/manually-authenticating-users).

### toolkits()

List available toolkits and their connection status. You can use this to build a UI showing which apps are connected.

**Python:**

```python
toolkits = session.toolkits()

for toolkit in toolkits.items:
    status = toolkit.connection.connected_account.id if toolkit.connection.is_active else "Not connected"
    print(f"{toolkit.name}: {status}")
```

**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const session = await composio.create("user_123");
// ---cut---
const toolkits = await session.toolkits();

toolkits.items.forEach((toolkit) => {
  console.log(`${toolkit.name}: ${toolkit.connection?.connectedAccount?.id ?? "Not connected"}`);
});
```

Returns the first 20 toolkits by default.

---

# Using as a native tool (/tool-router/using-as-a-native-tool)

Tool Router can be used as a single native tool with any AI framework. The tool handles search, authentication, and execution internally.

## Examples for popular frameworks

Jump to examples for:
- [OpenAI](#openai) - Python, TypeScript
- [Vercel AI SDK](#vercel-ai-sdk) - TypeScript

## OpenAI

### Installation

**Python:**

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

**TypeScript:**

```bash
npm install @composio/core @composio/openai-agents @openai/agents
```

### Usage

Create a Tool Router session and use it as a native tool with OpenAI Agents SDK:

> 
- Set your `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
- Set your `OPENAI_API_KEY` environment variable with your [OpenAI API key](https://platform.openai.com/api-keys).

**Python:**

```python
from dotenv import load_dotenv
from composio import Composio
from agents import Agent, Runner, SQLiteSession
from composio_openai_agents import OpenAIAgentsProvider

load_dotenv()

# Initialize Composio with OpenAI Agents provider (API key from env var COMPOSIO_API_KEY)
composio = Composio(provider=OpenAIAgentsProvider())

# Unique identifier of the user
user_id = "user_123"

# Create a session and get native tools for the user
session = composio.create(user_id=user_id)
tools = session.tools()

# Configure OpenAI agent with Composio tools
agent = Agent(
    name="Personal Assistant",
    instructions="You are a helpful personal assistant. Use Composio tools to take action.",
    model="gpt-5.2",
    tools=tools,
)

# Memory for multi-turn conversation
memory = SQLiteSession("conversation")

# Execute an initial task
print("Fetching GitHub issues from the Composio repository...\n")
try:
    result = Runner.run_sync(
        starting_agent=agent,
        input="Fetch all the open GitHub issues on the @ComposioHQ/composio repository and group them by bugs/features/docs.",
        session=memory,
    )
    print(f"{result.final_output}\n")
except Exception as e:
    print(f"[Error]: {e}")

# Continue with interactive conversation
print("\nWhat else would you like me to do? (Type 'exit' to exit)")

while True:
    user_input = input("You: ").strip()
    if user_input.lower() == "exit":
        break

    print("Assistant: ", end="", flush=True)
    try:
        result = Runner.run_sync(starting_agent=agent, input=user_input, session=memory)
        print(f"{result.final_output}\n")
    except Exception as e:
        print(f"\n[Error]: {e}")
```

**TypeScript:**

```typescript
import "dotenv/config";
import { Composio } from "@composio/core";
import { Agent, run, MemorySession } from "@openai/agents";
import { OpenAIAgentsProvider } from "@composio/openai-agents";
import { createInterface } from "readline/promises";

// Initialize Composio with OpenAI Agents provider (API key from env var COMPOSIO_API_KEY)
const composio = new Composio({ provider: new OpenAIAgentsProvider() });

// Unique identifier of the user
const userId = "user_123";

// Create a session and get native tools for the user
const session = await composio.create(userId);
const tools = await session.tools();

const agent = new Agent({
  name: "Personal Assistant",
  instructions: "You are a helpful personal assistant. Use Composio tools to take action.",
  model: "gpt-5.2",
  tools,
});

// Create a memory session for persistent multi-turn conversation
const memory = new MemorySession();

// Execute an initial task
console.log("Fetching GitHub issues from the Composio repository...\n");
try {
  const initialResult = await run(
    agent,
    "Fetch all the open GitHub issues on the composio repository and group them by bugs/features/docs.",
    { session: memory }
  );
  console.log(`${initialResult.finalOutput}\n`);
} catch (error) {
  console.error("[Error]:", error instanceof Error ? error.message : error);

// Continue with interactive conversation
const readline = createInterface({ input: process.stdin, output: process.stdout });

console.log(`
What else would you like me to do?
(Type 'exit' to exit)
`);

while (true) {
  const input = (await readline.question("You: ")).trim();
  if (input.toLowerCase() === "exit") break;

  console.log("Assistant: ");

  try {
    const result = await run(agent, input, { session: memory });
    console.log(`${result.finalOutput}\n`);
  } catch (error) {
    console.error("\n[Error]:", error instanceof Error ? error.message : error);

readline.close();
```

## Vercel AI SDK

### Installation

```bash
npm install @composio/core @composio/vercel ai @ai-sdk/anthropic
```

### Usage

Create a Tool Router session and use it as a native tool with Vercel AI SDK:

> 
- Set your `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
- Set your `ANTHROPIC_API_KEY` environment variable with your [Anthropic API key](https://console.anthropic.com/settings/keys).

```typescript
import "dotenv/config";
import { anthropic } from "@ai-sdk/anthropic";
import { Composio } from "@composio/core";
import { VercelProvider } from "@composio/vercel";
import { stepCountIs, streamText } from "ai";

// Initialize Composio with Vercel provider (API key from env var COMPOSIO_API_KEY)
const composio = new Composio({ provider: new VercelProvider() });

// Unique identifier of the user
const userId = "user_123";

// Create a session and get native tools for the user
const session = await composio.create(userId);
const tools = await session.tools();

console.log("Fetching GitHub issues from the Composio repository...");

// Stream the response with tool calling
const stream = await streamText({
  system: "You are a helpful personal assistant. Use Composio tools to take action.",
  model: anthropic("claude-sonnet-4-5"),
  prompt: "Fetch all the open GitHub issues on the composio repository and group them by bugs/features/docs.",
  stopWhen: stepCountIs(10),
  onStepFinish: (step) => {
    for (const toolCall of step.toolCalls) {
      console.log(`[Using tool: ${toolCall.toolName}]`);

  },
  tools,
});

for await (const textPart of stream.textStream) {
  process.stdout.write(textPart);

console.log("\n\n---");
console.log("Tip: If prompted to authenticate, complete the auth flow and run again.");
```

## Next steps

- [Quickstart](/tool-router/quickstart): 
    See both MCP and native tool in action
  
  - [Using with MCP](/tool-router/using-with-mcp-clients): 
    Use Tool Router with MCP-compatible clients
  
  - [Authentication](/tool-router/authentication): 
    Learn about authentication options
  
  - [Session management](/tool-router/users-and-sessions): 
    Configure sessions for your users

---

# Using custom auth configs (/tool-router/using-custom-auth-configs)

Some toolkits don't have Composio managed authentication and require you to provide your own credentials. When Tool Router tries to use these toolkits, it will throw an error asking you to create an auth config.

### Step: Check if a toolkit needs custom credentials

In the [Composio platform](https://platform.composio.dev), go to "All Toolkits" and select the toolkit. If it shows no Composio managed auth schemes, you'll need to create an auth config.

### Step: Create an auth config

1. Go to **Authentication management** in the [dashboard](https://app.composio.dev)
2. Click **Create Auth Config**
3. Select the toolkit
4. Choose the auth scheme (OAuth2, API Key, etc.)
5. Enter your credentials (client ID, client secret, API key, etc.)
6. Click **Create**

Copy the auth config ID (e.g., `ac_1234abcd`).

> 
For detailed instructions on getting credentials for specific toolkits, see [Custom auth configs](/docs/custom-auth-configs).

### Step: Use in Tool Router

Pass your auth config ID when creating a session:

**Python:**

```python
session = composio.create(
    user_id="user_123",
    auth_configs={
        "posthog": "ac_your_posthog_config"

)
```

**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const session = await composio.create("user_123", {
  authConfigs: {
    posthog: "ac_your_posthog_config",
  },
});
```

Tool Router will now use your auth config when users connect to this toolkit.

---

# Using In-chat authentication (/tool-router/using-in-chat-authentication)

In-chat authentication lets your agent prompt users to connect accounts during chat. When a tool requires authentication, the agent returns a Connect Link URL. The user authenticates, confirms in chat, and the agent retries.

## How it works

1. Agent searches for tools via the `COMPOSIO_SEARCH_TOOLS` meta-tool
2. The `COMPOSIO_MANAGE_CONNECTIONS` meta-tool checks connection status, returns Connect Link URL if needed
3. User authenticates, confirms in chat, agent continues

## Configuration

By just creating a session with default configs, you are enabling in-chat auth. The `manage_connections` parameter defaults to `True`, which includes the `COMPOSIO_MANAGE_CONNECTIONS` meta-tool automatically:

**Python:**

```python
session = composio.create(user_id="user_123")
```

**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const session = await composio.create("user_123");
```

### Custom callback URL

Redirect users back to your chat page after they complete authentication:

**Python:**

```python
session = composio.create(
    user_id="user_123",
    manage_connections={
        "callback_url": "https://yourapp.com/chat"
    },
)
```

**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const session = await composio.create("user_123", {
  manageConnections: {
    callbackUrl: "https://yourapp.com/chat",
  },
});
```

## Examples

**Python:**

```python
from dotenv import load_dotenv
from composio import Composio
from agents import Agent, Runner, SQLiteSession
from composio_openai_agents import OpenAIAgentsProvider

load_dotenv()

# Initialize Composio with OpenAI Agents provider (API key from env var COMPOSIO_API_KEY)
composio = Composio(provider=OpenAIAgentsProvider())

# Unique identifier of the user
user_id = "user_123"

# Create a session and get native tools for the user
session = composio.create(user_id=user_id)
tools = session.tools()

# Configure OpenAI agent with Composio tools
agent = Agent(
    name="Personal Assistant",
    instructions="You are a helpful personal assistant. Use Composio tools to take action.",
    model="gpt-5.2",
    tools=tools,
)

# Memory for multi-turn conversation
memory = SQLiteSession("conversation")

print("""
What task would you like me to help you with?
I can use tools like Gmail, GitHub, Linear, Notion, and more.
(Type 'exit' to exit)
Example tasks:
  • 'Summarize my emails from today'
  • 'List all open issues on the composio github repository'
""")

while True:
    user_input = input("You: ").strip()
    if user_input.lower() == "exit":
        break

    print("Assistant: ", end="", flush=True)
    try:
        result = Runner.run_sync(starting_agent=agent, input=user_input, session=memory)
        print(f"{result.final_output}\n")
    except Exception as e:
        print(f"\n[Error]: {e}")
```

**TypeScript:**

```typescript
import "dotenv/config";
import { Composio } from "@composio/core";
import { Agent, run, MemorySession } from "@openai/agents";
import { OpenAIAgentsProvider } from "@composio/openai-agents";
import { createInterface } from "readline/promises";

// Initialize Composio with OpenAI Agents provider (API key from env var COMPOSIO_API_KEY)
const composio = new Composio({ provider: new OpenAIAgentsProvider() });

// Unique identifier of the user
const userId = "user_123";
// Create a tool router session for the user
const session = await composio.create(userId);
const tools = await session.tools();

const agent = new Agent({
  name: "Personal Assistant",
  instructions: "You are a helpful personal assistant. Use Composio tools to take action.",
  model: "gpt-5.2",
  tools,
});

// Set up interactive terminal input/output for the conversation
const readline = createInterface({ input: process.stdin, output: process.stdout });
// Create a memory session for persistent multi-turn conversation
const memory = new MemorySession();

console.log(`
What task would you like me to help you with?
I can use tools like Gmail, GitHub, Linear, Notion, and more.
(Type 'exit' to exit)
Example tasks:
  • 'Summarize my emails from today'
  • 'List all open issues on the composio github repository and create a Google Sheet with the issues'
`);

// Multi-turn conversation with agentic tool calling
while (true) {
    const query = await readline.question("You: ");
    const input = query.trim();

    if (input.toLowerCase() === "exit") break;
    process.stdout.write("Assistant: ");

    try {
      const result = await run(agent, input, { session: memory });
      process.stdout.write(`${result.finalOutput}`);
    } catch (error) {
    console.error("\n[Error]:", error instanceof Error ? error.message : error);

readline.close();
```

What this looks like when you run the code:

```
Assistant: What would you like me to do today? Type 'exit' to end the conversation.

> Star the composio repo on GitHub
Assistant: I need you to connect your GitHub account first.
Please click here to authorize: https://connect.composio.dev/link/ln_abc123

> Done

---

# Using with MCP clients (/tool-router/using-with-mcp-clients)

Every Tool Router session provides a unique MCP server URL. This URL exposes the exact session you created - with the specific user, toolkits, and auth configs you configured. Any MCP client that supports HTTP transport can connect using just the URL and your API key.

## Examples for popular frameworks

Jump to examples for:
- [Claude Agent SDK](#claude-agent-sdk) - Python, TypeScript
- [OpenAI Agents SDK](#openai-agents-sdk) - Python, TypeScript
- [Vercel AI SDK](#vercel-ai-sdk) - TypeScript

## Claude Agent SDK

### Installation

**Python:**

```bash
pip install python-dotenv composio claude-agent-sdk
```

**TypeScript:**

```bash
npm install dotenv @composio/core @anthropic-ai/claude-agent-sdk
```

### Usage

Create a Tool Router session and execute tasks with Claude:

> 
- Set your `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
- Set your `ANTHROPIC_API_KEY` environment variable with your [Anthropic API key](https://platform.claude.com/settings/keys).

**Python:**

```python
import asyncio
from dotenv import load_dotenv
from claude_agent_sdk.client import ClaudeSDKClient
from claude_agent_sdk.types import (
    ClaudeAgentOptions,
    AssistantMessage,
    TextBlock,
    ToolUseBlock,
)
from composio import Composio

load_dotenv()

# Initialize Composio (API key from env var COMPOSIO_API_KEY or pass explicitly)
composio = Composio()

# Unique identifier of the user
user_id = "user_123"
# Create a tool router session for the user
session = composio.create(user_id=user_id)

# Configure Claude with Composio MCP server
options = ClaudeAgentOptions(
    system_prompt=(
        "You are a helpful assistant with access to external tools. "
        "Always use the available tools to complete user requests."
    ),
    mcp_servers={
        "composio": {
            "type": "http",
            "url": session.mcp.url,
            "headers": session.mcp.headers,  # Authentication headers for the Composio MCP server

    },
    permission_mode="bypassPermissions",  # Auto-approve tools (demo only)
)

async def main():
    print("""
What task would you like me to help you with?
I can use tools like Gmail, GitHub, Linear, Notion, and more.
(Type 'exit' to exit)
Example tasks:
  • 'Summarize my emails from today'
  • 'List all open issues on the composio github repository and create a notion page with the issues'
""")

    async with ClaudeSDKClient(options) as client:
        # Multi-turn conversation with agentic tool calling
        while True:
            user_input = input("\nYou: ").strip()
            if user_input.lower() == "exit":
                break

            print("\nClaude: ", end="", flush=True)
            try:
                await client.query(user_input)
                async for msg in client.receive_response():
                    if isinstance(msg, AssistantMessage):
                        for block in msg.content:
                            if isinstance(block, ToolUseBlock):
                                print(f"\n[Using tool: {block.name}]", end="")
                            elif isinstance(block, TextBlock):
                                print(block.text, end="", flush=True)
            except Exception as e:
                print(f"\n[Error]: {e}")

if __name__ == "__main__":
    asyncio.run(main())
```

**TypeScript:**

```typescript
import "dotenv/config";
import { query, type Options } from "@anthropic-ai/claude-agent-sdk";
import { Composio } from "@composio/core";
import { createInterface } from "readline/promises";

// Initialize Composio (API key from env var COMPOSIO_API_KEY or pass explicitly: { apiKey: "your-key" })
const composio = new Composio();

// Unique identifier of the user
const userId = "user_123";

// Create a tool router session for the user
const session = await composio.create(userId);

const options: Options = {
  systemPrompt: `You are a helpful assistant with access to external tools. ` +
    `Always use the available tools to complete user requests.`,
  mcpServers: {
    composio: {
      type: "http",
      url: session.mcp.url,
      headers: session.mcp.headers // Authentication headers for the Composio MCP server
    },
  },
  permissionMode: "bypassPermissions", // Auto-approve tools (demo only - use "default" in production)
};

// Set up interactive terminal input/output for the conversation
const readline = createInterface({ input: process.stdin, output: process.stdout });

console.log(`
What task would you like me to help you with?
I can use tools like Gmail, GitHub, Linear, Notion, and more.
(Type 'exit' to exit)
Example tasks:
  • 'Summarize my emails from today'
  • 'List all open issues on the composio github repository and create a notion page with the issues'
`);

let isFirstQuery = true;

// Multi-turn conversation with agentic tool calling
while (true) {
  const answer = await readline.question('You: ');
  const input = answer.trim();
  if (input.toLowerCase() === "exit") break;

  process.stdout.write("Claude: ");

  const queryOptions = isFirstQuery ? options : { ...options, continue: true };
  isFirstQuery = false;

  try {
    for await (const stream of query({ prompt: input, options: queryOptions })) {
      // Only process assistant messages (the SDK also sends result/error messages)
      if (stream.type === "assistant") {
        const { content } = stream.message;
        for (const block of content) {
          if (block.type === "tool_use") {
            process.stdout.write(`\n[Using tool: ${block.name}]`);
          } else if (block.type === "text") {
            process.stdout.write(block.text);

  } catch (error) {
    console.error("\n[Error]:", error instanceof Error ? error.message : error);

  process.stdout.write("\n");

readline.close();
```

## OpenAI Agents SDK

### Installation

**Python:**

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

**TypeScript:**

```bash
npm install dotenv @composio/core @openai/agents zod@3
```

### Usage

Create a Tool Router session and execute tasks with OpenAI agents:

> 
- Set `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
- Set `OPENAI_API_KEY` environment variable with your [OpenAI API key](https://platform.openai.com/api-keys).

**Python:**

```python
from dotenv import load_dotenv
from composio import Composio
from agents import Agent, Runner, HostedMCPTool

load_dotenv()

# Initialize Composio (API key from env var COMPOSIO_API_KEY)
composio = Composio()
# Unique identifier of the user
user_id = "user_123"

# Create a Tool Router session for the user
session = composio.create(user_id=user_id)

# Configure OpenAI agent with Composio MCP server
agent = Agent(
    name="Personal Assistant",
    instructions="You are a helpful personal assistant. Use Composio tools to take action.",
    model="gpt-5.2",
    tools=[
        HostedMCPTool(
            tool_config={
                "type": "mcp",
                "server_label": "composio",
                "server_url": session.mcp.url,
                "require_approval": "never",
                "headers": session.mcp.headers,

        )
    ],
)

# Execute the task
print("Fetching GitHub issues from the Composio repository @ComposioHQ/composio...\n")
try:
    result = Runner.run_sync(
        starting_agent=agent,
        input="Fetch all the open GitHub issues on the composio repository and group them by bugs/features/docs.",
    )
    print(result.final_output)
except Exception as e:
    print(f"[Error]: {e}")

print("\n\n---")
print("Tip: If prompted to authenticate, complete the auth flow and run again.")
```

**TypeScript:**

```typescript
import "dotenv/config";
import { Composio } from "@composio/core";
import { Agent, hostedMcpTool, run, MemorySession } from "@openai/agents";
import { createInterface } from "readline/promises";

// Initialize Composio (API key from env var COMPOSIO_API_KEY or pass explicitly: { apiKey: "your-key" })
const composio = new Composio();

// Unique identifier of the user
const userId = "user_123";

// Create a tool router session for the user
const session = await composio.create(userId);

const agent = new Agent({
  name: "Personal Assistant",
  instructions: "You are a helpful personal assistant. Use Composio tools to take action.",
  model: "gpt-5.2",
  tools: [
    hostedMcpTool({
      serverLabel: "composio",
      serverUrl: session.mcp.url,
      headers: session.mcp.headers, // Authentication headers for the Composio MCP server
    }),
  ],
});

// Create a memory session for persistent multi-turn conversation
const memory = new MemorySession();

// Execute an initial task
console.log("Fetching GitHub issues from the Composio repository...\n");
try {
  const initialResult = await run(
    agent,
    "Fetch all the open GitHub issues on the composio repository and group them by bugs/features/docs.",
    { session: memory }
  );
  console.log(`${initialResult.finalOutput}\n`);
} catch (error) {
  console.error("[Error]:", error instanceof Error ? error.message : error);

// Continue with interactive conversation
const readline = createInterface({ input: process.stdin, output: process.stdout });

console.log(`
What else would you like me to do?
(Type 'exit' to exit)
`);

while (true) {
  const input = (await readline.question("You: ")).trim();
  if (input.toLowerCase() === "exit") break;

  console.log("Assistant: ");

  try {
    const result = await run(agent, input, { session: memory });
    console.log(`${result.finalOutput}\n`);
  } catch (error) {
    console.error("\n[Error]:", error instanceof Error ? error.message : error);

readline.close();
```

## Vercel AI SDK

### Installation

```bash
npm install dotenv @composio/core ai @ai-sdk/anthropic @ai-sdk/mcp
```

### Usage

Use Tool Router with Vercel AI SDK's `generateText` for single completions:

> 
- Set `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
- Set `ANTHROPIC_API_KEY` environment variable with your [Anthropic API key](https://platform.claude.com/settings/keys).

```typescript
import "dotenv/config";
import { anthropic } from "@ai-sdk/anthropic";
import { experimental_createMCPClient as createMCPClient } from "@ai-sdk/mcp";
import { Composio } from "@composio/core";
import { stepCountIs, streamText } from "ai";

// Initialize Composio (API key from env var COMPOSIO_API_KEY or pass explicitly: { apiKey: "your-key" })
const composio = new Composio();

// Unique identifier of the user
const userId = "user_123";

// Create a tool router session for the user
const { mcp } = await composio.create(userId);

// Create an MCP client to connect to the Composio tool router
const client = await createMCPClient({
  transport: {
    type: "http",
    url: mcp.url,
    headers: mcp.headers, // Authentication headers for the Composio MCP server
  },
});
const tools = await client.tools();

console.log("Summarizing your emails from today");

const stream = await streamText({
  system: "You are a helpful personal assistant. Use Composio tools to take action.",
  model: anthropic("claude-sonnet-4-5"),
  prompt: "Summarize my emails from today",
  stopWhen: stepCountIs(10),
  onStepFinish: (step) => {
    for (const toolCall of step.toolCalls) {
      console.log(`[Using tool: ${toolCall.toolName}]`);

  },
  tools,
});

for await (const textPart of stream.textStream) {
  process.stdout.write(textPart);

console.log("\n\n---");
console.log("Tip: If prompted to authenticate, complete the auth flow and run again.")
```

---

# White-labeling authentication (/tool-router/white-labeling-authentication)

White-labeling lets you use your own OAuth apps instead of Composio's. Users will see your app name on consent screens instead of "Composio".

By default, OAuth screens show Composio's branding. With white-labeling, they'll see your app name and logo.

### Step: Create an OAuth app

Create a developer app in the toolkit's developer portal. You'll need the client ID and client secret. Set the callback URL to:

```
https://backend.composio.dev/api/v3/toolkits/auth/callback
```

> 
For step-by-step guides on creating OAuth apps for some toolkits, see [composio.dev/auth](https://composio.dev/auth).

### Step: Create auth config

Create an auth config in the [Composio dashboard](https://app.composio.dev):

1. Go to **Authentication management** → **Create Auth Config**
2. Select the toolkit (e.g., GitHub)
3. Choose **OAuth2** scheme
4. Enter your **Client ID** and **Client Secret**
5. Select the scopes you need
6. Click **Create**

Copy the auth config ID (e.g., `ac_1234abcd`).

> 
For detailed instructions with screenshots, see [Custom auth configs](/docs/custom-auth-configs).

### Step: Use in Tool Router

Pass your auth config ID in the session:

**Python:**

```python
session = composio.create(
    user_id="user_123",
    auth_configs={
        "github": "ac_your_github_config"
    },
)
```

**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const session = await composio.create("user_123", {
  authConfigs: {
    github: "ac_your_github_config",
  },
});
```

When users connect GitHub, they'll see your OAuth app's name and logo on the consent screen.

## Mixing custom and Composio-managed auth

You can white-label some toolkits while using Composio's managed credentials for others:

**Python:**

```python
session = composio.create(
    user_id="user_123",
    auth_configs={
        "github": "ac_your_github_config",
        "slack": "ac_your_slack_config",
        # gmail, linear, etc. use Composio managed auth
    },
)
```

**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const session = await composio.create("user_123", {
  authConfigs: {
    github: "ac_your_github_config",
    slack: "ac_your_slack_config",
    // gmail, linear, etc. use Composio managed auth
  },
});
```

## Custom redirect domain

When users authenticate, they briefly see `backend.composio.dev` in their browser URL. Composio needs to receive the OAuth callback to capture and store the authentication tokens.

If you need to hide this URL (for enterprise compliance or complete white-labeling), you can proxy the redirect through your own domain:

1. Set your OAuth app's redirect URI to your domain:
```
https://yourdomain.com/api/composio-redirect
```

2. Create an endpoint that forwards the OAuth callback to Composio:

**Python:**

```python
from fastapi import FastAPI, Request
from fastapi.responses import RedirectResponse

app = FastAPI()

@app.get("/api/composio-redirect")
def composio_redirect(request: Request):
    # Forward all OAuth parameters to Composio
    composio_url = "https://backend.composio.dev/api/v3/toolkits/auth/callback"
    return RedirectResponse(url=f"{composio_url}?{request.url.query}")
```

**TypeScript:**

```typescript
// pages/api/composio-redirect.ts (Next.js)
import type { NextApiRequest, NextApiResponse } from "next";

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  // Forward all OAuth parameters to Composio
  const composioUrl = "https://backend.composio.dev/api/v3/toolkits/auth/callback";
  const params = new URLSearchParams(req.query as Record<string, string>);
  res.redirect(302, `${composioUrl}?${params.toString()}`);

```

3. Update your auth config in the Composio dashboard to use your custom redirect URI.

This makes the OAuth flow go through your domain first, then to Composio for token storage.

---

# Beta to Stable Migration (/tool-router/migration-guide/beta-to-stable)

The stable version includes improved session management, multiple configuring options, and enhanced authentication capabilities.

## The basics

### Step: Upgrade composio package

Upgrade to the latest stable version:

**Python:**

```bash
pip install --upgrade composio
```

**TypeScript:**

```bash
npm install @composio/core@latest
```

### Step: Update session creation

**Python:**

```python
# Beta (before)
session = composio.experimental.tool_router.create_session(
    user_id="user@example.com"
)

# Stable (after)
session = composio.create(
    user_id="user@example.com"
)
```

**TypeScript:**

```typescript
// @noErrors
// Beta (before)
const session = await composio.experimental.toolRouter.createSession('user_123');

// Stable (after)
const session = await composio.create('user_123');
```

### Step: Moving users (optional)

If you have existing users on tool router and you don't want them to authenticate again:
- Tool Router will auto-detect auth configs and connected accounts it created (from the beta version).
- If you have custom auth configs (not created by Tool Router):
    - Search for the Auth config for that connected account. See [Connected Accounts](/docs/connected-accounts) to fetch existing accounts programmatically.
    - While creating a session configure to use this Auth config.
    - You need to repeat this for each toolkit you want to enable for that session.

**Python:**

```python
session = composio.create(
    user_id="user_123",
    auth_configs={
        "github": "ac_your_github_config",
        "slack": "ac_your_slack_config"

)
```

**TypeScript:**

```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const session = await composio.create('user_123',

        authConfigs: {
            github: "ac_your_github_config",
            slack: "ac_your_slack_config",
        },

);
```

### Step: Explore new capabilities

Check out these new features available in the stable version:

- **[Native tools](/tool-router/using-as-a-native-tool)**: Use Tool Router with any AI framework
- **Better [session](/tool-router/users-and-sessions) and [auth](/tool-router/authentication) config**
- **[Multi-account support](/tool-router/managing-multiple-accounts)**: Manage multiple accounts per user seamlessly
- **[Manual authentication](/tool-router/manually-authenticating-users)**: Control when and how users authenticate
- **[Custom auth](/tool-router/using-custom-auth-configs)**: Support for toolkits that don't have composio managed auth
- **[White labeling](/tool-router/white-labeling-authentication)**: Customize authentication screens with your branding

---


# Examples


---

# Basic FastAPI Server (/examples/fast-api)

This cookbook will guide you through building agents equipped with tools using `Composio`, `OpenAI`, and `FastAPI`.

## Prerequisites

* Python 3.10+
* [UV](https://docs.astral.sh/uv/getting-started/installation/)
* Composio API key
* OpenAI API key

## Building an AI agent that can interact with `gmail` service

First, let's start with building a simple AI agent with Composio tools that lets the agent interact with `gmail`.

```python
from openai import OpenAI
from composio import Composio
from composio_openai import OpenAIProvider
import os

def run_gmail_agent(
    composio_client: Composio[OpenAIProvider],
    openai_client: OpenAI,
    user_id: str,  # Composio uses the User ID to store and access user-level authentication tokens.
    prompt: str,
):
    """
    Run the Gmail agent using composio and openai clients.
    """
    # Step 1: Fetch the necessary Gmail tools list with Composio
    tools = composio_client.tools.get(
        user_id=user_id,
        tools=[
            "GMAIL_FETCH_EMAILS",
            "GMAIL_SEND_EMAIL",
            "GMAIL_CREATE_EMAIL_DRAFT"
        ]
    )

    # Step 2: Use OpenAI to generate a response based on the prompt and available tools
    response = openai_client.chat.completions.create(
        model="gpt-4.1",
        tools=tools,
        messages=[{"role": "user", "content": prompt}],
    )

    # Step 3: Handle tool calls with Composio and return the result
    result = composio_client.provider.handle_tool_calls(response=response, user_id=user_id)
    return result
```

> 
This example demonstrates a basic agent without state management or agentic loops,
suitable for simple one-step tasks. For complex multi-step workflows requiring
memory and iterative reasoning, see our cookbooks with frameworks like LangChain,
CrewAI, or AutoGen.

To invoke this agent, authenticate your users with Composio's managed authentication service.

## Authenticating users

To authenticate your users with Composio you need an authentication config for the given app. In this case you need one for gmail. 

To create an authentication config for `gmail` you need `client_id` and `client_secret` from your [Google OAuth Console](https://developers.google.com/identity/protocols/oauth2). Once you have the credentials, use the following piece of code to set up authentication for `gmail`.

```python
from composio import Composio
from composio_openai import OpenAIProvider

def create_auth_config(composio_client: Composio[OpenAIProvider]):
    """
    Create a auth config for the gmail toolkit.
    """
    client_id = os.getenv("GMAIL_CLIENT_ID")
    client_secret = os.getenv("GMAIL_CLIENT_SECRET")
    if not client_id or not client_secret:
        raise ValueError("GMAIL_CLIENT_ID and GMAIL_CLIENT_SECRET must be set")

    return composio_client.auth_configs.create(
        toolkit="GMAIL",
        options={
            "name": "default_gmail_auth_config",
            "type": "use_custom_auth",
            "auth_scheme": "OAUTH2",
            "credentials": {
                "client_id": client_id,
                "client_secret": client_secret,
            },
        },
    )
```

This will create a Gmail authentication config to authenticate your app’s users. Ideally, create one authentication object per project, so check for an existing auth config before creating a new one.

```python
def fetch_auth_config(composio_client: Composio[OpenAIProvider]):
    """
    Fetch the auth config for a given user id.
    """
    auth_configs = composio_client.auth_configs.list()
    for auth_config in auth_configs.items:
        if auth_config.toolkit == "GMAIL":
            return auth_config

    return None
```

> 
Composio platform provides composio managed authentication for some apps to
fast-track your development, `gmail` being one of them. You can use these
default auth configs for development, but for production, always use your
own oauth app configuration.

Once you have authentication management in place, we can start with connecting your users to your `gmail` app. Let's implement a function to connect users to your `gmail` app via composio.

```python
from fastapi import FastAPI

# Function to initiate a connected account
def create_connection(composio_client: Composio[OpenAIProvider], user_id: str):
    """
    Create a connection for a given user id and auth config id.
    """
    # Fetch or create the auth config for the gmail toolkit
    auth_config = fetch_auth_config(composio_client=composio_client)
    if not auth_config:
        auth_config = create_auth_config(composio_client=composio_client)

    # Create a connection for the user
    return composio_client.connected_accounts.initiate(
        user_id=user_id,
        auth_config_id=auth_config.id,
    )

# Setup FastAPI
app = FastAPI()

# Connection initiation endpoint
@app.post("/connection/create")
def _create_connection(
    request: CreateConnectionRequest,
    composio_client: ComposioClient,
) -> dict:
    """
    Create a connection for a given user id.
    """
    # For demonstration, using a default user_id. Replace with real user logic in production.
    user_id = "default"

    # Create a new connection for the user
    connection_request = create_connection(composio_client=composio_client, user_id=user_id)
    return {
        "connection_id": connection_request.id,
        "redirect_url": connection_request.redirect_url,

```

Now, you can make a request to this endpoint on your client app, and your user will get a URL which they can use to authenticate.

## Set Up FastAPI service

We will use [`FastApi`](https://fastapi.tiangolo.com/) to build an HTTP service that authenticates your users and lets them interact with your agent. This guide will provide best practices for using composio client in production environments.

### Setup dependencies

FastAPI allows [dependency injection](https://fastapi.tiangolo.com/reference/dependencies/) to simplify the usage of SDK clients that must be singletons. We recommend using composio SDK client as singleton.

```python
import os
import typing_extensions as te

from composio import Composio
from composio_openai import OpenAIProvider

from fastapi import Depends

_composio_client: Composio[OpenAIProvider] | None = None

def provide_composio_client():
    """
    Provide a Composio client.
    """
    global _composio_client
    if _composio_client is None:
        _composio_client = Composio(provider=OpenAIProvider())
    return _composio_client

ComposioClient = te.Annotated[Composio, Depends(provide_composio_client)]
"""
A Composio client dependency.
"""
```

Check [dependencies](./simple_gmail_agent/server/dependencies.py) module for more details.

### Invoke agent via FastAPI

When invoking an agent, make sure you validate the `user_id`.

```python
def check_connected_account_exists(
    composio_client: Composio[OpenAIProvider],
    user_id: str,
):
    """
    Check if a connected account exists for a given user id.
    """
    # Fetch all connected accounts for the user
    connected_accounts = composio_client.connected_accounts.list(
        user_ids=[user_id],
        toolkit_slugs=["GMAIL"],
    )

    # Check if there's an active connected account
    for account in connected_accounts.items:
        if account.status == "ACTIVE":
            return True

        # Ideally you should not have inactive accounts, but if you do, delete them.
        print(f"[warning] inactive account {account.id} found for user id: {user_id}")
    return False

def validate_user_id(user_id: str, composio_client: ComposioClient):
    """
    Validate the user id, if no connected account is found, create a new connection.
    """
    if check_connected_account_exists(composio_client=composio_client, user_id=user_id):
        return user_id

    raise HTTPException(
        status_code=404, detail={"error": "No connected account found for the user id"}
    )

# Endpoint: Run the Gmail agent for a given user id and prompt
@app.post("/agent")
def _run_gmail_agent(
    request: RunGmailAgentRequest,
    composio_client: ComposioClient,
    openai_client: OpenAIClient,  # OpenAI client will be injected as dependency
) -> List[ToolExecutionResponse]:
    """
    Run the Gmail agent for a given user id and prompt.
    """
    # For demonstration, using a default user_id. Replace with real user logic in production.
    user_id = "default"

    # Validate the user id before proceeding
    user_id = validate_user_id(user_id=user_id, composio_client=composio_client)

    # Run the Gmail agent using Composio and OpenAI
    result = run_gmail_agent(
        composio_client=composio_client,
        openai_client=openai_client,
        user_id=user_id,
        prompt=request.prompt,
    )
    return result
```

> 
Check [server](./simple_gmail_agent/server/) module for service implementation

## Putting everything together

So far, we have created an agent with ability to interact with `gmail` using the `composio` SDK, functions to manage connected accounts for users and a FastAPI service. Now let's run the service.

> 
Before proceeding, check the [code](./simple_gmail_agent/server/api.py) for utility endpoints not discussed in the cookbook

1. Clone the repository
   ```bash
   git clone git@github.com:composiohq/composio-fastapi
   cd composio-fastapi/
   ```
2. Setup environment
   ```bash
   cp .env.example .env
   ```

   Fill the api keys
   ```dotenv
   COMPOSIO_API_KEY=
   OPENAI_API_KEY=
   ```

   Create the virtual env
   ```bash
   make env
   source .venv/bin/activate
   ```
3. Run the HTTP server
   ```bash
   uvicorn simple_gmail_agent.server.api:create_app --factory
   ```
## Testing the API with curl

Assuming the server is running locally on `http://localhost:8000`.

### Check if a connection exists
```bash
curl -X POST http://localhost:8000/connection/exists
```

### Create a connection
Note: The body fields are required by the API schema, but are ignored internally in this example service.
```bash
curl -X POST http://localhost:8000/connection/create \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "default",
    "auth_config_id": "AUTH_CONFIG_ID_FOR_GMAIL_FROM_THE_COMPOSIO_DASHBOARD"
  }'
```
Response includes `connection_id` and `redirect_url`. Complete the OAuth flow at the `redirect_url`.

### Check connection status
Use the `connection_id` returned from the create step.
```bash
curl -X POST http://localhost:8000/connection/status \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "default",
    "connection_id": "CONNECTION_ID_FROM_CREATE_RESPONSE"
  }'
```

### Run the Gmail agent
Requires an active connected account for the `default` user.
```bash
curl -X POST http://localhost:8000/agent \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "default",
    "prompt": "Summarize my latest unread emails from the last 24 hours."
  }'
```

### Fetch emails (direct action)
```bash
curl -X POST http://localhost:8000/actions/fetch_emails \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "default",
    "limit": 5
  }'
```

These examples are intended solely for testing purposes.

## Using Composio for managed auth and tools

Composio reduces boilerplate for building AI agents that access and use various apps. In this cookbook, to build Gmail integration without Composio, you would have to write code to

- manage Gmail OAuth app
- manage user connections
- tools for your agents to interact with Gmail

Using Composio simplifies all of the above to a few lines of code as shown in the cookbook.

## Best practices

**🎯 Effective Prompts**:
- Be specific: "Send email to john@company.com about tomorrow's 2pm meeting" works better than "send email"
- Include context: "Reply to Sarah's email about the budget with our approval"
- Use natural language: The agent understands conversational requests

**🔒 User Management**:
- Use unique, consistent `user_id` values for each person
- Each user maintains their own Gmail connection
- User IDs can be email addresses, usernames, or any unique identifier

## Troubleshooting

**Connection Issues**:
- Ensure your `.env` file has valid `COMPOSIO_API_KEY` and `OPENAI_API_KEY`
- Check if the user has completed Gmail authorization.
- Verify the user_id matches exactly between requests

**API Errors**:
- Check the server logs for detailed error messages
- Ensure request payloads match the expected format
- Visit `/docs` endpoint for API schema validation

**Gmail API Limits**:
- Gmail has rate limits; the agent will handle these gracefully
- For high-volume usage, consider implementing request queuing

---

# Gmail Labeler (/examples/gmail-labeler)

With Composio's managed authentication, tool calling and triggers, it's easy to
build the AI agents that can interact and react the real world events reducing
the boilerplate required to setup and manage the authentication. This cookbook
will walk you through the process of building agents using `Composio`, `LangChain`.

## Prerequisites

* Python3.x
* [UV](https://docs.astral.sh/uv/getting-started/installation/)
* Composio API key
* OpenAI API key
* Understanding of building AI agents (Preferably with LangChain)

## Build gmail agent to label your messages

```python
from composio import Composio
from composio_langchain import LangchainProvider

from langchain import hub
from langchain.agents import AgentExecutor, create_openai_functions_agent
from langchain_openai import ChatOpenAI

def create_agent(user_id: str, composio_client: Composio[LangchainProvider]):
    """
    Create an agent for a given user id.
    """
    # Step 1: Get all the tools
    tools = composio_client.tools.get(
        user_id=user_id,
        tools=[
            "GMAIL_LIST_LABELS",
            "GMAIL_ADD_LABEL_TO_EMAIL",
            "GMAIL_CREATE_LABEL",
        ],
    )

    # Step 2: Pull relevant agent prompt.
    prompt = hub.pull("hwchase17/openai-functions-agent")

    # Step 3: Initialize chat model.
    openai_client = ChatOpenAI(model="gpt-5")

    # Step 4: Define agent
    return AgentExecutor(
        agent=create_openai_functions_agent(
            openai_client,
            tools,
            prompt,
        ),
        tools=tools,
        verbose=False,
    )
```

## Authenticating users

To authenticate your users with Composio you need an auth config for the given
app, In this case you need one for gmail. You can create and manage auth configs
from the [dashboard](https://platform.composio.dev/?next_page=/auth-configs?create_auth_config=gmail).
Composio platform provides composio managed authentication for some apps to help
you fast-track your development, `gmail` being one of them. You can use these
default auth configs for development, but for production you should always use
your own oauth app configuration.

Using dashboard is the preferred way of managing authentication configs, but if
you want to do it manually you can follow the guide below

<details>

<summary>Click to expand</summary>

To create an authentication config for `gmail` you need `client_id` and `client_secret`
from your from your [Google OAuth Console](https://developers.google.com/identity/protocols/oauth2).
Once you have the required credentials you can use the following piece of
code to set up authentication for `gmail`. 

```python
from composio import Composio
from composio_langchain import LangchainProvider

def create_auth_config(composio_client: Composio[OpenAIProvider]):
    """
    Create a auth config for the gmail toolkit.
    """
    client_id = os.getenv("GMAIL_CLIENT_ID")
    client_secret = os.getenv("GMAIL_CLIENT_SECRET")
    if not client_id or not client_secret:
        raise ValueError("GMAIL_CLIENT_ID and GMAIL_CLIENT_SECRET must be set")

    return composio_client.auth_configs.create(
        toolkit="gmail",
        options={
            "name": "default_gmail_auth_config",
            "type": "use_custom_auth",
            "auth_scheme": "OAUTH2",
            "credentials": {
                "client_id": client_id,
                "client_secret": client_secret,
            },
        },
    )
```

This will create an authentication config for `gmail` which you can use to
authenticate your users for your app. Ideally you should just create one
authentication object per project, so check for an existing auth config
before you create a new one.

```python
def fetch_auth_config(composio_client: Composio[OpenAIProvider]):
    """
    Fetch the auth config for a given user id.
    """
    auth_configs = composio_client.auth_configs.list()
    for auth_config in auth_configs.items:
        if auth_config.toolkit == "gmail":
            return auth_config

    return None
```
</details>

Once you have authentication management in place, we can start with connecting
your users to your `gmail` app. Let's implement a function to connect the users
to your `gmail` app via composio.

```python
# Function to initiate a connected account
def create_connection(composio_client: Composio[OpenAIProvider], user_id: str):
    """
    Create a connection for a given user id and auth config id.
    """
    # Fetch or create the auth config for the gmail toolkit
    auth_config = fetch_auth_config(composio_client=composio_client)
    if not auth_config:
        auth_config = create_auth_config(composio_client=composio_client)

    # Create a connection for the user
    return composio_client.connected_accounts.initiate(
        user_id=user_id,
        auth_config_id=auth_config.id,
    )
```

Now, when creating tools for your agent always check if the user already has a
connected account before creating a new one.

```python
def check_connected_account_exists(
    composio_client: Composio[LangchainProvider],
    user_id: str,
):
    """
    Check if a connected account exists for a given user id.
    """
    # Fetch all connected accounts for the user
    connected_accounts = composio_client.connected_accounts.list(
        user_ids=[user_id],
        toolkit_slugs=["GMAIL"],
    )

    # Check if there's an active connected account
    for account in connected_accounts.items:
        if account.status == "ACTIVE":
            return True

        # Ideally you should not have inactive accounts, but if you do, you should delete them
        print(f"[warning] inactive account {account.id} found for user id: {user_id}")
    return False
```

## Creating Triggers

You can use triggers to make your agents react to real world events. In this example,
we will use triggers to invoke your agent everytime there's a new message in your
gmail inbox.

```python
# Create a new trigger
def create_trigger(
    composio_client: Composio[LangchainProvider],
    connected_account_id: str,
) -> str:
    """
    Create a trigger.
    """
    response = composio_client.triggers.create(
        slug="GMAIL_NEW_GMAIL_MESSAGE",
        connected_account_id=connected_account_id,
        trigger_config={},
    )
    return response.trigger_id
```

When creating triggers, make sure there are no duplicate triggers. Use following
code as reference for checking if trigger for given connected account exists or not.

```python
def check_trigger_exists(
    composio_client: Composio[LangchainProvider],
    connected_account_id: str,
) -> t.Optional[str]:
    """
    Check if a trigger exists.
    """
    triggers = composio_client.triggers.list_active(
        trigger_names=["GMAIL_NEW_GMAIL_MESSAGE"],
        connected_account_ids=[connected_account_id],
    )
    for trigger in triggers.items:
        return trigger.id
    return None
```

Once trigger is created, you can listen to events using a trigger subscription.

```python
# Create subscription object
trigger_subscription = composio_client.triggers.subscribe()

# Register event handler
@trigger_subscription.handle(
    trigger_id="",  # Filter out events that does not belong this trigger id
    trigger_slug="GMAIL_NEW_GMAIL_MESSAGE",
)
def handle_event(event: TriggerEvent):
    print("> Received email with subject: ", event["payload"]["subject"])

# Wait for events
trigger_subscription.wait_forever()
```

## Putting everything together

Let's put together everything by making the agent react to new messages in your
inbox.

```python
# Create a trigger subscription factory

def create_trigger_subscription(
    composio_client: Composio[LangchainProvider],
    trigger_slug: str,
    trigger_id: str,
    agent: AgentExecutor,
):
    """
    Create a trigger subscription for the given agent.
    """
    trigger_subscription = composio_client.triggers.subscribe()

    @trigger_subscription.handle(
        trigger_slug=trigger_slug,
        trigger_id=trigger_id,
    )
    def handle_event(event: TriggerEvent):
        print("> Received email with subject: ", event["payload"]["subject"])
        result = agent.invoke(
            input={
                "input": APPLY_NEW_LABEL.format(  # Check `gmail_labeler/prompt.py`
                    message_id=event["payload"]["id"],
                    message_subject=event["payload"]["subject"],
                    message_text=event["payload"]["message_text"],
                )

        )
        print("> Result: ", result["output"])

    return trigger_subscription
```

Package everything as a single entry point.

```python
def run_agent(user_id: str):
    # Create composio client
    composio_client = Composio(provider=LangchainProvider())

    # Validate conected account
    connected_account_id = check_connected_account_exists(composio_client, user_id)
    if connected_account_id is None:
        connection_request = create_connection(composio_client, user_id)
        print(
            f"Authenticate with the following link: {connection_request.redirect_url}"
        )
        connection_request.wait_for_connection()
        connected_account_id = connection_request.id

    # Check if trigger exists, create if not
    trigger_id = check_trigger_exists(
        composio_client=composio_client,
        connected_account_id=connected_account_id,
    )
    if trigger_id is None:
        trigger_id = create_trigger(
            composio_client=composio_client,
            connected_account_id=connected_account_id,
        )

    # Create agent
    agent = create_agent(user_id=user_id, composio_client=composio_client)

    # Create trigger subscription
    trigger_subscription = create_trigger_subscription(
        composio_client=composio_client,
        trigger_slug=GMAIL_NEW_GMAIL_MESSAGE_TRIGGER,
        trigger_id=trigger_id,
        agent=agent,
    )

    # Wait forever
    print("Waiting for events...")
    trigger_subscription.wait_forever()
```

To test the above function as CLI, follow the steps below

1. Clone the repository
   ```bash
   git clone git@github.com:composiohq/gmail-labeler
   cd gmail-labeler/
   ```
2. Setup environment
   ```bash
   cp .env.example .env
   ```

   Fill the api keys
   ```dotenv
   COMPOSIO_API_KEY=
   OPENAI_API_KEY=
   ```

   Create the virtual env
   ```bash
   make env
   source .venv/bin/activate
   ```
3. Run the agent
   ```bash
   python gmail_labeler --user-id "default"
   ```

## Using Composio for managed auth and tools

Composio reduces a lot of boilerplate for building AI agents with ability access and use a wide variety of apps. For example in this cookbook, to build `gmail` integration without composio you would have to write code to
- manage `gmail` oauth app
- manage user connections
- tools for your agents to interact with `gmail`
- Infra for listening to changes in your gmail inbox

Using composio simplifies all of the above to a few lines of code as we've seen the cookbook.

## Best practices

**🔒 User Management**:

- Use unique, consistent `user_id` values for each person
- Each user maintains their own gmail connection
- User IDs can be email addresses, usernames, or any unique identifier

## Troubleshooting

**Connection Issues**:
- Ensure your `.env` file has valid `COMPOSIO_API_KEY` and `OPENAI_API_KEY`
- Check that the user has completed `gmail` authorization
- Verify the user_id matches exactly between requests

**API Errors**:
- Check the server logs for detailed error messages
- Ensure request payloads match the expected format
- Visit `/docs` endpoint for API schema validation

---

# Basic Hono Server (/examples/hono)

With Composio's managed authentication and tool calling, it's easy to build
AI agents that interact with the real world while reducing boilerplate for
setup and authentication management. This cookbook will guide you through
building and serving agents using `Composio`, `OpenAI`, and `Hono.js`.

## Prerequisites

* Node.js 18.x or higher
* npm or yarn package manager  
* Composio API key
* OpenAI API key
* Basic knowledge of OAuth
* Understanding of building HTTP services (preferably using Hono.js)

## Building an AI agent that can interact with `gmail` service

First, let's start with building a simple AI agent embedded with tools from
Composio that lets the agent interact with the `gmail` service.

```typescript
import { OpenAI } from 'openai';
import { Composio } from '@composio/core';
import { OpenAIProvider } from '@composio/openai';

export async function runGmailAgent(
    composioClient: Composio,
    openaiClient: OpenAI,
    userId: string,  // Composio uses the User ID to store and access user-level authentication tokens.
    prompt: string,
): Promise<any[]> {
    // Step 1: Fetch the necessary Gmail tools list with Composio
    const tools = await composioClient.tools.get(
        userId,

            tools: [
                "GMAIL_FETCH_EMAILS",
                "GMAIL_SEND_EMAIL", 
                "GMAIL_CREATE_EMAIL_DRAFT"
            ]

    );

    // Step 2: Use OpenAI to generate a response based on the prompt and available tools
    const response = await openaiClient.chat.completions.create({
        model: "gpt-4.1",
        tools,
        messages: [{ role: "user", content: prompt }],
    });

    // Step 3: Handle tool calls with Composio and return the result
    const result = await composioClient.provider.handleToolCalls(
        userId,
        response
    );
    return result;

```

> 
  This is a simple agent without state management and agentic loop implementation,
  so the agent can't perform complicated tasks. If you want to understand how
  composio can be used with agentic loops, check other cookbooks with more
  agentic frameworks.

To invoke this agent, authenticate your users with Composio's managed authentication service.

## Authenticating users

To authenticate your users with Composio you need an authentication config for the given app. In this case you need one for gmail.

To create an authentication config for `gmail` you need `client_id` and `client_secret` from your [Google OAuth Console](https://developers.google.com/identity/protocols/oauth2). Once you have the credentials, use the following piece of code to set up authentication for `gmail`.

```typescript
import { Composio } from '@composio/core';
import { OpenAIProvider } from '@composio/openai';

export async function createAuthConfig(composioClient: Composio) {
    /**
     * Create a auth config for the gmail toolkit.
     */
    const clientId = process.env.GMAIL_CLIENT_ID;
    const clientSecret = process.env.GMAIL_CLIENT_SECRET;
    if (!clientId || !clientSecret) {
        throw new Error("GMAIL_CLIENT_ID and GMAIL_CLIENT_SECRET must be set");

    return composioClient.authConfigs.create(
        "GMAIL",

            "name": "default_gmail_auth_config",
            "type": "use_custom_auth",
            "authScheme": "OAUTH2",
            "credentials": {
                "clientId": clientId,
                "clientSecret": clientSecret,
            },
        },
    );

```

This will create a Gmail authentication config to authenticate your app's users. Ideally, create one authentication object per project, so check for an existing auth config before creating a new one.

```typescript
import { Composio } from '@composio/core';
import { OpenAIProvider } from '@composio/openai';
// ---cut---
export async function fetchAuthConfig(composioClient: Composio) {
    /**
     * Fetch the auth config for a given user id.
     */
    const authConfigs = await composioClient.authConfigs.list();
    for (const authConfig of authConfigs.items) {
        if (authConfig.toolkit.slug === "gmail") {
            return authConfig;

    return null;

```

> 
  Composio platform provides composio managed authentication for some apps to
  fast-track your development, `gmail` being one of them. You can use these
  default auth configs for development, but for production, always use your
  own oauth app configuration.

Once you have authentication management in place, we can start with connecting your users to your `gmail` app. Let's implement a function to connect users to your `gmail` app via composio.

```typescript
import { Hono } from 'hono';
import { Composio } from '@composio/core';
import { OpenAIProvider } from '@composio/openai';

declare function fetchAuthConfig(client: Composio): Promise<{ id: string } | null>;
declare function createAuthConfig(client: Composio): Promise<{ id: string }>;
declare const composioClient: Composio;
// ---cut---
// Function to initiate a connected account
export async function createConnection(composioClient: Composio, userId: string) {
    /**
     * Create a connection for a given user id and auth config id.
     */
    // Fetch or create the auth config for the gmail toolkit
    let authConfig = await fetchAuthConfig(composioClient);
    if (!authConfig) {
        authConfig = await createAuthConfig(composioClient);

    // Create a connection for the user
    return composioClient.connectedAccounts.initiate(
        userId,
        authConfig.id,
    );

// Setup Hono
const app = new Hono();

// Connection initiation endpoint
app.post("/connection/create", async (c) => {
    /**
     * Create a connection for a given user id.
     */
    // For demonstration, using a default user_id. Replace with real user logic in production.
    const userId = "default";

    // Create a new connection for the user
    const connectionRequest = await createConnection(composioClient, userId);
    return c.json({
        "connection_id": connectionRequest.id,
        "redirect_url": connectionRequest.redirectUrl,
    });
});
```

Now, you can make a request to this endpoint on your client app, and your user will get a URL which they can use to authenticate.

## Set Up Hono service

We will use [`Hono.js`](https://hono.dev/) to build an HTTP service that authenticates your users and lets them interact with your agent. This guide will provide best practices for using composio client in production environments.

### Setup dependencies

Hono allows dependency injection patterns to simplify the usage of SDK clients that must be singletons. We recommend using composio SDK client as singleton.

```typescript
import { Composio } from '@composio/core';
import { OpenAIProvider } from '@composio/openai';
import { OpenAI } from 'openai';

let _composioClient: Composio | null = null;

export function provideComposioClient(): Composio {
    /**
     * Provide a Composio client.
     */
    if (_composioClient === null) {
        _composioClient = new Composio({ 
            provider: new OpenAIProvider() 
        });

    return _composioClient;

// A Composio client dependency.
export type ComposioClient = Composio;
```

Check [config/composio.ts](./src/config/composio.ts) module for more details.

### Invoke agent via Hono

When invoking an agent, make sure you validate the `user_id`.

```typescript
import { Composio } from '@composio/core';
import { OpenAIProvider } from '@composio/openai';
import { OpenAI } from 'openai';
import { Hono } from 'hono';

const app = new Hono();
declare const composioClient: Composio;
declare const openaiClient: OpenAI;
declare function runGmailAgent(c: Composio, o: OpenAI, u: string, p: string): Promise<any[]>;
// ---cut---
export function checkConnectedAccountExists(
    composioClient: Composio,
    userId: string,
): Promise<boolean> {
    /**
     * Check if a connected account exists for a given user id.
     */
    // Fetch all connected accounts for the user
    return composioClient.connectedAccounts.list({ userIds: [userId], toolkitSlugs: ["GMAIL"] }).then(connectedAccounts => {

        // Check if there's an active connected account
        for (const account of connectedAccounts.items) {
            if (account.status === "ACTIVE") {
                return true;

            // Ideally you should not have inactive accounts, but if you do, delete them.
            console.log(`[warning] inactive account ${account.id} found for user id: ${userId}`);

        return false;
    });

export async function validateUserId(userId: string, composioClient: Composio): Promise<string> {
    /**
     * Validate the user id, if no connected account is found, create a new connection.
     */
    if (await checkConnectedAccountExists(composioClient, userId)) {
        return userId;

    throw new Error("No connected account found for the user id");

// Endpoint: Run the Gmail agent for a given user id and prompt
app.post("/agent", async (c) => {
    /**
     * Run the Gmail agent for a given user id and prompt.
     */
    const request = await c.req.json();
    
    // For demonstration, using a default user_id. Replace with real user logic in production.
    const userId = "default";

    // Validate the user id before proceeding
    await validateUserId(userId, composioClient);

    // Run the Gmail agent using Composio and OpenAI
    const result = await runGmailAgent(
        composioClient,
        openaiClient,
        userId,
        request.prompt,
    );
    return c.json(result);
});
```

> 
  Check [src/api.ts](./src/api.ts) module for service implementation

## Putting everything together

So far, we have created an agent with ability to interact with `gmail` using the `composio` SDK, functions to manage connected accounts for users and a Hono service. Now let's run the service.

> 
  Before proceeding, check the [code](./src/api.ts) for utility endpoints not discussed in the cookbook

1. Clone the repository
   ```bash
   git clone git@github.com:composiohq/composio-hono
   cd composio-hono/
   ```
2. Setup environment

   ```bash
   cp .env.example .env
   ```

   Fill the api keys

   ```dotenv
   COMPOSIO_API_KEY=
   OPENAI_API_KEY=
   ```

   Install dependencies

   ```bash
   npm install
   ```
3. Run the HTTP server
   ```bash
   npm run dev
   ```

## Testing the API with curl

Assuming the server is running locally on `http://localhost:8000`.

### Check if a connection exists

```bash
curl -X POST http://localhost:8000/connection/exists
```

### Create a connection

Note: The body fields are required by the API schema, but are ignored internally in this example service.

```bash
curl -X POST http://localhost:8000/connection/create \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "default",
    "auth_config_id": "AUTH_CONFIG_ID_FOR_GMAIL_FROM_THE_COMPOSIO_DASHBOARD"
  }'
```

Response includes `connection_id` and `redirect_url`. Complete the OAuth flow at the `redirect_url`.

### Check connection status

Use the `connection_id` returned from the create step.

```bash
curl -X POST http://localhost:8000/connection/status \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "default",
    "connection_id": "CONNECTION_ID_FROM_CREATE_RESPONSE"
  }'
```

### Run the Gmail agent

Requires an active connected account for the `default` user.

```bash
curl -X POST http://localhost:8000/agent \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "default",
    "prompt": "Summarize my latest unread emails from the last 24 hours."
  }'
```

### Fetch emails (direct action)

```bash
curl -X POST http://localhost:8000/actions/fetch_emails \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "default",
    "limit": 5
  }'
```

These examples are intended solely for testing purposes.

## Using Composio for managed auth and tools

Composio reduces boilerplate for building AI agents that access and use various apps. In this cookbook, to build Gmail integration without Composio, you would have to write code to

* manage Gmail OAuth app
* manage user connections
* tools for your agents to interact with Gmail

Using Composio simplifies all of the above to a few lines of code as shown in the cookbook.

## Best practices

**🎯 Effective Prompts**:

* Be specific: "Send email to [john@company.com](mailto:john@company.com) about tomorrow's 2pm meeting" works better than "send email"
* Include context: "Reply to Sarah's email about the budget with our approval"
* Use natural language: The agent understands conversational requests

**🔑 User Management**:

* Use unique, consistent `user_id` values for each person
* Each user maintains their own Gmail connection
* User IDs can be email addresses, usernames, or any unique identifier

## Troubleshooting

**Connection Issues**:

* Ensure your `.env` file has valid `COMPOSIO_API_KEY` and `OPENAI_API_KEY`
* Check if the user has completed Gmail authorization.
* Verify the user\_id matches exactly between requests

**API Errors**:

* Check the server logs for detailed error messages
* Ensure request payloads match the expected format
* Visit `/docs` endpoint for API schema validation

**Gmail API Limits**:

* Gmail has rate limits; the agent will handle these gracefully
* For high-volume usage, consider implementing request queuing

---

# Examples (/examples)

Explore practical examples of building AI agents with Composio.

## Getting Started

- [Basic FastAPI Server](/examples/fast-api) - Build a Gmail agent with FastAPI
- [Basic Hono Server](/examples/hono) - Build a Gmail agent with Hono.js

## Productivity & Automation

- [Gmail Labeler](/examples/gmail-labeler) - Automatically label incoming emails using triggers
- [Slack Summarizer](/examples/slack-summariser) - Summarize Slack channel messages
- [Supabase SQL Agent](/examples/supabase-sql-agent) - Execute SQL queries using natural language

## Full Stack Applications

- [Full Stack Chat App](/examples/vercel-chat) - Build a chat interface with user connections

## Behind the Curtain

- [Tool Type Generator](/examples/tool-generator) - Build platforms using raw tool definitions

---

# Slack Summarizer (/examples/slack-summariser)

With Composio's managed authentication and tool calling, it's easy to build the
AI agents that can interact with the real world while reducing the boilerplate
required to setup and manage the authentication. This cookbook will walk you through
the process of building agents using `Composio`,  `LangChain`.

## Prerequisites

* Python3.x
* [UV](https://docs.astral.sh/uv/getting-started/installation/)
* Composio API key
* OpenAI API key
* Understanding of building AI agents (Preferably with LangChain)

## Build slack agent

Let's start by building an agent that can interact with your slack workspace using Composio.

```python
from composio import Composio
from composio_langchain import LangchainProvider

from langchain import hub
from langchain.agents import AgentExecutor, create_openai_functions_agent
from langchain_openai import ChatOpenAI

def create_agent(user_id: str, composio_client: Composio[LangchainProvider]):
    """
    Create an agent for a given user id.
    """
    # Step 1: Get all the tools
    tools = composio_client.tools.get(
        user_id=user_id,
        toolkits=["SLACK"],
    )

    # Step 2: Pull relevant agent prompt.
    prompt = hub.pull("hwchase17/openai-functions-agent")

    # Step 3: Initialize chat model.
    openai_client = ChatOpenAI(model="gpt-5")

    # Step 4: Define agent
    return AgentExecutor(
        agent=create_openai_functions_agent(
            openai_client,
            tools,
            prompt,
        ),
        tools=tools,
        verbose=True,
    )
```

## Authenticating users

To authenticate your users with Composio you need an auth config for the given
app, In this case you need one for slack. You can create and manage auth configs
from the [dashboard](https://platform.composio.dev/?next_page=/auth-configs?create_auth_config=slack).

Composio platform provides composio managed authentication for some apps to help
you fast-track your development, `slack` being one of them. You can use these
default auth configs for development, but for production you should always use
your own oauth app configuration.

Using dashboard is the preferred way of managing authentication configs, but if
you want to do it manually you can follow the guide below

<details>

<summary>Click to expand</summary>

---

To create an authentication config for `slack` you need `client_id` and `client_secret`
from your Slack [App](https://api.slack.com/apps). Once you have the required credentials
you can use the following piece of code to set up authentication for `slack`. 

```python
from composio import Composio
from composio_langchain import LangchainProvider

def create_auth_config(composio_client: Composio[OpenAIProvider]):
    """
    Create a auth config for the slack toolkit.
    """
    client_id = os.getenv("SLACK_CLIENT_ID")
    client_secret = os.getenv("SLACK_CLIENT_SECRET")
    if not client_id or not client_secret:
        raise ValueError("SLACK_CLIENT_ID and SLACK_CLIENT_SECRET must be set")

    return composio_client.auth_configs.create(
        toolkit="SLACK",
        options={
            "name": "default_slack_auth_config",
            "type": "use_custom_auth",
            "auth_scheme": "OAUTH2",
            "credentials": {
                "client_id": client_id,
                "client_secret": client_secret,
            },
        },
    )
```

This will create an authentication config for `slack` which you can use to
authenticate your users for your app. Ideally you should just create one
authentication object per project, so check for an existing auth config
before you create a new one.

```python
def fetch_auth_config(composio_client: Composio[OpenAIProvider]):
    """
    Fetch the auth config for a given user id.
    """
    auth_configs = composio_client.auth_configs.list()
    for auth_config in auth_configs.items:
        if auth_config.toolkit == "SLACK":
            return auth_config

    return None
```
</details>

Once you have authentication management in place, we can start with connecting
your users to your `slack` app. Let's implement a function to connect the users
to your `slack` app via composio.

```python

# Function to initiate a connected account
def create_connection(composio_client: Composio[OpenAIProvider], user_id: str):
    """
    Create a connection for a given user id and auth config id.
    """
    # Fetch or create the auth config for the slack toolkit
    auth_config = fetch_auth_config(composio_client=composio_client)
    if not auth_config:
        auth_config = create_auth_config(composio_client=composio_client)

    # Create a connection for the user
    return composio_client.connected_accounts.initiate(
        user_id=user_id,
        auth_config_id=auth_config.id,
    )
```

Now, when creating tools for your agent always check if the user already has a
connected account before creating a new one.

```python
def check_connected_account_exists(
    composio_client: Composio[LangchainProvider],
    user_id: str,
):
    """
    Check if a connected account exists for a given user id.
    """
    # Fetch all connected accounts for the user
    connected_accounts = composio_client.connected_accounts.list(
        user_ids=[user_id],
        toolkit_slugs=["SLACK"],
    )

    # Check if there's an active connected account
    for account in connected_accounts.items:
        if account.status == "ACTIVE":
            return True

        # Ideally you should not have inactive accounts, but if you do, you should delete them
        print(f"[warning] inactive account {account.id} found for user id: {user_id}")
    return False
```

## Modifiers

In the current setup, we are expanding too much unnecessary tokens because response
from `SLACK_FETCH_CONVERSATION_HISTORY` tool call contains too much unnecessary
information. This can be fixed using `after_execute` modifier. An after execute
modifier is called after a tool execution is complete, here you can process
and modify the response object to make it more easy to consume for your agent.

```python
from composio import after_execute
from composio.types import ToolExecutionResponse

@after_execute(tools=["SLACK_FETCH_CONVERSATION_HISTORY"])
def clean_conversation_history(
    tool: str,
    toolkit: str,
    response: ToolExecutionResponse,
) -> ToolExecutionResponse:
    """
    Clean the conversation history.
    """
    if not response["data"]["ok"]:
        return response

    try:
        response["data"]["messages"] = [
            {"user": message["user"], "text": message["text"]}
            for message in response["data"]["messages"]
            if message["type"] == "message"
        ]
    except KeyError:
        pass

    return response
```

To register modifiers, include them in the `composio.tools.get` call.

```python
tools = composio_client.tools.get(
    user_id=user_id,
    toolkits=[SLACK_TOOLKIT],
    modifiers=[clean_conversation_history],
)
```

## Putting everything together

So far, we have created an agent with ability to interact with your `slack` 
workspace using the `composio` SDK, functions to manage connected accounts
for users and a simple agent runner. Let's package this as a CLI tool.

```python
def run_agent(user_id: str, prompt: str):
    composio_client = Composio(provider=LangchainProvider())
    if not check_connected_account_exists(composio_client, user_id):
        connection_request = create_connection(composio_client, user_id)
        print(
            f"Authenticate with the following link: {connection_request.redirect_url}"
        )
        connection_request.wait_for_connection()

    agent = create_agent(user_id, composio_client)
    agent.invoke({"input": prompt})
```

To test the above function as CLI, follow the steps below

1. Clone the repository
   ```bash
   git clone git@github.com:composiohq/slack-summarizer
   cd slack-summarizer/
   ```
2. Setup environment
   ```bash
   cp .env.example .env
   ```

   Fill the api keys
   ```dotenv
   COMPOSIO_API_KEY=
   OPENAI_API_KEY=
   ```

   Create the virtual env
   ```bash
   make env
   source .venv/bin/activate
   ```
3. Run the agent
   ```bash
   python slack_summariser --user-id "default" --prompt "summarise last 5 messages from #general channel"
   ```

## Using Composio for managed auth and tools

Composio reduces a lot of boilerplate for building AI agents with ability access and use a wide variety of apps. For example in this cookbook, to build `slack` integration without composio you would have to write code to
- manage `slack` oauth app
- manage user connections
- tools for your agents to interact with `slack`

Using composio simplifies all of the above to a few lines of code as we've seen the cookbook.

## Best practices

**🔒 User Management**:

- Use unique, consistent `user_id` values for each person
- Each user maintains their own slack connection
- User IDs can be email addresses, usernames, or any unique identifier

## Troubleshooting

**Connection Issues**:
- Ensure your `.env` file has valid `COMPOSIO_API_KEY` and `OPENAI_API_KEY`
- Check that the user has completed `slack` authorization
- Verify the user_id matches exactly between requests

**API Errors**:
- Check the server logs for detailed error messages
- Ensure request payloads match the expected format
- Visit `/docs` endpoint for API schema validation

---

# Supabase SQL Agent (/examples/supabase-sql-agent)

With Composio's managed authentication and tool calling, it's easy to build
AI agents that interact with the real world while reducing boilerplate for
setup and authentication management. This guide will walk you through using
the Supabase CLI agent built with `Composio` and `LlamaIndex`.

## Requirements

* Python 3.10+
* [UV](https://docs.astral.sh/uv/getting-started/installation/) (recommended) or pip
* Composio API key
* OpenAI API key
* Understanding of building AI agents (Preferably with LlamaIndex)

## Build an agent to perform Supabase tasks

```python
from composio import Composio
from composio_llamaindex import LlamaIndexProvider

from llama_index.llms.openai import OpenAI
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.core.workflow import Context

def create_agent(user_id: str, composio_client: Composio[LlamaIndexProvider]):
   """
   Create a function agent that can perform Supabase tasks.
   """

   # Setup client
   llm = OpenAI(model="gpt-5")

   # Get All the tools
   tools = composio_client.tools.get(
      user_id=user_id,
      tools=[
         "SUPABASE_LIST_ALL_PROJECTS",
         "SUPABASE_BETA_RUN_SQL_QUERY",
      ],
   )

   agent = FunctionAgent(
      tools=tools,
      llm=llm,
      system_prompt=(
         "You are a helpful assistant that can help with supabase queries."
      ),
   )

   #  Since this is a continuosly running agent, we need to maintain state across
   # different user messages
   ctx = Context(workflow=agent)
   return agent, ctx
```

This agent can convert your natural language queries to SQL queries and execute
them on supabase for you. For you agent to be able to execute queries, you need
to authenticate the agent for supabase.

## Authenticating users

To authenticate your users with Composio you need an auth config for the given
app, In this case you need one for supabase. You can create and manage auth configs
from the [dashboard](https://platform.composio.dev/?next_page=/auth-configs?create_auth_config=supabase).
Composio platform provides composio managed authentication for some apps to help
you fast-track your development, `supabase` being one of them. You can use these
default auth configs for development, but for production you should always use
your own oauth app configuration.

Using dashboard is the preferred way of managing authentication configs, but if
you want to do it manually you can follow the guide below

<details>

<summary>Click to expand</summary>

---

To create an authentication config for `supabase` you need `client_id` and `client_secret`
from your from your [Google OAuth Console](https://developers.google.com/identity/protocols/oauth2).
Once you have the required credentials you can use the following piece of
code to set up authentication for `supabase`. 

```python
from composio import Composio
from composio_langchain import LangchainProvider

def create_auth_config(composio_client: Composio[OpenAIProvider]):
    """
    Create a auth config for the supabase toolkit.
    """
    client_id = os.getenv("SUPABASE_CLIENT_ID")
    client_secret = os.getenv("SUPABASE_CLIENT_SECRET")
    if not client_id or not client_secret:
        raise ValueError("SUPABASE_CLIENT_ID and SUPABASE_CLIENT_SECRET must be set")

    return composio_client.auth_configs.create(
        toolkit="supabase",
        options={
            "name": "default_supabase_auth_config",
            "type": "use_custom_auth",
            "auth_scheme": "OAUTH2",
            "credentials": {
                "client_id": client_id,
                "client_secret": client_secret,
            },
        },
    )
```

This will create an authentication config for `supabase` which you can use to
authenticate your users for your app. Ideally you should just create one
authentication object per project, so check for an existing auth config
before you create a new one.

```python
def fetch_auth_config(composio_client: Composio[OpenAIProvider]):
    """
    Fetch the auth config for a given user id.
    """
    auth_configs = composio_client.auth_configs.list()
    for auth_config in auth_configs.items:
        if auth_config.toolkit == "supabase":
            return auth_config

    return None
```
</details>

Once you have authentication management in place, we can start with connecting
your users to your `supabase` app. Let's implement a function to connect the users
to your `supabase` app via composio.

```python
# Function to initiate a connected account
def create_connection(composio_client: Composio[OpenAIProvider], user_id: str):
    """
    Create a connection for a given user id and auth config id.
    """
    # Fetch or create the auth config for the supabase toolkit
    auth_config = fetch_auth_config(composio_client=composio_client)
    if not auth_config:
        auth_config = create_auth_config(composio_client=composio_client)

    # Create a connection for the user
    return composio_client.connected_accounts.initiate(
        user_id=user_id,
        auth_config_id=auth_config.id,
    )
```

Now, when creating tools for your agent always check if the user already has a
connected account before creating a new one.

```python
def check_connected_account_exists(
    composio_client: Composio[LangchainProvider],
    user_id: str,
):
    """
    Check if a connected account exists for a given user id.
    """
    # Fetch all connected accounts for the user
    connected_accounts = composio_client.connected_accounts.list(
        user_ids=[user_id],
        toolkit_slugs=["SUPABASE"],
    )

    # Check if there's an active connected account
    for account in connected_accounts.items:
        if account.status == "ACTIVE":
            return True

        # Ideally you should not have inactive accounts, but if you do, you should delete them
        print(f"[warning] inactive account {account.id} found for user id: {user_id}")
    return False
```

## Create a chat loop

```python
async def run_loop(user_id: str):
    # Initialize composio client.
    composio_client = Composio(provider=LlamaIndexProvider())

    # Setup connection if required
    if not check_connected_account_exists(
        composio_client=composio_client,
        user_id=user_id,
    ):
        connection_request = create_connection(
            composio_client=composio_client,
            user_id=user_id,
        )
        print(
            f"Authenticate with the following link: {connection_request.redirect_url}"
        )

    # Create agent
    agent, ctx = create_agent(
        user_id=user_id,
        composio_client=composio_client,
    )

    # Run a simple REPL loop
    while True:
        user_input = input("user > ")
        if user_input.lower() == "exit":
            break

        result = await agent.run(user_msg=user_input, ctx=ctx)
        print("agent > ", result)
    print("Exiting...")
```

## Using Composio for managed auth and tools

Composio reduces a lot of boilerplate for building AI agents with ability access
and use a wide variety of apps. For example in this cookbook, to build `supabase`
integration without composio you would have to write code to

- manage `supabase` oauth app
- manage user connections
- tools for your agents to interact with `supabase`

Using composio simplifies all of the above to a few lines of code as we've seen the cookbook.

## Best practices

**🔒 User Management**:

- Use unique, consistent `user_id` values for each person
- Each user maintains their own supabase connection
- User IDs can be email addresses, usernames, or any unique identifier

## Troubleshooting

**Connection Issues**:
- Ensure your `.env` file has valid `COMPOSIO_API_KEY` and `OPENAI_API_KEY`
- Check that the user has completed `supabase` authorization
- Verify the user_id matches exactly between requests

**API Errors**:
- Check the server logs for detailed error messages
- Ensure request payloads match the expected format
- Visit `/docs` endpoint for API schema validation

---

# Tool Type Generator (/examples/tool-generator)

This is a bit of a checky tutorial as it is dogfooding the `docs` tool generation process.

To motivate this example clearly, in our tools section — we have details about let's say [`Github`](/toolkits/github) tool, that shows its auth scheme, actions and their params.

Now why would anyone outside of Composio want to do this? Well if you are building a platform on top of Composio, perchance a Workflow builder like langflow. You would want to show some or all of this information to your users.

This is a non standard use case, that we support and love users building on top of us but if this is uninteresting to you, you can skip this tutorial.

## How does one build a tool type generator?

In composio, we have two internal states for tools

1. Raw tool definition
2. Provider tool definition

The raw tool definition is an generic input output schema definition that we internally for tools, we expose it for customers if they want to build on top of it but it is not the primary way tools are normally used.

The provider tool definition, translates this raw tool definition to the specific schema of a provider (by default `openai`). 

For building something like this, we need to use the raw tool definition.

## Getting the raw tool definition

Of course, you need to initiate the `Composio` sdk first and use a `COMPOSIO_API_KEY` environment variable.

```python Python {2} title="tool_doc_generator/main.py" maxLines=40 wordWrap

    def __init__(self, include_local: bool = False):
        """
```

Let us see an example output for a raw `GMAIL` toolkit, with all of its tools.

this is just a taste but you can see the full output [here](https://github.com/composio-dev/composio/blob/next/fern/pages/src/examples/tool-generator/output.json).

```json JSON title="output.json" maxLines=40 
[

        "deprecated": {
            "available_versions": [
                "0_1",
                "latest",
                "latest:base"
            ],
            "display_name": "Modify email labels",
            "is_deprecated": false,
            "toolkit": {
                "logo": "https://cdn.jsdelivr.net/gh/ComposioHQ/open-logos@master/gmail.svg"
            },
            "version": "0_1",
            "displayName": "Modify email labels"
        },
        "description": "Adds and/or removes specified gmail labels for a message; ensure `message id` and all `label ids` are valid (use 'listlabels' for custom label ids).",
        "input_parameters": {
            "properties": {
                "add_label_ids": {
                    "default": [],
                    "description": "Label IDs to add. For custom labels, obtain IDs via 'listLabels'. System labels (e.g., 'INBOX', 'SPAM') can also be used.",
                    "examples": [
                        "STARRED",
                        "IMPORTANT",
                        "Label_123"
                    ],
                    "items": {
                        "type": "string"
                    },
                    "title": "Add Label Ids",
                    "type": "array"
                },
                "message_id": {
                    "description": "Immutable ID of the message to modify (e.g., from 'fetchEmails' or 'fetchMessagesByThreadId').",
                    "examples": [
                        "17f1b2b9c1b2a3d4"
                    ],
                    "title": "Message Id",
                    "type": "string"
                },
                "remove_label_ids": {
                    "default": [],
                    "description": "Label IDs to remove. For custom labels, obtain IDs via 'listLabels'. System labels can also be used.",
                    "examples": [
                        "UNREAD",
                        "Label_456"
                    ],
                    "items": {
                        "type": "string"
                    },
                    "title": "Remove Label Ids",
                    "type": "array"
                },
                "user_id": {
                    "default": "me",
                    "description": "User's email address or 'me' for the authenticated user.",
                    "examples": [
                        "me",
                        "user@example.com"
                    ],
                    "title": "User Id",
                    "type": "string"

            },
            "required": [
                "message_id"
            ],
            "title": "AddLabelToEmailRequest",
            "type": "object"
        },
        "name": "Modify email labels",
        "no_auth": false,
        "output_parameters": {
            "properties": {
                "data": {
                    "description": "Data from the action execution",
                    "properties": {
                        "response_data": {
                            "description": "Full `Message` resource with updated labels.",
                            "title": "Response Data",
                            "type": "object"

                    },
                    "required": [
                        "response_data"
                    ],
                    "title": "Data",
                    "type": "object"
                },
                "error": {
                    "anyOf": [

                            "type": "string"
                        },

                            "type": "null"

                    ],
                    "default": null,
```

```sh
jq '.[0] | keys' pages/src/examples/tool-generator/output.json
[
  "available_versions",
  "deprecated",
  "description",
  "input_parameters",
  "name",
  "no_auth",
  "output_parameters",
  "scopes",
  "slug",
  "tags",
  "toolkit",
  "version"
]
```

There is a bunch of useful information here, around the `input_parameters` and `output_parameters` for this example but `scopes` is very valuable to know what permissions are required for this tool.

Now from these `input_parameters` and `output_parameters` you can showcase the tool definitions.

```python Python title="tool_doc_generator/main.py" maxLines=40 
        fields = []
        _, field_config = field

        for field_list, required in [
            (getattr(field_config, "required", []), True),
            (getattr(field_config, "optional", []), False),
        ]:
            for f in field_list:
                if hasattr(f, "name"):
                    fields.append(self._create_param_from_field(f, required))
```

There is a bunch of other processing things happening here that are super generally relevant, so not going to call them out here that said there is another thing i want to showcase

## Toolkit Information

Toolkis are what we call apps or integrations, for us they are a collection of tools. `GMAIL` has `GMAIL_SEND_EMAIL` as a tool.

Now for building something out like this, you might also want information about the toolkit itself.

A toolkit has information like `categories` or `auth_schemes`

```python Python title="tool_doc_generator/main.py" maxLines=40 
        """
        Initialize the tool documentation generator.

        Args:
```

`auth_schemes` here are `OAUTH2`, `API_KEY` or `BASIC_AUTH`, etc — essentially the types of how one could authenticate with the toolkit.

```python Python title="tool_doc_generator/main.py" maxLines=40 
        # Initialize composio client
        self.composio = Composio()
        self.include_local = include_local

        # For tracking generated tools
        self.generated_tools = []
        self.problematic_actions = []

    def generate_docs(
        self, output_path: Path, max_workers: int | None = None, limit: int | None = None
```

Here is a way to parse the `auth_scheme` data

these are `tuple` objects as they have different schema for specific conditions like `auth_config_creation` or `connected_account_initiation`

they also have `required` and `optional` fields.

the context here is there are some fields you need while creating an auth config and some you need while connecting an account. this separation is done by the `tuple` here

```python Python title="tool_doc_generator/main.py" maxLines=40 
        auth_schemes: t.Optional[t.List[toolkit_retrieve_response.AuthConfigDetail]] = None,
    ) -> None:
        schemes = ", ".join(
            self._get_auth_type(s) for s in (auth_schemes or []) if self._extract_auth_fields(s)
        )
        self._blocks.extend(
            [
                f"""## Connecting to {app_name}
### Create an auth config
Use the dashboard to create an auth config for the {app_name} toolkit. This allows you to connect multiple {app_name} accounts to Composio for agents to use.

  
    Navigate to **[{app_name}](https://platform.composio.dev?next_page=/marketplace/{app_name})**.
  
  
    Select among the supported auth schemes of and configure them here.
  
  
    Click **"Create {app_name} Auth Config"**. After creation, **copy the displayed ID starting with `ac_`**. This is your auth config ID. This is _not_ a sensitive ID -- you can save it in environment variables or a database.
    **This ID will be used to create connections to the toolkit for a given user.**
  

"""
            ],
        )

        # Add auth code snippets
        self._add_auth_section(app_name, app_slug, auth_schemes)

    def _add_auth_section(
        self,
        app_name: str,
        app_slug: str,
        auth_schemes: t.List[toolkit_retrieve_response.AuthConfigDetail] = None,
    ) -> None:
        """Add code snippets for each auth scheme using direct template processing"""
        if not auth_schemes:
            return
        
        self._blocks.append("### Connect Your Account")
        
        # Group auth schemes by type to avoid duplicates
        seen_auth_types = set()
        
```

This is a fairly minimal explanation for the amount of code, as most of it is not super related to composio but it will be a good example on seeing behind the scenes of how composio is working and how to leverage the platform further.

---

# Full Stack Chat App (/examples/vercel-chat)

In this example, you will learn how to build a chatbot that:

- Lets users connect their various apps to the chatbot using the Composio SDK.
- Uses the Vercel provider in the Composio SDK to handle and execute tool calls from the LLM.

This page gives a high-level overview of the Composio SDK and how it is used in the
GitHub repository: [composiohq/chat](https://github.com/composiohq/chat). You can
find the demo live [here](https://chat.composio.dev/).

## Prerequisites

Ensure you've followed the README.md in the [composiohq/chat](https://github.com/composiohq/chat)
repository to set up the project locally.

## Creating auth configs

For all the apps you want to connect to the chatbot, you need to create their
respective auth configs. Learn how to create auth configs [here](/docs/authenticating-tools#creating-an-auth-config).
Once done, your auth configs will be available in the [Composio dashboard](https://app.composio.dev/integrations).

  <img src="../../../../assets/images/examples/auth-configs.png" alt="Auth configs" />

### Save auth config IDs to environment variables

For this project, the auth config IDs should be saved to the environment variables
with the `NEXT_PUBLIC_` prefix.

```bash .env.local
NEXT_PUBLIC_GMAIL_AUTH_CONFIG_ID=ac_1234567890
NEXT_PUBLIC_GITHUB_AUTH_CONFIG_ID=ac_1234567890
```

## Create a Composio client instance

We create a Composio client instance for server-side operations like API routes,
server components, etc.

```typescript lib/service/composio.ts
import { Composio } from '@composio/core';
import { VercelProvider } from '@composio/vercel';

const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
  provider: new VercelProvider(),
});

export default composio;
```

## Creating an API for fetching toolkits

The Composio SDK is meant to be used only in server-side code. For client-side
functionality, we create API endpoints in the `/app/api/` directory. In order to
list the toolkits and their connection status, we create a Next.js API route to
fetch the toolkits using Composio SDK.

  <img src="../../../../assets/images/examples/toolkits.png" />

### 1. Listing connected accounts

First, we fetch all connected accounts for a user and create a mapping of toolkit
slugs to their connection IDs:

```typescript app/api/composio/toolkits.ts
// @noErrors
export async function GET() {
  // ... auth logic ...

  // List connected accounts to get connection IDs for each toolkit
  const connectedAccounts = await composio.connectedAccounts.list({
    userIds: [session.user.id],
  });

  const connectedToolkitMap = new Map();
  connectedAccounts.items.forEach(account => {
    connectedToolkitMap.set(account.toolkit.slug.toUpperCase(), account.id);
  });

  // ... continue with toolkit fetching ...

```

### 2. Fetching toolkit data and building response

Next, we fetch toolkit information for each supported toolkit and combine it with the connection status:

```typescript app/api/composio/toolkits.ts
// @noErrors
export async function GET() {
  // ... auth logic ...
  // ... connected accounts mapping ...

  const SUPPORTED_TOOLKITS = ['GMAIL', 'GOOGLECALENDAR', 'GITHUB', 'NOTION'];

  // Fetch toolkit data from slugs
  const toolkitPromises = SUPPORTED_TOOLKITS.map(async slug => {
    const toolkit = await composio.toolkits.get(slug);
    const connectionId = connectedToolkitMap.get(slug.toUpperCase());

    return {
      name: toolkit.name,
      slug: toolkit.slug,
      description: toolkit.meta?.description,
      logo: toolkit.meta?.logo,
      categories: toolkit.meta?.categories,
      isConnected: !!connectionId,
      connectionId: connectionId || undefined,
    };
  });

  const toolkits = await Promise.all(toolkitPromises);
  return NextResponse.json({ toolkits });

```

## Managing connections

Users need to connect and disconnect their accounts from the chatbot to enable tool usage. When users click "Connect" on a toolkit, we initiate an OAuth flow, and when they click "Disconnect", we remove their connection.

### 1. Initiating a connection

When a user wants to connect their account, we create a connection request that redirects them to the OAuth provider:

  <img src="../../../../assets/images/examples/create-connection.png" />

```typescript app/api/connections/initiate/route.ts
// @noErrors
export async function POST(request: Request) {
  // ... auth and validation ...

  const { authConfigId } = requestBody;

  // Initiate connection with Composio
  const connectionRequest = await composio.connectedAccounts.initiate(
    session.user.id,
    authConfigId
  );

  return NextResponse.json({
    redirectUrl: connectionRequest.redirectUrl,
    connectionId: connectionRequest.id,
  });

```

### 2. Checking connection status

After initiating a connection, we need to wait for the OAuth flow to complete. We check the connection status to know when it's ready to use:

  <img src="../../../../assets/images/examples/connection-status.png" />

```typescript app/api/connections/status/route.ts
// @noErrors
export async function GET(request: Request) {
  // ... auth and validation ...

  const connectionId = searchParams.get('connectionId');

  // Wait for connection to complete
  const connection = await composio.connectedAccounts.waitForConnection(connectionId);

  return NextResponse.json({
    id: connection.id,
    status: connection.status,
    authConfig: connection.authConfig,
    data: connection.data,
  });

```

### 3. Deleting a connection

When a user wants to disconnect their account, we remove the connection using the connection ID:

```typescript app/api/connections/delete/route.ts
// @noErrors
export async function DELETE(request: Request) {
  // ... auth and validation ...

  const connectionId = searchParams.get('connectionId');

  // Delete the connection
  await composio.connectedAccounts.delete(connectionId);

  return NextResponse.json({
    success: true,
    message: 'Connection deleted successfully',
  });

```

## Working with tools

Once users have connected their accounts, we need to track which toolkits are enabled and fetch the corresponding tools for the LLM.

### 1. Tracking enabled toolkits

We keep track of which toolkits the user has enabled in the chat interface:

```typescript components/chat.tsx
// @noErrors
const { ... } = useChat({
    // ... other config ...
    experimental_prepareRequestBody: (body) => {
      // Get current toolbar state
      const currentToolbarState = toolbarStateRef.current;
      const enabledToolkits = Array.from(
        currentToolbarState.enabledToolkitsWithStatus.entries(),
      ).map(([slug, isConnected]) => ({ slug, isConnected }));

      return {
        // ... other fields ...
        enabledToolkits,
      };
    },
    // ... other handlers ...
  });
```

### 2. Fetching tools for enabled toolkits

We fetch Composio tools based on the enabled toolkit slugs:

```typescript lib/ai/tools/composio.ts
// @noErrors
export async function getComposioTools(userId: string, toolkitSlugs: string[]) {
  // ... validation ...

  const tools = await composio.tools.get(userId, {
    toolkits: toolkitSlugs,
  });
  return tools || {};

```

```typescript app/api/chat.ts
// @noErrors
export async function POST(request: Request) {
  // ... auth and parsing ...

  const toolkitSlugs = enabledToolkits?.map(t => t.slug) || [];

  const composioTools = await getComposioTools(session.user.id, toolkitSlugs);

  const result = streamText({
    // ... model config ...
    tools: {
      ...composioTools,
    },
  });

```

## Bonus: Creating custom component to show tool calls

By default, tool calls appear as raw JSON in the chat interface. To create a better user experience, we can build custom components that display tool calls with proper formatting and loading states.

  <img src="../../../../assets/images/examples/custom-tool-component.png" />

You can find the `ToolCall` component at `components/tool-call.tsx`. Here's how to integrate it into your message rendering:

```typescript components/messages.tsx
// @noErrors
if (type === 'tool-invocation') {
  const { toolInvocation } = part;
  const { toolName, toolCallId, state, args, result } = toolInvocation;

  if (state === 'call') {
    return (
      
    );

  if (state === 'result') {
    return (
      
    );

```