Architecture
The framework's design goals, its four layers, the agent loop, state channels and supersteps, checkpointing, local tracing, where Coco's check attaches, and the decisions behind it.
The layers, the agent loop, state, checkpointing, tracing, and where Coco attaches.
Design goals
- Stateful execution you can inspect: An agent runs as a compiled state graph over typed state, not an opaque loop. Every step can be inspected, checkpointed, replayed, or resumed.
- Governance through middleware: Every model call and tool call passes through the middleware pipeline, so an enforcement engine such as
CocoGuardattaches without changing the runtime. - Pause and resume: Any node, tool, or middleware can pause with
interrupt(), save the state to a checkpointer, and resume withCommand(resume=...). - Local tracing only: Traces stay in process memory. Nothing goes to an external tracing service.
Layers
| Layer | Distributions | Import | Holds |
|---|---|---|---|
| Core | trustcoco-core | coco_core | The runnable protocol, messages, @tool and BaseTool, prompt templates, serialization, and CocoTracer |
| Graph | trustcoco-graph, -prebuilt, -checkpoint, -checkpoint-sqlite, -checkpoint-postgres | coco_graph | The graph engine, StateGraph, state channels and reducers, ToolNode, interrupt(), Command, and the checkpointers |
| Model providers | trustcoco-openai, trustcoco-anthropic | coco_openai, coco_anthropic | Chat models and embeddings for OpenAI, Azure OpenAI, OpenAI-compatible servers, and Anthropic |
| Agents | trustcoco | coco | create_agent, init_chat_model, the middleware pipeline, the built-in middleware, and structured output |
coco-framework ships all four layers in one package. Your application, and CocoGuard, sit on top of the agent layer.
The agent loop
create_agent compiles a StateGraph that wires the model, the tools, structured output, and the middleware into one graph. Each run goes like this:
- Schemas:
create_agentmerges each middleware'sstate_schemainto the agent's state. Fields markedOmitFromInput,OmitFromOutputorPrivateStateAttrstay out of the graph's public input and output. - Before the model:
before_agenthooks run once per run, andbefore_modelhooks run before every model call, in list order. A hook marked@hook_config(can_jump_to=[...])can returnjump_toto change where the loop goes. - The model call:
wrap_model_callhooks nest, first in the list outermost. Each receives aModelRequestand makes changed copies withrequest.override(...). - After the model:
after_modelhooks run in reverse order. If the model's message has tool calls, each goes toToolNodeas its own task. If a structured output tool was called, its arguments are validated intostructured_response. Otherwise the run moves toafter_agentand ends. - The tool calls:
ToolNoderuns the calls in parallel, each through thewrap_tool_callhooks. A hook receives aToolCallRequestand returns aToolMessageor aCommand. The results join the messages, and the loop returns to step 2.
State channels and supersteps
The graph engine runs in supersteps. Each key in the state schema is a channel:
| Channel | Behaviour |
|---|---|
| Last value (the default) | Keeps the latest value. Only one node may write it per step, unless the key has a reducer. |
Reducer (Annotated[T, reducer]) | Merges the writes of one step with the reducer. add_messages dedupes messages by id, merges streamed chunks, and applies RemoveMessage. |
| Ephemeral | Clears at the end of each step, for signals such as jump_to. |
Overwrite(value) | Bypasses the reducer and replaces the value. |
Each superstep has three phases:
- Plan: Pick the nodes the last step's updates trigger, or the input, or
Sendpackets. - Execute: Run those nodes in parallel, with any retry, timeout or cache policy. If a node raises or calls
interrupt(), the writes of the nodes that finished are kept before the run stops. - Update and checkpoint: Apply the writes through the reducers, and save a checkpoint according to the durability mode:
"sync"before the next step,"async"alongside it, or"exit"when the graph exits.
Checkpointing
Checkpointers implement BaseCheckpointSaver and organise state by:
thread_id: The conversation or workflow, fromconfig["configurable"]["thread_id"].checkpoint_ns: A namespace that keeps subgraph checkpoints apart. The root graph's is"".checkpoint_id: A time-ordered ID for each superstep's snapshot.
To rebuild a channel's history, every built-in checkpointer walks the parent chain to the nearest full snapshot, then replays the writes after it, without loading unrelated channels. PostgresSaver stores simple values inline in the checkpoints table and larger objects in checkpoint_blobs.
Tracing
CocoTracer, at coco_core.tracers.coco, records model, chain, tool and retriever runs in memory, adds up token usage, and keeps the last finished root run on latest_run. The tracing context in coco_core.tracers._context uses Python ContextVars, so the parent run, project, tags and metadata follow sync and async calls. COCO_TRACING_V2 turns tracing on, and COCO_PROJECT names the project.
Middleware spans drop the non-serialisable runtime and handler arguments automatically, and a TracePolicy with omit_payload drops message and state payloads too. See Tracing.
Where Coco attaches
Coco's check sits in the Coco SDK, outside the framework. create_agent runs every tool call through wrap_tool_call, and CocoGuard is this middleware. For each call it asks Coco for a decision and acts on it.
| Decision | What the guard does |
|---|---|
| Runs | The guard calls the tool. In Monitor, a call Enforce would deny or escalate still runs, and the receipt records what Enforce would do. |
| Denied | The guard returns a ToolMessage with status error and content starting Coco denied this action., so the tool never runs and the model reads the reason. |
| Escalated | The guard pauses the graph with interrupt() until a person decides. The person decides through Coco, the application resumes the graph, and the guard reads the decision from Coco's record, never from the resume payload. |
The session a contract reads is the graph's thread_id, so session rules follow the checkpointed conversation. An escalation needs a checkpointer; without one the guard rejects the escalation and denies the call. The Quickstart attaches the guard and runs it, and Python agents covers it in full.
Decisions
| Area | Decided | Why |
|---|---|---|
| Names | trustcoco-* distributions with coco* imports | Avoids clashes with other packages in the same environment, and keeps every package in the runtime to the same telemetry and middleware rules. |
| Enforcement boundary | Policy lives in the SDK's CocoGuard; the framework exposes wrap_tool_call and interrupt() | Keeps the runtime small and mechanical, while the guard controls every tool call, denial, and approval. |
| Tracing | In-memory CocoTracer, with no network calls | Prompts, tool arguments and completions can't leave by accident. The record of what an agent did is the SDK's receipts. |
| Packaging | One coco-framework package, and nine trustcoco-* packages | One command to install everything, or only the parts a small production image needs. |
Related Resources
Tracing
Record runs in memory with CocoTracer, read the latest run, tag runs with a project, and keep payloads out of spans. Nothing leaves the process.
Agents and middleware
Look up create_agent and its parameters, init_chat_model, the structured output strategies, and every type, decorator and built-in middleware in coco.agents.middleware.