Agent Definition

What it is

The versioned artefact that specifies one agent: the instructions it operates under, the tools it is permitted to call, the model it is bound to, the shape of what it accepts and returns, and the hard limits on what it may do. Nothing in it is running. A single artefact backs every concurrent instance, and each of those instances is one interpretation of the same text.

Why it matters

Before an agent has an artefact, it is a prompt string interpolated somewhere inside a request handler — undiffable, unreviewable, untestable in isolation, and owned by whoever edited that file last. Turning the behaviour into a named, versioned object gives it an owner, a change history, and a test set. Every capability downstream assumes that object exists and means something stable: a catalogue needs something to catalogue, a selection rule needs declared facts to test, an approval policy needs a subject to attach itself to.

The artefact versus the instance that runs it

The artefact is static and shared; an instance has a conversation, a working scratchpad, a position in its own execution, and a session identity. Editing the artefact does not alter instances already running against the previous revision, and the states an instance moves through are not revisions of the artefact. Collapsing the two produces the familiar confusion where a wording change appears to take effect for new sessions and not for ones already open.

Key decisions

• Whether the operating instructions live in the artefact verbatim or are assembled at call time from layered fragments. Verbatim is reviewable in a pull request; assembled is adaptable but means the text that actually ran exists only in a log.
• Granularity. One broad agent with thirty tools is cheaper to build and harder to evaluate; six narrow agents are individually testable and create a selection problem that did not previously exist.
• Whether the model is pinned to an exact revision in the artefact or resolved at runtime from an alias. Pinning makes behaviour reproducible and makes retirement your problem.
• How the return contract is expressed — prose, a schema, or a schema with a prose field — and whether anything validates it before the caller sees it.
• Which constraints are declared as enforceable fields rather than written as sentences: the tool allow-list, a spend ceiling, a maximum number of iterations, forbidden argument values. Anything expressed only as a sentence is a request, not a limit.

Failure modes

• Instructions accrete one sentence per incident until the document contradicts itself, and nobody will delete a line because nobody remembers which incident it was for.
• The permitted tools are listed in the artefact while each tool's description lives with that tool's own code, so another team's wording change silently alters when this agent reaches for it.
• The pinned model revision is retired on the provider's schedule and the agent stops working on a day when nothing was deployed.
• A tenant-specific copy is forked from the original, the two drift, and a fix applied to one leaves the bug alive in the other for months.
• No task set is attached, so a wording change is accepted on the strength of a reviewer reading it and finding it reasonable.
• Limits written as polite prose — do not issue refunds above five hundred — are enforced nowhere else in the system, and the first adversarial user establishes that.
• The artefact is edited directly in a running environment, so the exact revision that produced last week's disputed transcript no longer exists anywhere.

Related capabilities

• Agent Registry — the catalogue these artefacts are published into
• Agent Lifecycle — the runtime states of an instance created from one
• Agent Routing — reads the declared facts to pick between artefacts
• Agent-as-a-Tool — the return contract declared here becomes a tool signature
• Autonomy Levels — attaches permission grades to the declared actions

Applies: Production readiness · Design questions