Mikhail Putilovskij
b6df29bd9b
- Surface Protocol: unified IncomingMessage/OutgoingUI/ChatContext - Telegram: Forum Topics (group + topics per chat) - Matrix: Space + rooms per chat - MockPlatformClient with PlatformClient Protocol - docs: surface-protocol, telegram/matrix specs, api-contract, claude-code-guide - project scaffold: src/, tests/, pyproject.toml Co-Authored-By: Claude Sonnet 4-6 <noreply@anthropic.com>
3.1 KiB
API Contract — Lambda Platform
Статус: ЧЕРНОВИК — проектируем сами, не ждём SDK Автор: @architect Последнее обновление: заполнить дату
Это описание того, что нам нужно от платформы.
MockPlatformClient реализует этот контракт. При подключении реального SDK — только он меняется.
Base URL
https://api.lambda-platform.io/v1
Аутентификация
Authorization: Bearer {SERVICE_TOKEN}
Сервисный токен выдаётся команде поверхностей. Не путать с токеном пользователя.
Users
GET /users/{external_id}?platform={platform}
Получает или создаёт пользователя.
Query params:
platform—telegram|matrix
Response 200:
{
"user_id": "usr_abc123",
"external_id": "12345678",
"platform": "telegram",
"display_name": "Иван Иванов",
"created_at": "2025-01-15T10:30:00Z",
"is_new": false
}
Sessions
POST /sessions
Создаёт новую сессию с AI-агентом.
Request:
{
"user_id": "usr_abc123",
"platform": "telegram",
"context": {}
}
Response 201:
{
"session_id": "ses_xyz789",
"agent_id": "agt_def456",
"created_at": "2025-01-15T10:30:00Z",
"expires_at": "2025-01-16T10:30:00Z"
}
GET /sessions/{session_id}
Получает информацию о сессии.
Response 200: — см. структуру выше + поле status: "active" | "closed"
Response 404: {"error": "SESSION_NOT_FOUND", "message": "..."}
DELETE /sessions/{session_id}
Завершает сессию.
Response 200:
{"closed": true}
Messages
POST /sessions/{session_id}/messages
Отправляет сообщение и получает ответ агента.
Request:
{
"text": "Привет, что ты умеешь?",
"attachments": []
}
Response 200:
{
"message_id": "msg_qwe012",
"response": "Я AI-агент Lambda...",
"tokens_used": 142,
"finished": true
}
GET /sessions/{session_id}/messages?limit=20&offset=0
История сообщений сессии.
Response 200:
[
{
"message_id": "msg_qwe012",
"user_text": "Привет",
"response": "Привет!",
"tokens_used": 42,
"created_at": "2025-01-15T10:31:00Z"
}
]
Error format
Все ошибки возвращаются в едином формате:
{
"error": "ERROR_CODE",
"message": "Human readable description",
"details": {}
}
Коды ошибок: SESSION_NOT_FOUND, USER_NOT_FOUND, RATE_LIMITED, PLATFORM_ERROR
TODO (открытые вопросы к команде платформы)
- Нужна ли стриминговая передача ответа (SSE / WebSocket)?
- Как обрабатываются вложения (изображения, файлы)?