Ledger schema

Ledger schema is an optional per-agent declaration of the typed entities the simulated world-state ledger may carry (orders, customers, files, …). It's null by default — and a null schema means the fully-open ledger you get today, where the simulator infers entities on the fly. Declare one when you want:

Tighter consistency — the simulator is told the exact entity types and fields your domain uses, so sandbox-mode responses stay coherent across a run.
Validated seeds — initial_state keys are checked against your declared types (see Task seeding).
Passthrough ledger writes — a tool with ledger_write_policy: "adapter" must bind to a declared entity type (see Tools schema → ledger writes).

You can register an agent without it and add one later via the UI or PUT /api/agents/{id} — nothing breaks.

Shape

{
  "ledger_schema": {
    "entities": [
      {
        "type": "order",
        "id_field": "order_id",
        "description": "A customer order.",
        "fields": [
          { "name": "status", "type": "string", "enum": ["paid", "shipped", "cancelled"] },
          { "name": "total", "type": "number" }
        ]
      }
    ],
    "flags": { "policy": "open", "values": ["warehouse_outage"] }
  }
}

Fields

Field	Required	Notes
`entities`	yes	List of entity types (max 100).
`entities[].type`	yes	The entity name. Use the singular noun (`order`, not `orders`); it's used verbatim by the simulator. Unique within the schema.
`entities[].id_field`	yes	Name of the stable identifier field (e.g. `order_id`).
`entities[].description`	no	Free-form hint for the simulator.
`entities[].fields`	no	Field list (max 100 per entity). Each: `name` + `type`, optional `enum` (scalar members) and `description`.
`fields[].type`	yes	One of `string`, `number`, `integer`, `boolean`, `object`, `array`.
`flags`	no	`{ policy: "open" \| "closed", values?: [string] }`. `closed` restricts ledger flags to `values`; `open` (default) allows any.

The whole schema must serialize to ≤ 100 KB.

Closure rules: entity types are closed (only declared types are allowed), but instances and extra leaf fields are open — declaring a schema constrains the shape of your world without forcing you to enumerate every row or attribute.

Setting it

In the UI

On the registration form (and the agent detail page), use the Ledger schema editor. Click Generate to draft one from your current tools_schema with an LLM, then review and edit before saving.

Via the API

ledger_schema is a field on POST /api/agents and PUT /api/agents/{id}. On update, omit it to leave it unchanged, or send an explicit null to clear it back to the open ledger.

Via the SDK

Mirror the UI's generate → review → save flow from a script:

from pipelines.odyssey import agents

draft = agents.generate_ledger_schema(
    api_key="pk_live_...",
    tools_schema=my_tools,
)
# inspect / tweak `draft` in code

agents.create_code_agent(
    name="orders-agent",
    entrypoint="run",
    api_key="pk_live_...",
    source_dir="./my_agent",
    tools_schema=my_tools,
    ledger_schema=draft,
)

generate_ledger_schema returns an un-persisted draft — nothing is saved until you pass it to create_code_agent / update_code_agent (or build_code_agent_payload). update_code_agent(..., ledger_schema=None) clears it.

Validation rule

A tool with ledger_write_policy: "adapter" requires a non-null ledger_schema whose entities include the adapter's entity_type. The platform validates this against the agent's merged state on save, so the order in which entities and tools are defined does not matter.

A 422 on save indicates an adapter tool without a matching declared entity. Resolve it by adding the entity to ledger_schema or changing the tool's ledger_write_policy, then save again.