composio

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

使用Composio构建AI Agent与应用程序的全面指南。您可以选择以下两种方式：

Tool Router - 为AI Agent创建隔离、安全的MCP会话，支持自动认证
Direct Execution - 构建传统应用程序，支持手动工具执行与CRUD操作

Getting Started

快速入门

📖 Prerequisites: Before using Composio, set up your API keys. See Setting Up API Keys for instructions on configuring Composio, OpenAI, and Anthropic API keys.

📖 前置要求： 在使用Composio之前，请先设置您的API密钥。如需了解配置Composio、OpenAI和Anthropic API密钥的说明，请查看设置API密钥。

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

在以下场景中使用该技能：

构建AI Agent时：

构建需要接入外部工具（Gmail、Slack、GitHub等）的对话式或自主运行Agent
创建为每个会话提供隔离工具访问权限的多用户应用程序
实现外部服务的自动认证流程
与AI框架（Vercel AI SDK、LangChain、OpenAI Agents、Claude）集成
使用MCP（Model Context Protocol）进行动态工具发现
构建带触发器的事件驱动型Agent

构建传统应用程序时：

创建直接执行工具的CRUD应用程序
无需Agent框架即可构建自动化工作流
管理关联账户与认证配置
创建具有特定认证要求的自定义工具
实现带会话隔离的多租户应用程序
构建带有执行前后钩子与修饰器的工具

1. Building Agents

1. 构建Agent

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

使用Tool Router构建交互式对话Agent或自主运行的长任务Agent。Tool Router会为用户创建隔离的MCP会话，提供对工具包和工具的范围化访问权限。

核心特性：

基于会话的用户级隔离
动态工具包与工具配置
自动认证管理
兼容任意AI框架的MCP协议服务器地址
用于UI构建的连接状态查询
带触发器的实时事件处理

1.1 Session Management & Configuration

1.1 会话管理与配置

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

创建Agent会话和配置工具的核心模式：

用户ID最佳实践 - 选择安全且具备隔离性的用户ID
创建基础会话 - 初始化Tool Router会话
会话生命周期最佳实践 - 何时创建新会话 vs 复用现有会话
会话配置 - 配置工具包、工具与过滤器
使用原生工具 - 优先使用原生工具以获得性能与控制权
框架集成 - 与Vercel AI、LangChain、OpenAI Agents集成

1.2 Authentication Flows

1.2 认证流程

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

实现流畅用户体验的认证模式：

对话内自动认证 - 启用对话内认证流程
手动授权 - 使用session.authorize()实现显式流程
连接管理 - 配置manageConnections、waitForConnections与自定义回调URL

1.3 Toolkit Querying & UI Building

1.3 工具包查询与UI构建

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

构建连接UI并检查工具包状态：

构建对话UI - 构建包含工具包选择、连接管理与会话处理的对话应用程序
查询工具包状态 - 使用session.toolkits()检查连接、过滤工具包并构建连接UI

1.4 Event-Driven Agents (Triggers)

1.4 事件驱动型Agent（触发器）

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

实时事件处理与Webhook集成模式：

创建触发器 - 为实时事件设置触发器实例
订阅事件 - 实时监听触发器事件
Webhook验证 - 验证并处理传入的Webhook负载
管理触发器 - 启用、禁用、更新与列出触发器

2. Building Apps with Composio Tools

2. 使用Composio工具构建应用程序

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

在无需Agent框架的传统应用程序中使用Composio，直接手动执行工具。这种方式让您完全掌控工具执行、认证与资源管理。

核心能力：

手动控制的直接工具执行
对关联账户、认证配置与工具包的CRUD操作
带认证的自定义工具创建
多租户应用的会话隔离
执行前后钩子与修饰器
带触发器的事件驱动工作流

2.1 Core Operations

2.1 核心操作

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)

2.2 资源管理（CRUD模式）

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

以编程方式管理认证与连接：

关联账户CRUD - 创建、读取、更新、删除关联账户
认证配置管理 - 管理认证配置
工具包管理 - 查询工具包、分类与认证要求

2.3 Extensibility & Customization

2.3 扩展性与定制化

Extend Composio with custom tools and behavior:

Creating Custom Tools - Build standalone and toolkit-based tools
Tool Modifiers - Schema modification and execution hooks

通过自定义工具与行为扩展Composio：

创建自定义工具 - 构建独立工具与基于工具包的工具
工具修饰器 - 模式修改与执行钩子

2.4 Event-Driven Applications

2.4 事件驱动型应用程序

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

使用触发器构建响应式应用程序（与Agent共享）：

创建触发器 - 为实时事件设置触发器实例
订阅事件 - 实时监听触发器事件
Webhook验证 - 验证并处理传入的Webhook
管理触发器 - 启用、禁用、更新与列出触发器

2.5 User Context & Multi-Tenancy

2.5 用户上下文与多租户

Manage user context and multi-tenant isolation:

User ID Patterns - User vs organization IDs, shared vs isolated connections

管理用户上下文与多租户隔离：

用户ID模式 - 用户ID vs 组织ID、共享 vs 隔离连接

Quick Start Examples

快速入门示例

Building an Agent with Tool Router

使用Tool Router构建Agent

typescript

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

typescript

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

使用直接执行模式构建应用程序

typescript

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

typescript

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:

Tool Router（Agent）：

直接执行（应用程序）：

共享资源：