# Agents API

Настраивайте AI-агентов: системный промпт, набор разрешённых коннекторов и доступ к учётным записям организации. Те же эндпоинты используются разделом «Агенты» в самом приложении.

## Что такое агент

Агент — это профиль (имя, описание, системный промпт, аватар) плюс список разрешённых коннекторов и выданных учётных записей. Когда вы стартуете сессию с agent_id, ассистент работает под этим профилем и ограничен только теми коннекторами и учётками, которые вы выдали явно.

## Создать агента

POST с профилем агента. Обязательное поле — только name, остальные опциональны.

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

## Список и получение агента

В списке системный агент идёт первым, затем ваши пользовательские агенты (с пагинацией).

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

## Обновить или удалить

PATCH принимает частичный профиль. DELETE — мягкое удаление. Системный агент только для чтения и на любые мутации возвращает 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"
```

## Разрешённые коннекторы

PUT .../connectors задаёт полный список ключей коннекторов, которые агент может вызывать (wildberries, ozon, telegram, …). Пустой массив очищает список. Коннекторы — это какими инструментами агенту разрешено пользоваться; учётки — под какими аккаунтами.

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

## Доступные учётные записи

Возвращает все учётные записи организации под разрешённые агенту коннекторы плюс флаг granted — есть ли уже у агента доступ к ним.

```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..."
  }
]
```

## Выдать учётную запись

Берёте credential_id из /available-credentials и выдаёте его агенту. Опциональные scopes сужают, какие части учётки агент может использовать. Отзыв — `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"
```

## Запустить сессию под агентом

Передайте `agent_id` в теле `POST /sessions/stream`. Вызов запускает ход и возвращает `202` с его id — читайте ответ через SSE, как описано в разделе [Стриминг (SSE)](/docs/streaming). Ассистент возьмёт системный промпт агента и ограничится его коннекторами и учётками.

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

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

## Структура описания инструмента

Каждое описание инструмента самодостаточно — отдельного слоя гайдов нет. Модель читает описание дословно, поэтому все они следуют одной пятиблочной структуре:

1. **Назначение** — одно-два предложения: что инструмент делает и что возвращает.
2. **Когда использовать** — конкретные сценарии, где этот инструмент — правильный выбор.
3. **Когда НЕ использовать** — границы применимости с указанием конкретного альтернативного инструмента.
4. **Ключевые ограничения** — предусловия, форматы, лимиты, порядок вызовов и контракт ошибок.
5. **Интерпретация результата** — как читать ответ, когда повторять, когда остановиться.

Дескрипторы инструментов лежат в config/prompts/tools.yaml и имеют такую форму:

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