agent_api/README.md

# Lambda Agent API

WebSocket API SDK для взаимодействия с AI-агентом.

## Release Notes
# v1.1
- **CRITICAL**: `AgentAPI` вместо `url` принимает `base_url` и сам дописывает нужный эндпоинт.
 Раньше: `AgentAPI(url="ws://localhost:8000/agent_ws/")`. Сейчас: `AgentAPI(base_url="ws://localhost:8000/")`
- Добавлен параметр `chat_id` в конструктор `AgentAPI`. Нужен для разделения истории сообщений по чатам/веткам.
- `AgentAPI.connect()` вызывает `AgentBusyException`, если выбранный чат уже занят другим API клиентом.
- Добавлен новый тип события `MsgEventSendFile` для отправки файлов пользователю. Поле `path` — путь к файлу относительно `/workspace`.
- `send_message(text, attachments)` теперь принимает `attachments` — список путей к файлам относительно `/workspace`.

## Установка
В `master` всегда будет актуальная рабочая версия.
```bash
pip install git+https://git.lambda.coredump.ru/platform/agent_api.git
```

Требуется Python 3.14+.

## Быстрый старт (с использованием AgentApi)

**Рабочий REPL пример: [tests/manual.py](tests/manual.py).**


## Предполагаемое управление подключениями

```python
from lambda_agent_api.agent_api import AgentApi

connected_agents: dict[str, AgentApi] = {}


# агент автоматически выключится после нескольких минут бездействия
# этот колбек вызовется при разрыве соединения
def on_agent_disconnect(agent: AgentApi):
    del connected_agents[agent.id]


async def on_telegram_message(from_user: int, text: str):
    agent_id = get_agent_id_by_user(user_id)

    agent = connected_agents.get(agent_id, None)
    if not agent:
        agent = AgentApi(agent_id, get_agent_url(agent_id), on_disconnect=on_agent_disconnect)
        await agent.connect()
        connected_agents[agent_id] = agent

    async for event in agent.send_message(text):
        ...
```

# Обработка ошибок

- `AgentBusyException` возникает, если отправить `send_message` пока предыдущий запрос ещё в процессе.
- `AgentException` возникает, если агент возвращает `ERROR` или есть проблемы с подключением.
- `on_disconnect` callback вызывается один раз при закрытии/разрыве соединения.


## Протокол

### Клиент → Сервер

#### USER_MESSAGE

Полное сообщение от пользователя.

```json
{
  "type": "USER_MESSAGE",
  "text": "Текст сообщения"
}
```

| Поле | Тип   | Описание          |
|------|-------|-------------------|
| type | string | Всегда `USER_MESSAGE` |
| text | string | Текст сообщения  |

### Сервер → Клиент

#### STATUS

Отправляется сервером при открытии соединения с клиентом. Будет дополнен информацией о готовности агента принимать сообщения.

```json
{
  "type": "STATUS"
}
```

#### AGENT_EVENT_TEXT_CHUNK

Чанк текста ответа агента.

```json
{
  "type": "AGENT_EVENT_TEXT_CHUNK",
  "text": "Фрагмент текста",
  "source": "main"
}
```

| Поле   | Тип    | Описание                                      |
|--------|--------|-----------------------------------------------|
| type   | string | Всегда `AGENT_EVENT_TEXT_CHUNK`              |
| text   | string | Фрагмент текста ответа агента                |
| source | string | Источник события (по умолчанию "main")       |

#### AGENT_EVENT_TOOL_CALL_CHUNK

Агент решил использовать инструмент и генерирует аргументы.

```json
{
  "type": "AGENT_EVENT_TOOL_CALL_CHUNK",
  "tool_name": "имя_инструмента",
  "args_chunk": "{\"key\": \"value\"}",
  "source": "main"
}
```

