Skip to content

AGENT_PROTOCOLS_GUIDE.md

Latest commit

 

History

History
284 lines (215 loc) · 22.7 KB

AGENT_PROTOCOLS_GUIDE.md

File metadata and controls

284 lines (215 loc) · 22.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 · 🇮🇳 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 · 🇱🇰 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 JSON-RPC 2.0 поверх HTTP 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 является одним из участников
  • Для предоставления агентам во фреймворках, таких как Google ADK, или в универсальных агентных сетях доступа к интеллектуальным возможностям маршрутизации OmniRoute (smart-routing, quota-management и т. д.)
  • Для предоставления доступа к OmniRoute через стандартный интерфейс обнаружения и вызова

Методы

  • message/send — отправить сообщение и получить синхронный ответ
  • message/stream — отправить сообщение и получать потоковые события о ходе выполнения через SSE
  • tasks/get — получить задачу по идентификатору
  • 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 — это локальный реестр CLI-агентов OmniRoute. Он определяет, какие CLI-инструменты для разработки установлены на хосте (Cursor, Cline, Claude Code, Codex CLI, Continue и т. д.), получает их версии и отображает их на панели управления, чтобы пользователь мог настроить каждый CLI для работы через OmniRoute.

Это НЕ внешний протокол — это внутренний реестр, обеспечивающий работу интерфейса «CLI Tools» и отслеживание отпечатков CLI (см. CLI-TOOLS.md).

Что он делает

  • Проверяет хост на наличие установленных исполняемых файлов CLI (использует which / where в зависимости от ОС)
  • Определяет версию каждого CLI (вызывает <bin> --version)
  • При необходимости принимает пользовательские агенты (путь к исполняемому файлу + команда проверки версии + аргументы запуска)
  • Сохраняет пользовательские агенты в настройках
  • Возвращает объединённый список на панель управления

REST API

Эндпоинт Метод Описание Аутентификация
/api/acp/agents GET Список обнаруженных и пользовательских агентов (установлено/всего) Ключ API
/api/acp/agents POST Добавление/обновление/удаление пользовательского агента (действие в теле) Ключ API

Формат тела POST (customAgentBodySchema в 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"
}

Варианты использования

  • Страница «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 направляет их нужному облачному агенту, опрашивает его состояние и возвращает результаты.

Поддерживаемые агенты (3, все подтверждены в src/lib/cloudAgent/agents/)

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

Жизненный цикл

POST /api/v1/agents/tasks
  → BaseAgent.createTask() для класса соответствующего агента
  → внешний сервис начинает работу
  → в БД создаётся запись задачи (cloud_agent_tasks)
  ↓
GET /api/v1/agents/tasks/[id]
  → отложенная синхронизация состояния с провайдером
  → возвращает текущее состояние + план + журнал активности
  ↓
POST /api/v1/agents/tasks/[id]   (действие: "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 репозитория + ветка)
Сценарий использования Совместная работа агентов, интеллектуальная маршрутизация как сервис Делегирование задачи «реализовать функцию X в репозитории Y»
Аутентификация Необязательный OMNIROUTE_API_KEY для /a2a; управление для вспомогательных REST API /api/a2a/* Всегда через управление

Примеры интеграции

Просмотр возможностей A2A в OmniRoute

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

Возвращает карточку агента со всеми 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
  }'

Получение списка установленных CLI-агентов через ACP

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 API — не протокол агентов)
  • Мультиагентное взаимодействие → A2A
  • Отображение локальных CLI в панели управления → ACP
  • Делегирование длительных задач программирования облачным сервисам → Cloud Agents

Внутренняя архитектура

                ┌─────────────────────┐
                │   Ядро OmniRoute    │
                └─────────────────────┘
                  ↑       ↑        ↑
        ┌─────────┘       │        └─────────┐
        │                 │                  │
    ┌───────┐        ┌─────────┐       ┌────────────┐
    │  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}/