Composio
Comprehensive guide to building AI agents and applications with Composio. Choose between:
- Tool Router - Create isolated, secure MCP sessions for AI agents with automatic authentication
- Direct Execution - Build traditional apps with manual tool execution and CRUD operations
When to use
Use this skill when:
Building AI Agents:
- Building chat-based or autonomous agents that need access to external tools (Gmail, Slack, GitHub, etc.)
- Creating multi-user applications with isolated tool access per session
- Implementing automatic authentication flows for external services
- Integrating with AI frameworks (Vercel AI SDK, LangChain, OpenAI Agents, Claude)
- Using MCP (Model Context Protocol) for dynamic tool discovery
- Building event-driven agents with triggers
Building Traditional Applications:
- Creating CRUD applications that execute tools directly
- Building automation workflows without agent frameworks
- Managing connected accounts and authentication configurations
- Creating custom tools with specific authentication requirements
- Implementing multi-tenant applications with session isolation
- Building tools with pre/post-execution hooks and modifiers
1. Building Agents
Use Tool Router to build interactive chat-based agents or autonomous long-running task agents. Tool Router creates isolated MCP sessions for users with scoped access to toolkits and tools.
Key Features:
- 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
- Real-time event handling with triggers
1.1 Session Management & Configuration
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
1.2 Authentication Flows
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, waitForConnections, and custom callback URLs
1.3 Toolkit Querying & UI Building
Build connection UIs and check toolkit states:
- Building Chat UIs - Build chat applications with toolkit selection, connection management, and session handling
- Query Toolkit States - Use session.toolkits() to check connections, filter toolkits, and build connection UIs
1.4 Event-Driven Agents (Triggers)
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
2. Building Apps with Composio Tools
Use Composio for traditional applications where tools are executed manually without agent frameworks. This approach gives you full control over tool execution, authentication, and resource management.
Key Capabilities:
- Direct tool execution with manual control
- CRUD operations on connected accounts, auth configs, and toolkits
- Custom tool creation with authentication
- Session isolation for multi-tenant apps
- Pre/post-execution hooks and modifiers
- Event-driven workflows with triggers
2.1 Core Operations
Fundamental patterns for fetching and executing tools:
- Fetching Tools - Get tools with filters and search
- Direct Tool Execution - Execute tools manually with parameters
- Tool Version Management - Version pinning strategies for stability
2.2 Resource Management (CRUD Patterns)
Manage authentication and connections programmatically:
- Connected Accounts CRUD - Create, read, update, delete connected accounts
- Auth Config Management - Manage authentication configurations
- Toolkit Management - Query toolkits, categories, and auth requirements
2.3 Extensibility & Customization
Extend Composio with custom tools and behavior:
- Creating Custom Tools - Build standalone and toolkit-based tools
- Tool Modifiers - Schema modification and execution hooks
2.4 Event-Driven Applications
Build reactive applications with triggers (shared with agents):
- 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 webhooks
- Managing Triggers - Enable, disable, update, and list triggers
2.5 User Context & Multi-Tenancy
Manage user context and multi-tenant isolation:
- User ID Patterns - User vs organization IDs, shared vs isolated connections
Quick Start Examples
Building an Agent with Tool Router
import { Composio } from '@composio/core';
const composio = new Composio();
// Create a session with Gmail tools
const session = await composio.create('user_123', {
toolkits: ['gmail'],
manageConnections: true
});
// Use MCP URL with any AI framework
console.log('MCP URL:', session.mcp.url);Building an App with Direct Execution
import { Composio } from '@composio/core';
const composio = new Composio({
apiKey: 'your-api-key',
toolkitVersions: { github: '12082025_00' }
});
// Fetch tools
const tools = await composio.tools.get('user_123', {
toolkits: ['github']
});
// Execute a tool
const result = await composio.tools.execute('GITHUB_GET_REPO', {
userId: 'user_123',
arguments: { owner: 'composio', repo: 'sdk' },
});
console.log(result.data);References
Tool Router (Agents):
Direct Execution (Apps):
Shared: