Agents API

Настраивайте AI-агентов: системный промпт, набор разрешённых коннекторов и доступ к учётным записям организации. Те же эндпоинты используются разделом «Агенты» в самом приложении.

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

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

Создать агента

POST с профилем агента. Обязательное поле — только name, остальные опциональны.

curl -X POST "$BASE/organizations/$ORG_ID/agents" \ -H "Authorization: Bearer $SAMRESHUUU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Marketplace Manager", "description": "Watches WB and Ozon stock, replies to reviews", "system_prompt": "You are a senior marketplace operator. Be concise, cite SKU codes.", "avatar_url": "https://cdn.example.com/avatars/mp.png" }'

{ "id": "8a4b9c12-...-...", "org_id": "...", "name": "Marketplace Manager", "description": "Watches WB and Ozon stock, replies to reviews", "system_prompt": "You are a senior marketplace operator...", "avatar_url": "https://cdn.example.com/avatars/mp.png", "is_enabled": true, "created_by": "...", "created_at": "2026-04-29T10:00:00Z", "connectors": [], "kind": "custom" }

Список и получение агента

В списке системный агент идёт первым, затем ваши пользовательские агенты (с пагинацией).

curl "$BASE/organizations/$ORG_ID/agents?limit=20&offset=0" \ -H "Authorization: Bearer $SAMRESHUUU_API_KEY" curl "$BASE/organizations/$ORG_ID/agents/$AGENT_ID" \ -H "Authorization: Bearer $SAMRESHUUU_API_KEY"

Обновить или удалить

PATCH принимает частичный профиль. DELETE — мягкое удаление. Системный агент только для чтения и на любые мутации возвращает HTTP 400.

curl -X PATCH "$BASE/organizations/$ORG_ID/agents/$AGENT_ID" \ -H "Authorization: Bearer $SAMRESHUUU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "description": "WB + Ozon + Yandex Market", "is_enabled": true }' curl -X DELETE "$BASE/organizations/$ORG_ID/agents/$AGENT_ID" \ -H "Authorization: Bearer $SAMRESHUUU_API_KEY"

Разрешённые коннекторы

PUT .../connectors задаёт полный список ключей коннекторов, которые агент может вызывать (wildberries, ozon, telegram, …). Пустой массив очищает список. Коннекторы — это какими инструментами агенту разрешено пользоваться; учётки — под какими аккаунтами.

curl -X PUT "$BASE/organizations/$ORG_ID/agents/$AGENT_ID/connectors" \ -H "Authorization: Bearer $SAMRESHUUU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "connector_keys": ["wildberries", "ozon", "telegram"] }'

Доступные учётные записи

Возвращает все учётные записи организации под разрешённые агенту коннекторы плюс флаг granted — есть ли уже у агента доступ к ним.

curl "$BASE/organizations/$ORG_ID/agents/$AGENT_ID/available-credentials" \ -H "Authorization: Bearer $SAMRESHUUU_API_KEY"

[ { "credential_id": "c1...", "service_name": "wildberries", "instance_id": "wb_main", "account_label": "WB Seller — main", "last_used_at": "2026-04-28T18:21:00Z", "granted": false, "grant_id": null }, { "credential_id": "c2...", "service_name": "ozon", "instance_id": "ozon_main", "account_label": "Ozon Seller", "last_used_at": null, "granted": true, "grant_id": "g1..." } ]

Выдать учётную запись

Берёте credential_id из /available-credentials и выдаёте его агенту. Опциональные scopes сужают, какие части учётки агент может использовать. Отзыв — DELETE /grants/{grant_id}.

curl -X POST "$BASE/organizations/$ORG_ID/agents/$AGENT_ID/grants" \ -H "Authorization: Bearer $SAMRESHUUU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "credential_id": "c1...", "scopes": { "read": true, "write": false } }' curl -X DELETE "$BASE/organizations/$ORG_ID/agents/$AGENT_ID/grants/$GRANT_ID" \ -H "Authorization: Bearer $SAMRESHUUU_API_KEY"

Запустить сессию под агентом

Передайте agent_id в теле POST /sessions/stream. Вызов запускает ход и возвращает 202 с его id — читайте ответ через SSE, как описано в разделе Стриминг (SSE). Ассистент возьмёт системный промпт агента и ограничится его коннекторами и учётками.

curl -X POST "$BASE/sessions/stream" \ -H "Authorization: Bearer $SAMRESHUUU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "message": "Какие SKU за неделю упали по продажам сильнее всего?", "agent_id": "8a4b9c12-...-..." }'

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

Полный набор инструментов, которые ассистент может вызывать внутри сессии агента. Набор фиксирован и одинаков для всех агентов — различаются только системный промпт и выданные коннекторы / учётные записи. Имена инструментов — это идентификаторы функций в tool_call.

Структура описания инструмента

Каждое описание инструмента самодостаточно — отдельного слоя гайдов нет. Модель читает описание дословно, поэтому все они следуют одной пятиблочной структуре:

Назначение — одно-два предложения: что инструмент делает и что возвращает.
Когда использовать — конкретные сценарии, где этот инструмент — правильный выбор.
Когда НЕ использовать — границы применимости с указанием конкретного альтернативного инструмента.
Ключевые ограничения — предусловия, форматы, лимиты, порядок вызовов и контракт ошибок.
Интерпретация результата — как читать ответ, когда повторять, когда остановиться.

Дескрипторы инструментов лежат в config/prompts/tools.yaml и имеют такую форму:

my_tool: display_name: "Display Name" description: >- One-paragraph purpose of the tool — what it does and what it returns. Когда использовать: concrete scenarios where this tool is the right choice. Когда НЕ использовать: cases where another tool fits better — name the alternative. Key constraints: prerequisites, formats, limits, ordering, error contract. Result interpretation: how to read the response, when to retry, when to stop. category: external # read | write | external | llm | code_execution result_type: contextual # authoritative | contextual | action | metadata | status timeout_ms: 30000 is_mutating: false is_idempotent: true is_query_tool: false synthesis: prefix: "[MY_TOOL]" examples: - param: "value" schema_overrides: require_fields: ["param"] strip_null_fields: ["optional_field"]

FAQ

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

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

Чем разрешённые коннекторы отличаются от выданных учётных данных?

Коннекторы определяют, какие инструменты агент может использовать; учётные данные решают, под какими аккаунтами он действует. Коннекторы задаются через PUT .../connectors, а учётные данные выдаются из /available-credentials.

Как запустить чат-сессию под конкретным агентом?

Передайте agent_id в теле POST /sessions/stream. Ход использует системный промпт агента и ограничен его выданными коннекторами и учётными данными; ответ читается по SSE.

Можно ли изменить или удалить встроенного системного агента?

Нет. Системный агент доступен только для чтения и отклоняет изменения с HTTP 400. Ваши собственные агенты поддерживают PATCH (частичное обновление) и DELETE (мягкое удаление).

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

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

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

Чем разрешённые коннекторы отличаются от выданных учётных данных?

Коннекторы определяют, какие инструменты агент может использовать; учётные данные решают, под какими аккаунтами он действует. Коннекторы задаются через PUT .../connectors, а учётные данные выдаются из /available-credentials.

Как запустить чат-сессию под конкретным агентом?

Передайте agent_id в теле POST /sessions/stream. Ход использует системный промпт агента и ограничен его выданными коннекторами и учётными данными; ответ читается по SSE.

Можно ли изменить или удалить встроенного системного агента?

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