Composio 集成

Composio 是一个集成平台，提供对 500 多种工具的访问，涵盖 GitHub、Slack、Notion 等流行应用程序。它使 AI 代理能够通过统一的 API 与外部服务交互，处理身份验证、权限和事件驱动的工作流。

概述

集成详情

类	包	可序列化	Python 支持	版本
Composio	@composio/langchain	❌	✅

工具特性

500+ 工具访问：为 GitHub、Slack、Gmail、Jira、Notion 等提供预构建集成
身份验证管理：处理 OAuth 流程、API 密钥和身份验证状态
事件驱动工作流：基于外部事件（新 Slack 消息、GitHub 问题等）触发代理
细粒度权限：按用户控制工具访问和数据暴露
自定义工具支持：添加专有 API 和内部工具

设置

集成位于 @composio/langchain 包中。

npm install @composio/langchain @composio/core

或使用其他包管理器：

yarn add @composio/langchain @composio/core
# 或
pnpm add @composio/langchain @composio/core

凭证

您需要一个 Composio API 密钥。在 composio.dev 免费注册以获取您的 API 密钥。

设置 API 密钥

import * as dotenv from 'dotenv';
dotenv.config();

// 设置您的 Composio API 密钥
process.env.COMPOSIO_API_KEY = 'your_api_key_here';

设置 LangSmith 以进行跟踪也很有帮助：

启用跟踪

// process.env.LANGSMITH_API_KEY = 'your_langsmith_key';
// process.env.LANGSMITH_TRACING = 'true';

实例化

使用 LangChain 提供程序初始化 Composio，并从特定工具包获取工具。每个工具包代表一个服务（例如 GitHub、Slack），包含多个工具（您可以执行的操作）。

初始化 Composio

import { Composio } from '@composio/core';
import { LangchainProvider } from '@composio/langchain';

// 使用 LangChain 提供程序初始化 Composio
const composio = new Composio({
    apiKey: process.env.COMPOSIO_API_KEY,
    provider: new LangchainProvider(),
});

// 从特定工具包获取工具
const tools = await composio.tools.get('default', 'GITHUB');

console.log(`从 GitHub 工具包加载了 ${tools.length} 个工具`);

可用工具包

Composio 为各种服务提供工具包： 生产力：GitHub、Slack、Gmail、Jira、Notion、Asana、Trello、ClickUp 通信：Discord、Telegram、WhatsApp、Microsoft Teams 开发：GitLab、Bitbucket、Linear、Sentry 数据与分析：Google Sheets、Airtable、HubSpot、Salesforce 以及 100 多种更多…

调用

从多个工具包获取工具

您可以从多个服务加载工具：

// 从多个工具包获取工具
const tools = await composio.tools.get('default', ['GITHUB', 'SLACK', 'GMAIL']);

获取特定工具

您可以加载特定工具，而不是整个工具包：

// 按名称获取特定工具
const tools = await composio.tools.get('default', {
    tools: ['GITHUB_CREATE_ISSUE', 'SLACK_SEND_MESSAGE']
});

用户特定工具

Composio 支持多用户场景，具有用户特定的身份验证：

// 获取特定用户的工具
// 此用户必须首先验证其账户
const tools = await composio.tools.get('user_123', 'GITHUB');

在代理中使用

以下是一个完整示例，使用 Composio 工具与 LangGraph 代理交互 HackerNews：

import { ChatOpenAI } from '@langchain/openai';
import { HumanMessage, AIMessage } from '@langchain/core/messages';
import { ToolNode } from '@langchain/langgraph/prebuilt';
import { StateGraph, MessagesAnnotation } from '@langchain/langgraph';
import { Composio } from '@composio/core';
import { LangchainProvider } from '@composio/langchain';

// 初始化 Composio
const composio = new Composio({
    apiKey: process.env.COMPOSIO_API_KEY,
    provider: new LangchainProvider(),
});

// 获取工具
console.log('🔄 正在获取工具...');
const tools = await composio.tools.get('default', 'HACKERNEWS_GET_USER');

// 定义代理要使用的工具
const toolNode = new ToolNode(tools);

// 创建模型并授予其工具访问权限
const model = new ChatOpenAI({
    model: 'gpt-5',
}).bindTools(tools);

// 定义决定是否继续的函数
function shouldContinue({ messages }: typeof MessagesAnnotation.State) {
    const lastMessage = messages[messages.length - 1] as AIMessage;

    // 如果 LLM 进行工具调用，则路由到 "tools" 节点
    if (lastMessage.tool_calls?.length) {
        return 'tools';
    }

    // 否则，我们停止（回复用户）
    return '__end__';
}

// 定义调用模型的函数
async function callModel(state: typeof MessagesAnnotation.State) {
    console.log('🔄 正在调用模型...');
    const response = await model.invoke(state.messages);
    return { messages: [response] };
}

// 定义新图
const workflow = new StateGraph(MessagesAnnotation)
    .addNode('agent', callModel)
    .addEdge('__start__', 'agent')
    .addNode('tools', toolNode)
    .addEdge('tools', 'agent')
    .addConditionalEdges('agent', shouldContinue);

