OmniRoute/docs/i18n/phi/docs/frameworks/A2A-SERVER.md

OmniRoute A2A Server Documentation (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

---

Agent-to-Agent Protocol v0.3 — OmniRoute bilang isang matalinong ahente sa pagruruta

May dalawang anyo ang A2A surface:

• JSON-RPC 2.0 sa POST /a2a (pangunahing entry point, na tinukoy sa src/app/a2a/route.ts).
• REST sa ilalim ng /api/a2a/* para sa mga dashboard at tooling (status, listahan ng gawain, pagkansela).

Sinusubaybayan ang mga gawain ng A2ATaskManager (src/lib/a2a/taskManager.ts, default na 5 minutong TTL). Ipinapadala ang mga skill sa pamamagitan ng A2A_SKILL_HANDLERS sa src/lib/a2a/taskExecution.ts.

Pagtuklas sa Ahente

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

Ibinabalik nito ang Agent Card na naglalarawan sa mga kakayahan, skill, at kinakailangan sa pagpapatotoo ng OmniRoute.

Ang field na version ng Agent Card ay kinukuha mula sa process.env.npm_package_version (tingnan ang src/app/.well-known/agent.json/route.ts:13), kaya awtomatiko itong nananatiling naka-sync sa package.json sa bawat release.

---

Pagpapatotoo

Nangangailangan ang lahat ng kahilingan sa /a2a ng API key sa pamamagitan ng header na Authorization:

Authorization: Bearer YOUR_OMNIROUTE_API_KEY

Kung walang API key na naka-configure sa server, nilalaktawan ang pagpapatotoo.

Pagpapagana

Kinokontrol ang A2A ng toggle na Endpoints → A2A at naka-disable ito bilang default. Kapag naka-disable, iniuulat ng GET /api/a2a/status ang status: "disabled" at online: false; ang mga JSON-RPC call sa POST /a2a ay nagbabalik ng HTTP 503 na may JSON-RPC error code na -32000.

---

Mga Pamamaraan ng JSON-RPC 2.0

message/send — Sabayang Pagpapatupad

Nagpapadala ng mensahe sa isang skill at naghihintay sa kumpletong tugon.

curl -X POST http://localhost:20128/a2a \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/send",
    "params": {
      "skill": "smart-routing",
      "messages": [{"role": "user", "content": "Write a hello world in Python"}],
      "metadata": {"model": "auto", "combo": "fast-coding"}
    }
  }'

Tugon:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "task": { "id": "uuid", "state": "completed" },
    "artifacts": [{ "type": "text", "content": "..." }],
    "metadata": {
      "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)",
      "cost_envelope": {
        "estimated": 0.005,
        "actual": 0.003,
        "currency": "USD"
      },
      "resilience_trace": [
        {
          "event": "primary_selected",
          "provider": "anthropic",
          "timestamp": "..."
        }
      ],
      "policy_verdict": {
        "allowed": true,
        "reason": "within budget and quota limits"
      }
    }
  }
}

message/stream — SSE Streaming

Kapareho ito ng message/send, ngunit nagbabalik ng Server-Sent Events para sa real-time streaming.

curl -N -X POST http://localhost:20128/a2a \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/stream",
    "params": {
      "skill": "smart-routing",
      "messages": [{"role": "user", "content": "Explain quantum computing"}]
    }
  }'

Mga SSE Event:

data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}}

: heartbeat 2026-03-03T17:00:00Z

data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}}

tasks/get — Suriin ang Status ng Gawain

curl -X POST http://localhost:20128/a2a \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}'

tasks/cancel — Kanselahin ang isang Gawain

curl -X POST http://localhost:20128/a2a \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}'

---

Mga Available na Skill

Naglalantad ang OmniRoute ng 6 na A2A skill na nakakonekta sa src/lib/a2a/taskExecution.ts::A2A_SKILL_HANDLERS. Matatagpuan ang bawat module ng skill sa src/lib/a2a/skills/.

Skill	ID	Paglalarawan	Mga Tag	Mga Halimbawa
Matalinong Pag-route	smart-routing	Dinaraanan ang isang prompt sa pinakamainam na provider/combo gamit ang combo engine at pagmamarka ng OmniRoute	routing, providers	"I-route ang prompt na ito gamit ang pinakamahusay na modelo"
Pamamahala ng Quota	quota-management	Iniuulat ang estado ng quota ng bawat provider at tinutulungan ang mga tumatawag na magpasya kung kailan maglilimita/lilipat	quota, providers	"Suriin ang quota para sa anthropic"
Pagtuklas ng Provider	provider-discovery	Inililista ang mga naka-install na provider kasama ang mga kakayahan, free-tier flag, at katayuan ng OAuth	providers, discovery	"Anong mga provider ang available?"
Pagsusuri ng Gastos	cost-analysis	Tinataya ang gastos ng isang kahilingan/pag-uusap batay sa catalog at kamakailang paggamit	cost, usage	"Tantiyahin ang gastos para sa pag-uusap na ito"
Ulat sa Kalagayan	health-report	Pinagsasama-sama ang estado ng circuit breaker, cooldown, at lockout ng bawat provider	health, resilience	"Ipakita ang katayuan ng kalagayan ng lahat ng provider"
Ilista ang mga Kakayahan	list-capabilities	Ibinabalik ang buong catalog ng Agent Skills na may 45 entry (23 API + 21 CLI + 1 config) bilang markdown table na may mga raw SKILL.md URL para sa paglalagay ng konteksto	catalog, discovery, skills	"Ilista ang lahat ng kakayahan ng OmniRoute"

Dapat panatilihing nakaayon ang Agent Card sa aktuwal na catalog ng 352 provider; kinukuha ang bilang ng mga provider at metadata ng libre/walang-auth mula sa runtime registry.

Mga Detalye ng Skill na list-capabilities

Partikular na kapaki-pakinabang ang skill na list-capabilities para sa mga panlabas na agent na kailangang tuklasin kung ano ang inilalantad ng OmniRoute bago magpadala ng mga API call. Nagbabalik ito ng isang artifact na nasa anyong structured markdown table:

| ID | Name | Category | Area | Endpoints/Commands | Raw URL |
| --- | --- | --- | --- | --- | --- |
| omni-auth | Auth & Sessions | api | auth | POST /api/auth/login, ... | https://raw.githubusercontent.com/... |
...

Kasama sa bawat row ang column na rawUrl upang agad na makuha ng mga agent ang buong SKILL.md. Tinutumbasan ng field na metadata.totalSkills ang laki ng catalog (45 sa kasalukuyan). Implementasyon: src/lib/a2a/skills/listCapabilities.ts. Tingnan din ang AGENT-SKILLS.md.

---

REST API (pantulong)

Ang JSON-RPC endpoint na /a2a ang kanonikal na A2A entry point. Nagbibigay ang mga REST endpoint sa ibaba ng pantulong na access para sa mga dashboard at panlabas na tooling:

Endpoint	Pamamaraan	Paglalarawan	Awtorisasyon
/api/a2a/status	GET	Katayuan ng server, mga nakarehistrong skill	(pampubliko)
/api/a2a/tasks	GET	Ilista ang mga task gamit ang mga filter	pamamahala
/api/a2a/tasks/[id]	GET	Kunin ang task ayon sa ID	pamamahala
/api/a2a/tasks/[id]/cancel	POST	Kanselahin ang tumatakbong task	pamamahala
/.well-known/agent.json	GET	Agent Card (A2A discovery)	(pampubliko, naka-cache nang 3600s)
/api/a2a/tasks	POST	Papasok na delegasyon sa OmniConductor fleet (Conductor PRD RF5)	Bearer vs OMNIROUTE_API_KEY + a2aEnabled

Papasok na delegasyon ng Conductor (POST /api/a2a/tasks): idinedelega ng mga panlabas na A2A agent ang gawaing coding sa OmniConductor fleet sa pamamagitan ng OmniRoute. Body: { skill: "conductor" | "conductor-cli-<profile>", messages: [{role, content}], metadata: { conductor: { repo: { url, base_ref? }, mode?, cli?, model? } } } — tanging mga skill ng Conductor fleet (ang mga inanunsyo sa Agent Card) ang maaaring delegahan; kinakailangan ang metadata.conductor.repo.url (gumagana ang fleet sa mga git repo). Isinasalin ng route ito sa POST /v1/tasks ng hub gamit ang server-side na CONDUCTOR_ORCHESTRATOR_TOKEN (fallback na CONDUCTOR_HUB_TOKEN) at nagbabalik ng 201 { conductor_task_id, state: "submitted" }; dumadaloy pabalik ang mga katayuan ng task sa pamamagitan ng SSE→A2A mirror (RF1) at makikita ang mga ito sa pamamagitan ng GET /api/a2a/tasks?skill=conductor.

---

Pagdaragdag ng Bagong Skill

1. Gumawa ng skill file: src/lib/a2a/skills/<your-skill>.ts

   Mag-export ng async function na (task: A2ATask) => Promise<{ artifacts, metadata }>. Sundin ang anyo ng mga kasalukuyang skill gaya ng smartRouting.ts.

2. Irehistro ang handler: sa src/lib/a2a/taskExecution.ts, magdagdag ng entry sa A2A_SKILL_HANDLERS:

   export const A2A_SKILL_HANDLERS = {
     // ...mga kasalukuyang skill
     "your-skill": async (task) => {
       const skillModule = await import("./skills/yourSkill");
       return skillModule.executeYourSkill(task);
     },
   };
   

3. Ilantad sa Agent Card: sa src/app/.well-known/agent.json/route.ts, idagdag sa dulo ng skills array:

   {
     "id": "your-skill",
     "name": "Your Skill",
     "description": "Brief, intent-focused description",
     "tags": ["routing", "quota"],
     "examples": ["Sample natural-language invocation"]
   }
   

4. Sumulat ng mga test: tests/unit/a2a-<your-skill>.test.ts. Saklawin ang matagumpay na path + error path.

5. Idokumento ang bagong skill sa talahanayang Available Skills ng file na ito.

---

TTL ng Gawain

Mag-e-expire ang mga gawain pagkalipas ng ttlMinutes (default na 5 min) — kino-configure sa constructor ng A2ATaskManager sa src/lib/a2a/taskManager.ts:82. Para i-customize ito, i-fork ang instantiation ng A2ATaskManager at magpasa ng ibang value (hal., new A2ATaskManager(15) para sa 15 minutong TTL). Nililinis ng isang background interval ang mga nag-expire na gawain kada 60 segundo.

---

Lifecycle ng Gawain

naisumite → ginagawa → nakumpleto
                     → nabigo
                     → kinansela

• Nag-e-expire ang mga gawain pagkalipas ng 5 minuto bilang default (tingnan ang TTL ng Gawain)
• Mga terminal state: completed, failed, cancelled
• Itinatala ng event log ang bawat transition ng state

---

Mga Error Code

Code	Kahulugan
-32700	Error sa pag-parse (invalid na JSON)
-32600	Invalid na request / Hindi awtorisado
-32601	Hindi nahanap ang method o skill
-32602	Invalid na mga parameter
-32603	Internal na error
-32000	Naka-disable ang A2A endpoint

---

Mga Halimbawa ng Integration

Python (requests)

import requests

resp = requests.post("http://localhost:20128/a2a", json={
    "jsonrpc": "2.0", "id": "1",
    "method": "message/send",
    "params": {
        "skill": "smart-routing",
        "messages": [{"role": "user", "content": "Hello"}]
    }
}, headers={"Authorization": "Bearer YOUR_KEY"})

result = resp.json()["result"]
print(result["artifacts"][0]["content"])
print(result["metadata"]["routing_explanation"])

TypeScript (fetch)

const resp = await fetch("http://localhost:20128/a2a", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer YOUR_KEY",
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "1",
    method: "message/send",
    params: {
      skill: "smart-routing",
      messages: [{ role: "user", content: "Hello" }],
    },
  }),
});
const { result } = await resp.json();
console.log(result.metadata.routing_explanation);