composio

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):

• Tool Router Docs
• MCP Protocol
• Framework Integration Examples

Direct Execution (Apps):

• Tools API
• Connected Accounts API
• Auth Configs API
• Toolkits API
• Custom Tools Guide
• Modifiers
• Core Concepts

Shared:

• Triggers API
• Webhook Verification