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

Shared: