OmniRoute/docs/i18n/phi/docs/frameworks/AGENT_PROTOCOLS_GUIDE.md

Agent Protocols Guide (Filipino)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 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 · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

Pinagmulan: src/lib/{a2a,acp,cloudAgent}/, src/app/api/{a2a,acp,cloud}/, src/app/api/v1/agents/ Huling na-update: 2026-06-28 — v3.8.40

Nagbibigay ang OmniRoute ng tatlong magkakaibang interface na nauugnay sa mga agent. Sa unang tingin, magkakahawig ang mga ito ngunit magkakaibang problema ang nilulutas ng mga ito. Gamitin ang pahinang ito upang piliin ang naaangkop.

TL;DR

Interface	Pinakamainam para sa	Transportasyon	Pamantayan
A2A — Agent-to-Agent	Pakikipagtulungan sa iba't ibang agent na gumagamit ng A2A protocol	JSON-RPC 2.0 sa HTTP	A2A v0.3 (bukas na espesipikasyon)
ACP — CLI Agents Registry	Pagtukoy / pagrerehistro / paglulunsad ng mga CLI coding agent na naka-install sa computer ng user (Cursor, Cline, Codex CLI, Claude Code, Aider, atbp.)	HTTP REST	Partikular sa OmniRoute
Cloud Agents	Pagsusumite ng matatagal na coding task sa mga panlabas na cloud service (Codex Cloud, Devin, Jules, Cursor Cloud)	HTTP REST + mga task na suportado ng DB	Partikular sa OmniRoute

Magkakahiwalay ang tatlo — pumili ng anumang subset.

Puno ng Pagpapasya

Kailangan mo ba ng cloud service upang gumawa ng trabaho sa labas ng computer na ito (Codex Cloud / Cursor Cloud / Devin / Jules)?
├─ OO → Cloud Agents (POST /api/v1/agents/tasks)
└─ HINDI → Magpatuloy
    │
    Mayroon ka bang kapwa agent na gumagamit ng A2A at gustong makipagtulungan?
    ├─ OO → A2A (POST /a2a)
    └─ HINDI → Magpatuloy
        │
        Kailangan mo bang ilista / i-configure ang mga CLI coding agent na lokal na naka-install?
        ├─ OO → ACP (GET /api/acp/agents)
        └─ HINDI → Gamitin ang karaniwang /v1/chat/completions

1. A2A — Agent-to-Agent

Espesipikasyon: A2A v0.3 Endpoint ng OmniRoute: POST /a2a (JSON-RPC 2.0) Agent Card: GET /.well-known/agent.json

Kailan gagamitin

• Pagbuo ng multi-agent system kung saan isa ang OmniRoute sa mga kapwa agent
• Pagbibigay sa mga agent ng routing intelligence ng OmniRoute (smart-routing, quota-management, atbp.) sa mga framework tulad ng Google ADK o mga generic na agent mesh
• Paglalagay sa OmniRoute sa likod ng isang pamantayang interface para sa discovery + invocation

Mga method

• message/send — magsumite ng mensahe at tumanggap ng sabayang tugon
• message/stream — magsumite at tumanggap ng mga progress event na ini-stream sa SSE
• tasks/get — basahin ang task ayon sa ID
• tasks/cancel — kanselahin ang tumatakbong task

Mga built-in na skill (6)

• smart-routing — iruta ang isang prompt sa pinakamainam na combo
• quota-management — iulat ang estado ng quota ng bawat provider
• provider-discovery — ilista ang mga naka-install na provider kasama ang kanilang mga kakayahan
• cost-analysis — tantiyahin ang halaga ng isang request/conversation
• health-report — pagsama-samahin ang estado ng breaker/cooldown/lockout ng bawat provider
• list-capabilities — isa-isahin ang mga available na skill at metadata ng agent

Mas malalim na talakayan

