AI Agent Specification Template
A fill-in specification for an autonomous agent, the task boundary, tool inventory with blast radius, stopping conditions, spend caps, human checkpoints and the log you will need when it does something surprising.
Markdown. No sign-up, no email.
An agent is a program that decides what to do next. Everything below exists because that sentence has consequences. Fill it in before the agent touches anything real, a blank cell here becomes an incident later, and the incident arrives with no record of what was intended.
Agent name: _______________ Owner (person, not team): _______________ Date: _______ Version: _______
1. The task#
One sentence, in the user's words: _______________
What it is explicitly NOT allowed to attempt: _______________
What a human does today instead, and how long it takes: _______________
If you cannot describe the task in one sentence, you have a workflow, not an agent task. Workflows are cheaper, more predictable, and easier to debug, build the workflow.
2. Autonomy level: pick one and record why#
| Level | Description | Chosen |
|---|---|---|
| 0 | Suggests; a human performs every action | |
| 1 | Acts on reversible things; asks before anything else | |
| 2 | Acts within a stated budget and scope; reports after | |
| 3 | Acts continuously; a human reviews samples |
Why this level: _______________ What would have to be true to move up one level: _______________
3. Tool inventory: the blast radius table#
Every tool the agent can call. Reversibility is the column that matters; fill it honestly.
| Tool | What it does | Reversible? | Worst realistic outcome | Confirmation required |
|---|---|---|---|---|
| yes / no | ||||
| yes / no | ||||
| yes / no |
Any row with "no" in the reversible column and "none" in confirmation is the incident you will be writing up. Decide now, not then.
Tools deliberately withheld, and why: _______________
4. Stopping conditions#
An agent without stopping conditions does not fail, it loops, spends, and retries.
| Condition | Limit |
|---|---|
| Maximum steps per task | |
| Maximum wall-clock time | |
| Maximum spend per task | |
| Maximum spend per day (hard cap, enforced where?) | |
| Repeated identical action | stop after ___ |
| Repeated tool error | stop after ___ |
| No measurable progress | stop after ___ steps |
Where each cap is enforced (in the agent's own logic is not sufficient, an agent can reason its way around its own instructions; the cap must sit in the layer the agent cannot edit): _______________
5. Human checkpoints#
| Trigger | Who is asked | How they are reached | What happens if nobody answers |
|---|---|---|---|
The last column is the one teams skip. Silence must have a defined meaning: default-stop is almost always correct, and it must be written down.
6. Untrusted input#
Agents read things: web pages, documents, tickets, emails, tool output. All of it can contain instructions aimed at the agent.
| Sources of text the agent will read | |
| How retrieved content is delimited as data | |
| Tools that can be triggered as a direct result of read content | |
| What prevents a read instruction from becoming an action |
The dangerous combination is: reads untrusted content and holds a tool with real-world effect and acts without confirmation. If all three are true, redesign rather than mitigate.
7. Memory and state#
| What persists between runs | |
| Who can write to that memory | |
| How a poisoned or wrong memory is detected | |
| How it is cleared |
Memory that only ever accumulates will eventually contain something false, and the agent will treat it as established fact.
8. Observability#
| Every tool call logged with arguments | yes / no |
| Reasoning/decision trace retained | yes / no |
| Retention period | |
| Cost per task tracked | yes / no |
| Where a human watches a run live | |
| Alert on: cap hit, loop detected, tool error rate |
Could you reconstruct, from logs alone, why the agent did something surprising three days ago? yes / no. If no, the observability is not finished.
9. Evaluation before release#
| Check | Result | Date |
|---|---|---|
| Runs on a fixed task set, results recorded | ||
| Behaviour when a tool fails | ||
| Behaviour when input is ambiguous | ||
| Behaviour when instructed by content it reads | ||
| Spend cap actually stops it (tested, not assumed) | ||
| Kill switch tested end to end |
10. Sign-off#
| Name | Date | |
|---|---|---|
| Built by | ||
| Security review | ||
| Budget owner | ||
| Approved to run unattended |