Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Fix tool router types from latest API changes (#2227)

Musthaq Ahamadf0e67c435cda
diff --git a/.changeset/shaggy-zoos-give.md b/.changeset/shaggy-zoos-give.md
new file mode 100644
index 000000000..b902b4aef
--- /dev/null
+++ b/.changeset/shaggy-zoos-give.md
@@ -0,0 +1,5 @@
+---
+'@composio/core': patch
+---
+
+Update API client and tool router types
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 5e448f2b4..9326f50ae 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -13,8 +13,8 @@ catalogs:
specifier: ^4.20250917.0
version: 4.20251126.0
'@composio/client':
- specifier: 0.1.0-alpha.46
- version: 0.1.0-alpha.46
+ specifier: 0.1.0-alpha.47
+ version: 0.1.0-alpha.47
'@modelcontextprotocol/sdk':
specifier: ^1.22.0
version: 1.23.0
@@ -774,7 +774,7 @@ importers:
version: 1.0.0-alpha.1
'@composio/client':
specifier: 'catalog:'
- version: 0.1.0-alpha.46
+ version: 0.1.0-alpha.47
'@composio/core':
specifier: workspace:*
version: link:../core
@@ -868,7 +868,7 @@ importers:
dependencies:
'@composio/client':
specifier: 'catalog:'
- version: 0.1.0-alpha.46
+ version: 0.1.0-alpha.47
'@composio/json-schema-to-zod':
specifier: workspace:*
version: link:../json-schema-to-zod
@@ -1536,8 +1536,8 @@ packages:
'@cloudflare/[email protected]':
resolution: {integrity: sha512-DSeI1Q7JYmh5/D/tw5eZCjrKY34v69rwj63hHt60nSQW5QLwWCbj/lLtNz9f2EPa+JCACwpLXHgCXfzJ29x66w==}
- '@composio/[email protected]':
- resolution: {integrity: sha512-lhVAf3p2yqjmRfhBsZ+2l7znTPXmcmfD7liZA9a7h9w9qbk5g9D+yn1OhVuc3pnih1W+ahF2uPiFflCRhXfXSw==}
+ '@composio/[email protected]':
+ resolution: {integrity: sha512-ggrfbsDrntwBhRn+kncKluISKys9lePNQsJLGS6j/mfH4RBFjtDT4almw3N9vnOwJb0q4OIb/hrmAxZvwsc0Iw==}
'@composio/[email protected]':
resolution: {integrity: sha512-IpbfST0SSs/CEv+PIf6+EL0feNuJhQyUrOHJLPge8NhyLLrCyVqvujRIPyRUUjy0NDsked/Mm5VpJmYM6OACbg==}
@@ -7691,7 +7691,7 @@ snapshots:
'@cloudflare/[email protected]': {}
- '@composio/[email protected]': {}
+ '@composio/[email protected]': {}
'@composio/[email protected]': {}
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index eb3ad20c3..a55a7f1df 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -15,7 +15,7 @@ packages:
catalog:
'@cloudflare/vitest-pool-workers': ^0.9.2
'@cloudflare/workers-types': ^4.20250917.0
- '@composio/client': 0.1.0-alpha.46
+ '@composio/client': 0.1.0-alpha.47
'@modelcontextprotocol/sdk': ^1.22.0
ai: 5.0.52
openai: ^5.20.3
diff --git a/python/composio/core/models/tool_router.py b/python/composio/core/models/tool_router.py
index 808bff0cf..dc8742961 100644
--- a/python/composio/core/models/tool_router.py
+++ b/python/composio/core/models/tool_router.py
@@ -9,6 +9,7 @@ from __future__ import annotations
import typing as t
from dataclasses import dataclass
+from enum import Enum
from composio_client import omit
import typing_extensions as te
@@ -22,8 +23,13 @@ if t.TYPE_CHECKING:
from composio.core.models._modifiers import Modifiers
# Type aliases
-AuthorizeFn = t.Callable[[str, t.Optional[t.Dict[str, str]]], ConnectionRequest]
-ToolkitsFn = t.Callable[[t.Optional[t.Dict[str, t.Any]]], "ToolkitConnectionsDetails"]
+AuthorizeFn = t.Callable[..., ConnectionRequest]
+
+
+ToolkitsFn = t.Callable[
+ ...,
+ "ToolkitConnectionsDetails",
+]
class ToolRouterToolkitsEnabledConfig(te.TypedDict, total=False):
@@ -132,13 +138,13 @@ class ToolRouterManageConnectionsConfig(te.TypedDict, total=False):
Attributes:
enabled: Whether to use tools to manage connections. Defaults to True.
If False, you need to manage connections manually.
- callback_uri: Optional callback URI to use for OAuth redirects.
+ callback_uri: Optional callback URL to use for OAuth redirects.
infer_scopes_from_tools: Whether to infer scopes from tools in the tool router session.
Defaults to False.
"""
enabled: bool
- callback_uri: str
+ callback_url: str
infer_scopes_from_tools: bool
@@ -200,7 +206,7 @@ class ToolkitConnectionState:
slug: str
name: str
is_no_auth: bool
- connection: ToolkitConnection
+ connection: t.Optional[ToolkitConnection] = None
logo: t.Optional[str] = None
@@ -219,12 +225,26 @@ class ToolkitConnectionsDetails:
next_cursor: t.Optional[str] = None
+class ToolRouterMCPServerType(str, Enum):
+ """Enum for MCP server types."""
+
+ HTTP = "http"
+ SSE = "sse"
+
+
@dataclass
class ToolRouterMCPServerConfig:
- """Configuration for MCP server."""
+ """Configuration for MCP server.
+
+ Attributes:
+ type: The type of MCP server (HTTP or SSE)
+ url: The URL of the MCP server
+ headers: Optional authentication headers (includes x-api-key)
+ """
- type: str
+ type: ToolRouterMCPServerType
url: str
+ headers: t.Optional[t.Dict[str, t.Optional[str]]] = None
@dataclass
@@ -289,6 +309,26 @@ class ToolRouter(Resource, t.Generic[TProvider]):
super().__init__(client)
self._provider = provider
+ def _create_mcp_server_config(
+ self,
+ mcp_type: ToolRouterMCPServerType,
+ url: str,
+ ) -> ToolRouterMCPServerConfig:
+ """
+ Create an MCP server config object with authentication headers.
+
+ :param mcp_type: The type of MCP server (HTTP or SSE)
+ :param url: The URL of the MCP server
+ :return: MCP server config with headers
+ """
+ return ToolRouterMCPServerConfig(
+ type=mcp_type,
+ url=url,
+ headers={
+ "x-api-key": self._client.api_key,
+ },
+ )
+
def _create_authorize_fn(self, session_id: str) -> AuthorizeFn:
"""
Create an authorization function for the session.
@@ -299,18 +339,44 @@ class ToolRouter(Resource, t.Generic[TProvider]):
def authorize_fn(
toolkit: str,
- options: t.Optional[t.Dict[str, str]] = None,
+ *,
+ callback_url: t.Optional[str] = None,
) -> ConnectionRequest:
"""
- Authorize a toolkit for the user.
+ Authorize a toolkit for the user and get a connection request.
+
+ This method initiates the OAuth flow for a toolkit and returns a
+ ConnectionRequest object containing the redirect URL for user authorization.
+
+ Args:
+ toolkit: The toolkit slug to authorize (e.g., 'github', 'slack', 'gmail')
+ callback_url: Optional URL to redirect user after OAuth authorization completes.
+ Use this to redirect users back to your application after they authorize.
+
+ Returns:
+ ConnectionRequest: Object containing:
+ - id: The connected account ID
+ - redirect_url: URL to redirect user for OAuth authorization
+ - status: Connection status ('INITIATED')
+ - wait_for_connection(): Method to poll until connection is active
+
+ Example:
+ ```python
+ # Basic authorization
+ connection = session.authorize('github')
+ print(f"Redirect user to: {connection.redirect_url}")
+
+ # With custom callback URL
+ connection = session.authorize(
+ 'slack',
+ callback_url='https://myapp.com/oauth/callback'
+ )
- :param toolkit: The toolkit to authorize
- :param options: Optional options dict with 'callback_url' key for OAuth redirect
- :return: Connection request object
+ # Wait for user to complete authorization
+ connected_account = connection.wait_for_connection(timeout=300)
+ print(f"Connected! Account ID: {connected_account.id}")
+ ```
"""
- # Make API call to create authorization link
- callback_url = options.get("callback_url") if options else None
-
response = self._client.tool_router.session.link(
session_id=session_id,
toolkit=toolkit,
@@ -336,20 +402,78 @@ class ToolRouter(Resource, t.Generic[TProvider]):
"""
def toolkits_fn(
- options: t.Optional[t.Dict[str, t.Any]] = None,
+ *,
+ toolkits: t.Optional[t.List[str]] = None,
+ next_cursor: t.Optional[str] = None,
+ limit: t.Optional[int] = None,
+ is_connected: t.Optional[bool] = None,
) -> ToolkitConnectionsDetails:
"""
Get toolkit connection states for the session.
- :param options: Optional dict with 'next_cursor' and 'limit' keys
- :return: Toolkit connections details with items, next_cursor, and total_pages
+ Retrieves information about toolkits available in this session, including
+ their connection status, auth configuration, and metadata.
+
+ Args:
+ toolkits: List of toolkit slugs to filter by (e.g., ['github', 'slack']).
+ If None, returns all toolkits in the session.
+ next_cursor: Cursor for pagination to fetch the next page of results.
+ Use the `next_cursor` from a previous response to get more results.
+ limit: Maximum number of toolkit items to return per page.
+ is_connected: Filter by connection status:
+ - True: Only return toolkits with active connections
+ - False: Only return toolkits without active connections
+ - None: Return all toolkits regardless of connection status
+
+ Returns:
+ ToolkitConnectionsDetails: Object containing:
+ - items: List of ToolkitConnectionState objects with:
+ - slug: Toolkit identifier (e.g., 'github')
+ - name: Display name (e.g., 'GitHub')
+ - logo: URL to toolkit logo
+ - is_no_auth: Whether toolkit requires no authentication
+ - connection: Connection details (is_active, auth_config, connected_account)
+ - next_cursor: Cursor for fetching next page (None if no more pages)
+ - total_pages: Total number of pages available
+
+ Example:
+ ```python
+ # Get all toolkits in the session
+ result = session.toolkits()
+ for toolkit in result.items:
+ status = "Connected" if toolkit.connection.is_active else "Not connected"
+ print(f"{toolkit.name}: {status}")
+
+ # Filter by specific toolkits
+ result = session.toolkits(toolkits=['github', 'slack', 'gmail'])
+
+ # Get only connected toolkits
+ connected = session.toolkits(is_connected=True)
+ print(f"You have {len(connected.items)} connected toolkits")
+
+ # Get only disconnected toolkits (need authorization)
+ disconnected = session.toolkits(is_connected=False)
+ for toolkit in disconnected.items:
+ print(f"Please connect: {toolkit.name}")
+
+ # Pagination example
+ result = session.toolkits(limit=10)
+ all_toolkits = list(result.items)
+ while result.next_cursor:
+ result = session.toolkits(limit=10, next_cursor=result.next_cursor)
+ all_toolkits.extend(result.items)
+ ```
"""
- options = options or {}
toolkits_params: t.Dict[str, t.Any] = {}
- if "next_cursor" in options and options["next_cursor"]:
- toolkits_params["cursor"] = options["next_cursor"]
- if "limit" in options and options["limit"]:
- toolkits_params["limit"] = options["limit"]
+
+ if next_cursor is not None:
+ toolkits_params["cursor"] = next_cursor
+ if limit is not None:
+ toolkits_params["limit"] = limit
+ if toolkits is not None:
+ toolkits_params["toolkits"] = toolkits
+ if is_connected is not None:
+ toolkits_params["is_connected"] = is_connected
result = self._client.tool_router.session.toolkits(
session_id=session_id,
@@ -375,21 +499,25 @@ class ToolRouter(Resource, t.Generic[TProvider]):
status=connected_account.status,
)
- connection = ToolkitConnection(
- is_active=(
- connected_account.status == "ACTIVE"
- if connected_account
- else False
- ),
- auth_config=auth_config,
- connected_account=connected_acc,
+ connection = (
+ None
+ if item.is_no_auth
+ else ToolkitConnection(
+ is_active=(
+ connected_account.status == "ACTIVE"
+ if connected_account
+ else False
+ ),
+ auth_config=auth_config,
+ connected_account=connected_acc,
+ )
)
toolkit_state = ToolkitConnectionState(
slug=item.slug,
name=item.name,
logo=item.meta.logo if item.meta else None,
- is_no_auth=False,
+ is_no_auth=item.is_no_auth if item.is_no_auth else False,
connection=connection,
)
toolkit_states.append(toolkit_state)
@@ -429,10 +557,58 @@ class ToolRouter(Resource, t.Generic[TProvider]):
def tools_fn(modifiers: t.Optional[Modifiers] = None) -> t.Any:
"""
- Get provider-wrapped tools for execution.
+ Get provider-wrapped tools for execution with your AI framework.
+
+ Returns tools configured for this session, wrapped in the format expected
+ by your AI provider (OpenAI, Anthropic, LangChain, etc.). The tools are
+ ready to be passed directly to your AI model for function calling.
+
+ Args:
+ modifiers: Optional execution modifiers to customize tool behavior:
+ - Custom pre/post processing hooks
+ - Schema modifications
+ - Execution callbacks
+
+ Returns:
+ Provider-wrapped tools in the format expected by your AI framework.
+ The exact type depends on the provider configured during initialization.
+
+ Example:
+ ```python
+ # Basic usage - get tools for your AI model
+ tools = session.tools()
+
+ # Use with OpenAI
+ from openai import OpenAI
+ client = OpenAI()
+
+ response = client.chat.completions.create(
+ model="gpt-4",
+ messages=[{"role": "user", "content": "Star the composio repo"}],
+ tools=tools,
+ )
+
+ # Use with Anthropic
+ from anthropic import Anthropic
+ client = Anthropic()
+
+ response = client.messages.create(
+ model="claude-3-opus-20240229",
+ messages=[{"role": "user", "content": "Send an email"}],
+ tools=tools,
+ )
- :param modifiers: Optional execution modifiers
- :return: Provider-wrapped tools
+ # With custom modifiers
+ tools = session.tools(modifiers={
+ 'pre_execute': lambda tool, args: print(f"Executing {tool}"),
+ 'post_execute': lambda tool, result: print(f"Result: {result}"),
+ })
+ ```
+
+ Note:
+ The tools returned are specific to this session and user. They include
+ only the tools enabled for this session based on the configuration
+ provided during session creation.
"""
router_tools = tools_model.get(
user_id=user_id, tools=list(tool_slugs), modifiers=modifiers
@@ -474,7 +650,7 @@ class ToolRouter(Resource, t.Generic[TProvider]):
Example: ['important'] or {'enabled': ['safe']} or {'disabled': ['dangerous']}
:param manage_connections: Whether to enable connection management tools.
- Boolean: True/False
- - Dict with keys: 'enabled', 'callback_uri', 'infer_scopes_from_tools'
+ - Dict with keys: 'enabled', 'callback_url', 'infer_scopes_from_tools'
:param auth_configs: Optional mapping of toolkit slug to auth config ID.
Example: {'github': 'ac_xxx', 'slack': 'ac_yyy'}
:param connected_accounts: Optional mapping of toolkit slug to connected account ID.
@@ -520,7 +696,7 @@ class ToolRouter(Resource, t.Generic[TProvider]):
'user_123',
manage_connections={
'enabled': True,
- 'callback_uri': 'https://example.com/callback',
+ 'callback_url': 'https://example.com/callback',
'infer_scopes_from_tools': True
}
)
@@ -606,8 +782,8 @@ class ToolRouter(Resource, t.Generic[TProvider]):
)
# Parse callback_uri
- callback_uri = (
- manage_connections.get("callback_uri")
+ callback_url = (
+ manage_connections.get("callback_url")
if isinstance(manage_connections, dict)
else omit
)
@@ -622,8 +798,8 @@ class ToolRouter(Resource, t.Generic[TProvider]):
"auto_manage_connections": auto_manage_connections,
"infer_scopes_from_tools": infer_scopes_from_tools,
}
- if callback_uri is not None and callback_uri is not omit:
- connections_config["callback_uri"] = callback_uri
+ if callback_url is not None and callback_url is not omit:
+ connections_config["callback_url"] = callback_url
create_params["connections"] = connections_config
@@ -658,8 +834,8 @@ class ToolRouter(Resource, t.Generic[TProvider]):
# Create and return the session
return ToolRouterSession(
session_id=session.session_id,
- mcp=ToolRouterMCPServerConfig(
- type=session.mcp.type.upper(),
+ mcp=self._create_mcp_server_config(
+ mcp_type=ToolRouterMCPServerType(session.mcp.type.lower()),
url=session.mcp.url,
),
tools=self._create_tools_fn(user_id, session.tool_router_tools),
@@ -699,8 +875,8 @@ class ToolRouter(Resource, t.Generic[TProvider]):
# Create and return the session
return ToolRouterSession(
session_id=session.session_id,
- mcp=ToolRouterMCPServerConfig(
- type=session.mcp.type.upper(),
+ mcp=self._create_mcp_server_config(
+ mcp_type=ToolRouterMCPServerType(session.mcp.type.lower()),
url=session.mcp.url,
),
tools=self._create_tools_fn(user_id, session.tool_router_tools),
@@ -724,4 +900,5 @@ __all__ = [
"ToolkitConnectionState",
"ToolkitConnectionsDetails",
"ToolRouterMCPServerConfig",
+ "ToolRouterMCPServerType",
]
diff --git a/python/docs/tool-router.md b/python/docs/tool-router.md
new file mode 100644
index 000000000..e1b6bb566
--- /dev/null
+++ b/python/docs/tool-router.md
@@ -0,0 +1,647 @@
+# Tool Router
+
+The Tool Router provides a powerful way to create isolated MCP (Model Context Protocol) sessions for users with scoped access to toolkits and tools. It enables dynamic configuration of which tools are available within a session and manages authentication for multiple toolkits.
+
+## Overview
+
+Tool Router allows you to:
+
+- Create isolated sessions with specific toolkit configurations
+- Manage authentication flows for users across multiple toolkits
+- Access tools via an MCP-compatible server URL
+- Query toolkit connection states
+- Integrate with multiple AI frameworks (OpenAI, Anthropic, LangChain, LlamaIndex, CrewAI)
+
+> **Note:** When using MCP clients to connect to Tool Router, you don't need to pass a provider to the Composio constructor. A provider is only required when using `session.tools()` to get framework-specific tool objects.
+
+## Installation
+
+```bash
+pip install composio
+```
+
+## Quick Start
+
+### Using MCP (Recommended)
+
+When using Tool Router with MCP clients, you don't need to pass a provider:
+
+```python
+from composio import Composio
+
+composio = Composio()
+
+# Create a session for a user with access to Gmail tools
+session = composio.tool_router.create(
+ user_id='user_123',
+ toolkits=['gmail']
+)
+
+# Use the MCP URL with any MCP-compatible client
+print(session.mcp.url)
+```
+
+### Using Framework-Specific Tools
+
+If you want to use `session.tools()` to get tools formatted for a specific AI framework, pass the appropriate provider:
+
+```python
+from composio import Composio
+from composio_openai import OpenAIProvider
+
+composio = Composio(provider=OpenAIProvider())
+
+# Create a session for a user with access to Gmail tools
+session = composio.tool_router.create(
+ user_id='user_123',
+ toolkits=['gmail']
+)
+
+# Get the tools formatted for OpenAI
+tools = session.tools()
+```
+
+## Creating Sessions
+
+### Basic Session Creation
+
+Use `composio.tool_router.create()` to create a new Tool Router session:
+
+```python
+from composio import Composio
+
+composio = Composio()
+
+# Create a session with Gmail access
+session = composio.tool_router.create(
+ user_id='user_123',
+ toolkits=['gmail']
+)
+
+print(f"Session ID: {session.session_id}")
+print(f"MCP URL: {session.mcp.url}")
+```
+
+### Using an Existing Session
+
+If you have an existing session ID, you can retrieve it using `composio.tool_router.use()`:
+
+```python
+session = composio.tool_router.use('existing_session_id')
+
+# Access session properties
+print(session.session_id)
+print(session.mcp.url)
+```
+
+## Configuration Options
+
+The session creation accepts the following configuration options:
+
+### `toolkits`
+
+Specify which toolkits to enable or disable in the session.
+
+```python
+# Simple list of toolkit slugs to enable
+session = composio.tool_router.create(
+ user_id='user_123',
+ toolkits=['gmail', 'slack', 'github']
+)
+
+# Explicit enabled configuration
+session = composio.tool_router.create(
+ user_id='user_123',
+ toolkits={'enabled': ['gmail', 'slack']}
+)
+
+# Disable specific toolkits (enable all others)
+session = composio.tool_router.create(
+ user_id='user_123',
+ toolkits={'disabled': ['calendar']}
+)
+```
+
+### `tools`
+
+Fine-grained control over which tools are available within toolkits.
+
+```python
+session = composio.tool_router.create(
+ user_id='user_123',
+ toolkits=['gmail'],
+ tools={
+ # Override tools per toolkit
+ 'overrides': {
+ 'gmail': ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL'], # Only these tools
+ # OR use enabled/disabled dicts
+ # 'gmail': {'enabled': ['GMAIL_FETCH_EMAILS']}
+ # 'gmail': {'disabled': ['GMAIL_DELETE_EMAIL']}
+ },
+ # Filter by tags
+ 'tags': ['email', 'messaging']
+ # OR use enabled/disabled
+ # 'tags': {'enabled': ['email']}
+ # 'tags': {'disabled': ['destructive']}
+ }
+)
+```
+
+### `auth_configs`
+
+Map toolkits to specific authentication configurations:
+
+```python
+session = composio.tool_router.create(
+ user_id='user_123',
+ toolkits=['gmail', 'github'],
+ auth_configs={
+ 'gmail': 'ac_gmail_work',
+ 'github': 'ac_github_personal'
+ }
+)
+```
+
+### `connected_accounts`
+
+Map toolkits to specific connected account IDs:
+
+```python
+session = composio.tool_router.create(
+ user_id='user_123',
+ toolkits=['gmail'],
+ connected_accounts={
+ 'gmail': 'ca_abc123'
+ }
+)
+```
+
+### `manage_connections`
+
+Control how connections are managed within the session:
+
+```python
+# Boolean: enable/disable automatic connection management
+session = composio.tool_router.create(
+ user_id='user_123',
+ toolkits=['gmail'],
+ manage_connections=True # default
+)
+
+# Dict: fine-grained control
+session = composio.tool_router.create(
+ user_id='user_123',
+ toolkits=['gmail'],
+ manage_connections={
+ 'enabled': True,
+ 'callback_url': 'https://your-app.com/auth/callback',
+ 'infer_scopes_from_tools': True # Infer OAuth scopes from allowed tools
+ }
+)
+```
+
+### `execution`
+
+Configure tool execution behavior:
+
+```python
+session = composio.tool_router.create(
+ user_id='user_123',
+ toolkits=['gmail'],
+ execution={
+ 'proxy_execution_enabled': True,
+ 'timeout_seconds': 30
+ }
+)
+```
+
+## Session Properties and Methods
+
+A Tool Router session provides the following properties and methods:
+
+### `session_id`
+
+The unique identifier for this session.
+
+```python
+print(session.session_id)
+```
+
+### `mcp`
+
+The MCP server configuration for this session, including authentication headers.
+
+```python
+print(session.mcp.url) # The URL to connect to
+print(session.mcp.type) # ToolRouterMCPServerType.HTTP or ToolRouterMCPServerType.SSE
+print(session.mcp.headers) # Authentication headers (includes x-api-key)
+```
+
+### `tools(modifiers=None)`
+
+Retrieve the tools available in the session, formatted for your AI framework.
+
+```python
+# Basic usage
+tools = session.tools()
+
+# With modifiers
+tools = session.tools(modifiers={
+ 'pre_execute': lambda tool, args: print(f"Executing {tool}"),
+ 'post_execute': lambda tool, result: print(f"Result: {result}"),
+})
+```
+
+### `authorize(toolkit, *, callback_url=None)`
+
+Initiate an authorization flow for a toolkit.
+
+```python
+# Start authorization for Gmail
+connection_request = session.authorize('gmail')
+
+print(connection_request.redirect_url) # URL to redirect user for auth
+
+# Wait for the user to complete authorization
+connected_account = connection_request.wait_for_connection()
+print(f"Connected: {connected_account}")
+
+# With custom callback URL
+connection_request = session.authorize(
+ 'gmail',
+ callback_url='https://your-app.com/auth/callback'
+)
+```
+
+### `toolkits(...)`
+
+Query the connection state of toolkits in the session.
+
+```python
+# Get all toolkits
+result = session.toolkits()
+
+for toolkit in result.items:
+ print(f"{toolkit.name} ({toolkit.slug})")
+ if toolkit.connection:
+ print(f" Connected: {toolkit.connection.is_active}")
+ if toolkit.connection.connected_account:
+ print(f" Account ID: {toolkit.connection.connected_account.id}")
+ print(f" Status: {toolkit.connection.connected_account.status}")
+
+# With pagination
+result = session.toolkits(limit=10, next_cursor='cursor_abc')
+
+# Filter by specific toolkits
+result = session.toolkits(toolkits=['gmail', 'slack'])
+
+# Filter by connection status
+connected_toolkits = session.toolkits(is_connected=True)
+disconnected_toolkits = session.toolkits(is_connected=False)
+
+# Combine all options
+result = session.toolkits(
+ toolkits=['gmail', 'github'],
+ limit=5,
+ is_connected=True
+)
+```
+
+## Framework Integrations
+
+### OpenAI
+
+```python
+from openai import OpenAI
+from composio import Composio
+from composio_openai import OpenAIProvider
+
+composio = Composio(provider=OpenAIProvider())
+client = OpenAI()
+
+session = composio.tool_router.create(
+ user_id='user_123',
+ toolkits=['gmail']
+)
+
+tools = session.tools()
+
+response = client.chat.completions.create(
+ model="gpt-4",
+ messages=[{"role": "user", "content": "Find my last email from gmail"}],
+ tools=tools,
+)
+
+print(response.choices[0].message)
+```
+
+### Anthropic
+
+```python
+from anthropic import Anthropic
+from composio import Composio
+from composio_anthropic import AnthropicProvider
+
+composio = Composio(provider=AnthropicProvider())
+client = Anthropic()
+
+session = composio.tool_router.create(
+ user_id='user_123',
+ toolkits=['gmail']
+)
+
+tools = session.tools()
+
+response = client.messages.create(
+ model="claude-3-opus-20240229",
+ max_tokens=1024,
+ messages=[{"role": "user", "content": "Find my last email from gmail"}],
+ tools=tools,
+)
+
+print(response.content)
+```
+
+### LangChain
+
+```python
+from langchain_openai import ChatOpenAI
+from langchain.agents import create_tool_calling_agent, AgentExecutor
+from langchain_core.prompts import ChatPromptTemplate
+from composio import Composio
+from composio_langchain import LangChainProvider
+
+composio = Composio(provider=LangChainProvider())
+
+session = composio.tool_router.create(
+ user_id='user_123',
+ toolkits=['gmail']
+)
+
+tools = session.tools()
+llm = ChatOpenAI(model="gpt-4")
+
+prompt = ChatPromptTemplate.from_messages([
+ ("system", "You are a helpful assistant."),
+ ("human", "{input}"),
+ ("placeholder", "{agent_scratchpad}"),
+])
+
+agent = create_tool_calling_agent(llm, tools, prompt)
+agent_executor = AgentExecutor(agent=agent, tools=tools)
+
+result = agent_executor.invoke({"input": "Find my last email from gmail"})
+print(result)
+```
+
+### Using MCP URL Directly
+
+You can also use the MCP URL directly with any MCP-compatible client:
+
+```python
+from composio import Composio
+
+composio = Composio()
+
+session = composio.tool_router.create(
+ user_id='user_123',
+ toolkits=['gmail'],
+ manage_connections=True
+)
+
+# Use with any MCP client
+mcp_url = session.mcp.url
+mcp_headers = session.mcp.headers # Pre-configured authentication headers
+print(f"MCP URL: {mcp_url}")
+print(f"MCP Type: {session.mcp.type}") # 'http' or 'sse'
+print(f"MCP Headers: {mcp_headers}") # {'x-api-key': 'your-api-key'}
+```
+
+## Authorization Flow
+
+When a user needs to connect a toolkit, use the `authorize()` method:
+
+```python
+from composio import Composio
+
+composio = Composio()
+
+session = composio.tool_router.create(
+ user_id='user_123',
+ toolkits=['gmail']
+)
+
+# Initiate authorization for Gmail
+connection_request = session.authorize('gmail')
+
+# Log the redirect URL for the user
+print(f"Redirect URL: {connection_request.redirect_url}")
+
+# Wait for the user to complete the authorization (with timeout)
+connected_account = connection_request.wait_for_connection(timeout=300)
+print(f"Connected Account: {connected_account}")
+```
+
+You can also provide a custom callback URL:
+
+```python
+connection_request = session.authorize(
+ 'gmail',
+ callback_url='https://your-app.com/auth/callback'
+)
+```
+
+## Querying Toolkit States
+
+Use the `toolkits()` method to check connection states:
+
+```python
+from composio import Composio
+
+composio = Composio()
+
+session = composio.tool_router.create(user_id='user_123')
+
+# Get all toolkits
+result = session.toolkits()
+
+for toolkit in result.items:
+ status = "Connected" if toolkit.connection and toolkit.connection.is_active else "Not connected"
+ print(f"{toolkit.name}: {status}")
+
+# Get only connected toolkits
+connected = session.toolkits(is_connected=True)
+print(f"You have {len(connected.items)} connected toolkits")
+
+# Get only disconnected toolkits (need authorization)
+disconnected = session.toolkits(is_connected=False)
+for toolkit in disconnected.items:
+ print(f"Please connect: {toolkit.name}")
+
+# Pagination example
+result = session.toolkits(limit=10)
+all_toolkits = list(result.items)
+while result.next_cursor:
+ result = session.toolkits(limit=10, next_cursor=result.next_cursor)
+ all_toolkits.extend(result.items)
+```
+
+The response structure:
+
+```python
+{
+ 'items': [
+ {
+ 'slug': 'gmail',
+ 'name': 'Gmail',
+ 'logo': 'https://...',
+ 'is_no_auth': False,
+ 'connection': {
+ 'is_active': True,
+ 'auth_config': {
+ 'id': 'ac_xxx',
+ 'mode': 'OAUTH2',
+ 'is_composio_managed': True
+ },
+ 'connected_account': {
+ 'id': 'ca_xxx',
+ 'status': 'ACTIVE'
+ }
+ }
+ }
+ ],
+ 'next_cursor': 'cursor_abc',
+ 'total_pages': 1
+}
+```
+
+## Best Practices
+
+1. **User Isolation**: Create separate sessions per user to ensure proper isolation of connections and tools.
+
+2. **Toolkit Selection**: Only enable toolkits that are necessary for the use case to maintain security and reduce complexity.
+
+3. **Connection Management**: Use `manage_connections=True` (default) for interactive applications where users can be prompted to connect accounts.
+
+4. **Scope Inference**: Enable `infer_scopes_from_tools` when you want OAuth scopes to be automatically derived from the tools you've enabled.
+
+5. **Session Reuse**: Store and reuse `session_id` to maintain user sessions across requests.
+
+```python
+import redis
+
+# Store session ID after creation
+session = composio.tool_router.create(user_id='user_123', toolkits=['gmail'])
+redis_client.set(f"session:user_123", session.session_id)
+
+# Retrieve existing session
+session_id = redis_client.get(f"session:user_123")
+if session_id:
+ session = composio.tool_router.use(session_id)
+```
+
+## Type Reference
+
+### ToolRouterSession
+
+```python
+@dataclass
+class ToolRouterSession:
+ session_id: str
+ mcp: ToolRouterMCPServerConfig
+ tools: Callable[[Optional[Modifiers]], Any]
+ authorize: Callable[..., ConnectionRequest]
+ toolkits: Callable[..., ToolkitConnectionsDetails]
+```
+
+### ToolRouterMCPServerConfig
+
+```python
+class ToolRouterMCPServerType(str, Enum):
+ HTTP = "http"
+ SSE = "sse"
+
+@dataclass
+class ToolRouterMCPServerConfig:
+ type: ToolRouterMCPServerType
+ url: str
+ headers: Optional[Dict[str, Optional[str]]] = None # Authentication headers (includes x-api-key)
+```
+
+### ToolkitConnectionState
+
+```python
+@dataclass
+class ToolkitConnectionState:
+ slug: str
+ name: str
+ is_no_auth: bool
+ connection: Optional[ToolkitConnection] = None
+ logo: Optional[str] = None
+
+@dataclass
+class ToolkitConnection:
+ is_active: bool
+ auth_config: Optional[ToolkitConnectionAuthConfig] = None
+ connected_account: Optional[ToolkitConnectedAccount] = None
+
+@dataclass
+class ToolkitConnectionAuthConfig:
+ id: str
+ mode: str
+ is_composio_managed: bool
+
+@dataclass
+class ToolkitConnectedAccount:
+ id: str
+ status: str
+```
+
+### ToolkitConnectionsDetails
+
+```python
+@dataclass
+class ToolkitConnectionsDetails:
+ items: List[ToolkitConnectionState]
+ total_pages: int
+ next_cursor: Optional[str] = None
+```
+
+### Configuration Types
+
+```python
+# Toolkits configuration
+toolkits: Union[
+ List[str], # ['gmail', 'slack']
+ Dict[str, List[str]] # {'enabled': [...]} or {'disabled': [...]}
+]
+
+# Tools configuration
+tools: TypedDict({
+ 'overrides': Dict[str, Union[
+ List[str], # ['TOOL_1', 'TOOL_2']
+ Dict[str, List[str]] # {'enabled': [...]} or {'disabled': [...]}
+ ]],
+ 'tags': Union[
+ List[str], # ['tag1', 'tag2']
+ Dict[str, List[str]] # {'enabled': [...]} or {'disabled': [...]}
+ ]
+})
+
+# Manage connections configuration
+manage_connections: Union[
+ bool,
+ TypedDict({
+ 'enabled': bool,
+ 'callback_url': str,
+ 'infer_scopes_from_tools': bool
+ })
+]
+
+# Execution configuration
+execution: TypedDict({
+ 'proxy_execution_enabled': bool,
+ 'timeout_seconds': int
+})
+```
+
diff --git a/python/examples/tool_router/claude_agent.py b/python/examples/tool_router/claude_agent.py
index 9fb4ed588..3ef212f28 100644
--- a/python/examples/tool_router/claude_agent.py
+++ b/python/examples/tool_router/claude_agent.py
@@ -1,7 +1,6 @@
from composio import Composio
from claude_agent_sdk import query, ClaudeAgentOptions
import asyncio
-import os
composio = Composio()
session = composio.experimental.create(
@@ -13,15 +12,7 @@ async def main():
options = ClaudeAgentOptions(
system_prompt="You are an expert Python developer",
permission_mode="bypassPermissions",
- mcp_servers={
- "composio": {
- "type": "http",
- "url": session.mcp.url,
- "headers": {
- "x-api-key": os.getenv("COMPOSIO_API_KEY"),
- },
- }
- },
+ mcp_servers={"composio": session.mcp},
)
async for message in query(
diff --git a/python/examples/tool_router/crewai_agent.py b/python/examples/tool_router/crewai_agent.py
index bd60b2311..61ce5ace3 100644
--- a/python/examples/tool_router/crewai_agent.py
+++ b/python/examples/tool_router/crewai_agent.py
@@ -1,7 +1,6 @@
from crewai import Agent, Task, Crew
from composio import Composio
from crewai.mcp import MCPServerHTTP
-import os
composio = Composio()
@@ -16,9 +15,7 @@ agent = Agent(
mcps=[
MCPServerHTTP(
url=session.mcp.url,
- headers={
- "x-api-key": os.getenv("COMPOSIO_API_KEY"),
- },
+ headers=session.mcp.headers,
)
],
)
diff --git a/python/examples/tool_router/langchain_agent.py b/python/examples/tool_router/langchain_agent.py
index 655a26bb4..894670020 100644
--- a/python/examples/tool_router/langchain_agent.py
+++ b/python/examples/tool_router/langchain_agent.py
@@ -2,7 +2,6 @@ from composio import Composio
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain.agents import create_agent
from langchain_openai.chat_models import ChatOpenAI
-import os
import asyncio
composio = Composio()
@@ -18,9 +17,7 @@ async def main():
"composio": {
"transport": "streamable_http",
"url": session.mcp.url,
- "headers": {
- "x-api-key": os.getenv("COMPOSIO_API_KEY"),
- },
+ "headers": session.mcp.headers,
}
}
)
diff --git a/python/examples/tool_router/openai_agents.py b/python/examples/tool_router/openai_agents.py
index 164d67fd2..733e63766 100644
--- a/python/examples/tool_router/openai_agents.py
+++ b/python/examples/tool_router/openai_agents.py
@@ -1,13 +1,12 @@
from composio import Composio
from agents import Agent, Runner, HostedMCPTool
-import os
composio = Composio()
session = composio.experimental.create(
user_id="user_123",
)
-print(session.mcp.url)
+print(session.mcp)
composio_mcp = HostedMCPTool(
tool_config={
@@ -15,7 +14,7 @@ composio_mcp = HostedMCPTool(
"server_label": "tool_router",
"server_url": session.mcp.url,
"require_approval": "never",
- "headers": {"x-api-key": os.getenv("COMPOSIO_API_KEY")},
+ "headers": session.mcp.headers,
}
)
diff --git a/python/examples/tool_router/tool_router_mcp.py b/python/examples/tool_router/tool_router_mcp.py
index 7ebd62cf3..3d4b39d30 100644
--- a/python/examples/tool_router/tool_router_mcp.py
+++ b/python/examples/tool_router/tool_router_mcp.py
@@ -36,9 +36,7 @@ async def main():
"server_label": "tool_router",
"server_url": session.mcp.url,
"require_approval": "never",
- "headers": {
- "x-api-key": api_key,
- },
+ "headers": session.mcp.headers,
}
)
diff --git a/python/providers/anthropic/pyproject.toml b/python/providers/anthropic/pyproject.toml
index 6817a7f42..7b2dbde2e 100644
--- a/python/providers/anthropic/pyproject.toml
+++ b/python/providers/anthropic/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-anthropic"
-version = "0.9.5-rc.1"
+version = "0.9.5-rc.2"
description = "Use Composio to get an array of tools with your Anthropic LLMs."
readme = "README.md"
requires-python = ">=3.10,<4"
diff --git a/python/providers/anthropic/setup.py b/python/providers/anthropic/setup.py
index ee9586a00..a226addf7 100644
--- a/python/providers/anthropic/setup.py
+++ b/python/providers/anthropic/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_anthropic",
- version="0.9.5-rc.1",
+ version="0.9.5-rc.2",
author="Composio",
author_email="[email protected]",
description="Use Composio to get an array of tools with your Anthropic LLMs.",
diff --git a/python/providers/autogen/pyproject.toml b/python/providers/autogen/pyproject.toml
index 3778f7943..59d810051 100644
--- a/python/providers/autogen/pyproject.toml
+++ b/python/providers/autogen/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-autogen"
-version = "0.9.5-rc.1"
+version = "0.9.5-rc.2"
description = "Use Composio to get an array of tools with your autogen agent."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/autogen/setup.py b/python/providers/autogen/setup.py
index 1b2a6f6c5..b573d4bb7 100644
--- a/python/providers/autogen/setup.py
+++ b/python/providers/autogen/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_autogen",
- version="0.9.5-rc.1",
+ version="0.9.5-rc.2",
author="Composio",
author_email="[email protected]",
description="Use Composio to get an array of tools with your Autogen agent.",
diff --git a/python/providers/crewai/pyproject.toml b/python/providers/crewai/pyproject.toml
index df9006c65..ee1c2c620 100644
--- a/python/providers/crewai/pyproject.toml
+++ b/python/providers/crewai/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-crewai"
-version = "0.9.5-rc.1"
+version = "0.9.5-rc.2"
description = "Use Composio to get an array of tools with your CrewAI agent."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/crewai/setup.py b/python/providers/crewai/setup.py
index a3dc0035c..95a9ede7a 100644
--- a/python/providers/crewai/setup.py
+++ b/python/providers/crewai/setup.py
@@ -6,7 +6,7 @@ from setuptools import setup
setup(
name="composio_crewai",
- version="0.9.5-rc.1",
+ version="0.9.5-rc.2",
author="Composio",
author_email="[email protected]",
description="Use Composio to get an array of tools with your CrewAI agent.",
diff --git a/python/providers/gemini/pyproject.toml b/python/providers/gemini/pyproject.toml
index 0d1f8762c..7527c8073 100644
--- a/python/providers/gemini/pyproject.toml
+++ b/python/providers/gemini/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-gemini"
-version = "0.9.5-rc.1"
+version = "0.9.5-rc.2"
description = "Use Composio to get an array of tools with your Gemini agent."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/gemini/setup.py b/python/providers/gemini/setup.py
index d0e1d1685..ad1dc05b7 100644
--- a/python/providers/gemini/setup.py
+++ b/python/providers/gemini/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_gemini",
- version="0.9.5-rc.1",
+ version="0.9.5-rc.2",
author="Composio",
author_email="[email protected]",
description="Use Composio to get an array of tools with your Gemini agent.",
diff --git a/python/providers/google/pyproject.toml b/python/providers/google/pyproject.toml
index 60b8c6b3b..73d787348 100644
--- a/python/providers/google/pyproject.toml
+++ b/python/providers/google/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-google"
-version = "0.9.5-rc.1"
+version = "0.9.5-rc.2"
description = "Use Composio to get an array of tools with your Google AI Python Gemini model."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/google/setup.py b/python/providers/google/setup.py
index 05060706b..fac442ca1 100644
--- a/python/providers/google/setup.py
+++ b/python/providers/google/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_google",
- version="0.9.5-rc.1",
+ version="0.9.5-rc.2",
author="Composio",
author_email="[email protected]",
description="Use Composio to get an array of tools with your Google AI Python Gemini model.",
diff --git a/python/providers/google_adk/pyproject.toml b/python/providers/google_adk/pyproject.toml
index 26bba0c05..31088f481 100644
--- a/python/providers/google_adk/pyproject.toml
+++ b/python/providers/google_adk/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-google-adk"
-version = "0.9.5-rc.1"
+version = "0.9.5-rc.2"
description = "Use Composio to get an array of tools with your Google AI Python Gemini model."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/google_adk/setup.py b/python/providers/google_adk/setup.py
index c9e887cd1..aae17504b 100644
--- a/python/providers/google_adk/setup.py
+++ b/python/providers/google_adk/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_google_adk",
- version="0.9.5-rc.1",
+ version="0.9.5-rc.2",
author="Composio",
author_email="[email protected]",
description="Use Composio to get an array of tools with your Google AI Python Gemini model.",
diff --git a/python/providers/langchain/pyproject.toml b/python/providers/langchain/pyproject.toml
index c00846faa..df4384cd8 100644
--- a/python/providers/langchain/pyproject.toml
+++ b/python/providers/langchain/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-langchain"
-version = "0.9.5-rc.1"
+version = "0.9.5-rc.2"
description = "Use Composio to get an array of tools with your Langchain agent."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/langchain/setup.py b/python/providers/langchain/setup.py
index 4afdc2635..af65ffb85 100644
--- a/python/providers/langchain/setup.py
+++ b/python/providers/langchain/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_langchain",
- version="0.9.5-rc.1",
+ version="0.9.5-rc.2",
author="composio",
author_email="[email protected]",
description="Use Composio to get an array of tools with your Langchain agent.",
diff --git a/python/providers/langgraph/pyproject.toml b/python/providers/langgraph/pyproject.toml
index 4622ea5bf..5ba226997 100644
--- a/python/providers/langgraph/pyproject.toml
+++ b/python/providers/langgraph/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-langgraph"
-version = "0.9.5-rc.1"
+version = "0.9.5-rc.2"
description = "Use Composio to get array of tools with LangGraph Agent Workflows."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/langgraph/setup.py b/python/providers/langgraph/setup.py
index ef1626491..fb6bf79ff 100644
--- a/python/providers/langgraph/setup.py
+++ b/python/providers/langgraph/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_langgraph",
- version="0.9.5-rc.1",
+ version="0.9.5-rc.2",
author="composio",
author_email="[email protected]",
description="Use Composio to get array of tools with LangGraph Agent Workflows",
diff --git a/python/providers/llamaindex/pyproject.toml b/python/providers/llamaindex/pyproject.toml
index 2138818db..41d00c6c4 100644
--- a/python/providers/llamaindex/pyproject.toml
+++ b/python/providers/llamaindex/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-llamaindex"
-version = "0.9.5-rc.1"
+version = "0.9.5-rc.2"
description = "Use Composio to get array of tools with LlamaIndex Agent Workflows."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/llamaindex/setup.py b/python/providers/llamaindex/setup.py
index 834fe6888..1ad8ad2df 100644
--- a/python/providers/llamaindex/setup.py
+++ b/python/providers/llamaindex/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_llamaindex",
- version="0.9.5-rc.1",
+ version="0.9.5-rc.2",
author="composio",
author_email="[email protected]",
description="Use Composio to get array of tools with LlamaIndex Agent Workflows",
diff --git a/python/providers/openai/pyproject.toml b/python/providers/openai/pyproject.toml
index e7a28403b..3e48264bf 100644
--- a/python/providers/openai/pyproject.toml
+++ b/python/providers/openai/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-openai"
-version = "0.9.5-rc.1"
+version = "0.9.5-rc.2"
description = "Use Composio to get an array of tools with your OpenAI Function Call."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/openai/setup.py b/python/providers/openai/setup.py
index 703e7c15b..66f92d396 100644
--- a/python/providers/openai/setup.py
+++ b/python/providers/openai/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_openai",
- version="0.9.5-rc.1",
+ version="0.9.5-rc.2",
author="Composio",
author_email="[email protected]",
description="Use Composio to get an array of tools with your OpenAI Function Call.",
diff --git a/python/providers/openai_agents/pyproject.toml b/python/providers/openai_agents/pyproject.toml
index 310c6457c..729d73f51 100644
--- a/python/providers/openai_agents/pyproject.toml
+++ b/python/providers/openai_agents/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-openai-agents"
-version = "0.9.5-rc.1"
+version = "0.9.5-rc.2"
description = "Use Composio to get array of strongly typed tools for OpenAI Agents"
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/openai_agents/setup.py b/python/providers/openai_agents/setup.py
index 90b08fb4f..d4d9e4d32 100644
--- a/python/providers/openai_agents/setup.py
+++ b/python/providers/openai_agents/setup.py
@@ -8,7 +8,7 @@ from setuptools import find_packages, setup
setup(
name="composio_openai_agents",
- version="0.9.5-rc.1",
+ version="0.9.5-rc.2",
author="Composio",
author_email="[email protected]",
description="Use Composio to get array of strongly typed tools for OpenAI Agents",
diff --git a/python/pyproject.toml b/python/pyproject.toml
index 887bca2b1..5f26bd04b 100644
--- a/python/pyproject.toml
+++ b/python/pyproject.toml
@@ -1,13 +1,13 @@
[project]
name = "composio"
-version = "0.9.5-rc.1"
+version = "0.9.5-rc.2"
description = "SDK for integrating Composio with your applications."
readme = "README.md"
requires-python = ">=3.10,<4"
dependencies = [
"pysher>=1.0.8",
"pydantic>=2.6.4",
- "composio-client>=1.17.1",
+ "composio-client>=1.18.0",
"typing-extensions>=4.0.0",
"openai",
]
diff --git a/python/tests/test_tool_router.py b/python/tests/test_tool_router.py
index 97b63e96a..002479e8a 100644
--- a/python/tests/test_tool_router.py
+++ b/python/tests/test_tool_router.py
@@ -12,6 +12,7 @@ from composio.core.models.tool_router import (
ToolRouterManageConnectionsConfig,
ToolkitConnectionState,
ToolkitConnectionsDetails,
+ ToolRouterMCPServerType,
)
@@ -19,12 +20,13 @@ from composio.core.models.tool_router import (
def mock_client():
"""Create a mock HTTP client."""
client = MagicMock()
+ client.api_key = "test-api-key"
# Mock session responses
mock_session_response = MagicMock()
mock_session_response.session_id = "session_123"
mock_session_response.mcp = MagicMock()
- mock_session_response.mcp.type = "HTTP"
+ mock_session_response.mcp.type = "http"
mock_session_response.mcp.url = "https://mcp.example.com/session_123"
mock_session_response.tool_router_tools = [
"GMAIL_FETCH_EMAILS",
@@ -48,6 +50,7 @@ def mock_client():
mock_toolkit_item_active.slug = "gmail"
mock_toolkit_item_active.name = "Gmail"
mock_toolkit_item_active.meta.logo = "https://example.com/gmail-logo.png"
+ mock_toolkit_item_active.is_no_auth = False
mock_toolkit_item_active.connected_account = MagicMock()
mock_toolkit_item_active.connected_account.id = "conn_123"
mock_toolkit_item_active.connected_account.status = "ACTIVE"
@@ -60,6 +63,7 @@ def mock_client():
mock_toolkit_item_inactive.slug = "github"
mock_toolkit_item_inactive.name = "GitHub"
mock_toolkit_item_inactive.meta.logo = "https://example.com/github-logo.png"
+ mock_toolkit_item_inactive.is_no_auth = False
mock_toolkit_item_inactive.connected_account = None
mock_toolkits_response = MagicMock()
@@ -101,8 +105,9 @@ class TestToolRouter:
# Verify session properties
assert session.session_id == "session_123"
- assert session.mcp.type == "HTTP"
+ assert session.mcp.type == ToolRouterMCPServerType.HTTP
assert session.mcp.url == "https://mcp.example.com/session_123"
+ assert session.mcp.headers == {"x-api-key": "test-api-key"}
assert callable(session.tools)
assert callable(session.authorize)
assert callable(session.toolkits)
@@ -223,7 +228,7 @@ class TestToolRouter:
user_id="user_123",
manage_connections={
"enabled": True,
- "callback_uri": "https://example.com/callback",
+ "callback_url": "https://example.com/callback",
"infer_scopes_from_tools": True,
},
)
@@ -233,7 +238,7 @@ class TestToolRouter:
call_args = mock_client.tool_router.session.create.call_args
kwargs = call_args.kwargs
assert kwargs["connections"]["auto_manage_connections"] is True
- assert kwargs["connections"]["callback_uri"] == "https://example.com/callback"
+ assert kwargs["connections"]["callback_url"] == "https://example.com/callback"
assert kwargs["connections"]["infer_scopes_from_tools"] is True
def test_create_session_with_auth_configs(self, tool_router, mock_client):
@@ -297,7 +302,7 @@ class TestToolRouter:
)
assert session.session_id == "session_123"
- assert session.mcp.type == "HTTP"
+ assert session.mcp.type == ToolRouterMCPServerType.HTTP
# Verify all parameters were passed correctly
call_args = mock_client.tool_router.session.create.call_args
@@ -324,8 +329,9 @@ class TestToolRouter:
# Verify session properties
assert session.session_id == "session_123"
- assert session.mcp.type == "HTTP"
+ assert session.mcp.type == ToolRouterMCPServerType.HTTP
assert session.mcp.url == "https://mcp.example.com/session_123"
+ assert session.mcp.headers == {"x-api-key": "test-api-key"}
assert callable(session.tools)
assert callable(session.authorize)
assert callable(session.toolkits)
@@ -338,7 +344,7 @@ class TestToolRouter:
mock_retrieve_response = MagicMock()
mock_retrieve_response.session_id = "session_456"
mock_retrieve_response.mcp = MagicMock()
- mock_retrieve_response.mcp.type = "HTTP"
+ mock_retrieve_response.mcp.type = "http"
mock_retrieve_response.mcp.url = "https://mcp.example.com/session_456"
mock_retrieve_response.tool_router_tools = ["TOOL_1"]
mock_retrieve_response.config = MagicMock()
@@ -349,7 +355,7 @@ class TestToolRouter:
session = tool_router.use(session_id="session_456")
assert session.session_id == "session_456"
- assert session.mcp.type == "HTTP"
+ assert session.mcp.type == ToolRouterMCPServerType.HTTP
def test_use_session_throws_error_on_failure(self, tool_router, mock_client):
"""Test that use() throws error if retrieve fails."""
@@ -376,9 +382,7 @@ class TestToolRouter:
"""Test the authorize function with callback URL."""
session = tool_router.create(user_id="user_123")
- session.authorize(
- "github", options={"callback_url": "https://myapp.com/callback"}
- )
+ session.authorize("github", callback_url="https://myapp.com/callback")
# Verify link was called with callback_url
call_args = mock_client.tool_router.session.link.call_args
@@ -405,7 +409,7 @@ class TestToolRouter:
"""Test the toolkits function with pagination options."""
session = tool_router.create(user_id="user_123")
- session.toolkits(options={"next_cursor": "cursor_abc", "limit": 10})
+ session.toolkits(next_cursor="cursor_abc", limit=10)
# Verify toolkits was called with pagination params
call_args = mock_client.tool_router.session.toolkits.call_args
@@ -487,18 +491,19 @@ class TestToolRouter:
call_args = mock_tools_instance.get.call_args
assert call_args.kwargs.get("modifiers") == modifiers
- def test_session_mcp_type_uppercase(self, tool_router, mock_client):
- """Test that MCP type is uppercase."""
+ def test_session_mcp_type_http(self, tool_router, mock_client):
+ """Test that MCP type is correctly set to HTTP enum."""
session = tool_router.create(user_id="user_123")
- assert session.mcp.type == "HTTP"
+ assert session.mcp.type == ToolRouterMCPServerType.HTTP
+ assert session.mcp.type.value == "http"
def test_session_mcp_sse_type(self, tool_router, mock_client):
"""Test that SSE MCP type is handled correctly."""
mock_sse_response = MagicMock()
mock_sse_response.session_id = "session_sse"
mock_sse_response.mcp = MagicMock()
- mock_sse_response.mcp.type = "SSE"
+ mock_sse_response.mcp.type = "sse"
mock_sse_response.mcp.url = "https://mcp.example.com/sse/session_sse"
mock_sse_response.tool_router_tools = ["TOOL_1"]
@@ -506,7 +511,8 @@ class TestToolRouter:
session = tool_router.create(user_id="user_123")
- assert session.mcp.type == "SSE"
+ assert session.mcp.type == ToolRouterMCPServerType.SSE
+ assert session.mcp.type.value == "sse"
assert session.mcp.url == "https://mcp.example.com/sse/session_sse"
def test_multiple_sessions_independently(self, tool_router, mock_client):
@@ -514,14 +520,14 @@ class TestToolRouter:
mock_session_1 = MagicMock()
mock_session_1.session_id = "session_1"
mock_session_1.mcp = MagicMock()
- mock_session_1.mcp.type = "HTTP"
+ mock_session_1.mcp.type = "http"
mock_session_1.mcp.url = "https://mcp.example.com/session_1"
mock_session_1.tool_router_tools = ["TOOL_1"]
mock_session_2 = MagicMock()
mock_session_2.session_id = "session_2"
mock_session_2.mcp = MagicMock()
- mock_session_2.mcp.type = "HTTP"
+ mock_session_2.mcp.type = "http"
mock_session_2.mcp.url = "https://mcp.example.com/session_2"
mock_session_2.tool_router_tools = ["TOOL_2"]
@@ -543,14 +549,14 @@ class TestToolRouter:
mock_create_response = MagicMock()
mock_create_response.session_id = "created_session"
mock_create_response.mcp = MagicMock()
- mock_create_response.mcp.type = "HTTP"
+ mock_create_response.mcp.type = "http"
mock_create_response.mcp.url = "https://mcp.example.com/created"
mock_create_response.tool_router_tools = ["TOOL_1"]
mock_retrieve_response = MagicMock()
mock_retrieve_response.session_id = "retrieved_session"
mock_retrieve_response.mcp = MagicMock()
- mock_retrieve_response.mcp.type = "HTTP"
+ mock_retrieve_response.mcp.type = "http"
mock_retrieve_response.mcp.url = "https://mcp.example.com/retrieved"
mock_retrieve_response.tool_router_tools = ["TOOL_2"]
mock_retrieve_response.config = MagicMock()
@@ -590,16 +596,31 @@ class TestToolRouterTypes:
"""Test ToolRouterManageConnectionsConfig type."""
config: ToolRouterManageConnectionsConfig = {
"enabled": True,
- "callback_uri": "https://example.com/callback",
+ "callback_url": "https://example.com/callback",
}
assert config["enabled"] is True
- assert config["callback_uri"] == "https://example.com/callback"
+ assert config["callback_url"] == "https://example.com/callback"
def test_mcp_server_config(self):
"""Test ToolRouterMCPServerConfig dataclass."""
- mcp = ToolRouterMCPServerConfig(type="HTTP", url="https://mcp.example.com")
- assert mcp.type == "HTTP"
+ mcp = ToolRouterMCPServerConfig(
+ type=ToolRouterMCPServerType.HTTP, url="https://mcp.example.com"
+ )
+ assert mcp.type == ToolRouterMCPServerType.HTTP
+ assert mcp.type.value == "http"
+ assert mcp.url == "https://mcp.example.com"
+ assert mcp.headers is None # Headers are optional
+
+ def test_mcp_server_config_with_headers(self):
+ """Test ToolRouterMCPServerConfig dataclass with headers."""
+ mcp = ToolRouterMCPServerConfig(
+ type=ToolRouterMCPServerType.HTTP,
+ url="https://mcp.example.com",
+ headers={"x-api-key": "test-api-key"},
+ )
+ assert mcp.type == ToolRouterMCPServerType.HTTP
assert mcp.url == "https://mcp.example.com"
+ assert mcp.headers == {"x-api-key": "test-api-key"}
def test_toolkit_connection_state(self):
"""Test ToolkitConnectionState dataclass."""
diff --git a/ts/docs/api/tool-router.md b/ts/docs/api/tool-router.md
index ec6752582..f24e32bf7 100644
--- a/ts/docs/api/tool-router.md
+++ b/ts/docs/api/tool-router.md
@@ -226,11 +226,12 @@ console.log(session.sessionId);
### `mcp`
-The MCP server configuration for this session.
+The MCP server configuration for this session, including authentication headers.
```typescript
-console.log(session.mcp.url); // The URL to connect to
-console.log(session.mcp.type); // 'HTTP' or 'SSE'
+console.log(session.mcp.url); // The URL to connect to
+console.log(session.mcp.type); // 'HTTP' or 'SSE'
+console.log(session.mcp.headers); // Authentication headers (includes x-api-key)
```
### `tools()`
@@ -354,14 +355,12 @@ const { mcp } = await composio.experimental.create('user_123', {
manageConnections: true
});
-// Create MCP client using the session URL
+// Create MCP client using the session URL and headers
const client = await createMCPClient({
transport: {
type: 'http',
url: mcp.url,
- headers: {
- 'x-api-key': process.env.COMPOSIO_API_KEY!,
- }
+ headers: mcp.headers, // Uses pre-configured authentication headers
}
});
@@ -411,9 +410,7 @@ const client = new MultiServerMCPClient({
composio: {
transport: "http",
url: session.mcp.url,
- headers: {
- 'x-api-key': process.env.COMPOSIO_API_KEY!,
- }
+ headers: session.mcp.headers, // Uses pre-configured authentication headers
},
});
@@ -454,9 +451,7 @@ console.log(`Connecting to MCP server: ${session.mcp.url}`);
const mcpTool = hostedMcpTool({
serverLabel: 'ComposioApps',
serverUrl: session.mcp.url,
- headers: {
- 'x-api-key': process.env.COMPOSIO_API_KEY!,
- }
+ headers: session.mcp.headers, // Uses pre-configured authentication headers
});
const agent = new Agent({
@@ -502,9 +497,7 @@ const stream = await query({
composio: {
type: 'http',
url: session.mcp.url,
- headers: {
- 'x-api-key': process.env.COMPOSIO_API_KEY!,
- }
+ headers: session.mcp.headers, // Uses pre-configured authentication headers
}
},
}
@@ -676,6 +669,7 @@ interface ToolRouterSession {
mcp: {
type: 'HTTP' | 'SSE';
url: string;
+ headers?: Record<string, string | undefined>; // Authentication headers (includes x-api-key)
};
tools: (modifiers?: ProviderOptions) => Promise<Tools>;
authorize: (toolkit: string, options?: { callbackUrl?: string }) => Promise<ConnectionRequest>;
diff --git a/ts/packages/core/src/models/ToolRouter.ts b/ts/packages/core/src/models/ToolRouter.ts
index abfc492a9..ec1298701 100644
--- a/ts/packages/core/src/models/ToolRouter.ts
+++ b/ts/packages/core/src/models/ToolRouter.ts
@@ -22,6 +22,10 @@ import {
ToolRouterCreateSessionConfig,
ToolRouterSession,
ToolkitConnectionStateSchema,
+ ToolRouterToolkitsOptions,
+ ToolRouterToolkitsOptionsSchema,
+ MCPServerType,
+ ToolRouterMCPServerConfig,
} from '../types/toolRouter.types';
import { ToolRouterCreateSessionConfigSchema } from '../types/toolRouter.types';
import { Tools } from './Tools';
@@ -31,7 +35,7 @@ import { createConnectionRequest } from './ConnectionRequest';
import { ConnectedAccountStatuses } from '../types/connectedAccounts.types';
import { transform } from '../utils/transform';
import { SessionCreateParams } from '@composio/client/resources/tool-router.mjs';
-import { transformToolRouterToolsParams } from '../lib/toolRouterParams';
+import { ValidationError } from '../errors';
export class ToolRouter<
TToolCollection,
@@ -88,15 +92,19 @@ export class ToolRouter<
* ```
*/
private createToolkitsFn = (sessionId: string): ToolRouterToolkitsFn => {
- const connectionsFn = async (options?: {
- toolkits?: Array<string>;
- nextCursor?: string;
- limit?: number;
- }) => {
+ const connectionsFn = async (options?: ToolRouterToolkitsOptions) => {
+ const toolkitOptions = ToolRouterToolkitsOptionsSchema.safeParse(options ?? {});
+ if (!toolkitOptions.success) {
+ throw new ValidationError('Failed to parse toolkits options', {
+ cause: toolkitOptions.error,
+ });
+ }
+
const result = await this.client.toolRouter.session.toolkits(sessionId, {
- cursor: options?.nextCursor,
- limit: options?.limit,
- toolkits: options?.toolkits,
+ cursor: toolkitOptions.data.nextCursor,
+ limit: toolkitOptions.data.limit,
+ toolkits: toolkitOptions.data.toolkits,
+ is_connected: toolkitOptions.data.isConnected,
});
const toolkitConnectedStates = result.items.map(item => {
@@ -105,22 +113,24 @@ export class ToolRouter<
.using(item => ({
slug: item.slug,
name: item.name,
- logo: item.meta.logo,
- isNoAuth: false,
- connection: {
- isActive: item.connected_account?.status === 'ACTIVE',
- authConfig: item.connected_account && {
- id: item.connected_account?.auth_config.id,
- mode: item.connected_account?.auth_config.auth_scheme,
- isComposioManaged: item.connected_account?.auth_config.is_composio_managed,
- },
- connectedAccount: item.connected_account
- ? {
- id: item.connected_account.id,
- status: item.connected_account.status,
- }
- : undefined,
- },
+ logo: item.meta?.logo,
+ isNoAuth: item.is_no_auth,
+ connection: item.is_no_auth
+ ? undefined
+ : {
+ isActive: item.connected_account?.status === 'ACTIVE',
+ authConfig: item.connected_account && {
+ id: item.connected_account?.auth_config.id,
+ mode: item.connected_account?.auth_config.auth_scheme,
+ isComposioManaged: item.connected_account?.auth_config.is_composio_managed,
+ },
+ connectedAccount: item.connected_account
+ ? {
+ id: item.connected_account.id,
+ status: item.connected_account.status,
+ }
+ : undefined,
+ },
}));
return connectedState;
});
@@ -161,6 +171,28 @@ export class ToolRouter<
};
};
+ /**
+ * Creates a MCP server config object.
+ * @param type {MCPServerType} The type of the MCP server
+ * @param url {string} The URL of the MCP server
+ * @returns {ToolRouterMCPServerConfig} The MCP server config object
+ */
+ private createMCPServerConfig = ({
+ type,
+ url,
+ }: {
+ type: MCPServerType;
+ url: string;
+ }): ToolRouterMCPServerConfig => {
+ return {
+ type,
+ url,
+ headers: {
+ 'x-api-key': this.config?.apiKey ?? undefined,
+ },
+ };
+ };
+
/**
* Creates a new tool router session for a user.
*
@@ -216,9 +248,9 @@ export class ToolRouter<
connections: {
infer_scopes_from_tools: inferScopesFromTools,
auto_manage_connections: manageConnectedAccounts,
- callback_uri:
+ callback_url:
typeof routerConfig.manageConnections === 'object'
- ? routerConfig.manageConnections.callbackUri
+ ? routerConfig.manageConnections.callbackUrl
: undefined,
},
execution: routerConfig.execution
@@ -232,10 +264,7 @@ export class ToolRouter<
return {
sessionId: session.session_id,
- mcp: {
- type: session.mcp.type,
- url: session.mcp.url,
- },
+ mcp: this.createMCPServerConfig(session.mcp),
tools: this.createToolsFn(userId, session.tool_router_tools),
authorize: this.createAuthorizeFn(session.session_id),
toolkits: this.createToolkitsFn(session.session_id),
@@ -260,10 +289,7 @@ export class ToolRouter<
const session = await this.client.toolRouter.session.retrieve(id);
return {
sessionId: session.session_id,
- mcp: {
- type: session.mcp.type,
- url: session.mcp.url,
- },
+ mcp: this.createMCPServerConfig(session.mcp),
tools: this.createToolsFn(session.config.user_id, session.tool_router_tools),
authorize: this.createAuthorizeFn(session.session_id),
toolkits: this.createToolkitsFn(session.session_id),
diff --git a/ts/packages/core/src/types/toolRouter.types.ts b/ts/packages/core/src/types/toolRouter.types.ts
index fbbd7ee1a..64c6e3fbc 100644
--- a/ts/packages/core/src/types/toolRouter.types.ts
+++ b/ts/packages/core/src/types/toolRouter.types.ts
@@ -3,7 +3,7 @@ import { BaseComposioProvider } from '../provider/BaseProvider';
import { ExecuteToolModifiers, ProviderOptions } from './modifiers.types';
import { ConnectionRequest } from './connectionRequest.types';
-export const MCPServerTypeSchema = z.enum(['HTTP', 'SSE']);
+export const MCPServerTypeSchema = z.enum(['http', 'sse']);
export type MCPServerType = z.infer<typeof MCPServerTypeSchema>;
// manage connections
@@ -16,7 +16,7 @@ export const ToolRouterConfigManageConnectionsSchema = z
.describe(
'Whether to use tools to manage connections in the tool router session. Defaults to true, if set to false, you need to manage connections manually'
),
- callbackUri: z
+ callbackUrl: z
.string()
.optional()
.describe('The callback uri to use in the tool router session'),
@@ -207,7 +207,7 @@ export const ToolRouterCreateSessionConfigSchema = z
* @param {Record<string, string>} connectedAccounts - The connected accounts to use in the tool router session
* @param {ToolRouterConfigManageConnectionsSchema | boolean} manageConnections - The config for the manage connections in the tool router session. Defaults to true, if set to false, you need to manage connections manually. If set to an object, you can configure the manage connections settings.
* @param {boolean} [manageConnections.enabled] - Whether to use tools to manage connections in the tool router session @default true
- * @param {string} [manageConnections.callbackUri] - The callback uri to use in the tool router session
+ * @param {string} [manageConnections.callbackUrl] - The callback uri to use in the tool router session
* @param {boolean} [manageConnections.inferScopesFromTools] - Whether to infer scopes from tools in the tool router session @default false
*/
export type ToolRouterCreateSessionConfig = z.infer<typeof ToolRouterCreateSessionConfigSchema>;
@@ -218,24 +218,29 @@ export const ToolkitConnectionStateSchema = z
name: z.string().describe('The name of a toolkit'),
logo: z.string().optional().describe('The logo of a toolkit'),
isNoAuth: z.boolean().default(false).describe('Whether the toolkit is no auth or not'),
- connection: z.object({
- isActive: z.boolean().describe('Whether the connection is active or not'),
- authConfig: z
- .object({
- id: z.string().describe('The id of the auth config'),
- mode: z.string().describe('The auth scheme used by the auth config'),
- isComposioManaged: z.boolean().describe('Whether the auth config is managed by Composio'),
- })
- .nullish()
- .describe('The auth config of a toolkit'),
- connectedAccount: z
- .object({
- id: z.string().describe('The id of the connected account'),
- status: z.string().describe('The status of the connected account'),
- })
- .optional()
- .describe('The connected account of a toolkit'),
- }),
+ connection: z
+ .object({
+ isActive: z.boolean().describe('Whether the connection is active or not'),
+ authConfig: z
+ .object({
+ id: z.string().describe('The id of the auth config'),
+ mode: z.string().describe('The auth scheme used by the auth config'),
+ isComposioManaged: z
+ .boolean()
+ .describe('Whether the auth config is managed by Composio'),
+ })
+ .nullish()
+ .describe('The auth config of a toolkit'),
+ connectedAccount: z
+ .object({
+ id: z.string().describe('The id of the connected account'),
+ status: z.string().describe('The status of the connected account'),
+ })
+ .optional()
+ .describe('The connected account of a toolkit'),
+ })
+ .optional()
+ .describe('The connection of a toolkit'),
})
.describe('The connection state of a toolkit');
@@ -248,7 +253,12 @@ export type ToolkitConnectionsDetails = z.infer<typeof ToolkitConnectionsDetails
export type ToolkitConnectionState = z.infer<typeof ToolkitConnectionStateSchema>;
-export type ToolRouterMCPServerConfig = { type: MCPServerType; url: string };
+export const ToolRouterMCPServerConfigSchema = z.object({
+ type: MCPServerTypeSchema,
+ url: z.string(),
+ headers: z.record(z.string(), z.string().optional()).optional(),
+});
+export type ToolRouterMCPServerConfig = z.infer<typeof ToolRouterMCPServerConfigSchema>;
export type ToolRouterToolsFn<
TToolCollection,
@@ -261,11 +271,17 @@ export type ToolRouterAuthorizeFn = (
options?: { callbackUrl?: string }
) => Promise<ConnectionRequest>;
-export type ToolRouterToolkitsFn = (options?: {
- toolkits?: Array<string>;
- nextCursor?: string;
- limit?: number;
-}) => Promise<ToolkitConnectionsDetails>;
+export const ToolRouterToolkitsOptionsSchema = z.object({
+ toolkits: z.array(z.string()).optional(),
+ nextCursor: z.string().optional(),
+ limit: z.number().optional(),
+ isConnected: z.boolean().optional(),
+});
+export type ToolRouterToolkitsOptions = z.infer<typeof ToolRouterToolkitsOptionsSchema>;
+
+export type ToolRouterToolkitsFn = (
+ options?: ToolRouterToolkitsOptions
+) => Promise<ToolkitConnectionsDetails>;
export interface ToolRouterSession<
TToolCollection,
TTool,
diff --git a/ts/packages/core/test/models/toolRouter.test.ts b/ts/packages/core/test/models/toolRouter.test.ts
index 5ae6db6f6..a2484374e 100644
--- a/ts/packages/core/test/models/toolRouter.test.ts
+++ b/ts/packages/core/test/models/toolRouter.test.ts
@@ -45,7 +45,7 @@ const createMockClient = () => ({
const mockSessionCreateResponse = {
session_id: 'session_123',
mcp: {
- type: 'HTTP',
+ type: 'http',
url: 'https://mcp.example.com/session_123',
},
tool_router_tools: ['GMAIL_FETCH_EMAILS', 'SLACK_SEND_MESSAGE', 'GITHUB_CREATE_ISSUE'],
@@ -59,7 +59,7 @@ const mockLinkResponse = {
const mockSessionRetrieveResponse = {
session_id: 'session_123',
mcp: {
- type: 'HTTP',
+ type: 'http',
url: 'https://mcp.example.com/session_123',
},
tool_router_tools: ['GMAIL_FETCH_EMAILS', 'SLACK_SEND_MESSAGE', 'GITHUB_CREATE_ISSUE'],
@@ -83,6 +83,7 @@ const mockToolkitsResponse = {
meta: {
logo: 'https://example.com/gmail-logo.png',
},
+ is_no_auth: false,
connected_account: {
id: 'conn_123',
status: 'ACTIVE',
@@ -99,6 +100,7 @@ const mockToolkitsResponse = {
meta: {
logo: 'https://example.com/slack-logo.png',
},
+ is_no_auth: false,
connected_account: {
id: 'conn_456',
status: 'INITIATED',
@@ -115,6 +117,7 @@ const mockToolkitsResponse = {
meta: {
logo: 'https://example.com/github-logo.png',
},
+ is_no_auth: false,
connected_account: null,
},
],
@@ -131,13 +134,13 @@ describe('ToolRouter', () => {
const createExpectedConnections = (
overrides: {
manageConnections?: boolean;
- callbackUri?: string;
+ callbackUrl?: string;
inferScopesFromTools?: boolean;
} = {}
) => ({
infer_scopes_from_tools: overrides.inferScopesFromTools ?? false,
auto_manage_connections: overrides.manageConnections ?? true,
- callback_uri: overrides.callbackUri ?? undefined,
+ callback_url: overrides.callbackUrl ?? undefined,
});
beforeEach(() => {
@@ -146,6 +149,7 @@ describe('ToolRouter', () => {
mockProvider = new MockProvider();
toolRouter = new ToolRouter(mockClient as unknown as ComposioClient, {
provider: mockProvider,
+ apiKey: 'test-api-key',
});
});
@@ -160,7 +164,7 @@ describe('ToolRouter', () => {
});
it('should store the config reference', () => {
- expect(toolRouter['config']).toEqual({ provider: mockProvider });
+ expect(toolRouter['config']).toEqual({ provider: mockProvider, apiKey: 'test-api-key' });
});
});
@@ -186,8 +190,11 @@ describe('ToolRouter', () => {
expect(session).toHaveProperty('sessionId', 'session_123');
expect(session).toHaveProperty('mcp');
expect(session.mcp).toEqual({
- type: 'HTTP',
+ type: 'http',
url: 'https://mcp.example.com/session_123',
+ headers: {
+ 'x-api-key': 'test-api-key',
+ },
});
expect(session).toHaveProperty('tools');
expect(session).toHaveProperty('authorize');
@@ -217,7 +224,7 @@ describe('ToolRouter', () => {
const session = await toolRouter.create(userId);
- expect(session.mcp.type).toBe('HTTP');
+ expect(session.mcp.type).toBe('http');
expect(mockClient.toolRouter.session.create).toHaveBeenCalledTimes(1);
});
});
@@ -562,13 +569,13 @@ describe('ToolRouter', () => {
});
});
- it('should create a session with manageConnections object with callbackUri', async () => {
+ it('should create a session with manageConnections object with callbackUrl', async () => {
mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
const config: ToolRouterCreateSessionConfig = {
manageConnections: {
enabled: true,
- callbackUri: 'https://myapp.com/callback',
+ callbackUrl: 'https://myapp.com/callback',
inferScopesFromTools: false,
},
};
@@ -583,7 +590,7 @@ describe('ToolRouter', () => {
tools: undefined,
connections: createExpectedConnections({
manageConnections: true,
- callbackUri: 'https://myapp.com/callback',
+ callbackUrl: 'https://myapp.com/callback',
}),
execution: undefined,
});
@@ -621,7 +628,7 @@ describe('ToolRouter', () => {
const config: ToolRouterCreateSessionConfig = {
manageConnections: {
enabled: true,
- callbackUri: 'https://myapp.com/callback',
+ callbackUrl: 'https://myapp.com/callback',
inferScopesFromTools: true,
},
};
@@ -637,7 +644,7 @@ describe('ToolRouter', () => {
connections: createExpectedConnections({
manageConnections: true,
inferScopesFromTools: true,
- callbackUri: 'https://myapp.com/callback',
+ callbackUrl: 'https://myapp.com/callback',
}),
execution: undefined,
});
@@ -1020,26 +1027,26 @@ describe('ToolRouter', () => {
describe('response handling', () => {
it('should handle MCP type correctly', async () => {
- const responseWithUppercase = {
+ const responseWithHttp = {
...mockSessionCreateResponse,
mcp: {
- type: 'HTTP',
+ type: 'http',
url: 'https://mcp.example.com/session_123',
},
};
- mockClient.toolRouter.session.create.mockResolvedValueOnce(responseWithUppercase);
+ mockClient.toolRouter.session.create.mockResolvedValueOnce(responseWithHttp);
const session = await toolRouter.create(userId);
- expect(session.mcp.type).toBe('HTTP');
+ expect(session.mcp.type).toBe('http');
});
it('should handle SSE MCP type correctly', async () => {
const sseResponse = {
...mockSessionCreateResponse,
mcp: {
- type: 'SSE',
+ type: 'sse',
url: 'https://mcp.example.com/sse/session_123',
},
};
@@ -1048,7 +1055,7 @@ describe('ToolRouter', () => {
const session = await toolRouter.create(userId);
- expect(session.mcp.type).toBe('SSE');
+ expect(session.mcp.type).toBe('sse');
expect(session.mcp.url).toBe('https://mcp.example.com/sse/session_123');
});
@@ -1187,6 +1194,7 @@ describe('ToolRouter', () => {
cursor: undefined,
limit: undefined,
toolkits: undefined,
+ is_connected: undefined,
});
expect(result).toHaveProperty('items');
@@ -1208,6 +1216,7 @@ describe('ToolRouter', () => {
cursor: 'cursor_abc',
limit: 10,
toolkits: undefined,
+ is_connected: undefined,
});
expect(result.items).toHaveLength(3);
@@ -1225,6 +1234,25 @@ describe('ToolRouter', () => {
cursor: undefined,
limit: undefined,
toolkits: ['gmail', 'slack'],
+ is_connected: undefined,
+ });
+
+ expect(result.items).toHaveLength(3);
+ });
+
+ it('should fetch toolkits with isConnected filter option', async () => {
+ mockClient.toolRouter.session.toolkits.mockResolvedValueOnce(mockToolkitsResponse);
+
+ const session = await toolRouter.create(userId);
+ const result = await session.toolkits({
+ isConnected: true,
+ });
+
+ expect(mockClient.toolRouter.session.toolkits).toHaveBeenCalledWith(sessionId, {
+ cursor: undefined,
+ limit: undefined,
+ toolkits: undefined,
+ is_connected: true,
});
expect(result.items).toHaveLength(3);
@@ -1244,6 +1272,28 @@ describe('ToolRouter', () => {
cursor: 'cursor_xyz',
limit: 5,
toolkits: ['github'],
+ is_connected: undefined,
+ });
+
+ expect(result.items).toHaveLength(3);
+ });
+
+ it('should fetch toolkits with all options combined', async () => {
+ mockClient.toolRouter.session.toolkits.mockResolvedValueOnce(mockToolkitsResponse);
+
+ const session = await toolRouter.create(userId);
+ const result = await session.toolkits({
+ limit: 5,
+ nextCursor: 'cursor_xyz',
+ toolkits: ['github', 'gmail'],
+ isConnected: false,
+ });
+
+ expect(mockClient.toolRouter.session.toolkits).toHaveBeenCalledWith(sessionId, {
+ cursor: 'cursor_xyz',
+ limit: 5,
+ toolkits: ['github', 'gmail'],
+ is_connected: false,
});
expect(result.items).toHaveLength(3);
@@ -1260,13 +1310,13 @@ describe('ToolRouter', () => {
expect(gmailToolkit.name).toBe('Gmail');
expect(gmailToolkit.logo).toBe('https://example.com/gmail-logo.png');
expect(gmailToolkit.isNoAuth).toBe(false);
- expect(gmailToolkit.connection.isActive).toBe(true);
- expect(gmailToolkit.connection.authConfig).toEqual({
+ expect(gmailToolkit.connection?.isActive).toBe(true);
+ expect(gmailToolkit.connection?.authConfig).toEqual({
id: 'auth_config_123',
mode: 'OAUTH2',
isComposioManaged: true,
});
- expect(gmailToolkit.connection.connectedAccount).toEqual({
+ expect(gmailToolkit.connection?.connectedAccount).toEqual({
id: 'conn_123',
status: 'ACTIVE',
});
@@ -1280,8 +1330,8 @@ describe('ToolRouter', () => {
const slackToolkit = result.items[1];
expect(slackToolkit.slug).toBe('slack');
- expect(slackToolkit.connection.isActive).toBe(false);
- expect(slackToolkit.connection.connectedAccount?.status).toBe('INITIATED');
+ expect(slackToolkit.connection?.isActive).toBe(false);
+ expect(slackToolkit.connection?.connectedAccount?.status).toBe('INITIATED');
});
it('should transform toolkit connection state correctly for no connection', async () => {
@@ -1292,9 +1342,38 @@ describe('ToolRouter', () => {
const githubToolkit = result.items[2];
expect(githubToolkit.slug).toBe('github');
- expect(githubToolkit.connection.isActive).toBe(false);
- expect(githubToolkit.connection.authConfig).toBeNull();
- expect(githubToolkit.connection.connectedAccount).toBeUndefined();
+ expect(githubToolkit.connection?.isActive).toBe(false);
+ expect(githubToolkit.connection?.authConfig).toBeNull();
+ expect(githubToolkit.connection?.connectedAccount).toBeUndefined();
+ });
+
+ it('should transform toolkit connection state correctly for no-auth toolkit', async () => {
+ const noAuthToolkitsResponse = {
+ items: [
+ {
+ slug: 'codeinterpreter',
+ name: 'Code Interpreter',
+ meta: {
+ logo: 'https://example.com/codeinterpreter-logo.png',
+ },
+ is_no_auth: true,
+ connected_account: null,
+ },
+ ],
+ next_cursor: undefined,
+ total_pages: 1,
+ };
+
+ mockClient.toolRouter.session.toolkits.mockResolvedValueOnce(noAuthToolkitsResponse);
+
+ const session = await toolRouter.create(userId);
+ const result = await session.toolkits();
+
+ const codeinterpreterToolkit = result.items[0];
+ expect(codeinterpreterToolkit.slug).toBe('codeinterpreter');
+ expect(codeinterpreterToolkit.name).toBe('Code Interpreter');
+ expect(codeinterpreterToolkit.isNoAuth).toBe(true);
+ expect(codeinterpreterToolkit.connection).toBeUndefined();
});
it('should handle empty toolkits response', async () => {
@@ -1356,12 +1435,12 @@ describe('ToolRouter', () => {
await expect(session.toolkits()).rejects.toThrow('Failed to fetch toolkits');
});
- it('should handle malformed response data', async () => {
+ it('should handle malformed response data gracefully with undefined values', async () => {
const malformedResponse = {
items: [
{
slug: 'gmail',
- // Missing required fields
+ // Missing required fields like name, meta, is_no_auth
},
],
next_cursor: undefined,
@@ -1372,8 +1451,24 @@ describe('ToolRouter', () => {
const session = await toolRouter.create(userId);
- // Should throw transformation error due to missing required fields
- await expect(session.toolkits()).rejects.toThrow();
+ // The code handles malformed data gracefully with undefined values
+ const result = await session.toolkits();
+ expect(result.items).toHaveLength(1);
+ expect(result.items[0].slug).toBe('gmail');
+ expect(result.items[0].name).toBeUndefined();
+ expect(result.items[0].logo).toBeUndefined();
+ expect(result.items[0].isNoAuth).toBeUndefined();
+ });
+
+ it('should throw validation error for invalid options', async () => {
+ const session = await toolRouter.create(userId);
+
+ // Invalid options should throw a validation error
+ await expect(
+ session.toolkits({
+ limit: 'invalid' as unknown as number, // Invalid type
+ })
+ ).rejects.toThrow();
});
});
@@ -1394,7 +1489,10 @@ describe('ToolRouter', () => {
const session = await toolRouter.create(userId);
const tools = await session.tools();
- expect(Tools).toHaveBeenCalledWith(mockClient, { provider: mockProvider });
+ expect(Tools).toHaveBeenCalledWith(mockClient, {
+ provider: mockProvider,
+ apiKey: 'test-api-key',
+ });
const toolsInstance = (Tools as any).mock.results[0].value;
expect(toolsInstance.get).toHaveBeenCalledWith(
@@ -1491,7 +1589,10 @@ describe('ToolRouter', () => {
const newSession = await toolRouter.create(userId);
await newSession.tools();
- expect(Tools).toHaveBeenCalledWith(mockClient, { provider: mockProvider });
+ expect(Tools).toHaveBeenCalledWith(mockClient, {
+ provider: mockProvider,
+ apiKey: 'test-api-key',
+ });
const toolsInstance = (Tools as any).mock.results[0].value;
expect(toolsInstance.get).toHaveBeenCalledWith(
userId,
@@ -1514,7 +1615,10 @@ describe('ToolRouter', () => {
const session = await toolRouter.create(userId);
await session.tools();
- expect(Tools).toHaveBeenCalledWith(mockClient, { provider: mockProvider });
+ expect(Tools).toHaveBeenCalledWith(mockClient, {
+ provider: mockProvider,
+ apiKey: 'test-api-key',
+ });
const toolsInstance = (Tools as any).mock.results[0].value;
expect(toolsInstance.get).toHaveBeenCalledWith(
userId,
@@ -1591,11 +1695,13 @@ describe('ToolRouter', () => {
cursor: undefined,
limit: undefined,
toolkits: undefined,
+ is_connected: undefined,
});
expect(mockClient.toolRouter.session.toolkits).toHaveBeenCalledWith('session_2', {
cursor: undefined,
limit: undefined,
toolkits: undefined,
+ is_connected: undefined,
});
});
@@ -1631,8 +1737,11 @@ describe('ToolRouter', () => {
expect(session).toHaveProperty('sessionId', 'session_123');
expect(session).toHaveProperty('mcp');
expect(session.mcp).toEqual({
- type: 'HTTP',
+ type: 'http',
url: 'https://mcp.example.com/session_123',
+ headers: {
+ 'x-api-key': 'test-api-key',
+ },
});
expect(session).toHaveProperty('tools');
expect(session).toHaveProperty('authorize');
@@ -1695,6 +1804,7 @@ describe('ToolRouter', () => {
cursor: undefined,
limit: undefined,
toolkits: undefined,
+ is_connected: undefined,
});
expect(toolkitsResult.items).toHaveLength(3);
expect(toolkitsResult.items[0].slug).toBe('gmail');
@@ -1728,7 +1838,7 @@ describe('ToolRouter', () => {
const session = await toolRouter.use(sessionId);
- expect(session.mcp.type).toBe('HTTP');
+ expect(session.mcp.type).toBe('http');
expect(session.mcp.url).toBe('https://mcp.example.com/session_123');
});
diff --git a/uv.lock b/uv.lock
index 89a3bd844..dc2dfef0f 100644
--- a/uv.lock
+++ b/uv.lock
@@ -468,7 +468,7 @@ wheels = [
[[package]]
name = "composio"
-version = "0.9.4"
+version = "0.9.5rc1"
source = { virtual = "python" }
dependencies = [
{ name = "composio-client" },
@@ -497,7 +497,7 @@ dev = [
[package.metadata]
requires-dist = [
- { name = "composio-client", specifier = ">=1.17.1" },
+ { name = "composio-client", specifier = ">=1.18.0" },
{ name = "openai" },
{ name = "pydantic", specifier = ">=2.6.4" },
{ name = "pysher", specifier = ">=1.0.8" },
@@ -523,7 +523,7 @@ dev = [
[[package]]
name = "composio-anthropic"
-version = "0.9.4"
+version = "0.9.5rc1"
source = { virtual = "python/providers/anthropic" }
dependencies = [
{ name = "anthropic" },
@@ -538,7 +538,7 @@ requires-dist = [
[[package]]
name = "composio-client"
-version = "1.17.1"
+version = "1.18.0"
source = { registry = "https://pypi.org/simple" }
dependencies = [
{ name = "anyio" },
@@ -548,14 +548,14 @@ dependencies = [
{ name = "sniffio" },
{ name = "typing-extensions" },
]
-sdist = { url = "https://files.pythonhosted.org/packages/8a/ac/2194260234ef364f7bd4b3dc7a4ae08b6e819ab22935218207795bf77c27/composio_client-1.17.1.tar.gz", hash = "sha256:c5e9d593bc2497f3c57614f544a7c5cf3601f310b2f1e65ccfa9a69dcb496733", size = 182234 }
+sdist = { url = "https://files.pythonhosted.org/packages/75/e0/b0d32c293a70d0469bf9fe435d6a3b04a0c1b5148030f7f693197222cb78/composio_client-1.18.0.tar.gz", hash = "sha256:c973fc8538ae358051f8094801b067887e35f23d5ae60b12c9c181bc2da82586", size = 182540 }
wheels = [
- { url = "https://files.pythonhosted.org/packages/30/4c/7dc1647fba7cdeeb3a62f1ddb03c57d556a81de731ac58b58ae43f2d0ff9/composio_client-1.17.1-py3-none-any.whl", hash = "sha256:ccf7f07e34e67d90eae33034eeccf76ecc98cbf36ebc167f8f4327f3180050c7", size = 198420 },
+ { url = "https://files.pythonhosted.org/packages/02/c3/4f078e5dc9d24449838fd63145c2d3e4c301b343a7bed469b8cbebb3a25e/composio_client-1.18.0-py3-none-any.whl", hash = "sha256:27e020cb876748507a49df1ca36b8b3a3b5dedef91355e60e8c8563f794cfa6a", size = 198537 },
]
[[package]]
name = "composio-crewai"
-version = "0.9.4"
+version = "0.9.5rc1"
source = { virtual = "python/providers/crewai" }
dependencies = [
{ name = "composio" },
@@ -570,7 +570,7 @@ requires-dist = [
[[package]]
name = "composio-gemini"
-version = "0.9.4"
+version = "0.9.5rc1"
source = { virtual = "python/providers/gemini" }
dependencies = [
{ name = "composio" },
@@ -585,7 +585,7 @@ requires-dist = [
[[package]]
name = "composio-google"
-version = "0.9.4"
+version = "0.9.5rc1"
source = { virtual = "python/providers/google" }
dependencies = [
{ name = "composio" },
@@ -600,7 +600,7 @@ requires-dist = [
[[package]]
name = "composio-google-adk"
-version = "0.9.4"
+version = "0.9.5rc1"
source = { virtual = "python/providers/google_adk" }
dependencies = [
{ name = "composio" },
@@ -615,7 +615,7 @@ requires-dist = [
[[package]]
name = "composio-langchain"
-version = "0.9.4"
+version = "0.9.5rc1"
source = { virtual = "python/providers/langchain" }
dependencies = [
{ name = "composio" },
@@ -630,7 +630,7 @@ requires-dist = [
[[package]]
name = "composio-openai"
-version = "0.9.4"
+version = "0.9.5rc1"
source = { virtual = "python/providers/openai" }
dependencies = [
{ name = "composio" },
@@ -645,7 +645,7 @@ requires-dist = [
[[package]]
name = "composio-openai-agents"
-version = "0.9.4"
+version = "0.9.5rc1"
source = { virtual = "python/providers/openai_agents" }
dependencies = [
{ name = "composio" },