Skip to content

AGENT_PROTOCOLS_GUIDE.md

Latest commit

 

History

History
284 lines (215 loc) · 18.9 KB

AGENT_PROTOCOLS_GUIDE.md

File metadata and controls

284 lines (215 loc) · 18.9 KB
Raw

Agent Protocols Guide (Tiếng Việt)

🌐 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 · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

Nguồn: src/lib/{a2a,acp,cloudAgent}/, src/app/api/{a2a,acp,cloud}/, src/app/api/v1/agents/ Cập nhật lần cuối: 2026-06-28 — v3.8.40

OmniRoute cung cấp ba giao diện khác nhau liên quan đến agent. Thoạt nhìn, chúng có vẻ giống nhau nhưng giải quyết các vấn đề khác nhau. Hãy sử dụng trang này để chọn giao diện phù hợp.

Tóm tắt nhanh

Giao diện Phù hợp nhất cho Phương thức truyền tải Tiêu chuẩn
A2A — Agent-to-Agent Cộng tác liên agent với các agent ngang hàng hỗ trợ giao thức A2A JSON-RPC 2.0 qua HTTP A2A v0.3 (đặc tả mở)
ACP — CLI Agents Registry Phát hiện / đăng ký / khởi chạy các agent lập trình CLI được cài đặt trên máy của người dùng (Cursor, Cline, Codex CLI, Claude Code, Aider, v.v.) HTTP REST Dành riêng cho OmniRoute
Cloud Agents Gửi các tác vụ lập trình kéo dài đến các dịch vụ đám mây bên ngoài (Codex Cloud, Devin, Jules, Cursor Cloud) HTTP REST + tác vụ lưu trên DB Dành riêng cho OmniRoute

Cả ba đều độc lập — có thể chọn bất kỳ tập hợp con nào.

Cây quyết định

Bạn có cần một dịch vụ đám mây thực hiện công việc bên ngoài máy này không (Codex Cloud / Cursor Cloud / Devin / Jules)?
├─ CÓ → Cloud Agents (POST /api/v1/agents/tasks)
└─ KHÔNG → Tiếp tục
    │
    Bạn có một agent ngang hàng hỗ trợ A2A và muốn cộng tác không?
    ├─ CÓ → A2A (POST /a2a)
    └─ KHÔNG → Tiếp tục
        │
        Bạn có cần liệt kê / cấu hình các agent lập trình CLI được cài đặt cục bộ không?
        ├─ CÓ → ACP (GET /api/acp/agents)
        └─ KHÔNG → Sử dụng trực tiếp /v1/chat/completions

1. A2A — Agent-to-Agent

Đặc tả: A2A v0.3 Điểm cuối OmniRoute: POST /a2a (JSON-RPC 2.0) Thẻ Agent: GET /.well-known/agent.json

Khi nào nên sử dụng

  • Xây dựng hệ thống đa agent, trong đó OmniRoute là một trong các agent ngang hàng
  • Cung cấp khả năng định tuyến thông minh của OmniRoute (smart-routing, quota-management, v.v.) cho các agent trong những framework như Google ADK hoặc các mạng lưới agent tổng quát
  • Bao bọc OmniRoute phía sau một giao diện khám phá + gọi thực thi tiêu chuẩn

Phương thức

  • message/send — gửi một thông điệp và nhận phản hồi đồng bộ
  • message/stream — gửi thông điệp + nhận các sự kiện tiến trình được truyền phát qua SSE
  • tasks/get — đọc tác vụ theo ID
  • tasks/cancel — hủy một tác vụ đang chạy

Kỹ năng tích hợp sẵn (6)

  • smart-routing — định tuyến lời nhắc qua tổ hợp tối ưu
  • quota-management — báo cáo trạng thái hạn ngạch của từng nhà cung cấp
  • provider-discovery — liệt kê các nhà cung cấp đã cài đặt cùng khả năng của họ
  • cost-analysis — ước tính chi phí của một yêu cầu/cuộc hội thoại
  • health-report — tổng hợp trạng thái ngắt mạch/thời gian chờ/khóa của từng nhà cung cấp
  • list-capabilities — liệt kê các kỹ năng và siêu dữ liệu hiện có của agent

Tìm hiểu chuyên sâu

Xem A2A-SERVER.md để biết chi tiết về phương thức truyền tải, cấu trúc thẻ agent, cấu hình TTL của tác vụ và mẫu để thêm kỹ năng mới.

