Skip to main content

C-06 Checkpoint Manager

Brick C: Agents, autonomy, execution. French version: C-06-checkpoint-manager

1. Role and responsibilities​

Persists the state of an agent turn after each significant step in PostgreSQL (eai.checkpoints) for resume and replay. AgentRunner writes the checkpoints (POST /v1/runs/{id}/checkpoints) and AgentLoop.resume(run_id) reads the last one to resume after a crash.

2. Position in the architecture and interactions​

  • Written by AgentRunner; read by AgentLoop.resume(), by replay (C-15) and by the portal.

3. Open source component and developed part​

  • Engine: Navin architecture of the Python SDK, with no declared graph. enterprise_ai.loop.AgentLoop takes in messages, prepares the context, manages sessions, resumes a run after a crash, handles stop, cron and heartbeat, and exposes serve(); enterprise_ai.runtime.AgentRunner runs one turn; enterprise_ai.subagents.SubagentManager runs sub-agents in parallel; enterprise_ai.loop.plan.RunPlan carries the plan; enterprise_ai.runtime.bus.MessageBus links channels and engine.
  • Optional adapters: LangGraph (enterprise_ai.runtime.langgraph.build_graph) and Temporal (enterprise_ai.runtime.temporal.build_workflow) reuse the same steps; neither is required.
  • Server side, python -m eai.worker runs the periodic jobs: scheduler tick, event outbox drain, quota reservation expiry, stale heartbeat detection, retention.

4. Data model​

Tables (schema eai, tenant_id RLS):

  • eai.checkpoints

Common columns: id uuid, tenant_id uuid NOT NULL, created_at, updated_at; RLS policy current_setting('app.tenant_id', true)::uuid.

5. Contract​

  • Applied contract: execution-contract
  • JSON Schema: contracts/v1/execution-contract.schema.json
  • Key fields: resume.checkpoint_id, steps[].index
  • Validation: POST /v1/contracts/{name}/validate; manifest apply: POST /v1/manifests/apply.

6. API endpoints​

  • POST /v1/runs/{id}/checkpoints
  • GET /v1/runs/{id}/checkpoints
  • GET /v1/checkpoints/{id}

Request POST /v1/runs/{id}/checkpoints:

{
  "step_index": 4,
  "state": {
    "messages": 12,
    "scratch": "..."
  }
}

Response:

{
  "checkpoint_id": "chk_0042",
  "sha256": "e3b0c4...",
  "created_at": "2025-01-10T10:00:00Z"
}

7. SDK examples​

Python:

from enterprise_ai import EnterpriseAI

client = EnterpriseAI(base_url="<control-plane-url>", api_key="eai_xxx_secret")
chk = client.runs.checkpoint("run_01J9", state=state, label="step-4")

TypeScript:

import { EnterpriseAI } from "@enterprise-ai/sdk";

const client = new EnterpriseAI({ baseUrl: "<control-plane-url>", apiKey: process.env.EAI_API_KEY });
const chk = await client.checkpoints.create("run_01J9", { label: "step-4", state });

Java:

EnterpriseAIClient client = EnterpriseAIClient.builder()
    .baseUrl("<control-plane-url>")
    .apiKey(System.getenv("EAI_API_KEY"))
    .build();
Checkpoint chk = client.checkpoints().create("run_01J9", 4, state);

Go:

c, _ := eai.NewClient(eai.WithBaseURL("<control-plane-url>"), eai.WithAPIKey(os.Getenv("EAI_API_KEY")))
chk, _ := c.Checkpoints.Create(ctx, "run_01J9", map[string]any{"label": "after-step-4", "state": map[string]any{"step_index": 4}})

8. Configuration​

  • Environment variables: EAI_DATABASE_URL
  • Helm values keys: controlPlane.config, controlPlane.secrets

9. Security controls​

  • RLS on tenant_id
  • Encrypted state, never a plaintext secret
  • Every request carries the tenant resolved from the credential; PostgreSQL RLS
  • Every mutation and policy decision writes a hash-chained audit event

10. Observability​

  • Prometheus metrics: eai_checkpoints_total, eai_checkpoint_bytes
  • Traces: OpenTelemetry spans with GenAI semantic conventions (gen_ai.operation.name, gen_ai.agent.id, gen_ai.tool.name), attributes eai.tenant_id, eai.run_id, traceparent propagation.
  • Audit actions: run.checkpoint

11. FinOps units​

  • Checkpoint storage (GB-month).
  • Emitted as Usage Event (POST /v1/finops/usage) with tenant, project, agent and run.

12. Failure modes and resilience​

  • Crash between two checkpoints: resume from the last checkpoint, the current step is replayed
  • PostgreSQL unavailable: the write fails, the turn stops rather than lose state

13. Standalone adoption (client of a client)​

  • enterprise_ai.agent + PostgreSQL.
  • SDK: enterprise_ai.agent (AgentsClient, RunsClient, SessionsClient)
  • Minimal deployment: Helm chart with controlPlane.enabled=true and PostgreSQL; disabled external components use their in-process fallback.

14. Acceptance tests​

  1. Write then read a checkpoint, identical hash
  2. Cross-tenant read -> 404
  3. Cross-tenant access refused
  4. Error returned in fr with Accept-Language: fr