Feature Spotlight: How schemas catch bad agent output before it matters

A Modulo pipeline gives every agent two typed contracts: an input schema and an output schema. These schemas define exactly what the agent receives and what it must produce. They are the mechanism that makes Modulo agent-agnostic — any agent that respects the contract can be plugged into any pipeline node.

In short

• What it does: schemas validate agent input before execution and output after execution, catching malformed or dangerous data at every boundary.
• When you would use it: any agent that produces structured output — PR descriptions, config files, JSON payloads, test fixtures.
• When you would not: simple text classification or summarization where a regex gate or eval score suffices.
• Schemas are versioned with semver, so you can evolve contracts without breaking in-flight pipelines.

The problem it solves

Say you run an agent that generates configuration files for your deployment pipeline. The agent receives a prompt, produces a YAML config, and the next step in the pipeline applies it to production. Without schemas, the agent might produce malformed YAML, miss a required field, or include a value that breaks the deployment. The error surfaces minutes later, after the config has already been applied, and the rollback takes an hour.

The damage is not that the agent made a mistake. The damage is that the mistake passed through two pipeline steps before anyone noticed. An input schema would have caught the malformed prompt before the agent started. An output schema would have caught the bad config before it reached the deployment step. Schemas exist to fail fast — at the boundary, not downstream.

How it works

Input schema

The input schema defines what data you send to the agent when it is dispatched. This includes the trigger context (repository, branch, PR number, ticket ID), the agent's prompt, and any relevant pipeline state. The input is validated against the schema before the agent receives it, so the agent never has to handle malformed or unexpected input.

This validation is important because agents are expensive to run. If the input is invalid, better to catch it before the agent starts than to let it fail mid-execution and waste the invocation.

Output schema

The output schema defines what the agent must produce. This could be a pull request diff, a PR description, a test file, a documentation update, or any other structured output. The output is validated against the schema after the agent finishes, before it reaches any gate or human reviewer.

If the output does not match the schema, the run pauses and the validation failure is recorded. The agent never gets to skip the schema check — it is enforced before anything else happens.

Schema versioning

Schemas are versioned with semver. When you update a schema, existing runs are unaffected because they reference the schema version pinned in their snapshot. This means you can evolve your contracts without breaking in-flight pipelines.

A major version bump means the contract changed in a breaking way — agents configured for the old schema will not be dispatched until they are updated. A minor version bump means the contract expanded (new optional fields) — existing agents continue to work.

Schema inference

Modulo can generate schema drafts from connector data. When you connect a GitHub repository, Modulo can inspect the repository structure and generate a schema for the types of changes the agent is expected to make. This is not a replacement for hand-authored schemas, but it accelerates the initial setup.

Journey example: before and after

Before

Imagine a team (led by an engineer named Sam) that runs an agent to generate PR descriptions. Half the descriptions are missing the "Testing" section. The team reviews each one manually, adds the missing section, and moves on. It works, but it costs 10 minutes per PR and the inconsistency frustrates the reviewers.

After

Sam adds an output schema that requires the "Testing" section. The agent now produces descriptions that always include it. The schema gate catches the 5% of runs where the agent still tries to omit it, and the run pauses for a correction instead of shipping an incomplete description. The team stops reviewing for structure and starts reviewing for content.

When to use it vs. when not to

Use schemas for any agent that produces structured output — JSON, YAML, config files, PR descriptions with required sections. The schema gives you a machine-checkable contract that catches structural failures without human review.

Do not use schemas for simple text agents where the output is free-form. A summarization agent that produces a paragraph does not need an output schema — a scored eval (quality rubric) is a better fit. Similarly, do not over-specify input schemas for simple triggers where the payload is already validated by the trigger's own guardrails.

Where it fits in a pipeline

Schemas sit at the input and output boundaries of every agent node. They are the first line of defense before gates, evals, or human review. For the governance layer that validates what the agent produces beyond structure, see Feature Spotlight: How HITL gates stop bad agent output before it ships. For the principles behind this approach, see the principles of Modulo.

Go deeper

Read the Schemas docs for the full schema configuration, or the related docs on agents and feedback. Try the hosted demo at demo.modulo.run, or use the contact page to talk to us about adding schemas to your pipeline.