2. ACP — Sổ đăng ký CLI Agent

Endpoint OmniRoute: GET /api/acp/agents Mã nguồn: src/lib/acp/{index,manager,registry}.ts

Đây là gì

ACP là kho kiểm kê CLI agent cục bộ của OmniRoute. Nó phát hiện những CLI lập trình nào được cài đặt trên máy chủ (Cursor, Cline, Claude Code, Codex CLI, Continue, v.v.), xác định phiên bản của chúng và hiển thị chúng trên bảng điều khiển để người dùng có thể cấu hình từng CLI trỏ đến OmniRoute.

Đây KHÔNG phải là một giao thức bên ngoài — đây là sổ đăng ký nội bộ hỗ trợ giao diện người dùng "CLI Tools" và việc theo dõi dấu vân tay CLI (xem CLI-TOOLS.md).

Chức năng

  • Kiểm tra máy chủ để tìm các tệp nhị phân CLI đã cài đặt (sử dụng which / where tùy theo hệ điều hành)
  • Đọc phiên bản của từng CLI (gọi <bin> --version)
  • Cho phép tùy chọn thêm các agent tùy chỉnh do người dùng định nghĩa (đường dẫn tệp nhị phân + lệnh kiểm tra phiên bản + đối số khởi chạy)
  • Lưu trữ lâu dài các agent tùy chỉnh trong phần cài đặt
  • Trả về danh sách hợp nhất cho bảng điều khiển

REST API

Endpoint Phương thức Mô tả Xác thực
/api/acp/agents GET Liệt kê agent được phát hiện + tùy chỉnh (số lượng đã cài đặt/tổng cộng) API key
/api/acp/agents POST Thêm/cập nhật/xóa agent tùy chỉnh (phân biệt hành động trong phần thân) API key

Cấu trúc phần thân cho POST (customAgentBodySchema trong src/app/api/acp/agents/route.ts):

{
  "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"
}

Trường hợp sử dụng

  • Trang "CLI Tools" trên bảng điều khiển liệt kê những công cụ đã cài đặt và giúp bạn cấu hình từng công cụ trỏ đến OmniRoute
  • Agent tùy chỉnh cho phép người dùng nâng cao đăng ký các CLI nội bộ/độc quyền mà OmniRoute chưa biết theo mặc định
  • Kết quả phát hiện cung cấp dữ liệu cho ma trận dấu vân tay cli-tools

Khi KHÔNG nên sử dụng ACP

  • ACP không chạy tác vụ. Nó chỉ phát hiện + cấu hình CLI. Để thực sự gọi một CLI, bạn cần tự khởi chạy CLI đó với các biến môi trường do OmniRoute cung cấp (OPENAI_BASE_URL, OPENAI_API_KEY, v.v.).

3. Cloud Agent

