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.
Поиск в интернете3
| Инструмент | Название | Описание |
|---|---|---|
| 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. |
Память пользователя2
| Инструмент | Название | Описание |
|---|---|---|
| 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). |
Данные и документы6
| Инструмент | Название | Описание |
|---|---|---|
| documents | Документы | Catalog and attach the user's knowledge-base documents to the current task: list all previously uploaded docs (with filters), or attach specific ones for retrieval. |
| list_datasets | Склад · каталог датасетов | Catalog of settled Bronze datasets in the org's warehouse — only what actually landed in warehouse_raw (real coverage, not the manifest wishlist). |
| describe_dataset | Склад · схема датасета | Schema of one Bronze dataset (not the data): the freshest settled payload for (connector, dataset_key), flattened into columns {path, type, sample}. |
| manage_dataset | Склад · Онбординг датасета | Onboard a dataset into the warehouse as data, without a deploy: a global descriptor (how to pull the endpoint) plus a per-org registry (sync cadence). |
| manage_silver | Склад · Silver-маппинг | Silver layer as data: a registry of parse-mappings over Bronze, read by one generic extractor — no CREATE VIEW per dataset. |
| manage_gold | Склад · Gold-витрина | Gold layer as data: a data-mart = a frozen author SELECT over the Bronze manifest, materialized by a deterministic runner. |
Навыки3
| Инструмент | Название | Описание |
|---|---|---|
| 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). |
Коннекторы и сервисы5
| Инструмент | Название | Описание |
|---|---|---|
| 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. |
Задачи и автоматизации3
| Инструмент | Название | Описание |
|---|---|---|
| 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 | Состояние и пауза задачи | Durable state and suspend (only inside task execution): save_state, load_state, suspend. |
Выполнение кода6
| Инструмент | Название | Описание |
|---|---|---|
| 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. |
| exec_command | Терминал | Run a command in a PTY session on the local machine; finished commands return stdout + exit_code, long-lived processes keep a session_id for write_stdin. |
| write_stdin | Терминал: ввод | Send characters to the stdin of a live exec_command session (by session_id) and read fresh output; append \n to submit a line. |
| bsl_check | Проверка BSL | Static analysis of 1C (BSL) code via bsl-language-server on the local machine; point it at a .bsl/.os file or a configuration export folder. |
Браузер и формы2
| Инструмент | Название | Описание |
|---|---|---|
| browser_interact | Браузер | Headless browser actions: navigate, snapshot, click, fill, type, select, upload_file, screenshot. |
| request_form | Форма пользователю | Interactive pause: clarify question or integration connect. |
Git2
| Инструмент | Название | Описание |
|---|---|---|
| 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). |
Генерация и обработка медиа5
| Инструмент | Название | Описание |
|---|---|---|
| generate_media | Генерация медиа | Generate image, video, or audio (TTS, music, SFX) from a prompt; image-to-image, platform presets, and count for N variants per call. |
| edit_image | Обработка изображений | Edit an existing image: remove/blur background, crop, add text/border, marketplace resize. Batches the same operation over up to 20 sources. |
| render_visual | Визуализация | Inline visual in the message bubble: exactly one number-driven object — a chart, diagram, timeline, scheme, or KPI card. Ephemeral, not a saved document. |
| render_map | Карта | Inline map in the bubble: business geo-points on an interactive OpenStreetMap. Ephemeral artifact, not a saved document. |
| message_compose | Черновик сообщения | Inline message draft in the bubble: 2–4 editable variants of one text the user edits, copies, and sends themselves. Ephemeral. |
Анализ (зрение, OCR, аудио)4
| Инструмент | Название | Описание |
|---|---|---|
| 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). |
| analyze_video | Анализ видео | Multimodal video analysis via Gemini 2.5 Flash + Files API; accepts .mp4, .mov, .webm. |
Планирование и управление3
| Инструмент | Название | Описание |
|---|---|---|
| run_subagent | Делегирование подзадачи | Delegate to an explore / execute / verify sub-agent with its own sandbox; up to 5 parallel tasks. |
| publish_app | Публикация лендинга | Publish a landing page built in the sandbox to <slug>.apps.samreshuuu.ru and return the public URL. Outward-facing and near-irreversible. |
| 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"]
Была ли страница полезна?