Agent 集成总览

Open Connector 专为需要代表用户行动的 AI Agent 而构建 — 创建 GitHub Issue、发送 Telegram 消息等。本章节介绍 Agent 如何进行认证、如何引用用户凭证，以及工具调用是如何执行的。

Agent 认证模型

Agent 通过在 x-api-key 请求头中传递范围化 API Key 来向 Open Connector 进行认证。每个 Key 绑定到特定的项目，项目隶属于某个组织。Key 的元数据同时携带 projectId 和 orgId，因此每个请求都能归属到正确的租户，Agent 无需单独传递这些值。

Agent 请求
  Header: x-api-key: oc_abc123...
                         └─ 解析后 → { projectId: "proj_...", orgId: "org_..." }

这种模型意味着：

Agent 永远不持有用户 OAuth Token。 Token 加密存储在保险库中，由服务端注入。
作用范围在 Key 级别强制执行。 项目 A 的 Key 无法访问属于项目 B 的连接。
Key 可以轮换。 如果某个 Key 泄露，在控制台撤销即可 — 现有连接不受影响。

典型 Agent 工作流

创建 Agent API Key

在 Open Connector 控制台为项目创建 Key。可信的管理工具也可以使用已登录的 Console Session 调用 POST /api/v1/console/orgs/{organizationId}/projects/{projectId}/api-keys。请把返回的 Key 作为 Secret 存储在 Agent 运行环境中。

为每个用户创建连接

当用户想要关联其 GitHub 账号时，您的 Agent（或后端服务）调用 POST /composio/api/v3.1/connected_accounts，传入对应的 auth_config id。Open Connector 返回 redirect_url，将用户引导至该 URL；回调由 Open Connector 自动处理，Token 加密存储后连接状态变为活跃。

代表已连接用户调用工具

连接建立后，Agent 调用 POST /composio/api/v3.1/tools/execute/{slug}，传入 connected_account_id。Open Connector 解密 Token，将其注入到对第三方 API 的出站请求中，并将响应返回。Agent 始终不会看到原始 Token。

SDK

官方 SDK 使用 Open Connector 原生类型化 API；已有集成仍可使用 Composio 兼容层：

import { createClient } from "@open-connector/sdk";

const oc = createClient({
  apiKey: process.env.OPEN_CONNECTOR_API_KEY!,
  baseUrl: "https://api.openconnector.dev",
});

import Composio from "@composio/client";

const composio = new Composio({
  apiKey: process.env.OPEN_CONNECTOR_API_KEY!,
  baseURL: "https://api.openconnector.dev/composio",
});

原生与兼容 API 的说明请参见 SDK。

Agent 认证模型

典型 Agent 工作流

SDK

Agent API Key

SDK

oc CLI

连接账户

调用工具

On this page