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 |