Agents API
Configure AI agents with custom instructions, attach connectors, and grant access to organization credentials. The same endpoints power the in-app Agents settings.
What is an agent
An agent is a profile (name, description, system prompt, avatar) plus a set of allowed connectors and granted credentials. When you start a chat session with agent_id, the assistant runs under that profile and is restricted to the connectors and credentials you have explicitly granted.
Create an agent
Send a POST with the agent profile. All fields except name are optional.
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"
}
List and get agents
Listing returns the system agent first, then your custom agents (paginated).
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"
Update or delete
PATCH accepts a partial profile. DELETE is a soft delete — the system agent is read-only and rejects mutations with 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"
Allowed connectors
Use PUT .../connectors to set the full list of connector keys the agent is allowed to call (wildberries, ozon, telegram, …). Sending an empty array clears the list. Connectors define what tools the agent may use; credentials decide which accounts.
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"] }'
Available credentials
Returns every credential in the organization that matches the agent's allowed connectors, plus a granted flag indicating whether this agent already has access.
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..."
}
]
Grant a credential
Pick a credential_id from /available-credentials and grant it to the agent. Optional scopes narrow what parts of the credential the agent may use; revoke with 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"
Run a session under an agent
Pass agent_id in the POST /sessions/stream body. The call spawns the turn and returns 202 with its ids — read the reply over SSE as described in Streaming (SSE). The assistant uses the agent's system prompt and is limited to its granted connectors and credentials.
curl -X POST "$BASE/sessions/stream" \
-H "Authorization: Bearer $SAMRESHUUU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "Какие SKU за неделю упали по продажам сильнее всего?",
"agent_id": "8a4b9c12-...-..."
}'
Available tools
Every tool the assistant can call inside an agent session. The set is fixed and applies to all agents — what differs per-agent is the system prompt and the connectors / credentials granted to it. Tool names are the function identifiers used in tool_call payloads.
Web & search3
| Tool | Display name | Summary |
|---|---|---|
| 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. |
User memory2
| Tool | Display name | Summary |
|---|---|---|
| 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). |
Data & documents6
| Tool | Display name | Summary |
|---|---|---|
| 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. |
Skills3
| Tool | Display name | Summary |
|---|---|---|
| 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). |
Connectors & external services5
| Tool | Display name | Summary |
|---|---|---|
| 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. |
Tasks & automations3
| Tool | Display name | Summary |
|---|---|---|
| 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. |
Code execution6
| Tool | Display name | Summary |
|---|---|---|
| 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. |
Browser & forms2
| Tool | Display name | Summary |
|---|---|---|
| browser_interact | Браузер | Headless browser actions: navigate, snapshot, click, fill, type, select, upload_file, screenshot. |
| request_form | Форма пользователю | Interactive pause: clarify question or integration connect. |
Git2
| Tool | Display name | Summary |
|---|---|---|
| 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). |
Media generation & editing5
| Tool | Display name | Summary |
|---|---|---|
| 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. |
Analysis (vision, OCR, audio)4
| Tool | Display name | Summary |
|---|---|---|
| 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. |
Planning & flow control3
| Tool | Display name | Summary |
|---|---|---|
| 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. |
Tool description structure
Every tool description is self-contained — no separate guidance layer. The model reads the description verbatim, so each one follows the same five-block structure:
- Purpose — one or two sentences: what the tool does and what it returns.
- When to use — concrete scenarios where this tool is the right pick.
- When NOT to use — boundaries that point to a specific alternative tool.
- Key constraints — prerequisites, formats, limits, ordering, and the error contract.
- Result interpretation — how to read the response, when to retry, when to stop.
Tool descriptors live in config/prompts/tools.yaml and follow this shape:
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"]
Was this page helpful?