// 编译图
const app = workflow.compile();

// 使用代理
const finalState = await app.invoke({
    messages: [new HumanMessage('查找 HackerNews 上用户 `pg` 的详细信息')]
});

console.log('✅ 收到来自模型的消息');
console.log(finalState.messages[finalState.messages.length - 1].content);

// 继续对话
const nextState = await app.invoke({
    messages: [...finalState.messages, new HumanMessage('haxzie 怎么样')]
});

console.log('✅ 收到来自模型的消息');
console.log(nextState.messages[nextState.messages.length - 1].content);

与 GitHub 工具包一起使用

以下是一个为 GitHub 仓库加星的示例：

import { ChatOpenAI } from '@langchain/openai';
import { createReactAgent } from '@langchain/langgraph/prebuilt';
import { Composio } from '@composio/core';
import { LangchainProvider } from '@composio/langchain';

// 初始化 Composio
const composio = new Composio({
    apiKey: process.env.COMPOSIO_API_KEY,
    provider: new LangchainProvider(),
});

// 获取 GitHub 工具
const tools = await composio.tools.get('default', 'GITHUB');

// 创建模型
const model = new ChatOpenAI({
    model: 'gpt-5',
});

// 创建代理
const agent = createReactAgent({
    llm: model,
    tools: tools,
});

// 执行任务
const result = await agent.invoke({
    messages: [
        {
            role: 'user',
            content: '为 GitHub 上的仓库 composiohq/composio 加星'
        }
    ]
});

console.log(result.messages[result.messages.length - 1].content);

身份验证设置

在使用需要身份验证的工具之前，用户需要连接他们的账户：

import { Composio } from '@composio/core';

const composio = new Composio({
    apiKey: process.env.COMPOSIO_API_KEY
});

// 获取用户的认证 URL
const authConnection = await composio.integrations.create({
    userId: 'user_123',
    integration: 'github'
});

console.log(`请在以下位置进行认证: ${authConnection.redirectUrl}`);

// 认证后，用户的连接账户将可用
// 工具将使用其凭据工作

多用户场景

对于具有多个用户的应用程序：

// 每个用户验证自己的账户
const toolsUser1 = await composio.tools.get('user_1', 'GITHUB');
const toolsUser2 = await composio.tools.get('user_2', 'GITHUB');

// 工具将使用相应用户的凭据
// 用户 1 的代理将在用户 1 的 GitHub 账户上操作
const agent1 = createAgent(model, toolsUser1);

// 用户 2 的代理将在用户 2 的 GitHub 账户上操作
const agent2 = createAgent(model, toolsUser2);

事件驱动工作流

Composio 支持基于外部事件触发代理。当连接的应用程序中发生事件（如新的 GitHub 提交或 Slack 消息）时，触发器会自动将结构化有效负载发送到您的应用程序。

创建触发器

首先，为您要监控的事件创建触发器：

import { Composio } from '@composio/core';

const composio = new Composio({ apiKey: 'your_api_key' });
const userId = 'user_123';

// 检查触发器所需的配置
const triggerType = await composio.triggers.getType('GITHUB_COMMIT_EVENT');
console.log(triggerType.config);

// 使用所需配置创建触发器
const trigger = await composio.triggers.create(
    userId,
    'GITHUB_COMMIT_EVENT',
    {
        triggerConfig: {
            owner: 'composiohq',
            repo: 'composio'
        }
    }
);

console.log(`触发器已创建: ${trigger.triggerId}`);

订阅触发器（开发）

对于本地开发和原型设计，您可以直接订阅触发器：

import { Composio } from '@composio/core';

const composio = new Composio({ apiKey: 'your_api_key' });

// 订阅触发器事件
composio.triggers.subscribe(
    (data) => {
        console.log(`检测到新提交:`, data);
        // 使用您的代理处理事件
        // ... 使用任务调用您的代理
    },
    {
        triggerId: 'your_trigger_id',
        // 您还可以按以下方式过滤：
        // userId: 'user@acme.com',
        // toolkits: ['github', 'slack'],
        // triggerSlug: ["GITHUB_COMMIT_EVENT"],
        // authConfigId: "ac_1234567890"
    }
);

// 注意：对于生产环境，请使用 Webhook

类型安全的触发器处理

为了更好的类型安全性，定义有效负载类型：

import { TriggerEvent } from '@composio/core';

// 定义类型安全的有效负载
export type GitHubStarAddedEventPayload = {
    action: 'created';
    repository_id: number;
    repository_name: string;
    repository_url: string;
    starred_at: string;
    starred_by: string;
};

// 类型安全的处理程序
function handleGitHubStarAddedEvent(event: TriggerEvent<GitHubStarAddedEventPayload>) {
    console.log(`⭐ ${event.data.repository_name} 由 ${event.data.starred_by} 加星`);
}

Webhook（生产环境）

对于生产环境，在 Composio 仪表板中配置 Webhook：

