composio

Composio

使用 Composio 构建 AI Agent 和应用的综合指南。可选择：

• Tool Router - 为 AI Agent 创建隔离、安全的 MCP 会话，并自动进行身份验证
• Direct Execution - 通过手动执行工具和 CRUD 操作构建传统应用

适用场景

在以下情况下使用此技能：

构建 AI Agent：

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

构建传统应用：

• 创建直接执行工具的 CRUD 应用
• 构建不使用 Agent 框架的自动化工作流
• 管理已连接的账户和身份验证配置
• 创建具有特定身份验证要求的自定义工具
• 实现具备会话隔离的多租户应用
• 构建带有执行前/后钩子和修饰器的工具

1. 构建 Agent

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

主要功能：

• 按用户进行基于会话的隔离
• 动态配置工具包和工具
• 自动管理身份验证
• 为任何 AI 框架提供兼容 MCP 的服务 URL
• 查询连接状态以构建 UI
• 使用触发器实时处理事件

1.1 会话管理与配置

创建 Agent 会话和配置工具的基本模式：

• 用户 ID 最佳实践 - 选择用户 ID，以确保安全和隔离
• 创建基本会话 - 初始化 Tool Router 会话
• 会话生命周期最佳实践 - 了解何时创建新会话、何时复用会话
• 会话配置 - 配置工具包、工具和筛选条件
• 使用原生工具 - 优先使用原生工具，以提升性能并加强控制
• 框架集成 - 连接 Vercel AI、LangChain、OpenAI Agents

1.2 身份验证流程

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

• 聊天中的自动身份验证 - 启用聊天内身份验证流程
• 手动授权 - 使用 session.authorize() 实现显式流程
• 连接管理 - 配置 manageConnections、waitForConnections 和自定义回调 URL

1.3 工具包查询与 UI 构建

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

• 构建聊天 UI - 构建聊天应用，支持工具包选择、连接管理和会话处理
• 查询工具包状态 - 使用 session.toolkits() 检查连接、筛选工具包并构建连接 UI

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

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

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

2. 使用 Composio 工具构建应用

对于无需 Agent 框架、由人工手动执行工具的传统应用，请使用 Composio。这种方式让你可以全面掌控工具执行、身份验证和资源管理。

主要功能：

• 直接执行工具并进行手动控制
• 对已连接的账户、身份验证配置和工具包执行 CRUD 操作
• 创建经过身份验证的自定义工具
• 为多租户应用隔离会话
• 执行前/后的钩子和修饰器
• 通过触发器实现事件驱动工作流

2.1 核心操作

获取和执行工具的基本模式：

• 获取工具 - 使用筛选条件和搜索获取工具
• 直接执行工具 - 手动传入参数执行工具
• 工具版本管理 - 使用版本固定策略确保稳定性

2.2 资源管理（CRUD 模式）

以编程方式管理身份验证和连接：

• 已连接账户的 CRUD 操作 - 创建、读取、更新和删除已连接的账户
• 身份验证配置管理 - 管理身份验证配置
• 工具包管理 - 查询工具包、类别和身份验证要求

2.3 扩展与自定义

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

• 创建自定义工具 - 构建独立工具和基于工具包的工具
• 工具修饰器 - 修改架构并添加执行钩子

2.4 事件驱动应用

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

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

2.5 用户上下文与多租户

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

• 用户 ID 模式 - 用户 ID 与组织 ID，以及共享连接与隔离连接

快速入门示例

使用 Tool Router 构建 Agent

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

使用直接执行构建应用

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

参考资料

Tool Router（Agent）：

• Tool Router 文档
• MCP 协议
• 框架集成示例

直接执行（应用）：

• 工具 API
• 已连接账户 API
• 身份验证配置 API
• 工具包 API
• 自定义工具指南
• 修饰器
• 核心概念

共用：

• 触发器 API
• Webhook 验证