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/.
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 при создании сессии или стриминге сообщения. Ассистент возьмёт системный промпт агента и ограничится его коннекторами и учётками.
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.
Веб и поиск
| Инструмент | Отображаемое имя | Описание |
|---|---|---|
| web_search | Поиск в интернете | Web search; returns titles, snippets, URLs. Plain query — no operators, no site:. |
| web_fetch | Загрузка страницы | Fetch readable text from a URL. Light alternative to a real browser; large pages are staged to /tmp/input. |
| yandex_image_search | Поиск картинок | Yandex/Pinterest image search; returns artifact UUIDs + source URLs for downstream tools. |
Память пользователя
| Инструмент | Отображаемое имя | Описание |
|---|---|---|
| read_memory | Чтение памяти | Read user long-term memory: list / read / read_many over markdown files. |
| manage_memory | Управление памятью | Write / delete / move user memory files. Content must include a YAML frontmatter (title, source). |
Навыки
| Инструмент | Отображаемое имя | Описание |
|---|---|---|
| skill_search | Поиск навыков | Search the skill catalog by task description; returns skill_id for read_skill. |
| read_skill | Чтение навыка | Load a skill's prompt, scripts, templates and checklists into context. |
| manage_skill | Управление навыками | List / create / update / delete / toggle / copy skills (custom and system). |
Коннекторы и внешние сервисы
| Инструмент | Отображаемое имя | Описание |
|---|---|---|
| list_services | Каталог сервисов | List connected services; returns canonical service ids. |
| describe_service | Паспорт сервиса | Service spec: modules, recipes, rate_limits, pagination_hints, response_examples. |
| connector_execute | Вызов сервиса | Single executor for any registered service: REST or RPC, validated against the service schema. |
| query_events | Журнал входящих событий | Local journal of inbound webhook events (read-only). |
| sign_document | Подписание документа КЭП | Sign a document with a qualified e-signature (CryptoPro) via Diadoc / SBIS. |
Задачи и автоматизации
| Инструмент | Отображаемое имя | Описание |
|---|---|---|
| query_tasks | Просмотр задач | Read-only queries: list tasks, get config, list_executions, execution_summary. |
| manage_task | Управление задачами | Create / run / toggle / update / delete a saved task: create, create_subtask, run, toggle, update, delete. |
| task_runtime | Task Runtime | Durable state and suspend (only inside task execution): save_state, load_state, suspend. |
Выполнение кода
| Инструмент | Отображаемое имя | Описание |
|---|---|---|
| sandbox_bash | Выполнение кода и команд | Run shell / Python in an isolated sandbox; returns stdout, stderr, exit_code, files. |
| repl_execute | Код и данные | Persistent Jupyter-like Python REPL with helpers (peek, grep, chunk_indices, llm_query, FINAL). |
| edit_file | Редактирование файла | Search-and-replace edits in sandbox files with fuzzy matching fallback. |
Браузер и формы
| Инструмент | Отображаемое имя | Описание |
|---|---|---|
| browser_interact | Браузер | Headless browser actions: navigate, snapshot, click, fill, type, select, upload_file, screenshot. |
| request_form | Форма пользователю | Interactive pause: clarify question or integration connect. |
Git
| Инструмент | Отображаемое имя | Описание |
|---|---|---|
| git_clone | Клонирование репозитория | Clone a Git repo into the sandbox with auto-auth (GitHub, GitLab; public or via integration token). |
| open_pull_request | Открыть PR/MR | Push the working branch and open a Pull Request (GitHub) or Merge Request (GitLab). |
Генерация и обработка медиа
| Инструмент | Отображаемое имя | Описание |
|---|---|---|
| generate_media | Генерация медиа | Generate image or video from a prompt; supports image-to-image and platform presets. |
| generate_audio | Генерация аудио | TTS (ElevenLabs), music (MiniMax), short SFX. Returns mp3 in sandbox. |
| edit_image | Обработка изображений | Edit an existing image: remove/blur background, crop, add text/border, marketplace resize. |
| create_slideshow | Создание слайдшоу | Render text overlays on background images into a PNG slideshow (carousels, stories, reels). |
Анализ (vision, OCR, аудио)
| Инструмент | Отображаемое имя | Описание |
|---|---|---|
| analyze_image | Анализ изображения | VLM visual analysis: describe, compare, audit UI screenshots; up to 5 images per call. |
| ocr | Распознавание текста (OCR) | OCR for images and scanned PDFs; batch up to 10 documents per call. |
| transcribe | Транскрибация аудио | Speech-to-text for mp3 / wav / ogg / m4a; batch up to 10, idempotent (cached). |
Планирование и управление потоком
| Инструмент | Отображаемое имя | Описание |
|---|---|---|
| run_subagent | Делегирование подзадачи | Delegate to an explore / execute / verify sub-agent with its own sandbox; up to 5 parallel tasks. |
| exit | Завершение | Finish the task: deliver the answer text and any output filepaths to the user. |
Структура описания инструмента
Каждое описание инструмента самодостаточно — отдельного слоя гайдов нет. Модель читает описание дословно, поэтому все они следуют одной пятиблочной структуре:
- Назначение — одно-два предложения: что инструмент делает и что возвращает.
- Когда использовать — конкретные сценарии, где этот инструмент — правильный выбор.
- Когда НЕ использовать — границы применимости с указанием конкретного альтернативного инструмента.
- Ключевые ограничения — предусловия, форматы, лимиты, порядок вызовов и контракт ошибок.
- Интерпретация результата — как читать ответ, когда повторять, когда остановиться.
Дескрипторы инструментов лежат в 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"]