A2A-агенты, которые вызывают API сайта

A2A-агенты позволяют одной ИИ-системе находить другую, передавать ей задачу и получать структурированный результат. Если такой агент умеет вызывать API сайта, он превращается из собеседника в участника реального бизнес-процесса: проверяет наличие товара, создаёт заявку, рассчитывает стоимость, обновляет статус заказа или собирает данные для отчёта.

• A2A - протокол взаимодействия между агентами
• API сайта - контролируемая точка доступа к данным и операциям
• Карточка агента - описание возможностей агента и адресов подключения
• Задача - задача с состоянием, результатом и историей выполнения
• Главный принцип - агент вызывает не произвольные URL, а разрешённые бизнес-операции

Что такое A2A

A2A, или Agent2Agent, нужен для связи независимых агентов. Один агент выступает клиентом, другой публикует свои возможности и выполняет задачи. Они могут быть написаны на разных языках, использовать разные модели и работать в разных инфраструктурах.

Типичный сценарий выглядит так:

1. Клиентский агент получает запрос пользователя.
2. Он находит подходящего удалённого агента по Карточке агента.
3. Создаёт задачу и передаёт контекст.
4. Удалённый агент вызывает API сайта.
5. Результат возвращается как сообщение или артефакт.

A2A отвечает за взаимодействие агентов, а API - за доступ к функциям сайта. Эти уровни дополняют друг друга, но не заменяют друг друга.

Что это значит для владельца бизнеса

Подключение A2A-агента к API сайта - не разовая настройка, а отдельный инженерный проект с последствиями для безопасности и данных. Внешний агент, вызывающий ваш API, - это ещё одна точка, через которую можно случайно или намеренно затронуть заказы, цены или персональные данные клиентов. Владельцу не обязательно разбираться в протоколе самому, но стоит спросить у команды: какие операции агенту разрешено вызывать, какие действия требуют подтверждения человека, и кто будет следить за логами после запуска. Чек-лист таких вопросов - в статье про Карточку агента в A2A.

Зачем агенту API сайта

Без API агент обычно ограничен текстом, поиском по документам или нестабильной автоматизацией интерфейса. API даёт предсказуемый контракт и позволяет выполнять действия без имитации кликов.

Полезные операции:

• поиск товаров, услуг и материалов;
• расчёт цены, срока или тарифа;
• создание лида, заявки или заказа;
• проверка статуса оплаты и доставки;
• обновление профиля или бронирования;
• получение персонализированного результата после авторизации.

Например, агент консультанта может передать агенту сайта задачу: "Подбери доступный тариф для команды из 20 человек". Агент сайта проверит актуальные правила через внутренний API и вернёт варианты в структурированном виде.

Архитектура интеграции

Практичная схема состоит из пяти частей:

Не стоит давать модели универсальный инструмент вида request(url, method, body). Безопаснее определить узкие функции:

search_products(query, filters)
calculate_quote(product_id, quantity)
create_lead(name, contact, consent)
get_order_status(order_id)

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

Карточка агента и описание возможностей

Карточка агента помогает клиенту понять, для каких задач подходит агент. В ней обычно указывают имя, описание, URL, поддерживаемые способы аутентификации и набор навыков.

Описание навыков должно быть конкретным. Формулировка "работает с сайтом" почти бесполезна. Лучше написать: "Ищет товары по каталогу, рассчитывает стоимость и создаёт заявку после подтверждения пользователя".

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

Аутентификация и права

A2A-соединение и вызов API сайта могут использовать разные учётные данные. Агент должен подтвердить, кто он, а API - от чьего имени выполняется действие.

Есть три распространённых режима:

1. Техническая учётная запись - подходит для общих данных и фоновых операций.
2. Делегированный доступ пользователя - нужен для заказов, профилей и персональных данных.
3. Подтверждаемая операция - агент готовит действие, а пользователь подтверждает его перед записью.

Права следует ограничивать по эндпоинтам, HTTP-методу, пользователю и типу данных. Доступ на чтение каталога не должен автоматически давать право менять цены или удалять заказы.

