Composio Tool Router
Comprehensive guide to building AI agents with Composio Tool Router - create isolated, secure tool sessions for your users with seamless authentication and toolkit management.
When to use
Use this skill when:
- Building AI agents that need access to external tools (Gmail, Slack, GitHub, etc.)
- Creating multi-user applications with isolated tool access
- Implementing authentication flows for external services
- Managing toolkit connections and permissions
- Integrating with AI frameworks (Vercel AI SDK, LangChain, OpenAI Agents, Claude)
- Using MCP (Model Context Protocol) for tool discovery
- Building UI for connection management
Core Concepts
Tool Router creates isolated MCP sessions for users with scoped access to toolkits and tools. It handles:
- Session-based isolation per user
- Dynamic toolkit and tool configuration
- Automatic authentication management
- MCP-compatible server URLs for any AI framework
- Connection state querying for UI building
Rules
1. Building Agents with Tool Router
Essential patterns for creating agent sessions and configuring tools:
- User ID Best Practices - Choose user IDs for security and isolation
- Creating Basic Sessions - Initialize Tool Router sessions
- Session Lifecycle Best Practices - When to create new sessions vs reuse
- Session Configuration - Configure toolkits, tools, and filters
- Using Native Tools - Prefer native tools for performance and control
- Framework Integration - Connect with Vercel AI, LangChain, OpenAI Agents
2. Authenticating Users
Authentication patterns for seamless user experiences:
- Auto Authentication in Chat - Enable in-chat authentication flows
- Manual Authorization - Use session.authorize() for explicit flows
- Connection Management - Configure manageConnections options
- Wait for Connections - Block until authentication completes
- Custom Callback URLs - Handle OAuth redirects
3. Fetching Toolkits and Connection Status
Build connection UIs and check toolkit states:
- Query Toolkit States - Use session.toolkits() to check connections
- Build Connection UI - Display connection status and auth buttons
- Filter Toolkits - Query specific toolkits
- Pagination - Handle large toolkit lists
- Connection Details - Access auth configs and account info
Advanced (Coming Soon)
- Session modifiers and middleware
- Custom tool configuration
- Workbench integration
- Experimental features
Quick Start
import { Composio } from '@composio/core';
// Create a session with Gmail tools
const composio = new Composio();
const session = await composio.create('user_123', {
toolkits: ['gmail'],
manageConnections: true
});
// Use with any MCP-compatible framework
console.log('MCP URL:', session.mcp.url);4. Advanced Features (Triggers & Events)
Real-time event handling and webhook integration patterns:
- Creating Triggers - Set up trigger instances for real-time events
- Subscribing to Events - Listen to trigger events in real-time
- Webhook Verification - Verify and process incoming webhook payloads
- Managing Triggers - Enable, disable, update, and list triggers