from lambda_agent_api import AgentApi

Lambda Agent API

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

Установка

В master всегда будет актуальная рабочая версия.

pip install git+https://git.lambda.coredump.ru/platform/agent_api.git

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

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

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())

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

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

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

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

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

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

STATUS

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

{
  "type": "STATUS"
}

AGENT_EVENT

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

TEXT_CHUNK

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

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

END

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

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

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

ERROR

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

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

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

GRACEFUL_DISCONNECT

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

{
  "type": "GRACEFUL_DISCONNECT"
}