from lambda_agent_api import AgentApi

# Lambda Agent API

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

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

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

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

```python
import asyncio

from lambda_agent_api.agent_api import AgentApi
from lambda_agent_api.server import MsgEventTextChunk


async def main():
    api = AgentApi("agent-1", "ws://localhost:8000/ws")

    await api.connect()
    try:
        response = await api.send_message("Привет, агент!")

        async for chunk in response:
            if isinstance(chunk, MsgEventTextChunk):
                print(chunk.text, end="", flush=True)

    finally:
        await api.close()


asyncio.run(main())
```

## Предполагаемое использование

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

Базовый класс для ивентов, которые стримит агент во время генерации ответа. Конкретный класс для ивента определяется по `subtype`.

##### TEXT_CHUNK

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

```json
{
  "type": "AGENT_EVENT",
  "subtype": "TEXT_CHUNK",
  "text": "Фрагмент текста"
}
```

##### END

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

```json
{
  "type": "AGENT_EVENT",
  "subtype": "END",
  "tokens_used": 42
}
```

| Поле        | Тип    | Описание              |
|-------------|--------|-----------------------|
| tokens_used | int    | Количество использованных токенов |

#### ERROR

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

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

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

#### GRACEFUL_DISCONNECT

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

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

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