调用工具

工具调用是 Open Connector 的核心功能。Agent 向执行端点发送一个请求，Open Connector 完成凭证解密、注入，代理执行到第三方 API，并将结果返回给 Agent — 整个过程中 Agent 始终不会接触到原始 Token。

执行端点

POST /composio/api/v3.1/tools/execute/{slug}

slug — 工具标识符，采用 TOOLKIT_ACTION_NAME 格式，例如 GITHUB_CREATE_AN_ISSUE

请求体中 connected_account_id（要使用的连接）和 user_id（让 Open Connector 自动解析该用户的连接）二选一，工具参数放在 arguments 下。

基本工具调用示例

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

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

const result = await oc.executeTool({
  slug: "GITHUB_CREATE_AN_ISSUE",
  connectedAccountId: "conn_01j9xyz789",
  arguments: {
    owner: "my-org",
    repo: "my-repo",
    title: "Agent 检测到的问题",
    body: "Agent 在生产环境中发现了一个异常情况。",
  },
});

import Composio from "@composio/client";

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

const result = await composio.tools.execute("GITHUB_CREATE_AN_ISSUE", {
  connected_account_id: "conn_01j9xyz789",
  arguments: {
    owner: "my-org",
    repo: "my-repo",
    title: "Agent 检测到的问题",
    body: "Agent 在生产环境中发现了一个异常情况。",
  },
});

curl -X POST "https://api.openconnector.dev/composio/api/v3.1/tools/execute/GITHUB_CREATE_AN_ISSUE" \
  -H "x-api-key: oc_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{
    "connected_account_id": "conn_01j9xyz789",
    "arguments": {
      "owner": "my-org",
      "repo": "my-repo",
      "title": "Agent 检测到的问题",
      "body": "Agent 在生产环境中发现了一个异常情况。"
    }
  }'

响应示例：

{
  "data": {
    "id": 1234567890,
    "number": 42,
    "html_url": "https://github.com/my-org/my-repo/issues/42",
    "title": "Agent 检测到的问题",
    "state": "open"
  },
  "error": null,
  "successful": true,
  "session_info": null,
  "log_id": "key_01j9def456"
}

工具调用执行流程

每次工具调用都经过以下处理步骤：

1. 验证 x-api-key → 解析 projectId + orgId
2. 加载连接账户（验证归属于该 projectId）
3. 从加密保险库解密 OAuth Token（AES-256-GCM 解密）
4. 如需要，自动刷新 Access Token
5. 向第三方 API 发送请求（注入 Authorization 头）
6. 写入审计日志（哈希链追加）
7. 将 API 响应代理返回给 Agent

其他连接器的工具调用示例

Telegram：发送消息

const result = await oc.executeTool({
  slug: "TELEGRAM_SEND_MESSAGE",
  connectedAccountId: "conn_telegram_user123",
  arguments: { chat_id: "123456789", text: "Agent 任务已完成，结果已就绪。" },
});

const result = await composio.tools.execute("TELEGRAM_SEND_MESSAGE", {
  connected_account_id: "conn_telegram_user123",
  arguments: { chat_id: "123456789", text: "Agent 任务已完成，结果已就绪。" },
});

发现可用工具

要查看可用的工具，查询工具目录。用 toolkit_slug 按连接器过滤：

curl "https://api.openconnector.dev/composio/api/v3.1/tools?toolkit_slug=github" \
  -H "x-api-key: oc_abc123xyz..."

响应中包含工具的 slug 与描述；查询单个 Tool 可以获取输入 Schema：

const tools = await oc.listTools({ toolkit: "github", limit: 100 });

for (const tool of tools.items) {
  const detail = await oc.getTool({ slug: tool.slug });
  console.log(detail.slug, detail.inputParameters);
}

const tools = await composio.tools.list({ toolkit_slug: "github" });

for (const tool of tools.items) {
  console.log(tool.slug, tool.description);
}

错误处理

工具调用可能返回以下错误：

HTTP 状态码	说明
`200`	工具已执行。请检查响应体中的 `successful` — 即使 HTTP 200，第三方 API 也可能返回了错误。
`400`	请求有误，例如缺少 `connected_account_id`/`user_id`，或 `arguments` 格式不正确。
`401`	`x-api-key` 无效或缺失。
`403`	该工具对此连接不被允许，或连接属于其他项目。
`404`	工具 slug 不存在，或无法解析连接。
`408`	第三方请求超时。

失败时，响应体中 successful 为 false，error 字段携带错误说明：

{
  "data": null,
  "error": "GitHub API returned 422: Validation Failed",
  "successful": false,
  "session_info": null,
  "log_id": "key_01j9def456"
}

在 Agent 代码中处理结果：

const result = await oc.executeTool({
  slug: "GITHUB_CREATE_AN_ISSUE",
  connectedAccountId: connectionId,
  arguments: { /* ... */ },
});

if (!result.successful) throw new Error(`Tool failed with status ${result.status}`);

const result = await composio.tools.execute("GITHUB_CREATE_AN_ISSUE", {
  connected_account_id: connectionId,
  arguments: { /* ... */ },
});

if (!result.successful) console.error(result.error);

审计记录

每次工具调用无论成功或失败，都会写入防篡改的审计日志（采用 SHA-256 哈希链），其中包含连接账户 ID、工具 slug、请求时间戳和响应状态。详细说明请参见审计日志文档。

On this page