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.

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:

  1. Purpose — one or two sentences: what the tool does and what it returns.
  2. When to use — concrete scenarios where this tool is the right pick.
  3. When NOT to use — boundaries that point to a specific alternative tool.
  4. Key constraints — prerequisites, formats, limits, ordering, and the error contract.
  5. 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"]

FAQ

What is an agent?

A profile (name, description, system prompt, avatar) plus a set of allowed connectors and granted credentials. Running a session with agent_id restricts the assistant to exactly those connectors and credentials.

What is the difference between allowed connectors and granted credentials?

Connectors define which tools the agent may use; credentials decide which accounts it acts on. Set connectors with PUT .../connectors and grant credentials chosen from /available-credentials.

How do I run a chat session under a specific agent?

Pass agent_id in the POST /sessions/stream body. The turn uses the agent's system prompt and is limited to its granted connectors and credentials; read the reply over SSE.

Can I edit or delete the built-in system agent?

No. The system agent is read-only and rejects mutations with HTTP 400. Your custom agents support PATCH (partial update) and DELETE (soft delete).

Frequently asked questions

What is an agent?

A profile (name, description, system prompt, avatar) plus a set of allowed connectors and granted credentials. Running a session with agent_id restricts the assistant to exactly those connectors and credentials.

What is the difference between allowed connectors and granted credentials?

Connectors define which tools the agent may use; credentials decide which accounts it acts on. Set connectors with PUT .../connectors and grant credentials chosen from /available-credentials.

How do I run a chat session under a specific agent?

Pass agent_id in the POST /sessions/stream body. The turn uses the agent's system prompt and is limited to its granted connectors and credentials; read the reply over SSE.

Can I edit or delete the built-in system agent?

No. The system agent is read-only and rejects mutations with HTTP 400. Your custom agents support PATCH (partial update) and DELETE (soft delete).

Was this page helpful?