Skip to content

v0.5: Web UI And OpenAI-Compatible API [PARTIAL]

Implementation Status

  • [x] GatewayConfig exists in config/schema.py.
  • [x] Agent, AgentLoop, MessageBus, ChannelManager, and SessionManager expose reusable runtime hooks.
  • [x] observability/http_server.py exists for metrics.
  • [x] First-party product API server exists under g_agent/api/.
  • [x] api/openai_compat.py contains the current text-only OpenAI request and response helpers.
  • [x] GET /v1/models plus non-streaming and SSE POST /v1/chat/completions exist.
  • [x] Multipart POST /media stores files under the workspace and writes session media refs.
  • [x] channels/websocket.py exists as minimal aiohttp channel with local token auth and chat-id session mapping. Implemented, not Nanobot full surface.
  • [x] Approval list/approve/deny endpoints exist.
  • [x] Learning list/detail/approve/reject/edit/apply endpoints exist.
  • [x] Profile list/detail endpoints exist.
  • [x] API canonical + compatibility aliases tested: /api/health, /health, /api/status, /status, /api/v1/models, /v1/models, /api/v1/chat/completions, /v1/chat/completions.
  • [ ] No /v1/responses endpoint exists.
  • [x] webui/ exists: React SPA source/build/static serving/bootstrap tests exist; implemented core, tests minimal. Some stale Nanobot naming artifacts.
  • [ ] Advanced Nanobot features missing: token issuance endpoint, media signing, SSL/TLS, capability registry entry gap.

Goal

Add a first-party control room and make other clients able to talk to G-Agent.

User Outcome

The owner can use a local Web UI to inspect sessions, channels, approvals, learning queue, character profiles, memory, skills, routines, providers, and visual settings. External clients can use OpenAI-compatible endpoints.

Scope

  • Add WebSocket channel with local-first bind, token auth, streaming deltas, session list, media upload envelope, and lifecycle events.
  • Add REST endpoints for health/status, sessions, history, media upload, pending approvals, learning queue, and character profiles.
  • Add OpenAI-compatible API endpoints.
  • Build Web UI around G-Agent's actual product, not just a generic chat box.

API Surface

  • GET /health
  • GET /status
  • GET /sessions
  • GET /sessions/{id}
  • POST /media
  • GET /approvals
  • POST /approvals/{id}/approve
  • POST /approvals/{id}/deny
  • GET /learning
  • POST /learning/{candidate_id}/apply
  • GET /profiles
  • GET /profiles/{id}
  • GET /v1/models
  • POST /v1/chat/completions
  • POST /v1/responses later

Module Targets

  • backend/agent/g_agent/api/server.py
  • backend/agent/g_agent/api/openai_compat.py
  • backend/agent/g_agent/channels/websocket.py
  • webui/
  • backend/agent/tests/test_api_*.py
  • backend/agent/tests/test_websocket_*.py

Acceptance Criteria

  • [x] WebSocket accepts inbound messages and sends outbound runtime messages.
  • [x] WebSocket streams full message lifecycle events.
  • [x] API can list sessions and fetch history from the session store.
  • [x] OpenAI-compatible chat endpoint talks to the active character.
  • [x] OpenAI-compatible chat endpoint can return SSE chunks for stream=true.
  • [x] Media upload stores references in session store.
  • [x] Pending approvals are visible and actionable through API.
  • [x] Learning queue is visible and skill candidates are applicable through API.
  • [x] Character profiles are visible through API.
  • [x] Web UI exposes real runtime controls.

References

  • nanobot-ref/webui
  • nanobot-ref/nanobot/channels/websocket.py
  • nanobot-ref/nanobot/api/server.py
  • hermes-agent-ref/gateway/platforms/api_server.py

Agent Handoff

Current G-Agent State

  • g_agent/api/server.py exposes an aiohttp app factory and g-agent api starts it with local-first bind defaults.
  • channels/websocket.py exists as minimal aiohttp channel with local token auth and chat-id session mapping. Implemented, not Nanobot full surface. Advanced Nanobot features missing: token issuance endpoint, media signing, SSL/TLS, capability registry entry gap.
  • webui/ exists: React SPA source/build/static serving/bootstrap tests exist; implemented core, tests minimal. Some stale Nanobot naming artifacts.
  • GatewayConfig exists in config/schema.py with host, port, optional API token, and request size limit.
  • AgentLoop, MessageBus, ChannelManager, and SessionManager already provide the runtime hooks needed for API/WebSocket.
  • observability/http_server.py exists for metrics; do not confuse it with the product API server.

Reference Details To Inspect

  • nanobot-ref/nanobot/api/server.py
  • smaller API implementation; good first reference.
  • JSON + multipart handling.
  • SSE chunks for chat completions.
  • /health and /v1/models.
  • nanobot-ref/nanobot/channels/websocket.py
  • WebSocket auth.
  • static SPA serving.
  • media upload and signed media URLs.
  • MIME hardening.
  • streaming events.
  • hermes-agent-ref/gateway/platforms/api_server.py
  • stronger long-term reference for /v1/responses, async runs, auth, request limits, SSE keepalive, and structured lifecycle events.

Implementation Strategy

Ship API before full Web UI. A tiny API proves the runtime boundary and gives the Web UI something real to call.

Recommended shape:

  • api/server.py: aiohttp app factory.
  • api/openai_compat.py: request/response conversion.
  • channels/websocket.py: runtime WebSocket channel after API basics.
  • webui/: only after sessions and API endpoints exist.

Implementation Slices

  1. Add local API server with /health, /status, /v1/models. Shipped.
  2. Add POST /v1/chat/completions non-streaming.
  3. Create an API session key.
  4. Publish inbound message or call embedded agent API if simpler. Shipped through embedded agent API.
  5. Add auth token.
  6. Config field under gateway or api.
  7. Bearer token support. Shipped.
  8. Add session endpoints backed by v0.2 store. Shipped.
  9. Add SSE streaming.
  10. Add WebSocket channel.
  11. Add Web UI control room.

API Compatibility Rules

  • Do not claim complete OpenAI compatibility at first.
  • Support common chat messages and text content first.
  • Multimodal normalization can follow Hermes patterns later.
  • /v1/responses should wait until chat completions is stable.

Tests

  • test_api_server.py
  • health/status/models
  • auth required when token configured
  • unauthorized request rejected
  • test_api_chat_completions.py
  • non-streaming happy path
  • bad request shape
  • session key behavior
  • test_api_streaming.py
  • SSE format when implemented
  • test_websocket_channel.py
  • auth, connect, send, receive, disconnect.

Shipped Slice

API server with /health, /status, /v1/models, and non-streaming /v1/chat/completions, plus session list/detail, approval, and learning review endpoints, skill-candidate apply, profile list/detail endpoints, multipart media upload backed by session media refs, and a first WebSocket channel slice. API canonical + compatibility aliases tested: /api/health, /health, /api/status, /status, /api/v1/models, /v1/models, /api/v1/chat/completions, /v1/chat/completions. Web UI React SPA source/build/static serving/bootstrap tests exist; implemented core, tests minimal. Some stale Nanobot naming artifacts. WebSocket exists as minimal aiohttp channel, not Nanobot full surface. Advanced Nanobot features missing: token issuance endpoint, media signing, SSL/TLS, capability registry entry gap. OpenAI-compatible helper logic is split into api/openai_compat.py; multimodal input and /v1/responses remain open. WebSocket channel tests cover token auth, inbound session mapping, outbound sends, capabilities, and channel-manager registration.