Tingnan ang A2A-SERVER.md para sa mga detalye ng transportasyon, istruktura ng agent card, configuration ng task TTL, at template para sa pagdaragdag ng mga bagong skill.

2. ACP — Rehistro ng mga CLI Agent

OmniRoute endpoint: GET /api/acp/agents Source: src/lib/acp/{index,manager,registry}.ts

Ano ito

Ang ACP ay ang lokal na imbentaryo ng mga CLI agent ng OmniRoute. Tinutukoy nito kung aling mga coding CLI ang naka-install sa host (Cursor, Cline, Claude Code, Codex CLI, Continue, atbp.), kinukuha ang mga bersyon ng mga ito, at ipinapakita ang mga ito sa dashboard upang maituro ng user ang bawat CLI sa OmniRoute.

HINDI ito isang panlabas na protocol — isa itong panloob na rehistro na nagpapatakbo sa UI na "CLI Tools" at sa pagsubaybay ng CLI fingerprint (tingnan ang CLI-TOOLS.md).

Ano ang ginagawa nito

• Sinusuri ang host para sa mga naka-install na CLI binary (gumagamit ng which / where depende sa OS)
• Binabasa ang bersyon ng bawat CLI (tinatawag ang <bin> --version)
• Opsyonal na tumatanggap ng mga custom agent na tinukoy ng user (binary path + version probe + spawn args)
• Iniimbak ang mga custom agent sa mga setting
• Ibinabalik ang pinagsamang listahan sa dashboard

REST API

Endpoint	Pamamaraan	Paglalarawan	Awtorisasyon
/api/acp/agents	GET	Ilista ang mga natukoy + custom agent (bilang ng naka-install/kabuuan)	API key
/api/acp/agents	POST	Magdagdag/mag-update/mag-alis ng custom agent (action discriminator sa body)	API key

Anyo ng body para sa POST (customAgentBodySchema sa 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"
}

Mga gamit

• Inililista ng page na "CLI Tools" sa dashboard kung ano ang naka-install at tinutulungan kang ituro ang bawat isa sa OmniRoute
• Nagbibigay-daan ang mga custom agent sa mga power user na irehistro ang mga panloob/proprietaryong CLI na hindi kilala ng OmniRoute bilang default
• Ginagamit ang resulta ng pagtukoy upang punan ang cli-tools fingerprint matrix

Kailan HINDI dapat gamitin ang ACP

• Hindi nagpapatakbo ng mga task ang ACP. Tinutukoy at kino-configure lamang nito ang mga CLI. Upang aktuwal na gamitin ang isang CLI, ikaw mismo ang maglunsad nito gamit ang mga env var na ibinibigay ng OmniRoute (OPENAI_BASE_URL, OPENAI_API_KEY, atbp.).

3. Mga Cloud Agent

