Skip to content

AGENT_PROTOCOLS_GUIDE.md

Latest commit

 

History

History
284 lines (215 loc) · 24.7 KB

AGENT_PROTOCOLS_GUIDE.md

File metadata and controls

284 lines (215 loc) · 24.7 KB
Raw

Agent Protocols Guide (हिन्दी)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇭🇷 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 · 🇹🇼 zh-TW

स्रोत: 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 + DB-समर्थित कार्य 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 समकक्षों में से एक हो
  • Google ADK या सामान्य एजेंट मेश जैसे फ़्रेमवर्क में एजेंटों को OmniRoute की रूटिंग इंटेलिजेंस (smart-routing, quota-management आदि) उपलब्ध कराते समय
  • 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 Tools" UI और CLI फ़िंगरप्रिंट ट्रैकिंग को संचालित करती है (CLI-TOOLS.md देखें)।

यह क्या करता है

  • इंस्टॉल किए गए CLI बाइनरी के लिए होस्ट की जाँच करता है (OS के अनुसार 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 Tools" पेज इंस्टॉल किए गए टूल की सूची दिखाता है और प्रत्येक को OmniRoute की ओर इंगित करने में आपकी सहायता करता है
  • कस्टम एजेंट उन्नत उपयोगकर्ताओं को ऐसे आंतरिक/मालिकाना CLI पंजीकृत करने देते हैं, जिनके बारे में OmniRoute को डिफ़ॉल्ट रूप से जानकारी नहीं होती
  • पहचान का परिणाम 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() per agent class
  → external service starts work
  → task row created in DB (cloud_agent_tasks)
  ↓
GET /api/v1/agents/tasks/[id]
  → lazy status sync from provider
  → returns current status + plan + activity log
  ↓
POST /api/v1/agents/tasks/[id]   (action: "approve" | "message" | "cancel")
  → forwards to provider (or marks cancelled locally)
  ↓
DELETE /api/v1/agents/tasks/[id]
  → local cancel

प्रमाणीकरण

⚠️ सभी /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

यह सभी 6 कौशलों, ट्रांसपोर्ट और संस्करण के साथ Agent Card लौटाता है।

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=..."

किस स्थिति में क्या उपयोग करें

  • चैटबॉट / कोपायलट फ़्रंटएंड → /v1/chat/completions (OpenAI-संगत — एजेंट प्रोटोकॉल नहीं)
  • मल्टी-एजेंट सहयोग → A2A
  • डैशबोर्ड में स्थानीय CLI सूचीबद्ध करना → ACP
  • लंबे समय तक चलने वाले कोडिंग कार्य क्लाउड सेवाओं को सौंपना → Cloud Agents

आंतरिक आर्किटेक्चर

                ┌─────────────────────┐
                │   OmniRoute Core    │
                └─────────────────────┘
                  ↑       ↑        ↑
        ┌─────────┘       │        └─────────┐
        │                 │                  │
    ┌───────┐        ┌─────────┐       ┌────────────┐
    │  A2A  │        │   ACP   │       │  क्लाउड    │
    │ (/a2a)│        │ (/acp)  │       │  एजेंट     │
    └───────┘        └─────────┘       │ (/v1/agents│
        │                 │            │  /tasks)   │
        ↓                 ↓            └────────────┘
   बाहरी सहकर्मी     होस्ट पर स्थानीय         │
   एजेंट, जो         CLI बाइनरी               ↓
   A2A v0.3 बोलते हैं                   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}/