Protocols and Surfaces

A surface is a thin reader over the one canonical event stream every run produces — nothing about how a run is played changes with who is watching it. The Python API is the base case: no wire, no translation, just the events themselves.

async for event in deck.stream("Support", "and now?", session_id="wa-123"):
    ...  # a text.delta per chunk, message.completed once the reply is in, run.completed last

What exists today

HTTP and SSE. agentdeck-serve (agentdeck/serve.py) runs a FastAPI app wire-compatible with v1.2.1: POST /agents/{name}/chat, ?stream=true for an event stream, the same shape for /workflows/{name}, and /runs/{run_id}/{pause,cancel,resume} for run control. Every one of those handlers calls into the same Runtime the Python API uses, passing it plain arguments — name, session_id, and so on. The Runtime mints the RunContext itself for every call; no handler builds one. One canonical log either way.

curl -X POST http://localhost:8000/agents/Support/chat -d '{"session_id": "wa-123", "message": "where is my order?"}'

The CLI. agentdeck runs signal <run_id> {pause,cancel,resume} (see Reference → CLI) is the one shipped command, and it is a control surface, not a chat client — it writes a pause/cancel/resume request for a run someone else is running. There is no shipped command that starts or renders a conversation.

What is not built

Stated plainly, because a reader deciding whether AgentDeck fits needs it, not a rosier version of it:

• No authentication on any endpoint. Anyone who can reach the process can call every route above, including run control.
• Unnamespaced. The HTTP surface runs every request without a namespace, so one log space serves the whole deployment — RunContext carries namespace, but nothing today varies them per caller.
• A second, native HTTP surface exists but is not reachable. agentdeck/surfaces/serve/app.py builds a FastAPI app over the raw canonical events, with routes under /v2/invocables/{name}/chat and none of v1’s wire translation. No console script mounts it, so it is exercised only by the test suite (and by a reference terminal renderer, agentdeck/surfaces/cli/chat.py, that reads its stream using nothing but event.origin and a message’s id — proof that a thin reader is enough, not something pip install agentdeck gives you to run).
• ACP, A2A, an MCP server, and an OpenAI-compatible endpoint do not exist. The PRD’s “any invocable, any surface, zero per-surface code” claim (FR-2, FR-14) holds for the two surfaces above and stops there today.

None of this is scheduled to change quietly — a new surface earns its own page here once it ships, not before.