Внешняя интеграция Agent MCP

Используйте Agents Manager AGI как инструменты MCP из доверенного серверного приложения. Руководство описывает настройку, аутентификацию, нижестоящую авторизацию, вызовы, восстановление и стабильные ошибки.

Быстрый старт

1. В Web Admin создайте активное стороннее приложение, привяжите компанию и скопируйте App ID и App Secret.
2. Назначьте компании включённого Agent с действующими опубликованными Skills.
3. Подключите MCP Streamable HTTP клиент к POST|GET|DELETE /openapi/v1/agents/mcp на HTTPS-хосте Engine.
4. Инициализируйте сессию, отправьте notifications/initialized, вызовите tools/list, затем agent_{id}.

Общий ассистент не публикуется. Храните Secret только на сервере.

Аутентификация и область полномочий

Среды API:

• Тестовая: https://aim-api-test.proton-system.com
• Рабочая: https://aim-api.proton-system.com

Каждый запрос должен содержать:

Authorization: Basic Base64(KEY:SECRET)
Content-Type: application/json
Accept: application/json, text/event-stream

Удалённый MCP-клиент с поддержкой пользовательских заголовков запроса может использовать следующую конфигурацию:

{
  "mcpServers": {
    "manager-agi": {
      "url": "https://xxx.com/openapi/v1/agents/mcp",
      "headers": {
        "Authorization": "Basic <Base64(AppID:AppSecret)>"
      }
    }
  }
}

Активное приложение получает постоянное одобрение в рамках компании. Назначенные сейчас или позже Agents и новые опубликованные Skills доступны без подтверждения человеком, включая запись и операции высокого риска. CompanyRole не ограничивает эти полномочия. Engine по-прежнему проверяет статусы, назначение, публикацию, нижестоящую авторизацию, изменение схемы/риска, валидацию, лимиты, идемпотентность и аудит.

Инициализация и сессия

Инициализируйте клиент и сохраните заголовок ответа Mcp-Session-Id:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"partner-server","version":"1.0.0"}}}

{"jsonrpc":"2.0","method":"notifications/initialized"}

Передавайте Mcp-Session-Id в следующих POST, GET и DELETE. После INVALID_MCP_SESSION инициализируйтесь заново.

Инструменты Agent и метаданные

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

Имя инструмента — agent_{id}, где после префикса указан полный ID Agent. Верхнеуровневый title равен имени Agent, а description использует описание или имя, если описание пусто. _meta.easyposAgent содержит только открытые id, name, description, iconUrl. authorizationRequirements содержит mcpHubId, mcpHubName, authType, status, expiresAt, authorized и при необходимости созданный Engine authorizationUrl. Промпты, быстрые вопросы, определения Skills, внутренние схемы и учётные данные не раскрываются.

Нижестоящая авторизация

Если status равен MISSING или REAUTH_REQUIRED, откройте созданный Engine authorizationUrl, путь которого начинается с /openapi/v1/mcp/authorization/start. После завершения пользователем приложение повторяет tools/list или исходный tools/call; ACTIVE означает, что Engine может выполнять вызовы с сохранённой для приложения авторизацией. Истечение срока или downstream 401 требует повторить тот же процесс. Не обновляйте токены, не отправляйте downstream-заголовки и не повторяйте неудачный бизнес-вызов автоматически.

Вызов Agent

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"agent_a441d514-2aed-4b86-b12f-7cce1bd90134","arguments":{"requestId":"req-20260825-001","message":"Суммируй открытые заказы за сегодня","conversationId":"optional-existing-id"},"_meta":{"progressToken":"req-20260825-001"}}}

requestId обязателен, обрезается и ограничен 128 байтами UTF-8; message обязателен и ограничен 16 KiB; conversationId необязателен и повторно используется только теми же приложением, компанией и Agent. _meta.progressToken включает стандартный прогресс MCP.

Успех содержит "status":"COMPLETED", "answer", requestId, conversationId, метаданные и authorizationRequirements. Без нижестоящих данных возвращаются isError:true, status:"authorization_required", errorCode:"MCP_AUTHORIZATION_REQUIRED", и выполнение не создаётся.

SSE, возобновление, отмена и закрытие

Читайте прогресс MCP и один финальный результат. Для восстановления сделайте авторизованный GET с Mcp-Session-Id, непрозрачным Last-Event-ID, EasyPOS-Agent-Request-Id, EasyPOS-Agent-Id и Accept: text/event-stream. Воспроизведение не запускает Agent повторно; при необходимости повторяйте GET с новым курсором.

Явная отмена MCP лишь запрашивает отмену и не откатывает отправленные эффекты. transport disconnect не отменяет принятую работу. Закройте сессию авторизованным DELETE с Mcp-Session-Id.

Лимиты и идемпотентность

requestId идемпотентен внутри приложения 90 дней. Одинаковый ввод воспроизводит результат без новой единицы выполнения; другой ввод даёт IDEMPOTENCY_CONFLICT, а выполняющийся запрос может дать REQUEST_IN_PROGRESS.

Контракт ошибок

Транспортные ошибки используют HTTP и JSON вида {"code":"COMPANY_INACTIVE","description":"The company is inactive."}. Ошибки MCP/домена возвращают isError:true, errorCode и errorDescription. Описание — стабильный английский текст без чувствительных данных; ветвление выполняйте по коду.

Безопасность и диагностика

Используйте TLS и хранилище секретов, удаляйте заголовки авторизации из журналов. Не помещайте App Secret в браузер, мобильное приложение, URL или репозиторий. Сервер должен опускать Origin; если он есть, это должен быть разрешённый HTTPS Origin. При утечке отключите приложение или сбросьте Secret.

Если tools/list пуст, проверьте компанию, Agent, назначение и опубликованные Skills. Если требуется авторизация, откройте authorizationUrl и повторите обнаружение или вызов после её завершения; переинициализируйте неверную сессию. callbackUrl уведомлений не получает результаты Agent — читайте их через MCP/SSE.