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:
In server/ap_server/main.py, the FastAPI gateway mounts five modular routers generated from openapi.json via tooling/Makefile:
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 forinput_schema,output_schema,state_schema, andconfig_schema.threads.router(/threads,/threads/{thread_id},/threads/{thread_id}/history,/threads/{thread_id}/copy): Manages persistentThreadenvelopes,ThreadCheckpointlineage, andThreadPatchstate branching.runs.router(/runs/stream,/runs/wait): Executes ephemeral or thread-bound synchronous/streaming runs configured withon_disconnect(cancelvs.continue) andon_completion(deletevs.keep).background_runs.router(/runs,/runs/{run_id}/cancel): Dispatches asynchronous runs and supports mid-flight cancellation viaAction.interruptorAction.rollback.store.router(/store/items,/store/items/search,/store/namespaces): Provides a cross-thread document store indexed by hierarchicalnamespace: list[str]paths and item keys.
2. The 9-Channel RFC 8610 CDDL Streaming Engine
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,customorcustom:<name>).namespaces: Optional list of hierarchicalNamespace(list[str]) prefixes to filter subgraph events.depth: Maximum subgraph nesting depth below the matched namespace prefix.since: Monotonicjs-uintsequence number; the server replays matching events from its ring buffer aftersincebefore 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
On the messages channel, protocol.cddl eliminates fragile heuristic stream parsing by enforcing a deterministic, non-interleaved lifecycle per (namespace, node) pair:
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).
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 atasksubagent invocation) directly to the originatingtool-startedevent andToolCallcontent block on the parent namespace.LifecycleCauseSend(type: "send",from_node: str): Identifies parallel fan-out subgraphs spawned via LangGraph'sSend(node, state)primitive.LifecycleCauseEdge(type: "edge",from_node: str): Identifies single-successor subgraph transitions routed viaadd_edgeoradd_conditional_edges.
4. Multi-Language Codegen & Python AST Topological Sorting (fixup.py)
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:
- CDDL Primitive Collision Patch:
_patch_text_content_block_type()repairs acddl2pybug wheretype: "text"onTextContentBlockcollides with the CDDL primitivetext(str), rewriting it totype: Literal["text"]. - AST Dependency Extraction & Greedy Topological Sort:
_runtime_deps(node)walks each top-levelast.ClassDef(base classes and keyword arguments) andast.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 andTypedDictis defined prior to its first runtime reference.
Continue Reading
All Blog PostsInside Autonomous Agentic Code Editor: AST Indexing, Diff Generation, and Sandbox Verification
A commit-pinned examination of autonomous agentic code refactoring architectures detailing tree-sitter AST symbol indexing, unified diff generation, and isolated sandbox execution loops.
Inside Apache Kafka Partition Storage & Zero-Copy Engine
An evidence-audited, 20-diagram interactive system breakdown tracing sequential commit log append (.log, .index, .timeindex), Linux sendfile() zero-copy page cache transfers, Producer RecordAccumulator memory pools, Consumer Group Cooperative Rebalancing, and KRaft quorum leader fencing.
Inside Apple MLX Framework & Unified Memory Engine
An evidence-audited, 20-diagram interactive system breakdown tracing Apple MLX framework Unified Memory Architecture (UMA) zero-copy CPU/GPU buffer sharing, C++ Metal lazy evaluation graph compilation, SIMD group quantized weight unpacking, FlashAttention fast kernels, and multi-Mac distributed array parallel execution.
