Agent Definition — Patterns

Identity in the artefact, prose assembled at call time

Problem. A single file holding every sentence an agent might need becomes a monolith that nobody can safely edit: tenant-specific wording, seasonal policy, and core behaviour are interleaved, and a change for one caller risks all of them.

Approach. Keep the artefact small and factual — name, owner, tool references, model binding, input and output contracts, enforceable limits — and assemble the operating prose at call time from a base layer plus named fragments selected by tenant, locale, and task. Record the resolved text, or a hash of it plus the fragment identifiers, on every run.

Trade-off. The text that actually ran is no longer visible in the repository, so review moves from reading a file to reading a composition rule and its test fixtures. Without the resolved-text record, incident investigation becomes guesswork.

Declared facts separate from the prose

Problem. Selection rules, catalogues, and permission policies need to ask questions of an agent — what task types does it handle, what data scopes does it touch, how much does a typical run cost — and prose cannot be queried.

Approach. Give the artefact a structured block distinct from its instructions: task classes, input modalities, required data scopes, expected cost band, maximum blast radius. Validate the block against a schema in continuous integration, and make it the only thing other systems are allowed to read.

Trade-off. Declared facts rot faster than prose because nothing fails when they become untrue. They need their own tests — a run that touches a scope the artefact did not declare should fail the build, not merely surprise someone later.

Task set bound to the artefact

Problem. A wording change is reviewed the way a document is reviewed: someone reads it, finds it sensible, and approves. Nothing establishes that the agent still does what it did yesterday on the cases that matter.

Approach. Store a set of representative cases and their assertions in the same folder as the artefact, so they version together. Run them on every change to either file, and block the merge on a regression rather than reporting it afterwards.

Trade-off. Every change now costs model calls and minutes. The set also ossifies: it encodes yesterday's idea of correct behaviour, and an intended improvement will show up as a failure that someone has to adjudicate rather than silence.

Limits expressed twice, enforced once

Problem. Constraints that exist only in instructions are suggestions. Constraints that exist only in enforcement code are invisible to the model, which then spends iterations attempting actions that will be refused.

Approach. Express each hard limit as a structured field, generate the corresponding sentence in the instructions from that field, and enforce the field in the runtime before the action is attempted. One source, two renderings.

Trade-off. Generated instruction text reads less naturally than hand-written prose and occasionally phrases a limit in a way the model handles poorly. The alternative — writing both by hand — guarantees they disagree eventually.