Unattended AI agent work is easier to operate when the final answer has a predictable shape. A human can read a narrative, but a runbook, dashboard, or follow-up agent needs stable fields: what changed, what was checked, what failed, and where to look next.
An output contract is a small agreement about the completion receipt before work begins. It does not need to be a formal API schema. It can be a Markdown template, a JSON object, or a short checklist. The important part is that every run reports the same operational facts in the same order.
Free-form summaries often sound confident while leaving out the evidence needed to trust them. They may say “deployed successfully” without naming the build command, the routes checked, or the files changed. They may bury a warning in prose that later automation cannot parse.
A simple output contract reduces that ambiguity. It turns the final message into a verification surface instead of a status vibe.
Useful fields include:
- Outcome: completed, blocked, skipped, or rolled back.
- Changed surface: public-safe names for files, content sections, services, or routes affected.
- Verification: commands, checks, or probes that actually ran.
- Evidence: concise results such as exit codes, URLs checked, or test names.
- Exceptions: anything intentionally not done, with the reason.
- Next step: the smallest safe follow-up if more work remains.
Keep the contract public-safe
The receipt should be structured, but it should not become a data leak. Avoid raw logs, credentials, private identifiers, local paths, personal data, and account-specific details. If a sensitive fact matters, summarize the invariant instead: “required credential was unavailable” is safer than printing where it was stored.
For public publishing or shared incident notes, prefer stable labels over environment-specific names. The goal is to preserve decision quality without exposing operational internals.
Copyable runbook step
Before starting, define the final output contract. Require the agent to report outcome, changed surface, verification performed, evidence, exceptions, and next step. The receipt must be public-safe: no secrets, raw logs, private paths, account identifiers, or personal data. If a field cannot be completed, the agent must mark the run blocked instead of omitting it.
Lightweight checklist
- Could another operator compare the receipt to the diff and checks?
- Can automation distinguish completed, blocked, skipped, and rolled-back runs?
- Are warnings and exceptions in named fields instead of buried in prose?
- Does the receipt avoid private details while preserving the useful invariant?
- Is the format short enough that agents will actually follow it?
Rule of thumb: if the next operator has to infer whether the run succeeded, the output contract is too loose.