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

References

• Tool Router Docs

• Triggers API

• Webhook Verification

• MCP Protocol

• TypeScript Examples