Skip to content

PATTERN Cited by 1 source

Artifact-as-API between agents

Definition

The artifact-as-API pattern replaces unstructured context passing between agents (or between agents and humans) with schema-validated files on disk that serve as the typed interface contract between workflow stages. Each agent reads its documented inputs from artifact files, produces documented outputs validated against a schema, and the orchestrator advances to the next gate only when the contract holds.

This is the distributed-systems analog of typed message passing: the artifact file is the message, the JSON schema is the type, and the gate validator is the consumer's contract check.

Mechanics

  1. Each role/agent has a declared set of input artifacts it may read
  2. Each role/agent produces a declared set of output artifacts
  3. Outputs are validated against a JSON schema before the next stage fires
  4. Missing artifacts are treated as failed gates
  5. Malformed artifacts are treated as missing
  6. No implicit state crosses the boundary — only the artifact file

Why it works at scale

  • Reviewable: artifacts are files in the repo, diffable and auditable
  • Replayable: the same inputs produce the same gate evaluation
  • Governable: schema constraints prevent drift in agent outputs
  • Composable: any orchestrator (IDE, CI job, human shell) can call the CLIs

Anti-pattern

"Dump context and ask for output" in a chat window. The context cannot be reviewed, versioned, or replayed. At team scale with multiple agents, unstructured handoffs produce unmaintainable systems.

Seen in

Last updated · 542 distilled / 1,571 read