Make Agent Outputs Operable with an Artifact Contract

This article shows a practical workflow for designing, running, and verifying agent tasks around concrete artifacts rather than conversational confidence.

Start with the output contract

Before asking an agent to research, edit, or execute, write a compact output contract. It should answer four questions:

1. 1. What is being produced? Name the file, API result, or other durable object.
2. 2. Where will it live? Use an exact project-relative path or endpoint.
3. 3. What must it contain? Define the minimum schema, sections, or fields.
4. 4. How will completion be checked? Specify a command, test, or read-back operation.

For example:

``text Artifact: COO-FILESYSTEM/articles/drafts/2026-09-10-artifact-contract.md Format: Markdown Required: H1, lede, framing paragraph, 3–5 H2 sections, next steps Verification: read the file and confirm the required headings exist ``

This is intentionally boring. Boring is useful: the contract gives the agent a target and gives the operator a finite inspection job.

Do not substitute a topic for an artifact. “Write about reliable agents” is a content request; it does not say what counts as shipped. The path and acceptance check make the request operational.

Separate production from verification

A common mistake is to let the same step both produce an artifact and declare it successful. Instead, treat the workflow as two stages.

Production creates or updates the named object. The agent may use tools, consult source material, and make intermediate decisions, but its write should be limited to the contracted location.

Verification happens afterward and asks whether the intended object exists and satisfies the contract. At minimum:

``sh test -f "$artifact" grep -q '^# ' "$artifact" grep -q '^## ' "$artifact" ``

For structured output, validate the structure rather than merely checking that the file is non-empty. A JSON artifact should parse. A generated report should include its required fields. A code change should run its relevant tests.

The distinction matters because a successful tool call proves only that a process ran. It does not prove that the requested result was produced, written to the right place, or usable by the next step.

Keep evidence beside the result

An artifact becomes easier to trust when its verification trail is durable. Record the task identifier, the output path, the checks performed, and their result in a short work log or task record.

A useful verification note can be as small as:

``text Task: article_daily / 2026-09-10 Artifact: COO-FILESYSTEM/articles/drafts/2026-09-10-artifact-contract.md Checks: file exists; headings present; draft-only path confirmed Result: verified ``

The point is not to create paperwork for its own sake. It is to preserve the information needed for handoff. If another operator opens the queue tomorrow, they should not need to reconstruct whether “done” meant “the agent answered” or “the file was checked.”

Use stable identifiers where possible. A path alone identifies the object but not the attempt that produced it. A task ID alone identifies the attempt but not the deliverable. Together they provide a minimal evidence link.

Design failure states explicitly

Artifact-first workflows should make failure legible instead of forcing every run into success or silence. Define what happens when the agent cannot write, writes an incomplete result, or discovers that the source material is insufficient.

For example:

• Missing input: stop and request the specific source or decision required.
• Write failure: report the permission or path problem and do not claim completion.
• Validation failure: keep the artifact in a draft or quarantine location, then list the failed check.
• Ambiguous scope: narrow the contract before execution rather than generating a plausible but unsupported result.

This is especially important for autonomous jobs. A scheduled task should end with either a verified artifact or a concrete blocker. “The model generated text” is not a useful third state.

Failure handling also protects downstream automation. A publisher can safely consume files that passed the draft checks; it should not have to infer readiness from timestamps or filenames. A review queue can prioritize blockers when each one includes a precise next action.

Make handoffs consume the contract

The final test of an artifact contract is whether the next actor can use it without another explanation. A reviewer should know what to inspect. A publisher should know which directory is eligible. A later agent should know which fields are stable and which remain provisional.

Design the handoff around explicit states such as draft, verified, approved, and published. Do not collapse approval into verification: a file can be structurally correct and still require human judgment. Likewise, publication should be a separate state from approval when it has external effects.

A compact handoff can include:

``text Status: verified / awaiting approval Artifact: <exact path> Evidence: <checks or command output> Open decision: <what the reviewer must decide> Next permitted action: <review, publish, or revise> ``

That format keeps the safe part moving without quietly authorizing the risky part. The artifact can be inspected and refined while external actions remain behind their normal gate.

A repeatable implementation checklist

Use this sequence for the next agent task:

1. 1. Name the artifact with an exact path or endpoint.
2. 2. Write acceptance checks before execution begins.
3. 3. Limit the write scope to the contracted location.
4. 4. Run independent verification after production.
5. 5. Record evidence with the task and artifact identifiers.
6. 6. Set an explicit state: draft, verified, approved, or blocked.
7. 7. Hand off only the next permitted action.

Start with one artifact type and a handful of checks. You can add schemas, test suites, lineage, and richer evidence later. The first win is simply replacing an uncheckable completion sentence with a result that exists, has a known location, and can be inspected by someone else.

Artifact-first design is not a demand for heavier process. It is a way to make agent work composable. When every meaningful task names its output and its proof, operators spend less time chasing status and more time making the decisions that actually require them.