Coco
Understand the framework

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 CocoGuard attaches without changing the runtime.
  • Pause and resume: Any node, tool, or middleware can pause with interrupt(), save the state to a checkpointer, and resume with Command(resume=...).
  • Local tracing only: Traces stay in process memory. Nothing goes to an external tracing service.

Layers

LayerDistributionsImportHolds
Coretrustcoco-corecoco_coreThe runnable protocol, messages, @tool and BaseTool, prompt templates, serialization, and CocoTracer
Graphtrustcoco-graph, -prebuilt, -checkpoint, -checkpoint-sqlite, -checkpoint-postgrescoco_graphThe graph engine, StateGraph, state channels and reducers, ToolNode, interrupt(), Command, and the checkpointers
Model providerstrustcoco-openai, trustcoco-anthropiccoco_openai, coco_anthropicChat models and embeddings for OpenAI, Azure OpenAI, OpenAI-compatible servers, and Anthropic
Agentstrustcococococreate_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:

  1. Schemas: create_agent merges each middleware's state_schema into the agent's state. Fields marked OmitFromInput, OmitFromOutput or PrivateStateAttr stay out of the graph's public input and output.
  2. Before the model: before_agent hooks run once per run, and before_model hooks run before every model call, in list order. A hook marked @hook_config(can_jump_to=[...]) can return jump_to to change where the loop goes.
  3. The model call: wrap_model_call hooks nest, first in the list outermost. Each receives a ModelRequest and makes changed copies with request.override(...).
  4. After the model: after_model hooks run in reverse order. If the model's message has tool calls, each goes to ToolNode as its own task. If a structured output tool was called, its arguments are validated into structured_response. Otherwise the run moves to after_agent and ends.
  5. The tool calls: ToolNode runs the calls in parallel, each through the wrap_tool_call hooks. A hook receives a ToolCallRequest and returns a ToolMessage or a Command. 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:

ChannelBehaviour
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.
EphemeralClears 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:

  1. Plan: Pick the nodes the last step's updates trigger, or the input, or Send packets.
  2. 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.
  3. 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, from config["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.

DecisionWhat the guard does
RunsThe guard calls the tool. In Monitor, a call Enforce would deny or escalate still runs, and the receipt records what Enforce would do.
DeniedThe 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.
EscalatedThe 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

AreaDecidedWhy
Namestrustcoco-* distributions with coco* importsAvoids clashes with other packages in the same environment, and keeps every package in the runtime to the same telemetry and middleware rules.
Enforcement boundaryPolicy 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.
TracingIn-memory CocoTracer, with no network callsPrompts, tool arguments and completions can't leave by accident. The record of what an agent did is the SDK's receipts.
PackagingOne coco-framework package, and nine trustcoco-* packagesOne command to install everything, or only the parts a small production image needs.

On this page