Typed result schema

How it works

A typed result schema turns an agent response from loose text into a contract the harness can check. The schema names the fields the agent must return, the types each field must carry, which values are optional, and which cases are allowed. The model may still produce the result probabilistically, but acceptance becomes deterministic: either the output conforms or it does not.

In practice, the loop usually looks like this:

• The harness gives the agent a task and a required output shape.
• The agent returns structured data, often alongside no extra prose.
• The harness parses the result and validates it against the schema.
• Invalid results are rejected, repaired through a bounded retry, or parked as an operational failure.
• Valid results move into the next stage as typed input, ledger state, or an auditable decision record.

The schema is not the same thing as truth. A field named sourceIds can be present while the source IDs are weak, irrelevant, or fabricated. The schema only proves that the output has the expected form. The harness still needs verifiers, provenance checks, and policy gates for claims that matter. Its job is narrower and important: make malformed work impossible to silently accept.

Why it matters in an agent harness

Agent systems fail in small, boring ways before they fail dramatically. A model omits a field. It renames a status. It returns a paragraph where the next stage expects an enum. It says the work is complete while placing the actual result in a footnote. Humans can often read through that mess. Harnesses should not.

A typed result schema gives the harness a clean boundary between generation and acceptance. That boundary improves control because downstream code no longer has to infer intent from prose. It improves reversibility because validated results can be stored, replayed, diffed, and compared across runs. It improves observability because schema failures become visible events rather than vague quality problems.

The largest benefit is failure containment. Without a schema, one malformed agent response can become bad state, then bad context, then bad work. With a schema, the first bad output is stopped at the stage boundary. The failure has a location, a reason, and a recovery path.

Typed result schemas also support permission design. A harness can require an agent to return a proposed action rather than directly performing it. The proposal can include target path, operation type, confidence, evidence IDs, and required approvals. The harness can then decide whether that proposed action fits the current authority boundary. This keeps capability separate from permission.

The tradeoff is that schemas make ambiguity expensive. That is usually desirable in production. If a stage cannot say whether the result is approved, blocked, or needs_input, the harness should not pretend the distinction is cosmetic. The schema forces the system designer to name the states that matter.

Typed result schema vs prompt instruction

The distinction changes how the system fails. A prompt instruction asks the model to behave. A typed result schema gives the harness something to enforce after the model behaves.

A good harness uses all three. The prompt describes the work. The schema defines the result surface. The verifier checks whether important claims and actions deserve to pass.

The Rifty take

We treat typed result schemas as one of the basic instruments of harness engineering. They do not make an agent reliable by themselves, but they make unreliability inspectable at the boundary where it matters.

The judgment call is how much structure to require. We prefer tight schemas for stage outputs that affect state, permissions, publishing, spending, or irreversible work. We accept looser prose only where the output is advisory and cannot directly mutate the system.

A schema should also make absence visible. Optional fields are fine when absence has a clear meaning. They are dangerous when they become a quiet way for the system to proceed without evidence, approval, or attribution.

Implementation checks

• Define the schema from the downstream decision, not from the model's preferred prose style.
• Use enums for operational states that drive control flow.
• Treat parse failure and validation failure as first-class events in the run trace.
• Keep retry limits explicit. Infinite repair loops hide bad contracts.
• Store the validated result, the schema version, and the validation outcome together.
• Do not let a missing required field fall back to a plausible default unless that fallback is recorded as a visible event.
• Separate structural validation from truth validation. A valid object can still contain an invalid claim.
• Version schemas when changes affect stored state, replay, approvals, or handoff compatibility.
• Test malformed, partial, over-complete, and adversarial outputs, not only happy-path examples.

Frequently asked questions

Does a typed result schema make an agent deterministic?

No. A typed result schema makes acceptance deterministic, not generation. The model may still produce different attempts across runs, but the harness applies the same validation rule each time. This narrows uncertainty at the boundary where output becomes state, input, approval material, or an action proposal.

What should go into a typed result schema?

The schema should include fields the harness needs to make the next decision: status, evidence references, proposed actions, affected resources, confidence only when it is used, and machine-readable reasons. Avoid fields that merely decorate prose. Every required field should correspond to a real control, routing, audit, or recovery need.

Is schema validation enough to trust an agent output?

No. Schema validation only proves that the result has the expected structure. Trustworthy operation also needs provenance checks, deterministic verifiers, permission gates, and evaluation where the stakes justify them. A well-typed unsupported claim is still unsupported. The schema keeps that claim inspectable instead of buried in prose.

How strict should the schema be?

Use stricter schemas where the result affects durable state, user-visible output, money, credentials, file writes, or external systems. Use lighter schemas for exploratory analysis and advisory notes. The useful rule is risk-proportionate structure: the more the next step depends on the result, the less ambiguity the harness should accept.

What is a common mistake when adding typed result schemas?

A common mistake is treating the schema as a formatting preference instead of a control boundary. Teams validate shape but then add silent defaults, ignore missing evidence, or parse fallback prose when validation fails. That preserves the appearance of structure while letting malformed work keep moving through the system.