# 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.

```bash
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"
  }'
```

```json
{
  "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).

```bash
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.

```bash
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.

```bash
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.

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

```json
[
  {
    "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}`.

```bash
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)](/docs/streaming). The assistant uses the agent's system prompt and is limited to its granted connectors and credentials.

```bash
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.

_The full agent tool catalog is rendered on this page._

## 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:

```bash
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"]
```