Агенты

Каждый ответ даёт агент: профиль со своими инструкциями, моделью, коннекторами и навыками. Через API вы выбираете агента, а не LLM: его хэндл передаётся в поле model запроса POST /v1/chat/completions.

Что такое агент

Агент это профиль (имя, handle, инструкции, модель, аватар) плюс разрешённые коннекторы и навыки. В каждой организации есть встроенный ассистент samreshu, а любой участник может создать своих агентов в приложении в разделе Агенты. handle это адрес, которым агента зовут в приложении (@mp-manager), и model, который вы передаёте через API.

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

Адресовать агента

GET /v1/models перечисляет агентов, доступных ключу, первым встроенного ассистента. id это хэндл, owned_by это system у встроенного ассистента и id организации у агентов организации.

bash
curl https://samreshuuu.ru/v1/models \ -H "Authorization: Bearer $SAMRESHUUU_API_KEY"
json
{ "object": "list", "data": [ { "id": "samreshu", "object": "model", "created": 1719187200, "owned_by": "system" }, { "id": "mp-manager", "object": "model", "created": 1777456800, "owned_by": "5b2e9d7a-1c4f-4e8b-a6d3-7f0c2b9e4a18" } ] }

Передайте хэндл как model; ведущий @ допускается. Ответ несёт тот же хэндл в model. Пример ниже зовёт встроенного ассистента samreshu: чтобы позвать своего агента, подставьте его id из GET /v1/models.

python
import os from openai import OpenAI client = OpenAI(api_key=os.environ["SAMRESHUUU_API_KEY"], base_url="https://samreshuuu.ru/v1") reply = client.chat.completions.create( model="samreshu", messages=[{"role": "user", "content": "Привет! Что ты умеешь?"}], ) print(reply.choices[0].message.content)

Ключ действует от имени сотрудника, который его выпустил, поэтому ему доступны агенты, доступные этому сотруднику: встроенный ассистент, его собственные агенты и общие агенты организации. Хэндл вне этого набора, несуществующий хэндл и выключенный агент получают 404 DATA_NOT_FOUND с param: "model", одинаковый ответ на все три случая: знание хэндла доступа не даёт. Держите session_id на каждого агента свой: разговор принадлежит агенту, с которым начат (и организации ключа), и с другим model он отвечает 409 DATA_CONFLICT с param: "session_id".

Модель, коннекторы и кабинеты

Как агент отвечает, решают его настройки:

  • Модель. LLM задана на агенте, и каждая дверь (приложение, мессенджеры, задачи, API) работает на одной и той же. Запрос её не переопределяет.
  • Коннекторы. Агент вызывает только разрешённые ему коннекторы. Что он может вызывать, определяет набор его инструментов.
  • Кабинеты. Агент обращается к подключённым кабинетам того, для кого работает, кроме отключённых для него. Для вызова через API это создатель ключа.

Выдача коннекторов и кабинетов

Выдача устроена в два слоя, оба на карточке интеграций агента в приложении:

  1. Коннекторы. Список коннекторов решает, какие инструменты у агента есть (wildberries, ozon, …). Коннектор, который агенту не разрешён, отсутствует в его наборе инструментов.
  2. Кабинеты. Переключатель у каждого подключённого кабинета решает, какими кабинетами агент может пользоваться: разрешённый коннектор, у которого все кабинеты отключены, данных не вернёт.

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

Общий агент организации

Открыть агента организации значит опубликовать неизменяемую ревизию его инструкций, навыков, нужных подключений и модели; коллеги работают с опубликованной ревизией, а не с черновиком владельца. Коллега принимает ревизию в приложении до первого чата и выбирает, какие из своих подключений даёт агенту. Пока он этого не сделал, ход под этим агентом отклоняется с AGENT_REVISION_NOT_ACCEPTED. Подключения владельца к коллегам не попадают, и каждый коллега платит за свои запросы сам.

Доступные инструменты

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

Ошибки

Конверт ошибки, все коды и лимиты описаны в разделе Ошибки и лимиты API агентов. Отказы, которые касаются выбора агента:

HTTPКодКогда
402SUBSCRIPTION_REQUIREDУ организации ключа нет действующего тарифа: ключ агента работает только при нём (reason: plan_required или plan_expired)
403AUTH_PERMISSION_DENIEDУ ключа нет chat:write
404DATA_NOT_FOUNDmodel не называет агента, доступного ключу (param: "model")
409DATA_CONFLICTsession_id принадлежит другому агенту или разговору другого ключа (param: "session_id")
AGENT_REVISION_NOT_ACCEPTEDОбщий агент, чью текущую ревизию создатель ключа не принял

Частые вопросы

Что такое агент?

Профиль (имя, хэндл, инструкции, модель, аватар) плюс разрешённые коннекторы и навыки. Чат с агентом идёт под этим профилем и достаёт только коннекторы агента и включённые для него подключённые кабинеты.

Как говорить с конкретным агентом через API?

Передайте его хэндл в поле model запроса POST /v1/chat/completions. GET /v1/models перечисляет хэндлы, доступные ключу; встроенный ассистент это samreshu.

Где создавать и настраивать агентов?

В приложении, в разделе «Агенты». Инструкции, модель, коннекторы, навыки и доступ к кабинетам задаются там; API адресует результат.

Можно ли выбрать LLM в запросе?

Нет. Модель входит в агента: меняйте её в настройках агента, и каждая дверь (приложение, мессенджеры, задачи, API) работает на одной модели.

Была ли страница полезна?