Внешние агенты

Внешний агент — AI-агент, который работает вне портала и принимает задачи по протоколу A2A версии 1.0. Портал подключается к агенту по URL его карточки и API-ключу, после чего агента можно выбрать в AI-ассистенте, виджете «AI-чат» и элементе процесса «AI-агент».

Если агентов много и они уже описаны в каталоге, подключайте их через источник агентов: источник создаёт и обновляет подключения сам.

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

Чтобы подключить внешнего агента:

1. Перейдите в раздел «AI» → «AI-агенты» → «Каталог» и нажмите «Подключить». Кнопка доступна с разрешением edit:ai-agents.
2. На вкладке «Основная информация» заполните «Название» и «Идентификатор».
3. На вкладке «Подключение» включите переключатель «Включить агента».
4. Укажите «URL Agent Card» — адрес карточки агента, например https://agents.example.com/.well-known/agent-card.json.
5. Укажите «API-ключ», который ожидает агент.
6. Нажмите «Сохранить».

Агент появится в каталоге с отметкой «Внешний». Запускать его может только владелец подключения — пользователь, который его создал.

Параметры подключения

Форма подключения состоит из вкладок «Основная информация» и «Подключение».

Основная информация

На вкладке «Основная информация» задаются поля:

По идентификатору агент указывается в элементе процесса «AI-агент» и в настройках виджета «AI-чат».

Подключение

Поля вкладки «Подключение» отображаются, когда включён переключатель «Включить агента»:

API-ключ хранится в базе данных в зашифрованном виде и после сохранения не отображается. При редактировании подключения оставьте поле «API-ключ» пустым, чтобы сохранить текущий ключ. При ротации ключа шифрования API-ключи агентов перешифровываются.

Требования к агенту

Портал работает с агентом, который отвечает следующим требованиям:

• поддерживает протокол A2A версии 1.0 с привязкой HTTP+JSON или JSON-RPC;
• публикует карточку агента, доступную из кластера портала;
• принимает API-ключ из заголовка X-A2A-Api-Key или Authorization: Bearer.

Портал отправляет агенту сообщение A2A и ожидает завершения задачи, опрашивая её состояние каждые 2 секунды. Ответ агента — текст его итогового сообщения.

Метаданные сообщения

В метаданных каждого сообщения A2A портал передаёт агенту доступы, которые ему разрешены:

Адреса в метаданных строятся от публичного адреса портала, поэтому агент должен иметь сетевой доступ к порталу.

Вызов инструментов портала

Чтобы вызвать инструменты портала, агент обращается к MCP-эндпоинту из метаданных с токеном запуска в заголовке X-Agent-Run-Token:

• POST <ddp.mcp.endpoint>/tools/list — возвращает список доступных инструментов с JSON-схемой аргументов;
• POST <ddp.mcp.endpoint>/tools/call — вызывает инструмент. Тело запроса — {"tool": "<NAME>", "arguments": {...}}.

Пример вызова инструмента:

curl -s -X POST "https://<DOMAIN>/api/v2/agent-mcp/tools/call" -H "X-Agent-Run-Token: <RUN_TOKEN>" -H "Content-Type: application/json" -d '{"tool": "get_resources", "arguments": {}}'

где:

• <DOMAIN> — домен портала;
• <RUN_TOKEN> — значение ddp.mcp.runToken из метаданных сообщения.

Инструмент, которого нет в ddp.mcp.toolAllowlist, возвращает ошибку 403. Недействительный или отозванный токен — ошибку 401.

Обращение к модели через портал

Если агенту разрешён прокси моделей DDP, он обращается к <ddp.llm.baseUrl>/chat/completions как к API OpenAI Chat Completions и передаёт ddp.llm.apiKey как API-ключ. Ограничения прокси описаны в разделе «Языковая модель агента».

Результат запуска

Агент может сообщить тип результата в метаданных итогового сообщения, задачи или артефакта:

• ddp.deliverableType — тип результата: message, merge_request, branch или patch;
• ddp.deliverableRef — ссылка на результат, например URL merge request.

Тип и ссылка отображаются в деталях запуска в истории запусков. Если тип не передан, результатом считается сообщение.

Подключение агента kagent

Агенты, развёрнутые в кластере с помощью kagent, подключаются через A2A-эндпоинт kagent. Карточка такого агента содержит адреса сервисов внутри кластера, поэтому портал вызывает базовый URL карточки.

Чтобы подключить агента kagent:

1. В поле «URL Agent Card» укажите адрес A2A-эндпоинта агента в kagent, например https://<KAGENT_HOST>/api/a2a/<NAMESPACE>/<AGENT_NAME>/.
2. Выключите переключатель «Вызывать адрес из карточки агента».
3. В поле «API-ключ» укажите ключ, который ожидает A2A-эндпоинт kagent.
4. Если у агента нет собственных доступов к модели, включите «Разрешить прокси моделей DDP».

где:

• <KAGENT_HOST> — адрес A2A-эндпоинта kagent;
• <NAMESPACE> — неймспейс агента;
• <AGENT_NAME> — имя агента.

Если агентов kagent несколько, создайте источник агентов с выключенным переключателем «Вызывать адрес из карточки агента».

Изменение и удаление

Изменять и удалять подключение могут его владелец, участники команды-владельца и супер-администратор. Чтобы изменить или удалить подключение, выберите «Редактировать» или «Удалить» в меню карточки агента в каталоге.

Если выключить агента вручную, он не включится автоматически, даже если им управляет источник агентов.

Устранение неполадок

Ошибки вызова агента отображаются в AI-ассистенте и в деталях запуска: