Runtime surfaces

A runtime surface is one way in which a user or program interacts with the same Agent runtime. This stage does not repeat the official usage manual. It explains how each surface reaches the core, where it creates unique state, and where debugging should begin.

Corresponding source

Runtime surface	Source
Channels and Gateway	nanobot/channels/, nanobot/gateway/
HTTP API and SDK	nanobot/api/server.py, nanobot/nanobot.py, nanobot/sdk/
WebSocket and WebUI	nanobot/channels/websocket.py, nanobot/session/webui_turns.py, nanobot/webui/, webui/
Provider resolution and fallback	nanobot/providers/registry.py, factory.py, fallback_provider.py

Reading order

1. Channels and Gateway
2. HTTP API and Python SDK
3. WebSocket and WebUI
4. Provider resolution and fallback

Overall relationships

flowchart TD
    USER["User / program"] --> CLI["CLI"]
    USER --> CH["Chat Channel"]
    USER --> WEB["WebUI"]
    USER --> API["HTTP API"]
    USER --> SDK["Python SDK"]

    CLI --> LOOP["AgentLoop"]
    CH --> GW["Gateway + MessageBus"]
    WEB --> WS["WebSocket Channel"]
    WS --> GW
    GW --> LOOP
    API --> LOOP
    SDK --> LOOP

    LOOP --> PS["Provider snapshot"]
    PS --> P["LLM Provider / fallback"]

Learning boundary

• Use representative Channels to understand the shared contract.
• Do not cover every platform SDK.
• Do not repeat the API parameter reference.
• Do not attempt a complete React course.
• For Providers, focus on resolution and shared contracts rather than vendor configuration.

Next step

Read Channels and Gateway.