A2A-агенты, которые вызывают API сайта
A2A-агенты позволяют одной ИИ-системе находить другую, передавать ей задачу и получать структурированный результат. Если такой агент умеет вызывать API сайта, он превращается из собеседника в участника реального бизнес-процесса: проверяет наличие товара, создаёт заявку, рассчитывает стоимость, обновляет статус заказа или собирает данные для отчёта.
- A2A - протокол взаимодействия между агентами
- API сайта - контролируемая точка доступа к данным и операциям
- Agent Card - описание возможностей агента и адресов подключения
- Task - задача с состоянием, результатом и историей выполнения
- Главный принцип - агент вызывает не произвольные URL, а разрешённые бизнес-операции
Что такое A2A
A2A, или Agent2Agent, нужен для связи независимых агентов. Один агент выступает клиентом, другой публикует свои возможности и выполняет задачи. Они могут быть написаны на разных языках, использовать разные модели и работать в разных инфраструктурах.
Типичный сценарий выглядит так:
- Клиентский агент получает запрос пользователя.
- Он находит подходящего удалённого агента по Agent Card.
- Создаёт задачу и передаёт контекст.
- Удалённый агент вызывает API сайта.
- Результат возвращается как сообщение или артефакт.
A2A отвечает за взаимодействие агентов, а API - за доступ к функциям сайта. Эти уровни дополняют друг друга, но не заменяют друг друга.
Зачем агенту API сайта
Без API агент обычно ограничен текстом, поиском по документам или нестабильной автоматизацией интерфейса. API даёт предсказуемый контракт и позволяет выполнять действия без имитации кликов.
Полезные операции:
- поиск товаров, услуг и материалов;
- расчёт цены, срока или тарифа;
- создание лида, заявки или заказа;
- проверка статуса оплаты и доставки;
- обновление профиля или бронирования;
- получение персонализированного результата после авторизации.
Например, агент консультанта может передать агенту сайта задачу: "Подбери доступный тариф для команды из 20 человек". Агент сайта проверит актуальные правила через внутренний API и вернёт варианты в структурированном виде.
Архитектура интеграции
Практичная схема состоит из пяти частей:
| Компонент | Ответственность |
|---|---|
| Клиентский агент | Понимает намерение пользователя и выбирает исполнителя |
| A2A-сервер | Принимает задачи, сообщения и запросы статуса |
| Слой инструментов | Преобразует намерение агента в конкретный вызов |
| API сайта | Проверяет права, валидирует данные и выполняет операцию |
| Аудит | Сохраняет безопасную историю вызовов и результатов |
Не стоит давать модели универсальный инструмент вида request(url, method, body). Безопаснее определить узкие функции:
search_products(query, filters)
calculate_quote(product_id, quantity)
create_lead(name, contact, consent)
get_order_status(order_id)
Так проще ограничивать права, проверять аргументы и понимать, что именно сделал агент.
Agent Card и описание возможностей
Agent Card помогает клиенту понять, для каких задач подходит агент. В ней обычно указывают имя, описание, URL, поддерживаемые способы аутентификации и набор skills.
Описание skill должно быть конкретным. Формулировка "работает с сайтом" почти бесполезна. Лучше написать: "Ищет товары по каталогу, рассчитывает стоимость и создаёт заявку после подтверждения пользователя".
Не публикуйте в Agent Card:
- API-ключи и внутренние токены;
- приватные адреса сервисов;
- детали, которые упрощают обход авторизации;
- операции, недоступные внешним клиентам.
Аутентификация и права
A2A-соединение и вызов API сайта могут использовать разные учётные данные. Агент должен подтвердить, кто он, а API - от чьего имени выполняется действие.
Есть три распространённых режима:
- Техническая учётная запись - подходит для общих данных и фоновых операций.
- Делегированный доступ пользователя - нужен для заказов, профилей и персональных данных.
- Подтверждаемая операция - агент готовит действие, а пользователь подтверждает его перед записью.
Права следует ограничивать по endpoint, HTTP-методу, пользователю и типу данных. Доступ на чтение каталога не должен автоматически давать право менять цены или удалять заказы.
Безопасность вызовов
Основные риски - подмена инструкций, неправильные аргументы, утечка данных и повторное выполнение операции.
Минимальный набор мер:
- проверять входные параметры по строгой схеме;
- использовать allowlist разрешённых операций;
- не передавать секреты в промпт и A2A-сообщения;
- добавлять idempotency key для создания и оплаты;
- ограничивать частоту и стоимость вызовов;
- запрашивать подтверждение перед финансовыми и необратимыми действиями;
- маскировать персональные данные и токены в логах;
- возвращать агенту только необходимые поля ответа.
Текст от пользователя и другого агента всегда считается недоверенным вводом. Даже убедительная инструкция внутри документа не должна расширять права инструмента.
Синхронные и длительные задачи
Поиск или расчёт часто можно вернуть сразу. Импорт, генерация большого отчёта или обработка заказа могут занять минуты. Для них полезна модель задачи со статусами submitted, working, completed, failed и canceled.
Клиент может получать обновления через поток событий, webhook или периодический запрос статуса. Важно, чтобы повторное подключение не запускало бизнес-операцию заново.
Ошибки и наблюдаемость
Агенту нужен не сырой stack trace, а понятный результат: операция временно недоступна, аргумент неверен, доступ запрещён или требуется подтверждение. Внутренние детали остаются в защищённых логах.
Для диагностики сохраняйте:
- идентификаторы task, session и пользователя;
- имя вызванного инструмента;
- безопасную копию аргументов;
- код ответа API и время выполнения;
- факт подтверждения;
- версию агента и схемы инструмента.
Это позволяет отличить ошибку модели от ошибки API, сети или бизнес-правила.
План внедрения
- Выберите один сценарий с измеримой пользой.
- Опишите узкий API-контракт и схемы данных.
- Реализуйте отдельные инструменты вместо универсального HTTP-доступа.
- Добавьте аутентификацию, лимиты и аудит.
- Опубликуйте Agent Card с точным описанием skills.
- Протестируйте ошибки, повторы, отмену и вредоносный ввод.
- Сначала включите read-only или режим черновика.
- Разрешайте запись только после анализа реальных логов.
Итог
A2A-агент с доступом к API сайта может связывать внешние ИИ-системы с реальными услугами бизнеса. Надёжная интеграция строится не вокруг свободы модели, а вокруг узких инструментов, строгих схем, ограниченных прав, подтверждений и аудита.
Хотите подключить A2A-агента к API сайта - свяжитесь со мной.
Часто задаваемые вопросы
Чем A2A отличается от обычного REST API?
REST API описывает операции приложения, а A2A - взаимодействие агентов и жизненный цикл задач. A2A может использовать REST или другой транспорт внутри, а агент затем обращается к API сайта через контролируемые инструменты.
Нужен ли A2A, если агент уже умеет вызывать API?
Не всегда. Для одного внутреннего агента прямого вызова API может быть достаточно. A2A полезен, когда независимые агенты должны находить друг друга, делегировать задачи и обмениваться результатами по общему протоколу.
Можно ли дать агенту универсальный HTTP-клиент?
Технически можно, но для продакшена это рискованно. Узкие функции с allowlist, схемами и отдельными правами проще защищать, тестировать и журналировать.
Как не создать заказ дважды?
Используйте idempotency key и храните связь между A2A task и бизнес-операцией. Повторный запрос с тем же ключом должен возвращать прежний результат, а не создавать новую запись.
Какие действия требуют подтверждения пользователя?
Подтверждение нужно для оплаты, публикации, отправки сообщений, изменения персональных данных и других дорогих или необратимых операций. Поиск, чтение открытых данных и подготовка черновика обычно можно автоматизировать.