Agent Protocols Guide (中文 (繁體))

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN

來源： src/lib/{a2a,acp,cloudAgent}/、src/app/api/{a2a,acp,cloud}/、src/app/api/v1/agents/ 最後更新： 2026-06-28 — v3.8.40

OmniRoute 提供三種不同的代理程式相關介面。乍看之下它們很相似，但解決的是不同問題。請使用本頁選擇適合的介面。

簡要說明

介面	最適合的用途	傳輸方式	標準
A2A — 代理程式對代理程式	與支援 A2A 協定的對等代理程式進行跨代理程式協作	透過 HTTP 的 JSON-RPC 2.0	A2A v0.3（開放規範）
ACP — CLI 代理程式登錄庫	偵測／註冊／啟動安裝於使用者電腦上的 CLI 程式設計代理程式（Cursor、Cline、Codex CLI、Claude Code、Aider 等）	HTTP REST	OmniRoute 專用
雲端代理程式	將長時間執行的程式設計任務提交至外部雲端服務（Codex Cloud、Devin、Jules、Cursor Cloud）	HTTP REST + 資料庫支援的任務	OmniRoute 專用

三者彼此獨立——可任選其中任意組合。

決策樹

是否需要雲端服務在此電腦以外執行工作（Codex Cloud / Cursor Cloud / Devin / Jules）？
├─ 是 → 雲端代理程式（POST /api/v1/agents/tasks）
└─ 否 → 繼續
    │
    是否有支援 A2A 且想要協作的對等代理程式？
    ├─ 是 → A2A（POST /a2a）
    └─ 否 → 繼續
        │
        是否需要列出／設定安裝於本機的 CLI 程式設計代理程式？
        ├─ 是 → ACP（GET /api/acp/agents）
        └─ 否 → 使用一般的 /v1/chat/completions

1. A2A — 代理程式對代理程式

規範： A2A v0.3 OmniRoute 端點： POST /a2a（JSON-RPC 2.0） 代理程式資訊卡： GET /.well-known/agent.json

使用時機

建置以 OmniRoute 作為其中一個對等端的多代理程式系統
將 OmniRoute 的路由智慧（智慧路由、配額管理等）提供給 Google ADK 等框架中的代理程式或通用代理程式網狀架構
將 OmniRoute 封裝於標準的探索與呼叫介面之後

方法

message/send — 提交訊息並接收同步回應
message/stream — 提交訊息並接收透過 SSE 串流傳送的進度事件
tasks/get — 依 ID 讀取任務
tasks/cancel — 取消執行中的任務

內建技能（6 項）

smart-routing — 透過最佳組合路由提示詞
quota-management — 回報各提供者的配額狀態
provider-discovery — 列出已安裝的提供者及其功能
cost-analysis — 估算請求／對話的成本
health-report — 彙整各提供者的斷路器／冷卻／鎖定狀態
list-capabilities — 列舉代理程式可用的技能與中繼資料

深入瞭解

如需傳輸詳細資料、代理程式資訊卡結構、任務 TTL 設定，以及新增技能的範本，請參閱 A2A-SERVER.md。

2. ACP — CLI 代理程式登錄檔

OmniRoute 端點： GET /api/acp/agents 原始碼： src/lib/acp/{index,manager,registry}.ts

這是什麼

ACP 是 OmniRoute 的本機 CLI 代理程式清單。它會偵測主機上安裝了哪些程式設計 CLI（Cursor、Cline、Claude Code、Codex CLI、Continue 等），解析其版本，並將這些資訊顯示於儀表板，讓使用者可以將每個 CLI 設定為指向 OmniRoute。

這不是外部協定，而是支援「CLI 工具」UI 與 CLI 指紋追蹤的內部登錄檔（請參閱 CLI-TOOLS.md）。

功能

探測主機上已安裝的 CLI 二進位檔（依作業系統使用 which / where）
讀取每個 CLI 的版本（呼叫 <bin> --version）
可選擇接受使用者定義的自訂代理程式（二進位檔路徑 + 版本探測 + 啟動引數）
將自訂代理程式持久儲存於設定中
將統一清單回傳至儀表板

REST API

端點	方法	說明	驗證
`/api/acp/agents`	GET	列出偵測到的代理程式與自訂代理程式（已安裝數量／總數）	API 金鑰
`/api/acp/agents`	POST	新增／更新／移除自訂代理程式（請求主體中的動作識別欄位）	API 金鑰