Các endpoint OmniRoute: /api/v1/agents/tasks/* (vòng đời) + /api/cloud/* (hạ tầng kết nối) Mã nguồn: src/lib/cloudAgent/

Đây là gì

Một giao diện thống nhất dành cho các agent lập trình đám mây của bên thứ ba. Bạn gửi một lời nhắc + URL kho mã nguồn, OmniRoute sẽ chuyển tiếp đến đúng cloud agent, thăm dò trạng thái và trả về kết quả.

Các agent được hỗ trợ (4, tất cả đều được xác nhận trong src/lib/cloudAgent/agents/)

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

Vòng đời

POST /api/v1/agents/tasks
  → BaseAgent.createTask() cho từng lớp agent
  → dịch vụ bên ngoài bắt đầu xử lý
  → hàng tác vụ được tạo trong DB (cloud_agent_tasks)
  ↓
GET /api/v1/agents/tasks/[id]
  → đồng bộ trạng thái trì hoãn từ nhà cung cấp
  → trả về trạng thái hiện tại + kế hoạch + nhật ký hoạt động
  ↓
POST /api/v1/agents/tasks/[id]   (action: "approve" | "message" | "cancel")
  → chuyển tiếp đến nhà cung cấp (hoặc đánh dấu đã hủy cục bộ)
  ↓
DELETE /api/v1/agents/tasks/[id]
  → hủy cục bộ

Xác thực

⚠️ Tất cả endpoint /api/v1/agents/tasks/* đều yêu cầu xác thực quản trị (commit 588a0333). Các trình gọi chỉ sử dụng Bearer sẽ nhận mã 401 kể từ v3.8.0.

Tìm hiểu chuyên sâu

Xem CLOUD_AGENT.md để biết hợp đồng CloudAgentBase, thông tin cụ thể của từng agent, chi tiết schema và các endpoint phục vụ việc kết nối thông tin xác thực.

So sánh: A2A và Cloud Agents

Cả hai đều có "tác vụ chạy trong thời gian dài" nhưng ở các tầng khác nhau:

Khía cạnh A2A Cloud Agents
Tiêu chuẩn Open A2A v0.3 Đặc thù của OmniRoute
Nơi thực hiện tính toán Bên trong OmniRoute (sử dụng các tổ hợp đã cấu hình) Bên ngoài (máy chủ Codex / Devin / Jules)
Thời lượng tác vụ TTL mặc định là 5 phút (có thể cấu hình trong TaskManager) Từ vài phút đến vài giờ
Nhận biết kho mã nguồn Không (chỉ chuyển tiếp prompt) Có (URL kho mã nguồn + nhánh)
Trường hợp sử dụng Cộng tác giữa các tác nhân, định tuyến thông minh dưới dạng dịch vụ Ủy quyền "triển khai tính năng X trong kho Y"
Xác thực OMNIROUTE_API_KEY tùy chọn cho /a2a; quyền quản trị cho các trình trợ giúp REST /api/a2a/* Luôn yêu cầu quyền quản trị

Ví dụ tích hợp

Khám phá các khả năng A2A của OmniRoute

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

Trả về Agent Card chứa đầy đủ cả 6 kỹ năng, phương thức vận chuyển và phiên bản.

Gọi OmniRoute dưới dạng một tác nhân 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": "Định tuyến prompt này"}],
      "skill": "smart-routing"
    },
    "id": 1
  }'

Liệt kê các tác nhân CLI đã cài đặt thông qua ACP

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

Thêm một tác nhân CLI tùy chỉnh

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": "CLI tùy chỉnh của tôi",
    "binary": "/opt/mycli/bin/mycli",
    "versionCommand": "--version",
    "providerAlias": "openai"
  }'

Gửi một tác vụ 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": "Triển khai tính năng X trong kho Y",
    "source": {
      "repoName": "user/repo",
      "repoUrl": "https://github.com/user/repo",
      "branch": "main"
    }
  }'

Thăm dò trạng thái tác vụ đám mây

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

Khi nào nên sử dụng giải pháp nào

  • Giao diện chatbot / copilot → /v1/chat/completions (tương thích OpenAI — không phải giao thức tác nhân)
  • Cộng tác đa tác nhân → A2A
  • Liệt kê các CLI cục bộ trong bảng điều khiển → ACP
  • Ủy quyền các tác vụ lập trình chạy trong thời gian dài cho dịch vụ đám mây → Cloud Agents

Kiến trúc nội bộ

                ┌─────────────────────┐
                │   Lõi OmniRoute     │
                └─────────────────────┘
                  ↑       ↑        ↑
        ┌─────────┘       │        └─────────┐
        │                 │                  │
    ┌───────┐        ┌─────────┐       ┌────────────┐
    │  A2A  │        │   ACP   │       │ Tác nhân   │
    │ (/a2a)│        │ (/acp)  │       │ đám mây    │
    └───────┘        └─────────┘       │ (/v1/agents│
        │                 │            │  /tasks)   │
        ↓                 ↓            └────────────┘
   Các tác nhân      Các tệp nhị phân       │
   ngang hàng bên    CLI cục bộ trên         ↓
   ngoài dùng A2A    máy chủ            Codex Cloud, Cursor,
   v0.3                                  Devin, Jules

Xem thêm

  • A2A-SERVER.md — Tìm hiểu chuyên sâu về A2A
  • CLOUD_AGENT.md — Tìm hiểu chuyên sâu về Tác nhân đám mây
  • CLI-TOOLS.md — Các tích hợp CLI bên ngoài (sử dụng ACP)
  • SKILLS.md — Khung kỹ năng (khác với kỹ năng A2A — sandbox thực thi cục bộ)
  • API_REFERENCE.md — tài liệu tham khảo về endpoint
  • Nguồn: src/lib/{a2a,acp,cloudAgent}/