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

composio-tool-router