Open Studio
system breakdown

Inside Agent Protocol: OpenAPI Control Plane, RFC 8610 CDDL Streaming & Thread Checkpoint Architecture

A production teardown of LangChain Agent Protocol (v0.1.6)—deconstructing the 5-router OpenAPI control plane, thread checkpoint branching, 9-channel RFC 8610 CDDL streaming, subgraph causation edges, and AST topological code generation.

FullStack AI Hub Editorial19 min readPublished 29 Sep 20262 primary sources
Inside Agent Protocol: OpenAPI Control Plane, RFC 8610 CDDL Streaming & Thread Checkpoint Architecture

Evidence boundary

This system breakdown analyzes agent-protocol (server/ap_server, streaming/protocol.cddl, streaming/py/langchain_protocol, and streaming/scripts/fixup.py) at commit d9fd23d762bf4cffe876890a854fb79bcdd14f1a (release v0.1.6).


1. Dual-Specification Architecture: OpenAPI REST Control Plane + RFC 8610 CDDL Streaming

agent-protocol defines the framework-agnostic wire contract for deploying, inspecting, and streaming stateful AI agents. Rather than forcing all interactions into a single transport paradigm, the repository combines two machine-compiled specifications:

code(14 lines)
1+-------------------------------------------------------------------------------+
2| 1. OpenAPI 3.1 REST Control Plane (openapi.json -> server/ap_server) |
3| Agents (/agents), Threads (/threads), Runs (/runs), Store (/store/items) |
4+-------------------------------------------------------------------------------+
5| 2. Thread-Centric State Machine & Interrupts (models.py, protocol.cddl) |
6| ThreadStatus (idle|busy|interrupted|error), input.respond + atomic Goto jump |
7+-------------------------------------------------------------------------------+
8| 3. RFC 8610 CDDL 9-Channel Streaming Protocol (streaming/protocol.cddl) |
9| values, updates, messages, tools, lifecycle, input, checkpoints, tasks, custom|
10+-------------------------------------------------------------------------------+
11| 4. Multi-Language Codegen & AST Topological Sort (tooling/, fixup.py) |
12| fastapi-codegen + cddl2py -> AST Kahn topological sort -> protocol.py / .ts |
13+-------------------------------------------------------------------------------+
Missing evidence claim: ap-five-router-control-plane

In server/ap_server/main.py, the FastAPI gateway mounts five modular routers generated from openapi.json via tooling/Makefile:

  1. agents.router (/agents/search, /agents/{agent_id}, /agents/{agent_id}/schemas): Exposes agent capabilities (ap.io.messages, ap.io.streaming, plus reverse-domain extensions) and JSON Schemas for input_schema, output_schema, state_schema, and config_schema.
  2. threads.router (/threads, /threads/{thread_id}, /threads/{thread_id}/history, /threads/{thread_id}/copy): Manages persistent Thread envelopes, ThreadCheckpoint lineage, and ThreadPatch state branching.
  3. runs.router (/runs/stream, /runs/wait): Executes ephemeral or thread-bound synchronous/streaming runs configured with on_disconnect (cancel vs. continue) and on_completion (delete vs. keep).
  4. background_runs.router (/runs, /runs/{run_id}/cancel): Dispatches asynchronous runs and supports mid-flight cancellation via Action.interrupt or Action.rollback.
  5. store.router (/store/items, /store/items/search, /store/namespaces): Provides a cross-thread document store indexed by hierarchical namespace: list[str] paths and item keys.

2. The 9-Channel RFC 8610 CDDL Streaming Engine

Missing evidence claim: ap-cddl-nine-channel-streaming

While OpenAPI governs CRUD resources, streaming/protocol.cddl (version 0.0.13, RFC 8610 Concise Data Definition Language) specifies the real-time event and command framing across SSE/HTTP, WebSocket, and in-process transports.