POST 的請求主體格式（src/app/api/acp/agents/route.ts 中的 customAgentBodySchema）：

{
  "action": "add|update|remove",
  "id": "cursor",
  "name": "Cursor",
  "binary": "/usr/local/bin/cursor",
  "versionCommand": "--version",
  "providerAlias": "cursor",
  "spawnArgs": ["--api-base", "http://localhost:20128"],
  "protocol": "stdio"
}

使用案例

儀表板的「CLI 工具」頁面會列出已安裝的工具，並協助您將每個工具設定為指向 OmniRoute
自訂代理程式可讓進階使用者登錄 OmniRoute 預設不支援的內部／專有 CLI
偵測結果會提供給 cli-tools 指紋矩陣使用

不應使用 ACP 的情況

ACP 不會_執行_工作。它只會偵測及設定 CLI。若要實際呼叫 CLI，您必須使用 OmniRoute 提供的環境變數（OPENAI_BASE_URL、OPENAI_API_KEY 等）自行啟動。

3. 雲端代理程式

OmniRoute 端點： /api/v1/agents/tasks/*（生命週期）+ /api/cloud/*（底層連接） 原始碼： src/lib/cloudAgent/

這是什麼

這是一個針對第三方雲端程式設計代理程式的統一介面。您提交提示詞與儲存庫 URL 後，OmniRoute 會將工作分派給適當的雲端代理程式、輪詢狀態，並回傳結果。

支援的代理程式（共 4 個，均已在 `src/lib/cloudAgent/agents/` 中確認）

codex-cloud — OpenAI Codex Cloud
devin — Cognition Devin
jules — Google Jules

生命週期

POST /api/v1/agents/tasks
  → 每個代理程式類別的 BaseAgent.createTask()
  → 外部服務開始工作
  → 在 DB 中建立工作資料列（cloud_agent_tasks）
  ↓
GET /api/v1/agents/tasks/[id]
  → 延遲同步提供者的狀態
  → 回傳目前狀態 + 計畫 + 活動記錄
  ↓
POST /api/v1/agents/tasks/[id]   （action: "approve" | "message" | "cancel"）
  → 轉送至提供者（或在本機標記為已取消）
  ↓
DELETE /api/v1/agents/tasks/[id]
  → 在本機取消

驗證

⚠️ 所有 /api/v1/agents/tasks/* 端點皆需要管理驗證（提交 588a0333）。自 v3.8.0 起，僅使用 Bearer 驗證的呼叫者會收到 401。

深入瞭解

如需瞭解 CloudAgentBase 合約、各代理程式的具體資訊、結構描述詳細資料，以及憑證底層連接端點，請參閱 CLOUD_AGENT.md。

比較：A2A 與 Cloud Agents

兩者都有「長時間執行的任務」，但位於不同層級：

面向	A2A	Cloud Agents
標準	開放式 A2A v0.3	OmniRoute 專用
運算執行位置	OmniRoute 內部（使用已設定的組合）	外部（Codex / Devin / Jules 伺服器）
任務持續時間	預設 TTL 為 5 分鐘（可在 `TaskManager` 中設定）	數分鐘至數小時
儲存庫感知能力	無（僅傳遞提示詞）	有（儲存庫 URL + 分支）
使用情境	跨代理協作、將智慧路由作為服務	委派「在儲存庫 Y 中實作功能 X」
驗證	`/a2a` 可選用 `OMNIROUTE_API_KEY`；`/api/a2a/*` REST 輔助功能需管理權限	一律需要管理權限

整合範例

探索 OmniRoute 的 A2A 功能

curl http://localhost:20128/.well-known/agent.json

傳回 Agent Card，其中包含全部 6 項技能、傳輸方式及版本。

將 OmniRoute 作為 A2A 代理呼叫

curl -X POST http://localhost:20128/a2a \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "message/send",
    "params": {
      "messages": [{"role": "user", "content": "Route this prompt"}],
      "skill": "smart-routing"
    },
    "id": 1
  }'

透過 ACP 列出已安裝的 CLI 代理

curl http://localhost:20128/api/acp/agents \
  -H "Authorization: Bearer <api-key>"

新增自訂 CLI 代理

curl -X POST http://localhost:20128/api/acp/agents \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "add",
    "id": "my-custom-cli",
    "name": "My Custom CLI",
    "binary": "/opt/mycli/bin/mycli",
    "versionCommand": "--version",
    "providerAlias": "openai"
  }'

提交 Cloud Agent 任務

curl -X POST http://localhost:20128/api/v1/agents/tasks \
  -H "Cookie: auth_token=..." \
  -H "Content-Type: application/json" \
  -d '{
    "providerId": "devin",
    "prompt": "Implement feature X in repo Y",
    "source": {
      "repoName": "user/repo",
      "repoUrl": "https://github.com/user/repo",
      "branch": "main"
    }
  }'

輪詢雲端任務狀態

curl http://localhost:20128/api/v1/agents/tasks/<task-id> \
  -H "Cookie: auth_token=..."

使用時機

聊天機器人／copilot 前端 → /v1/chat/completions（OpenAI 相容——並非代理協定）
多代理協作 → A2A
在儀表板中列出本機 CLI → ACP
將長時間執行的程式設計任務委派給雲端服務 → Cloud Agents

內部架構

                ┌─────────────────────┐
                │   OmniRoute 核心    │
                └─────────────────────┘
                  ↑       ↑        ↑
        ┌─────────┘       │        └─────────┐
        │                 │                  │
    ┌───────┐        ┌─────────┐       ┌────────────┐
    │  A2A  │        │   ACP   │       │   雲端     │
    │ (/a2a)│        │ (/acp)  │       │   代理     │
    └───────┘        └─────────┘       │ (/v1/agents│
        │                 │            │  /tasks)   │
        ↓                 ↓            └────────────┘
   使用 A2A v0.3    主機上的本機             │
   的外部對等代理    CLI 二進位檔             ↓
                                     Codex Cloud、Cursor、
                                        Devin、Jules

另請參閱

A2A-SERVER.md — A2A 深入解析
CLOUD_AGENT.md — 雲端代理深入解析
CLI-TOOLS.md — 外部 CLI 整合（使用 ACP）
SKILLS.md — 技能框架（不同於 A2A 技能——本機執行沙箱）
API_REFERENCE.md — 端點參考
原始碼：src/lib/{a2a,acp,cloudAgent}/

Navigation Menu

Repository navigation

AGENT_PROTOCOLS_GUIDE.md

AGENT_PROTOCOLS_GUIDE.md

Agent Protocols Guide (中文 (繁體))

簡要說明

決策樹

1. A2A — 代理程式對代理程式

使用時機

方法

內建技能（6 項）

深入瞭解

2. ACP — CLI 代理程式登錄檔

這是什麼

功能

REST API

使用案例

不應使用 ACP 的情況

3. 雲端代理程式

這是什麼

支援的代理程式（共 4 個，均已在 `src/lib/cloudAgent/agents/` 中確認）

生命週期

驗證

深入瞭解

比較：A2A 與 Cloud Agents

整合範例

探索 OmniRoute 的 A2A 功能

將 OmniRoute 作為 A2A 代理呼叫

透過 ACP 列出已安裝的 CLI 代理

新增自訂 CLI 代理

提交 Cloud Agent 任務

輪詢雲端任務狀態

使用時機

內部架構

另請參閱

FilesExpand file tree

AGENT_PROTOCOLS_GUIDE.md

Latest commit

History

AGENT_PROTOCOLS_GUIDE.md

File metadata and controls

Agent Protocols Guide (中文 (繁體))

簡要說明

決策樹

1. A2A — 代理程式對代理程式

使用時機

方法

內建技能（6 項）

深入瞭解

2. ACP — CLI 代理程式登錄檔

這是什麼

功能

REST API

使用案例

不應使用 ACP 的情況

3. 雲端代理程式

這是什麼

支援的代理程式（共 4 個，均已在 src/lib/cloudAgent/agents/ 中確認）

生命週期

驗證

深入瞭解

比較：A2A 與 Cloud Agents

整合範例

探索 OmniRoute 的 A2A 功能

將 OmniRoute 作為 A2A 代理呼叫

透過 ACP 列出已安裝的 CLI 代理

新增自訂 CLI 代理

提交 Cloud Agent 任務

輪詢雲端任務狀態

使用時機

內部架構

另請參閱

支援的代理程式（共 4 個，均已在 `src/lib/cloudAgent/agents/` 中確認）