Безопасность вызовов

Основные риски - подмена инструкций, неправильные аргументы, утечка данных и повторное выполнение операции.

Минимальный набор мер:

• проверять входные параметры по строгой схеме;
• использовать список разрешённых операций;
• не передавать секреты в промпт и A2A-сообщения;
• добавлять ключ идемпотентности для операций создания и оплаты;
• ограничивать частоту и стоимость вызовов;
• запрашивать подтверждение перед финансовыми и необратимыми действиями;
• маскировать персональные данные и токены в логах;
• возвращать агенту только необходимые поля ответа.

Текст от пользователя и другого агента всегда считается недоверенным вводом. Даже убедительная инструкция внутри документа не должна расширять права инструмента.

Синхронные и длительные задачи

Поиск или расчёт часто можно вернуть сразу. Импорт, генерация большого отчёта или обработка заказа могут занять минуты. Для них полезна модель задачи со статусами submitted, working, completed, failed и canceled.

Клиент может получать обновления через поток событий, вебхук или периодический запрос статуса. Важно, чтобы повторное подключение не запускало бизнес-операцию заново.

Ошибки и наблюдаемость

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

Для диагностики сохраняйте:

• идентификаторы задачи, сессии и пользователя;
• имя вызванного инструмента;
• безопасную копию аргументов;
• код ответа API и время выполнения;
• факт подтверждения;
• версию агента и схемы инструмента.

Это позволяет отличить ошибку модели от ошибки API, сети или бизнес-правила.

План внедрения

Это отдельный инженерный проект, а не разовая настройка - план ниже помогает ограничить риски и затраты на старте.

1. Выберите один сценарий с измеримой пользой.
2. Опишите узкий API-контракт и схемы данных.
3. Реализуйте отдельные инструменты вместо универсального HTTP-доступа.
4. Добавьте аутентификацию, лимиты и аудит.
5. Опубликуйте Карточку агента с точным описанием навыков.
6. Протестируйте ошибки, повторы, отмену и вредоносный ввод.
7. Сначала включите только чтение или режим черновика.
8. Разрешайте запись только после анализа реальных логов.

Когда это не подходит

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

Итог

A2A-агент с доступом к API сайта может связывать внешние ИИ-системы с реальными услугами бизнеса. Надёжная интеграция строится не вокруг свободы модели, а вокруг узких инструментов, строгих схем, ограниченных прав, подтверждений и аудита.

Хотите подключить A2A-агента к API сайта - свяжитесь со мной.

Часто задаваемые вопросы

Чем A2A отличается от обычного REST API?

REST API описывает операции приложения, а A2A - взаимодействие агентов и жизненный цикл задач. A2A может использовать REST или другой транспорт внутри, а агент затем обращается к API сайта через контролируемые инструменты.

Нужен ли A2A, если агент уже умеет вызывать API?

Не всегда. Для одного внутреннего агента прямого вызова API может быть достаточно. A2A полезен, когда независимые агенты должны находить друг друга, делегировать задачи и обмениваться результатами по общему протоколу.

Можно ли дать агенту универсальный HTTP-клиент?

Технически можно, но для продакшена это рискованно. Узкие функции с allowlist, схемами и отдельными правами проще защищать, тестировать и журналировать.

Как не создать заказ дважды?

Используйте ключ идемпотентности и храните связь между A2A-задачей и бизнес-операцией. Повторный запрос с тем же ключом должен возвращать прежний результат, а не создавать новую запись.

Какие действия требуют подтверждения пользователя?

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

Термины в статье

A2A — Agent-to-Agent — протокол взаимодействия ИИ-агентов друг с другом

API-ключи — API keys — секретные токены для доступа к API

промпт — prompt — текст-инструкция или запрос к модели

вебхук — webhook — HTTP-уведомление при наступлении события

REST API — HTTP API that exposes resources via URLs and verbs — HTTP API: ресурсы через URL и методы GET/POST и т.д.