The protocol is strictly thread-centric: there is no stateful connection handshake. Over SSE/HTTP (POST /threads/:thread_id/stream), each HTTP request carries an EventStreamRequest body specifying:

  • channels: One or more of the 9 standard channels (values, updates, messages, tools, lifecycle, input, checkpoints, tasks, custom or custom:<name>).
  • namespaces: Optional list of hierarchical Namespace (list[str]) prefixes to filter subgraph events.
  • depth: Maximum subgraph nesting depth below the matched namespace prefix.
  • since: Monotonic js-uint sequence number; the server replays matching events from its ring buffer after since before switching to live delivery.

When a graph pauses for human-in-the-loop approval, it emits an input.requested event carrying an interrupt_id. The client resumes the thread via input.respond (InputRespondOne or InputRespondMany), which supports applying a state update and a directed goto jump (str | RunSend | list[str | RunSend]) in the exact same Pregel superstep as the resume.


3. Non-Interleaved Content Blocks & Subgraph Causation Edges

Missing evidence claim: ap-non-interleaved-content-blocks

On the messages channel, protocol.cddl eliminates fragile heuristic stream parsing by enforcing a deterministic, non-interleaved lifecycle per (namespace, node) pair:

text(9 lines)
1message-start(id, role, metadata)
2 └── content-block-start(index=0, contentBlock)
3 └── content-block-delta(index=0, TextDelta | ReasoningDelta | DataDelta | BlockDelta) ...
4 └── content-block-finish(index=0, FinalizedContentBlock)
5 └── content-block-start(index=1, contentBlock)
6 └── content-block-delta(index=1, BlockDelta) ...
7 └── content-block-finish(index=1, FinalizedContentBlock)
8message-finish(usage)

Content block $N$ must emit content-block-finish (upgrading chunk variants like ToolCallChunk into finalized ToolCall blocks) before block $N+1$ emits content-block-start. Incremental deltas use four explicit strategies: text-delta, reasoning-delta, data-delta (for base64 multimodal chunks), and block-delta (shallow-merging arbitrary fields onto the active block).

Missing evidence claim: ap-subgraph-lifecycle-causation

When a parent agent spawns nested subagents or parallel worker subgraphs, over-the-wire clients need to correlate child events back to the parent trigger without hardcoding agent internals. The lifecycle channel solves this via LifecycleCause on started events:

  • LifecycleCauseToolCall (type: "toolCall", tool_call_id: str): Links a spawned subgraph (such as a task subagent invocation) directly to the originating tool-started event and ToolCall content block on the parent namespace.
  • LifecycleCauseSend (type: "send", from_node: str): Identifies parallel fan-out subgraphs spawned via LangGraph's Send(node, state) primitive.
  • LifecycleCauseEdge (type: "edge", from_node: str): Identifies single-successor subgraph transitions routed via add_edge or add_conditional_edges.

4. Multi-Language Codegen & Python AST Topological Sorting (fixup.py)

Missing evidence claim: ap-cddl-ast-topological-fixup

streaming/package.json compiles protocol.cddl into TypeScript (cddl2ts protocol.cddl --field-case snake > ./js/protocol.ts) and Python (cddl2py protocol.cddl | python3 scripts/fixup.py > ./py/langchain_protocol/protocol.py).

Because CDDL specifications are written top-down (high-level unions before leaf records), raw cddl2py output violates Python's eager runtime evaluation rules for class base classes (class _CommandVariant1(_CommandFields, SubscriptionSubscribe)) and Union[...] assignments. streaming/scripts/fixup.py resolves this in two deterministic passes:

  1. CDDL Primitive Collision Patch: _patch_text_content_block_type() repairs a cddl2py bug where type: "text" on TextContentBlock collides with the CDDL primitive text (str), rewriting it to type: Literal["text"].
  2. AST Dependency Extraction & Greedy Topological Sort: _runtime_deps(node) walks each top-level ast.ClassDef (base classes and keyword arguments) and ast.Assign (right-hand side value) to compute intra-module symbol dependencies while ignoring lazy stringified type annotations (from __future__ import annotations). It then runs a stable greedy Kahn topological sort (pick = min(ready, key=lambda b: b["idx"])) so every base class and TypedDict is defined prior to its first runtime reference.

Continue Reading

All Blog Posts