Агенты
Каждый ответ даёт агент: профиль со своими инструкциями, моделью, коннекторами и навыками. Через API вы выбираете агента, а не LLM: его хэндл передаётся в поле model запроса POST /v1/chat/completions.
Что такое агент
Агент это профиль (имя, handle, инструкции, модель, аватар) плюс разрешённые коннекторы и навыки. В каждой организации есть встроенный ассистент samreshu, а любой участник может создать своих агентов в приложении в разделе Агенты. handle это адрес, которым агента зовут в приложении (@mp-manager), и model, который вы передаёте через API.
Агент бывает личным (видит и пишет ему только владелец) или общим для организации (писать может любой участник). В обоих случаях настройки меняет только владелец.
Адресовать агента
GET /v1/models перечисляет агентов, доступных ключу, первым встроенного ассистента. id это хэндл, owned_by это system у встроенного ассистента и id организации у агентов организации.
Передайте хэндл как model; ведущий @ допускается. Ответ несёт тот же хэндл в model. Пример ниже зовёт встроенного ассистента samreshu: чтобы позвать своего агента, подставьте его id из GET /v1/models.
Ключ действует от имени сотрудника, который его выпустил, поэтому ему доступны агенты, доступные этому сотруднику: встроенный ассистент, его собственные агенты и общие агенты организации. Хэндл вне этого набора, несуществующий хэндл и выключенный агент получают 404 DATA_NOT_FOUND с param: "model", одинаковый ответ на все три случая: знание хэндла доступа не даёт. Держите session_id на каждого агента свой: разговор принадлежит агенту, с которым начат (и организации ключа), и с другим model он отвечает 409 DATA_CONFLICT с param: "session_id".
Модель, коннекторы и кабинеты
Как агент отвечает, решают его настройки:
- Модель. LLM задана на агенте, и каждая дверь (приложение, мессенджеры, задачи, API) работает на одной и той же. Запрос её не переопределяет.
- Коннекторы. Агент вызывает только разрешённые ему коннекторы. Что он может вызывать, определяет набор его инструментов.
- Кабинеты. Агент обращается к подключённым кабинетам того, для кого работает, кроме отключённых для него. Для вызова через API это создатель ключа.
Выдача коннекторов и кабинетов
Выдача устроена в два слоя, оба на карточке интеграций агента в приложении:
- Коннекторы. Список коннекторов решает, какие инструменты у агента есть (
wildberries,ozon, …). Коннектор, который агенту не разрешён, отсутствует в его наборе инструментов. - Кабинеты. Переключатель у каждого подключённого кабинета решает, какими кабинетами агент может пользоваться: разрешённый коннектор, у которого все кабинеты отключены, данных не вернёт.
В момент исполнения агент дотягивается только до разрешённых коннекторов и неотключённых кабинетов, в том числе когда его зовут через API по хэндлу. Подключения владельца агента до коллег не доходят: коллега запускает общего агента на своих подключениях. Как подключаются кабинеты и где хранятся их секреты, описано в разделе Коннекторы.
Общий агент организации
Открыть агента организации значит опубликовать неизменяемую ревизию его инструкций, навыков, нужных подключений и модели; коллеги работают с опубликованной ревизией, а не с черновиком владельца. Коллега принимает ревизию в приложении до первого чата и выбирает, какие из своих подключений даёт агенту. Пока он этого не сделал, ход под этим агентом отклоняется с AGENT_REVISION_NOT_ACCEPTED. Подключения владельца к коллегам не попадают, и каждый коллега платит за свои запросы сам.
Доступные инструменты
Все инструменты, которые агент может вызвать за ход. Набор фиксирован и одинаков для всех агентов, а различаются инструкции, модель, навыки, коннекторы и кабинеты. Имена инструментов те же, что несут в tool_name события инструментов.
Ошибки
Конверт ошибки, все коды и лимиты описаны в разделе Ошибки и лимиты API агентов. Отказы, которые касаются выбора агента:
| HTTP | Код | Когда |
|---|---|---|
| 402 | SUBSCRIPTION_REQUIRED | У организации ключа нет действующего тарифа: ключ агента работает только при нём (reason: plan_required или plan_expired) |
| 403 | AUTH_PERMISSION_DENIED | У ключа нет chat:write |
| 404 | DATA_NOT_FOUND | model не называет агента, доступного ключу (param: "model") |
| 409 | DATA_CONFLICT | session_id принадлежит другому агенту или разговору другого ключа (param: "session_id") |
AGENT_REVISION_NOT_ACCEPTED | Общий агент, чью текущую ревизию создатель ключа не принял |
Частые вопросы
Что такое агент?
Профиль (имя, хэндл, инструкции, модель, аватар) плюс разрешённые коннекторы и навыки. Чат с агентом идёт под этим профилем и достаёт только коннекторы агента и включённые для него подключённые кабинеты.
Как говорить с конкретным агентом через API?
Передайте его хэндл в поле model запроса POST /v1/chat/completions. GET /v1/models перечисляет хэндлы, доступные ключу; встроенный ассистент это samreshu.
Где создавать и настраивать агентов?
В приложении, в разделе «Агенты». Инструкции, модель, коннекторы, навыки и доступ к кабинетам задаются там; API адресует результат.
Можно ли выбрать LLM в запросе?
Нет. Модель входит в агента: меняйте её в настройках агента, и каждая дверь (приложение, мессенджеры, задачи, API) работает на одной модели.