Программная интеграция
VibeOS поставляется с тремя протоколами для управления агентом из внешних программ — плагинов IDE, пользовательских интерфейсов, CI-пайплайнов, встроенных под-агентов. Выберите тот, который соответствует вашему транспорту и потребителю.
| Протокол | Транспорт | Лучше всего подходит для | Определяется |
|---|---|---|---|
| ACP | JSON-RPC через stdio | Клиенты IDE (VS Code, Zed, JetBrains), которые уже поддерживают Agent Client Protocol | acp_adapter/ |
| TUI-шлюз | JSON-RPC через stdio (или WebSocket) | Пользовательские хосты, которым нужен детальный контроль сессий, слеш-команд, подтверждений и потоковых событий | tui_gateway/server.py |
| API-сервер | HTTP + Server-Sent Events | Фронтенды, совместимые с OpenAI (Open WebUI, LobeChat, LibreChat…) и языконезависимые веб-клиенты | gateway/platforms/api_server.py |
Все три управляют одним и тем же ядром AIAgent. Они различаются только форматом передачи данных и набором доступных функций.
ACP (Agent Client Protocol)
vibeos acp запускает JSON-RPC-сервер через stdio, работающий по протоколу ACP. Используется в продакшене с VS Code (расширение ACP от Zed Industries), Zed и любой IDE JetBrains с плагином ACP.
Доступные возможности: создание сессии, отправка промпта, потоковая передача фрагментов сообщений агента, события вызова инструментов, запросы разрешений, форк сессии, отмена и аутентификация. Вывод инструментов преобразуется в блоки контента ACP Diff/ToolCall, понятные IDE.
Полный жизненный цикл, мост событий и процесс утверждения: Внутреннее устройство ACP.
vibeos acp # запуск ACP через stdio
vibeos acp --bootstrap # вывод фрагмента установки для IDE, поддерживающей ACP
TUI-шлюз JSON-RPC
tui_gateway/server.py — это протокол, с которым общаются Ink TUI (vibeos --tui) и встроенный PTY-мост панели управления. Любой внешний хост может использовать тот же протокол через stdio (или WebSocket через tui_gateway/ws.py).
Каталог методов (выборочно)
prompt.submit prompt.background session.steer
session.create session.list session.active_list
session.activate session.close session.interrupt
session.history session.compress session.branch
session.title session.usage session.status
clarify.respond sudo.respond secret.respond
approval.respond config.set / config.get commands.catalog
command.resolve command.dispatch cli.exec
reload.mcp reload.env process.stop
delegation.status subagent.interrupt spawn_tree.save / list / load
terminal.resize clipboard.paste image.attach
session.active_list, session.activate и session.close — это элементы управления активными сессиями в рамках процесса, используемые переключателем сессий TUI. Используйте session.list / /resume для поиска сохранённых транскриптов; методы активных сессий применяйте только к сессиям, которые в данный момент открыты в процессе TUI-шлюза.
Потоковые события
message.delta, message.complete, tool.start, tool.progress, tool.complete, approval.request, clarify.request, sudo.request, secret.request, gateway.ready, а также события жизненного цикла сессии и ошибки.
Отображение RPC в стиле Pi
Каждая команда из спецификации RPC Pi-mono (issue #360) имеет эквивалент в TUI-шлюзе:
| Команда Pi | Эквивалент в VibeOS |
|---|---|
prompt | prompt.submit (или ACP session/prompt) |
steer | session.steer |
follow_up | prompt.submit в очереди после текущего хода |
abort | session.interrupt |
set_model | command.dispatch для /model <провайдер:модель> (в середине сессии, постоянно) |
compact | session.compress |
get_state | session.status |
get_messages | session.history |
switch_session | session.resume |
fork | session.branch |
ui_request / ui_response | clarify.respond / sudo.respond / secret.respond / approval.respond |
API-сервер, совместимый с OpenAI
gateway/platforms/api_server.py предоставляет vibeos через HTTP для любого клиента, который уже поддерживает формат OpenAI. Полезно, когда нужен веб-фронтенд, CI-раннер на curl или потребитель не на Python.
Эндпоинты:
POST /v1/chat/completions OpenAI Chat Completions (потоковая передача через SSE)
POST /v1/responses OpenAI Responses API (с сохранением состояния)
POST /v1/runs Запуск выполнения, возвращает run_id (202)
GET /v1/runs/{id} Статус выполнения
GET /v1/runs/{id}/events SSE-поток событий жизненного цикла
POST /v1/runs/{id}/approval Разрешение ожидающего подтверждения
POST /v1/runs/{id}/stop Прерывание выполнения
GET /v1/capabilities Машиночитаемые флаги функций
GET /v1/models Список vibeos-agent
GET /health, /health/detailed
Настройка, заголовки (X-VibeOS-Session-Id, X-VibeOS-Session-Key) и подключение фронтенда: API-сервер.
Какой из них использовать?
- Вы пишете плагин для IDE, и IDE уже поддерживает ACP → ACP. Нулевая работа с протоколом на стороне IDE.
- Вы пишете пользовательский десктопный / веб / TUI-хост и хотите все функции VibeOS (слеш-команды, подтверждения, уточнения, мультиагентность, ветвление сессий) → TUI-шлюз JSON-RPC.
- Вам нужен любой фронтенд, совместимый с OpenAI, языконезависимый HTTP-клиент или автоматизация через curl → API-сервер.
- Вам нужно встроить Python без подпроцесса → импортируйте
run_agent.AIAgentнапрямую. См. Цикл агента.
Горячая замена модели
Переключение модели в середине сессии работает на всех поверхностях — под капотом это слеш-команда /model.
- CLI / TUI:
/model claude-sonnet-4или/model openrouter:anthropic/claude-sonnet-4.6 - TUI-шлюз RPC:
command.dispatchс{"command": "/model claude-sonnet-4"} - ACP: IDE отправляет слеш-команду как промпт; агент её обрабатывает
- API-сервер: включите поле
modelв тело запроса или установитеX-VibeOS-Model
Разрешение с учётом провайдера (одно и то же имя модели выбирает правильный формат для вашего провайдера) встроено. См. vibeos_cli/model_switch.py.
Примечание о --mode rpc
VibeOS не имеет флага --mode rpc. Три описанных выше протокола уже покрывают все случаи использования — ACP для клиентов протокола IDE, TUI-шлюз для хостов JSON-RPC через stdio и API-сервер для HTTP. Если вы обнаружите реальный пробел, который ни один из них не заполняет, откройте issue с описанием конкретного потребителя, которого вы создаёте.