Перейти к основному содержимому

API-сервер

API-сервер предоставляет vibeos-agent в виде OpenAI-совместимой HTTP-конечной точки. Любой фронтенд, поддерживающий формат OpenAI — Open WebUI, LobeChat, LibreChat, NextChat, ChatBox и сотни других — может подключиться к vibeos-agent и использовать его в качестве бэкенда.

Ваш агент обрабатывает запросы, используя полный набор инструментов (терминал, файловые операции, веб-поиск, память, навыки), и возвращает итоговый ответ. При стриминге индикаторы выполнения инструментов отображаются встроенно, чтобы фронтенды могли показывать, что делает агент.

Один бэкенд покрывает модели и инструменты

Для полезной работы API-сервера VibeOS требуется настроенный провайдер и инструментальные бэкенды. Подписка Nous Portal обеспечивает и то, и другое — более 300 моделей плюс веб, изображения, TTS и браузер через Tool Gateway. Выполните vibeos setup --portal один раз перед запуском API-сервера, и фронтенды вроде Open WebUI или LobeChat получат полностью оснащённый инструментами бэкенд.

Быстрый старт​

1. Включите API-сервер​

Добавьте в ~/.vibeos/.env:

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev
# Опционально: только если браузер должен напрямую вызывать VibeOS
# API_SERVER_CORS_ORIGINS=http://localhost:3000

2. Запустите шлюз​

vibeos gateway

Вы увидите:

[API Server] API server listening on http://127.0.0.1:8642

3. Подключите фронтенд​

Направьте любой OpenAI-совместимый клиент на http://localhost:8642/v1:

# Проверка с помощью curl
curl http://localhost:8642/v1/chat/completions \
-H "Authorization: Bearer change-me-local-dev" \
-H "Content-Type: application/json" \
-d '{"model": "vibeos-agent", "messages": [{"role": "user", "content": "Hello!"}]}'

Или подключите Open WebUI, LobeChat или любой другой фронтенд — смотрите руководство по интеграции Open WebUI для пошаговых инструкций.

Обёртка CLI (vibeos api)​

Для скриптов и CI используйте тонкий клиент вместо ручного curl:

vibeos api health
vibeos api chat "Hello"
vibeos api run "Investigate flaky test X" --wait
vibeos api runs --status running --limit 20
vibeos api stream run_…

Смотрите навык vibeos-api-automation (и open-webui-vibeos для браузерного UI). Базовый URL по умолчанию: http://127.0.0.1:8642; переопределите с помощью --base-url / $VIBEOS_API_BASE. Аутентификация использует $API_SERVER_KEY.

Вкладка «Операции» на панели управления: установите examples/plugins/vibeos-runs-inspector/ → API Runs.

Конечные точки​

POST /v1/chat/completions​

Стандартный формат OpenAI Chat Completions. Не сохраняет состояние — полный диалог включается в каждый запрос через массив messages.

Запрос:

{
"model": "vibeos-agent",
"messages": [
{"role": "system", "content": "You are a Python expert."},
{"role": "user", "content": "Write a fibonacci function"}
],
"stream": false
}

Ответ:

{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1710000000,
"model": "vibeos-agent",
"choices": [{
"index": 0,
"message": {"role": "assistant", "content": "Here's a fibonacci function..."},
"finish_reason": "stop"
}],
"usage": {"prompt_tokens": 50, "completion_tokens": 200, "total_tokens": 250}
}

Встроенный ввод изображений: сообщения пользователя могут отправлять content в виде массива частей text и image_url. Поддерживаются как удалённые http(s) URL, так и URL вида data:image/...:

{
"model": "vibeos-agent",
"messages": [
{
"role": "user",
"content": [
{"type": "text", "text": "What is in this image?"},
{"type": "image_url", "image_url": {"url": "https://example.com/cat.png", "detail": "high"}}
]
}
]
}

Загруженные файлы (file / input_file / file_id) и URL data: не для изображений возвращают 400 unsupported_content_type.