import type { NextApiRequest, NextApiResponse } from 'next';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
    if (req.method !== 'POST') {
        return res.status(405).json({ error: 'Method not allowed' });
    }

    try {
        const payload = req.body;

        console.log('收到触发器事件:', payload);

        // 使用您的代理处理事件
        if (payload.triggerSlug === 'GITHUB_COMMIT_EVENT') {
            const commitData = payload.payload;
            // ... 使用 commitData 调用您的代理
        }

        res.status(200).json({ status: 'success' });
    } catch (error) {
        console.error('处理 Webhook 时出错:', error);
        res.status(500).json({ error: 'Internal server error' });
    }
}

更多详情，请参阅 Composio Triggers 文档

高级功能

自定义工具

Composio 允许您创建可与内置工具一起使用的自定义工具。有两种类型：

独立工具

不需要身份验证的简单工具：

import { Composio } from '@composio/core';
import { z } from 'zod';

const composio = new Composio({
    apiKey: process.env.COMPOSIO_API_KEY
});

const tool = await composio.tools.createCustomTool({
    slug: 'CALCULATE_SQUARE',
    name: 'Calculate Square',
    description: 'Calculates the square of a number',
    inputParams: z.object({
        number: z.number().describe('The number to calculate the square of'),
    }),
    execute: async input => {
        const { number } = input;
        return {
            data: { result: number * number },
            error: null,
            successful: true,
        };
    },
});

// 与您的代理一起使用
const allTools = [...tools, tool];

基于工具包的工具

需要身份验证并可以使用工具包凭据的工具：

import { Composio } from '@composio/core';
import { z } from 'zod';

const composio = new Composio({
    apiKey: process.env.COMPOSIO_API_KEY
});

const tool = await composio.tools.createCustomTool({
    slug: 'GITHUB_STAR_COMPOSIOHQ_REPOSITORY',
    name: 'Github star composio repositories',
    toolkitSlug: 'github',
    description: 'Star any specified repo of `composiohq` user',
    inputParams: z.object({
        repository: z.string().describe('The repository to star'),
        page: z.number().optional().describe('Pagination page number'),
        customHeader: z.string().optional().describe('Custom header'),
    }),
    execute: async (input, connectionConfig, executeToolRequest) => {
        // 此方法向相关 API 发出经过身份验证的请求
        // Composio 将自动注入 baseURL
        const result = await executeToolRequest({
            endpoint: `/user/starred/composiohq/${input.repository}`,
            method: 'PUT',
            body: {},
            // 添加自定义标头或查询参数
            parameters: [
                // 添加查询参数
                {
                    name: 'page',
                    value: input.page?.toString() || '1',
                    in: 'query',
                },
                // 添加自定义标头
                {
                    name: 'x-custom-header',
                    value: input.customHeader || 'default-value',
                    in: 'header',
                },
            ],
        });
        return result;
    },
});

执行自定义工具：

import { Composio } from '@composio/core';

const composio = new Composio({
    apiKey: process.env.COMPOSIO_API_KEY
});

const result = await composio.tools.execute('TOOL_SLUG', {
    arguments: {
        // 工具输入参数
    },
    userId: 'user-id',
    connectedAccountId: 'optional-account-id', // 基于工具包的工具需要此参数
});

更多详情，请参阅 Composio Custom Tools 文档

细粒度权限

控制工具可以执行的操作：

// 获取具有特定权限的工具
const tools = await composio.tools.get('default', 'GITHUB', {
    // 限制为只读操作
    permissions: ['read']
});

API 参考

有关所有 Composio 功能和配置的详细文档，请访问：

在 GitHub 上编辑此页面或提交问题。

通过 MCP 将这些文档连接到 Claude、VSCode 等以获取实时答案。

Popular Providers

General integrations

RAG integrations

概述

集成详情

工具特性

设置

凭证

实例化

可用工具包

调用

从多个工具包获取工具

获取特定工具

用户特定工具

在代理中使用

与 GitHub 工具包一起使用

身份验证设置

多用户场景

事件驱动工作流

创建触发器

订阅触发器（开发）

类型安全的触发器处理

Webhook（生产环境）

高级功能

自定义工具

独立工具

基于工具包的工具

细粒度权限

API 参考

Popular Providers

General integrations

RAG integrations

​概述

​集成详情

​工具特性

​设置

​凭证

​实例化

​可用工具包

​调用

​从多个工具包获取工具

​获取特定工具

​用户特定工具

​在代理中使用

​与 GitHub 工具包一起使用

​身份验证设置

​多用户场景

​事件驱动工作流

​创建触发器

​订阅触发器（开发）

​类型安全的触发器处理

​Webhook（生产环境）

​高级功能

​自定义工具

​独立工具

​基于工具包的工具

​细粒度权限

​API 参考

概述

集成详情

工具特性

设置

凭证

实例化

可用工具包

调用

从多个工具包获取工具

获取特定工具

用户特定工具

在代理中使用

与 GitHub 工具包一起使用

身份验证设置

多用户场景

事件驱动工作流

创建触发器

订阅触发器（开发）

类型安全的触发器处理

Webhook（生产环境）

高级功能

自定义工具

独立工具

基于工具包的工具

细粒度权限

API 参考