OmniRoute endpoints: /api/v1/agents/tasks/* (lifecycle) + /api/cloud/* (plumbing) Source: src/lib/cloudAgent/

Ano ito

Isang pare-parehong interface para sa mga third-party na cloud coding agent. Magsusumite ka ng prompt + repo URL, ipapadala ito ng OmniRoute sa tamang cloud agent, pana-panahong susuriin ang status, at ibabalik ang mga resulta.

Mga sinusuportahang agent (4, lahat ay nakumpirma sa src/lib/cloudAgent/agents/)

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

Lifecycle

POST /api/v1/agents/tasks
  → BaseAgent.createTask() para sa bawat agent class
  → magsisimulang gumawa ang panlabas na serbisyo
  → gagawa ng task row sa DB (cloud_agent_tasks)
  ↓
GET /api/v1/agents/tasks/[id]
  → lazy na pag-sync ng status mula sa provider
  → ibabalik ang kasalukuyang status + plano + tala ng aktibidad
  ↓
POST /api/v1/agents/tasks/[id]   (action: "approve" | "message" | "cancel")
  → ipapasa sa provider (o lokal na mamarkahang nakansela)
  ↓
DELETE /api/v1/agents/tasks/[id]
  → lokal na pagkansela

Awtorisasyon

⚠️ Nangangailangan ng management auth ang lahat ng /api/v1/agents/tasks/* endpoint (commit 588a0333). Makakatanggap ng 401 ang mga caller na Bearer-only mula noong v3.8.0.

Mas malalim na talakayan

Tingnan ang CLOUD_AGENT.md para sa kontrata ng CloudAgentBase, mga detalye ng bawat agent, mga detalye ng schema, at mga endpoint para sa credential plumbing.

Paghahambing: A2A vs Cloud Agents

Parehong may "mga matagal na tumatakbong gawain" ang dalawa ngunit nasa magkaibang layer:

Aspeto	A2A	Cloud Agents
Pamantayan	Open A2A v0.3	Partikular sa OmniRoute
Saan isinasagawa ang compute	Sa loob ng OmniRoute (gumagamit ng mga naka-configure na combo)	External (mga server ng Codex / Devin / Jules)
Tagal ng gawain	Default na TTL na 5 min (maaaring i-configure sa TaskManager)	Ilang minuto hanggang ilang oras
May kaalaman sa repo	Wala (mga prompt lamang ang ipinapasa)	Oo (URL ng repo + branch)
Gamit	Pakikipagtulungan sa pagitan ng mga agent, smart routing bilang serbisyo	Italaga ang "ipatupad ang feature X sa repo Y"
Auth	Opsyonal na OMNIROUTE_API_KEY para sa /a2a; management para sa mga REST helper ng /api/a2a/*	Laging management

Mga Halimbawa ng Integration

Tuklasin ang mga kakayahan ng A2A ng OmniRoute

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

Ibinabalik ang Agent Card kasama ang lahat ng 6 na skill, transport, at bersyon.

Tawagin ang OmniRoute bilang A2A agent

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
  }'

Ilista ang mga naka-install na CLI agent sa pamamagitan ng ACP

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

Magdagdag ng custom na CLI agent

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

Magsumite ng gawain sa 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"
    }
  }'

Suriin nang pana-panahon ang status ng cloud task

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

Kailan Gagamitin ang Bawat Isa

• Frontend ng chatbot / copilot → /v1/chat/completions (compatible sa OpenAI — hindi isang agent protocol)
• Pakikipagtulungan ng maraming agent → A2A
• Paglilista ng mga lokal na CLI sa dashboard → ACP
• Pagtatalaga ng mga matagal na coding task sa mga cloud service → Cloud Agents

Panloob na Arkitektura

                ┌─────────────────────┐
                │   OmniRoute Core    │
                └─────────────────────┘
                  ↑       ↑        ↑
        ┌─────────┘       │        └─────────┐
        │                 │                  │
    ┌───────┐        ┌─────────┐       ┌────────────┐
    │  A2A  │        │   ACP   │       │ Mga Cloud  │
    │ (/a2a)│        │ (/acp)  │       │  Agent     │
    └───────┘        └─────────┘       │ (/v1/agents│
        │                 │            │  /tasks)   │
        ↓                 ↓            └────────────┘
 Mga panlabas na     Mga lokal na CLI        │
 peer agent na       binary sa host          ↓
 gumagamit ng A2A v0.3                Codex Cloud, Cursor,
                                      Devin, Jules

Tingnan Din

• A2A-SERVER.md — Masusing talakay sa A2A
• CLOUD_AGENT.md — Masusing talakay sa Mga Cloud Agent
• CLI-TOOLS.md — Mga integrasyon sa panlabas na CLI (gumagamit ng ACP)
• SKILLS.md — Balangkas ng mga skill (iba sa mga skill ng A2A — lokal na sandbox ng pagpapatupad)
• API_REFERENCE.md — sanggunian ng endpoint
• Pinagmulan: src/lib/{a2a,acp,cloudAgent}/