Стриминг ("stream": true): Возвращает Server-Sent Events (SSE) с фрагментами ответа токен за токеном. Для Chat Completions поток использует стандартные события chat.completion.chunk плюс пользовательское событие VibeOS vibeos.tool.progress для UX начала работы инструмента. Для Responses поток использует типы событий OpenAI Responses, такие как response.created, response.output_text.delta, response.output_item.added, response.output_item.done и response.completed.

Прогресс инструментов в потоках:

  • Chat Completions: VibeOS отправляет event: vibeos.tool.progress для отображения начала работы инструмента без загрязнения сохранённого текста ассистента.
  • Responses: VibeOS отправляет нативные для спецификации элементы вывода function_call и function_call_output во время потока SSE, чтобы клиенты могли отображать структурированный UI инструментов в реальном времени.

POST /v1/responses​

Формат OpenAI Responses API. Поддерживает состояние диалога на стороне сервера через previous_response_id — сервер хранит полную историю диалога (включая вызовы инструментов и результаты), так что контекст многошагового общения сохраняется без управления им со стороны клиента.

Запрос:

{
"model": "vibeos-agent",
"input": "What files are in my project?",
"instructions": "You are a helpful coding assistant.",
"store": true
}

Ответ:

{
"id": "resp_abc123",
"object": "response",
"status": "completed",
"model": "vibeos-agent",
"output": [
{"type": "function_call", "name": "terminal", "arguments": "{\"command\": \"ls\"}", "call_id": "call_1"},
{"type": "function_call_output", "call_id": "call_1", "output": "README.md src/ tests/"},
{"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "Your project has..."}]}
],
"usage": {"input_tokens": 50, "output_tokens": 200, "total_tokens": 250}
}

Встроенный ввод изображений: input[].content может содержать части input_text и input_image. Поддерживаются как удалённые URL, так и URL вида data:image/...:

{
"model": "vibeos-agent",
"input": [
{
"role": "user",
"content": [
{"type": "input_text", "text": "Describe this screenshot."},
{"type": "input_image", "image_url": "data:image/png;base64,iVBORw0K..."}
]
}
]
}

Загруженные файлы (input_file / file_id) и URL data: не для изображений возвращают 400 unsupported_content_type.

Многошаговое общение с previous_response_id​

Связывайте ответы для сохранения полного контекста (включая вызовы инструментов) между шагами:

{
"input": "Now show me the README",
"previous_response_id": "resp_abc123"
}

Сервер восстанавливает полный диалог из сохранённой цепочки ответов — все предыдущие вызовы инструментов и результаты сохраняются. Связанные запросы также используют один и тот же сеанс, поэтому многошаговые диалоги отображаются как одна запись на панели управления и в истории сеансов.

Именованные диалоги​

Используйте параметр conversation вместо отслеживания идентификаторов ответов:

{"input": "Hello", "conversation": "my-project"}
{"input": "What's in src/?", "conversation": "my-project"}
{"input": "Run the tests", "conversation": "my-project"}

Сервер автоматически связывает с последним ответом в этом диалоге. Аналогично команде /title для сеансов шлюза.

GET /v1/responses/{id}​

Получить ранее сохранённый ответ по идентификатору.

DELETE /v1/responses/{id}​

Удалить сохранённый ответ.

GET /v1/models​

Выводит агента как доступную модель. Отображаемое имя модели по умолчанию соответствует имени профиля (или vibeos-agent для профиля по умолчанию). Требуется большинством фронтендов для обнаружения моделей.

GET /v1/capabilities​

Возвращает машиночитаемое описание стабильной поверхности API-сервера для внешних UI, оркестраторов и плагинных мостов.

{
"object": "vibeos.api_server.capabilities",
"platform": "vibeos-agent",
"model": "vibeos-agent",
"auth": {"type": "bearer", "required": true},
"features": {
"chat_completions": true,
"responses_api": true,
"run_submission": true,
"run_status": true,
"run_events_sse": true,
"run_stop": true
}
}

Используйте эту конечную точку при интеграции панелей управления, браузерных UI или плоскостей управления, чтобы они могли определить, поддерживает ли работающая версия VibeOS запуски, стриминг, отмену и непрерывность сеансов, не полагаясь на закрытые внутренности Python.

GET /health​

Проверка работоспособности. Возвращает {"status": "ok"}. Также доступна по адресу GET /v1/health для OpenAI-совместимых клиентов, ожидающих префикс /v1/.

GET /health/detailed​

Расширенная проверка работоспособности, которая также сообщает об активных сеансах, работающих агентах и использовании ресурсов. Полезна для инструментов мониторинга и наблюдаемости.

API запусков (стриминг-ориентированная альтернатива)​

В дополнение к /v1/chat/completions и /v1/responses сервер предоставляет API запусков для длительных сеансов, где клиент хочет подписаться на события прогресса вместо самостоятельного управления стримингом.

POST /v1/runs​

Создать новый запуск агента. Возвращает run_id, который можно использовать для подписки на события прогресса.

{
"run_id": "run_abc123",
"status": "started"
}

Запуски принимают простую строку input и опциональные session_id, instructions, conversation_history или previous_response_id. При указании session_id VibeOS отображает его в статусе запуска, чтобы внешние UI могли сопоставлять запуски со своими идентификаторами диалогов.

GET /v1/runs​

Вывести список недавних статусов запусков в памяти (локально для процесса; теряются при перезапуске шлюза). Опциональные параметры запроса: ?status=running и ?limit=50 (макс. 200). Сначала новые.

{
"object": "list",
"data": [{"object": "vibeos.run", "run_id": "run_abc123", "status": "completed"}],
"has_more": false
}

Объявляется в /v1/capabilities как runs_list.

GET /v1/runs/{run_id}​

Опрос текущего состояния запуска. Полезно для панелей управления, которым нужен статус без удержания открытого SSE-соединения, или для UI, которые переподключаются после навигации.

{
"object": "vibeos.run",
"run_id": "run_abc123",
"status": "completed",
"session_id": "space-session",
"model": "vibeos-agent",
"output": "Done.",
"usage": {"input_tokens": 50, "output_tokens": 200, "total_tokens": 250}
}

Статусы сохраняются ненадолго после конечных состояний (completed, failed или cancelled) для опроса и согласования UI.

GET /v1/runs/{run_id}/events​

Поток Server-Sent Events с прогрессом вызовов инструментов, дельтами токенов и событиями жизненного цикла запуска. Предназначен для панелей управления и «толстых» клиентов, которые хотят подключаться/отключаться без потери состояния.

POST /v1/runs/{run_id}/stop​

Прервать текущий шаг агента. Конечная точка возвращает {"status": "stopping"} немедленно, пока VibeOS просит активного агента остановиться в ближайшей безопасной точке прерывания.

POST /v1/runs/{run_id}/approval​

Разрешить ожидающее утверждение для запуска, который ждёт решения человека (например, вызов инструмента, заблокированный политикой утверждения). Тело запроса содержит решение об утверждении; запуск возобновляется после записи решения. Эта конечная точка объявляется в /v1/capabilities как функция run_approval, чтобы внешние UI могли обнаружить поддержку перед отображением запроса на утверждение.

API заданий (фоновая работа по расписанию)​

Сервер предоставляет лёгкую CRUD-поверхность для заданий для управления запланированными / фоновыми запусками агента с удалённого клиента. Все конечные точки защищены той же bearer-аутентификацией.

GET /api/jobs​

Вывести список всех запланированных заданий.

POST /api/jobs​

Создать новое запланированное задание. Тело принимает ту же структуру, что и vibeos cron — промпт, расписание, навыки, переопределение провайдера, цель доставки.

GET /api/jobs/{job_id}​

Получить определение одного задания и состояние последнего запуска.

PATCH /api/jobs/{job_id}​

Обновить поля существующего задания (промпт, расписание и т.д.). Частичные обновления объединяются.

DELETE /api/jobs/{job_id}​

Удалить задание. Также отменяет любой выполняющийся запуск.

POST /api/jobs/{job_id}/pause​

Приостановить задание без удаления. Метки времени следующего запланированного запуска приостанавливаются до возобновления.

POST /api/jobs/{job_id}/resume​

Возобновить ранее приостановленное задание.

POST /api/jobs/{job_id}/run​

Запустить задание немедленно, вне расписания.

API сеансов (управление сеансами через REST)​

Внешние UI могут управлять сеансами VibeOS через REST без использования панели управления. Все конечные точки защищены API_SERVER_KEY и находятся по адресу /api/sessions/*.

МетодПутьОписание
GET/api/sessionsСписок сеансов (с пагинацией — limit, offset, source, include_children)
POST/api/sessionsСоздать пустой сеанс; при необходимости привязать зарегистрированный проект
GET/api/sessions/{id}Прочитать метаданные сеанса
PATCH/api/sessions/{id}Обновить заголовок или end_reason
DELETE/api/sessions/{id}Удалить сеанс
GET/api/sessions/{id}/messagesИстория сообщений сеанса
POST/api/sessions/{id}/forkРазветвить сеанс через родословную SessionDB (соответствует семантике CLI /branch)
POST/api/sessions/{id}/chatВыполнить один синхронный шаг агента
POST/api/sessions/{id}/chat/streamSSE-обёртка над одним шагом — отправляет события assistant.delta, tool.started, tool.completed, run.completed

/v1/capabilities объявляет полную поверхность через флаги функций session_* и записи endpoints.session_*, чтобы внешние UI могли обнаружить поддержку и безопасно откатиться. Встроенные изображения поддерживаются в полезных нагрузках chat и chat/stream (мультимодальный путь).

Чтобы память и инструменты терминала/файлов API были привязаны к проекту, создайте сессию с зарегистрированным slug или ID проекта. VibeOS сохраняет устойчивый project_id, использует рабочую папку проекта только в task-local контексте этого запроса и изолирует одновременные API-сессии. Неизвестный проект отклоняется ответом 400 project_not_found.

# создать сессию в зарегистрированном проекте "vibeos"
curl -X POST http://localhost:8642/api/sessions \
-H "Authorization: Bearer $API_SERVER_KEY" \
-H "Content-Type: application/json" \
-d '{"title": "проверить память", "project": "vibeos"}'

# разветвить сеанс и выполнить один шаг
curl -X POST http://localhost:8642/api/sessions/$ID/fork \
-H "Authorization: Bearer $API_SERVER_KEY" \
-d '{"title": "explore alt path"}'

# стриминг шага через SSE
curl -N -X POST http://localhost:8642/api/sessions/$ID/chat/stream \
-H "Authorization: Bearer $API_SERVER_KEY" \
-d '{"input": "what files changed in the last hour?"}'

Обнаружение навыков и наборов инструментов​

GET /v1/skills и GET /v1/toolsets позволяют внешним клиентам детерминированно перечислять возможности агента через REST, а не спрашивать модель. Оба доступны только для чтения и защищены API_SERVER_KEY.

curl http://localhost:8642/v1/skills \
-H "Authorization: Bearer $API_SERVER_KEY"
# → [{"name": "github-pr-workflow", "description": "...", "category": "..."}, ...]

curl http://localhost:8642/v1/toolsets \
-H "Authorization: Bearer $API_SERVER_KEY"
# → [{"name": "core", "label": "...", "description": "...", "enabled": true,
# "configured": true, "tools": ["read_file", "write_file", ...]}, ...]

/v1/skills возвращает те же метаданные, которые внутренне использует центр навыков. /v1/toolsets возвращает наборы инструментов, разрешённые для платформы api_server, с конкретным списком tools, в который они разворачиваются. Оба объявляются в endpoints.* в /v1/capabilities.

Область долговременной памяти (X-VibeOS-Session-Key)​

Многопользовательским фронтендам, таким как Open WebUI, требуется стабильный идентификатор канала для долговременной памяти, который не зависит от привязанного к транскрипту X-VibeOS-Session-Id (который меняется при /new). Передайте X-VibeOS-Session-Key в /v1/chat/completions, /v1/responses, /v1/runs и в каждый связанный запрос /api/sessions. VibeOS передаст его в AIAgent(gateway_session_key=...) для провайдеров вроде Honcho и также создаст отдельную область владельца API для встроенной памяти USER.md, поиска сессий и REST API сессий. Поэтому два канала одного развёртывания API не будут молча использовать одну и ту же память или перечислять сессии друг друга.

POST /v1/chat/completions HTTP/1.1
Authorization: Bearer ***
X-VibeOS-Session-Id: transcript-alpha
X-VibeOS-Session-Key: agent:main:webui:dm:user-42

Правила: максимум 256 символов, управляющие символы (\r, \n, \x00) отклоняются, значение повторяется в ответах (JSON + SSE). /v1/capabilities объявляет поддержку через "session_key_header": "X-VibeOS-Session-Key". Ключ — это разрешённое сервером разделение для клиента, но не замена аутентификации каждого человека: клиенты с общим ключом сервера всё ещё могут намеренно указать один и тот же ключ канала, а враждебное многопользовательское развёртывание обязано аутентифицировать пользователей до API. Без ключа стратегия Honcho per-session создаёт другую область для каждого session_id — именно такое поведение было у VibeOS раньше.

Обработка системного промпта​

Когда фронтенд отправляет системное сообщение (Chat Completions) или поле instructions (Responses API), vibeos-agent накладывает его поверх своего основного системного промпта. Ваш агент сохраняет все свои инструменты, память и навыки — системный промпт фронтенда добавляет дополнительные инструкции.

Это означает, что вы можете настраивать поведение для каждого фронтенда без потери возможностей:

  • Системный промпт Open WebUI: «Вы эксперт по Python. Всегда включайте подсказки типов.»
  • Агент по-прежнему имеет терминал, файловые инструменты, веб-поиск, память и т.д.

Аутентификация​

Аутентификация с помощью bearer-токена через заголовок Authorization:

Authorization: Bearer ***

Настройте ключ через переменную окружения API_SERVER_KEY. Если браузер должен напрямую вызывать VibeOS, также установите API_SERVER_CORS_ORIGINS в явный список разрешённых.

Безопасность

API-сервер предоставляет полный доступ к набору инструментов vibeos-agent, включая терминальные команды. API_SERVER_KEY обязателен для каждого развёртывания, включая привязку к loopback по умолчанию на 127.0.0.1. Сужайте API_SERVER_CORS_ORIGINS для контроля доступа браузера, когда вы явно разрешаете вызовы из браузера.

Конфигурация​

Переменные окружения​

ПеременнаяПо умолчаниюОписание
API_SERVER_ENABLEDfalseВключить API-сервер
API_SERVER_PORT8642Порт HTTP-сервера
API_SERVER_HOST127.0.0.1Адрес привязки (только localhost по умолчанию)
API_SERVER_KEY(обязательно)Bearer-токен для аутентификации
API_SERVER_CORS_ORIGINS(нет)Разрешённые источники браузера через запятую
API_SERVER_MODEL_NAME(имя профиля)Имя модели в /v1/models. По умолчанию — имя профиля или vibeos-agent для профиля по умолчанию.

config.yaml​

# Пока не поддерживается — используйте переменные окружения.
# Поддержка config.yaml появится в одном из будущих релизов.

Заголовки безопасности​

Все ответы включают заголовки безопасности:

  • X-Content-Type-Options: nosniff — предотвращает подмену MIME-типа
  • Referrer-Policy: no-referrer — предотвращает утечку реферера

CORS​

API-сервер не включает CORS для браузера по умолчанию.

Для прямого доступа из браузера установите явный список разрешённых:

API_SERVER_CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

Когда CORS включён:

  • Предварительные ответы включают Access-Control-Max-Age: 600 (кэш на 10 минут)
  • SSE-стриминг ответов включает заголовки CORS, чтобы клиенты EventSource в браузере работали корректно
  • Idempotency-Key является разрешённым заголовком запроса — клиенты могут отправлять его для дедупликации (ответы кэшируются по ключу на 5 минут)

Большинство документированных фронтендов, таких как Open WebUI, подключаются «сервер-к-серверу» и не нуждаются в CORS.

Совместимые фронтенды​

Любой фронтенд, поддерживающий формат API OpenAI, работает. Протестированные/документированные интеграции:

ФронтендЗвёздыПодключение
Open WebUI126kПолное руководство доступно
LobeChat73kПользовательская конечная точка провайдера
LibreChat34kПользовательская конечная точка в librechat.yaml
AnythingLLM56kУниверсальный провайдер OpenAI
NextChat87kПеременная окружения BASE_URL
ChatBox39kНастройка API Host
Jan26kКонфигурация удалённой модели
HF Chat-UI8kOPENAI_BASE_URL
big-AGI7kПользовательская конечная точка
OpenAI Python SDK—OpenAI(base_url="http://localhost:8642/v1")
curl—Прямые HTTP-запросы

Многопользовательская настройка с профилями​

Чтобы предоставить нескольким пользователям собственные изолированные экземпляры VibeOS (отдельная конфигурация, память, навыки), используйте профили:

# Создайте профиль для каждого пользователя
vibeos profile create alice
vibeos profile create bob

# Настройте API-сервер каждого профиля на другом порту. API_SERVER_* — это
# переменные окружения (не ключи config.yaml), поэтому запишите их в .env каждого профиля:
cat >> ~/.vibeos/profiles/alice/.env <<EOF
API_SERVER_ENABLED=true
API_SERVER_PORT=8643
API_SERVER_KEY=alice-secret
EOF

cat >> ~/.vibeos/profiles/bob/.env <<EOF
API_SERVER_ENABLED=true
API_SERVER_PORT=8644
API_SERVER_KEY=bob-secret
EOF

# Запустите шлюз каждого профиля
vibeos -p alice gateway &
vibeos -p bob gateway &

API-сервер каждого профиля автоматически объявляет имя профиля как идентификатор модели:

  • http://localhost:8643/v1/models → модель alice
  • http://localhost:8644/v1/models → модель bob

В Open WebUI добавьте каждое как отдельное подключение. Выпадающий список моделей покажет alice и bob как отдельные модели, каждая из которых поддерживается полностью изолированным экземпляром VibeOS. Смотрите руководство Open WebUI для подробностей.

Ограничения​

  • Хранение ответов — сохранённые ответы (для previous_response_id) хранятся в SQLite и переживают перезапуски шлюза. Максимум 100 сохранённых ответов (вытеснение LRU).
  • Нет загрузки файлов — встроенные изображения поддерживаются как в /v1/chat/completions, так и в /v1/responses, но загруженные файлы (file, input_file, file_id) и неграфические документы через API не поддерживаются.
  • Поле model косметическое — поле model в запросах принимается, но фактическая используемая LLM-модель настраивается на стороне сервера в config.yaml.

Режим прокси​

API-сервер также служит бэкендом для режима прокси шлюза. Когда другой экземпляр шлюза VibeOS настроен с GATEWAY_PROXY_URL, указывающим на этот API-сервер, он пересылает все сообщения сюда вместо запуска собственного агента. Это позволяет разделённые развёртывания — например, Docker-контейнер, обрабатывающий Matrix E2EE, который ретранслирует агенту на хосте.

Смотрите Matrix Proxy Mode для полного руководства по настройке.