| Поле        | Тип     | Описание                                      |
|-------------|---------|-----------------------------------------------|
| type        | string  | Всегда `AGENT_EVENT_TOOL_CALL_CHUNK`         |
| tool_name   | string  | Имя инструмента (может быть null в первом чанке) |
| args_chunk  | string  | Кусок JSON-аргументов (может быть null)      |
| source      | string  | Источник события (по умолчанию "main")       |

#### AGENT_EVENT_TOOL_RESULT

Инструмент отработал и вернул результат.

```json
{
  "type": "AGENT_EVENT_TOOL_RESULT",
  "tool_name": "имя_инструмента",
  "result": "результат выполнения",
  "source": "main"
}
```

| Поле       | Тип    | Описание                                      |
|------------|--------|-----------------------------------------------|
| type       | string | Всегда `AGENT_EVENT_TOOL_RESULT`             |
| tool_name  | string | Имя инструмента                              |
| result     | any    | Результат выполнения (строка, объект или массив) |
| source     | string | Источник события (по умолчанию "main")       |

#### AGENT_EVENT_CUSTOM_UPDATE

Кастомный прогресс (например, скачивание файла) изнутри инструмента.

```json
{
  "type": "AGENT_EVENT_CUSTOM_UPDATE",
  "payload": {"status": "in_progress", "progress": 50},
  "source": "main"
}
```

| Поле     | Тип             | Описание                                      |
|----------|-----------------|-----------------------------------------------|
| type     | string          | Всегда `AGENT_EVENT_CUSTOM_UPDATE`           |
| payload  | object          | Любые данные о прогрессе                      |
| source   | string          | Источник события (по умолчанию "main")       |

#### AGENT_EVENT_SEND_FILE

Агент отправляет файл пользователю. Путь к файлу относительно `/workspace`.

```json
{
  "type": "AGENT_EVENT_SEND_FILE",
  "path": "reports/2024/report.pdf"
}
```

| Поле   | Тип    | Описание                                      |
|--------|--------|-----------------------------------------------|
| type   | string | Всегда `AGENT_EVENT_SEND_FILE`                |
| path   | string | Путь к файлу относительно `/workspace`       |

#### AGENT_EVENT_END

Агент закончил генерацию ответа.

```json
{
  "type": "AGENT_EVENT_END",
  "tokens_used": 42
}
```

| Поле        | Тип    | Описание                                      |
|-------------|--------|-----------------------------------------------|
| type        | string | Всегда `AGENT_EVENT_END`                     |
| tokens_used | int    | Количество использованных токенов            |

#### ERROR

Неопределенная ошибка в работе агента.

```json
{
  "type": "ERROR",
  "code": "error_code",
  "details": "Описание ошибки"
}
```

| Поле    | Тип   | Описание       |
|---------|-------|----------------|
| code    | string | Код ошибки    |
| details | string | Подробности   |

#### GRACEFUL_DISCONNECT

Отправляется перед завершением работы контейнера с агентом. Например, при долгом бездействии. Нужно, чтобы отделять обрыв соединения из-за ошибки с необходимостью повторного подключения. Приход этого сообщения означает, что агент осознанно завершает работу с клиентом по какой-то причине. Для дальнейшего взаимодействия нужно снова обратиться к мастеру.

```json
{
  "type": "GRACEFUL_DISCONNECT"
}
```

Неопределенная ошибка в работе агента.

```json
{
  "type": "ERROR",
  "code": "error_code",
  "details": "Описание ошибки"
}
```

| Поле    | Тип   | Описание       |
|---------|-------|----------------|
| code    | string | Код ошибки    |
| details | string | Подробности   |

#### GRACEFUL_DISCONNECT

Отправляется перед завершением работы контейнера с агентом. Например, при долгом бездействии. Нужно, чтобы отделять обрыв соединения из-за ошибки с необходимостью повторного подключения. Приход этого сообщения означает, что агент осознанно завершает работу с клиентом по какой-то причине. Для дальнейшего взаимодействия нужно снова обратиться к мастеру.

```json
{
  "type": "GRACEFUL_DISCONNECT"
}
```

![Схема взаимодействия](docs/schema.png)