Доступ по API¶
Любого опубликованного агента можно вызывать программно через API, совместимый с OpenAI, — так разработчики могут встроить его в свои приложения с помощью уже знакомых инструментов.
API-токены¶
Как владелец агента, вы создаёте для него API-токены. Создавать, просматривать и отзывать их может только владелец — не соредактор с уровнем Может редактировать и не администраторы платформы Атома:
- У каждого токена есть название, чтобы их можно было различать.
- Полный секрет показывается только один раз, при создании (он начинается с
dk_). Скопируйте и сохраните его сразу — потом показывается только короткий префикс. - Вы можете просмотреть список своих токенов (название, префикс, время последнего использования) и отозвать любой из них. Потерянный секрет восстановить нельзя — отзовите его и выпустите новый. Отзыв токена также завершает уже идущие запуски этого человека на этом агенте — например, живую голосовую сессию, открытую с этим ключом: доступ к коду, данным и подключениям прекращается примерно в течение полуминуты, а ответ останавливается на ближайшей проверке.
Токен действует для одного агента и принадлежит человеку, который его создал: каждый вызов с ним выполняется от имени этого человека — с его собственной памятью, файлами и профилем на этом агенте, — а в списке токенов видно, чей это токен. Вызов оплачивается так же, как использование агента этим человеком: по настройке агента по умолчанию или с личного либо организационного кошелька, который он выбрал (см. Кто платит). Месячный лимит владельца для этого человека действует только на использование, за которое платит владелец. Использование, за которое человек платит сам, в него не засчитывается. Вызов отклоняется, если уже учтённый расход за счёт владельца достиг этого лимита или если выбранный кошелёк был отозван или удалён. Тогда человеку нужно снова выбрать кошелёк на странице агента; вызов не переносится на баланс владельца. Работа, которая уже началась, по-прежнему оплачивается. Какие модели может использовать вызов, зависит от тарифа того, кто платит. Как владелец, вы всегда видите в своей панели все ключи агента — включая те, что пользователи создали для себя, — с тем, кто их создал, и можете отозвать любой из них.
Эндпоинт, совместимый с OpenAI¶
API повторяет интерфейс Chat Completions от OpenAI, отдельно для каждого агента:
- Поддерживаются ответы с потоковой передачей и без неё (потоковая передача использует тот же формат server-sent events, которого ожидают клиенты OpenAI).
- Существующие SDK OpenAI можно направить на этот эндпоинт, указав базовый URL и API-ключ: в поле «model» укажите адрес агента, а что на самом деле будет работать, определяют модель, настроенная владельцем, и его тариф.
- Вызов получает то же, что и чат. Он ищет по коллекциям знаний агента, к которым есть доступ у владельца ключа (по всем — для владельца агента), читает файлы и память этого человека на этом агенте и видит выводы, которые агент сделал на опыте, — так же как собственный разговор этого человека или голосовая сессия. Раньше вызовы эндпоинта работали без всего этого.
- Если у агента есть схема структурированного вывода (JSON), API проверяет ответ по ней и автоматически повторяет запрос один раз, чтобы получить соответствующий ответ.
- Кратковременный сбой на стороне провайдера — тайм-аут, обрыв соединения, перегрузка провайдера — автоматически повторяется, не более двух раз после короткой паузы, прежде чем запрос завершится ошибкой вышестоящего провайдера. Это касается и потоковых запросов: ответ просто придёт чуть позже. Запрос, который провайдер отклоняет (некорректный запрос, проблема с аутентификацией или квотой, блокировка контент-фильтром), не повторяется.
- Ошибки возвращаются в формате ошибок OpenAI и различают реальные случаи: закончились кредиты или квота, исчерпан месячный лимит владельца для этого человека, выбранный кошелёк больше недоступен, отдельный запрос превышает свой бюджет, некорректный запрос и проблемы вышестоящего провайдера.
Охват
Эмулируется только chat completions. Эндпоинта со списком моделей нет, как нет и маршрутов embeddings, images и других маршрутов OpenAI. Это прямая замена для чата, а не для всего API OpenAI.
Ключи для пользователей вашего агента¶
Как владелец, вы можете включить Разрешить пользователям создавать свои API-ключи в настройках общего доступа агента (см. Общий доступ к воркфлоу, знаниям и API). После этого любой, у кого есть доступ к агенту, открывает API-ключи на странице агента — человека, который ещё не согласился с описанием агента, сначала попросят это сделать — и может:
- создать до 10 ключей,
- увидеть каждый секрет один раз, при создании,
- удалять свои ключи.
Ключ пользователя работает точно так же, как токены владельца, описанные выше: он действует от имени этого человека — с его собственной памятью, файлами, профилем и личными подключениями — и оплачивается так же, как остальное использование агента этим человеком, а в базе данных агента получает доступ уровня пользователя, ограниченный тем, что таблицы агента разрешают конечным пользователям. Если вы выключите настройку или человек потеряет доступ к агенту, его ключи сразу перестают работать для новых запросов, а его уже идущие запуски теряют доступ примерно в течение полуминуты. Удаление ключа делает то же самое для уже идущих запусков этого человека на этом агенте. Это не связано с панелью токенов в консоли, описанной выше: она доступна только владельцу и продолжает показывать все ключи, кто бы их ни создал.
Ключи нельзя создавать или управлять ими из мобильных приложений — используйте страницу агента в вебе.
Перед вызовом агента ключом нужно завершить настройку¶
Если ключ пользователя принадлежит человеку, который не завершил настройку агента, — не подключил свои личные подключения или не заполнил обязательные параметры, — вызов chat completions или realtime с этим ключом отклоняется до запуска:
{"error": {"code": "agent_setup_required", "message": "Finish setting up this agent before using it."}}
Вызов завершается с HTTP 409. Человек завершает настройку на странице агента (см. Настройка агента, которым с вами поделились) и повторяет вызов.
Перед вызовом агента ключом нужно дать согласие¶
Если ключ пользователя принадлежит человеку, который не согласился с текущим описанием агента, — он никогда не соглашался или описание с тех пор изменилось и стало показывать автору больше, — вызов chat completions с этим ключом отклоняется до запуска с HTTP 409:
{"error": {"code": "consent_required", "type": "invalid_request_error", "message": "Open https://app.agentatom.ru/chat/support-bot to review how \"Support bot\" uses your data, then come back."}}
Realtime-сессия отклоняется так же. Человек открывает ссылку, соглашается (см. Что видит автор агента) и повторяет вызов. Когда его ключ задерживают впервые, он получает одно письмо. Ваши собственные токены и ключи владельцев и администраторов вашей организации, а также людей, которым вы дали уровень Может редактировать, это не затрагивает.
Устройства¶
В Агенте Атом приложения для Windows нет, поэтому регистрировать компьютер с Windows как устройство и отправлять на него задачи из облака нельзя. Работать на вашем компьютере агент может через приложение для Mac или браузерное расширение — см. Управление компьютером и браузер.