# AI Agent Specification

> 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 | | |