Agent spec template¶

Last verified: 2026-05-06 · Drift risk: low

An agent spec is a concise, authoritative document that describes what an agent does, how it should behave, what it is allowed to do, and who is responsible for it. Write it before building. Update it whenever the agent's behavior, tools, or ownership changes.

Template¶

Job statement¶

One sentence. Start with a verb. Describes what the agent does, for whom, in what context.

[Agent name] [does what] for [whom] by [means / using what].

Inputs¶

What the agent receives at the start of a session. Include data type, source, and whether it is required or optional.

Input	Type	Source	Required?	Notes

Outputs¶

What the agent produces. Include format, destination, and whether the output is advisory (shown to a human) or action-taking (triggers a downstream effect).

Output	Format	Destination	Type (advisory/action)	Notes

Tools¶

List every tool the agent is allowed to call. For each tool, provide the least-privilege rationale: why does the agent need this tool, and what is the minimum permission level required?

Tool name	Permission level	Least-privilege rationale	Worst-case side effect

Tools NOT on this list must not be called. This is an explicit allowlist.

Stop conditions¶

The agent must stop when any of the following is true:

[Condition 1 — e.g., the task has been completed and a result returned]
[Condition 2 — e.g., the maximum step count has been reached]
[Condition 3 — e.g., a required input is missing and cannot be retrieved]
[Condition 4 — e.g., a tool returns an error that cannot be recovered from]

Error handling¶

Error type	Expected behavior
Tool call fails with a retryable error	Retry up to [N] times with [backoff strategy], then surface error to user
Tool call fails with a non-retryable error	Stop and return a plain-language explanation to the user
Required input is missing	Ask the user for the missing input before proceeding
Model produces output that fails format validation	Retry once, then return raw output with a warning
Step budget is exhausted	Stop, return partial results with a note that the task was incomplete

HITL gates¶

List every point at which the agent must pause and wait for human confirmation before proceeding.

Trigger	Gate type	Confirmation prompt
[e.g., About to send an email]	Approve-before-act	[Full text of what the agent shows the user]
[e.g., About to update more than 10 records]	Dry-run + approve	[Full text]

If no HITL gates are needed (read-only, advisory-only agents), state that explicitly.

Eval set reference¶

Eval set file	Version	# Cases	Last run

Link to the eval set in version control.

Owner¶

Role	Name	Contact
Primary owner
On-call contact
Escalation contact

Review cadence¶

Scheduled review: [monthly / quarterly / on major change]
Last reviewed: [date]
Next review due: [date]

Filled example: Literature triage agent¶