💭 in your head · nothing to type
The goal of this unit is to pull everything you did in module 08 into one specification document for your first AI project.
Don't picture this as "a form to fill out" — picture it as a general staging a campaign on the map. He doesn't charge into battle himself — he positions the units, sets the objectives, draws the supply lines. The fighting comes later. First — the plan on paper.
Run the task from unit 1 through your head. Picture yourself as that general: your agents, tools, and triggers are units on the map. Where are they positioned? Which flank is exposed?
💭 in your head · nothing to type
A good agent spec answers these questions before any code is written.
Don't picture this as a questionnaire — picture it as an architectural blueprint: a building doesn't go up until there's a drawing. A mistake on paper costs a pencil stroke. A mistake in the foundation costs a teardown. The architect holds the entire structure in mind at once — load paths, utilities, fire exits — before a single pile is driven.
| Question | What goes in the answer |
|---|---|
| Trigger | What kicks off the agent? (cron / webhook / event / poll / manual run) |
| Inputs | What arrives? (format, volume, source) |
| Steps | What nodes does the pipeline consist of? |
| AI vs Code | Which nodes are LLM, which are code (see u2)? |
| Outputs | Where does the result get written? |
| Failure modes | What can break, what to do? |
| Observability | Where do you look to see what happened? |
| Cost ceiling | Max spend per day? |
| Human-in-loop | Where is your review needed? |
| Quality | How will you check the agent answers well? (a set of examples with expected results) |
If even one question has no answer — the foundation isn't ready to pour. Which load-bearing element in your blueprint is still without support?
Agent specification template
# Agent: [name]
## Goal
[One sentence: what the agent does, what pain it solves]
## Trigger
- Type: cron / webhook / event / poll / manual
- Params: [e.g., every 5 minutes / on Gmail label / on repo push]
## Pipeline
1. [Node type] — [what it does] — [in → out]
2. [Node type] — [what it does] — [in → out]
3. ...
## AI nodes
List of nodes where an LLM is used:
- Node X: model [provider/model], prompt in `prompts/x.md`
- ...
## Tools / APIs
- Gmail API (scope: ...)
- Notion API (workspace: ...)
- ...
## Execution
- Where the agent lives: a Docker container on a server
## Security
- Dashboard access through Cloudflare Access with a PIN
## Storage
- SQLite: `inbox.db`, email states and failure reasons
- Idempotency: a processed email is skipped on a repeat pass
## Observability
- Trace: the model gateway's log / OpenTelemetry (OTel, a telemetry collection standard) / stdout logs (Langfuse is an option too; the author removed it because nobody read it)
- Alerting: where errors go (Telegram / email / Slack)
## Failure modes
| Scenario | Behavior |
|---|---|
| LLM 500 | Retry 3× with exp backoff, then fallback model |
| Bad input | Log + Telegram alert + skip |
| Storage full | Hard fail + alert |
## Cost
- LLM calls per day: ~N
- Estimated $: free pools; ceiling — [not determined]
- Hard cap: [?]
## Human-in-loop
- Where: [step N]
- What you confirm
- How: [Telegram message / Notion task / email]
Real example of a filled-out spec — a Gmail agent:
# Agent: Gmail inbox assistant
## Goal
Every two minutes or so, the agent processes new personal inbox mail, assigns
one of five labels, and prepares a draft when a reply is needed. Sending is
possible only after a human clicks the button.
## Trigger
- Type: poll
- Params: Gmail API about every two minutes, up to 20 emails per pass, oldest first
## Pipeline
1. Poll — fetch new emails — () → [up to 20 emails]
2. Normalize — standardize fields — [email] → [normalized]
3. Classify — choose `AI/Now`, `AI/Later`, `AI/FYI`, `AI/Newsletter`, or `AI/Ignore` — [normalized] → [label]
4. Apply — add the label and archive when required — [label] → [Gmail thread]
5. Draft — write a reply draft when needed — [normalized] → [draft]
6. Review — dashboard: confirm label / approve and send / remove — [draft + label] → [human decision]
7. Send — send in the same thread through Gmail API — [approved draft] → [sent]
## AI nodes
- Classify — LLM through the model gateway, with the five labels and their meanings
- Draft — LLM through the model gateway, writes a draft only
## Tools
- Gmail API: label and archive only; sending is a separate post-button step
- SQLite: `inbox.db`, email states and failure reasons
## Storage
- SQLite: `inbox.db`, email states and failure reasons
- Idempotency: `new → labeled/drafted → sent/failed`; after five failures, a dead-letter queue
## Observability
- Service log + SQLite email state
- Model gateway log, with usage recorded by service name
- Dashboard metric: “hours since last processed email”; a green container does not prove the flow is alive
## Failure modes
| Scenario | Behavior |
|---|---|
| Gateway 5xx | Retry 3× with a pause; after 5 failures, dead-letter queue |
| Gmail access failure | Stop the pass and wait 15 minutes |
| Stale Gmail cursor | Read the mailbox again instead of jumping straight to “now” |
| Missing gateway key | Refuse to start; do not pretend the inbox is empty |
## Cost
- At most two LLM calls per email; the pass is capped at 20 emails
- Every request carries the service name; usage is visible in the gateway log
## Human-in-loop
- On the dashboard I confirm the label, approve and send, or remove the proposal
- The agent cannot delete mail or send without confirmation
This is on paper. There's no code yet. But anyone — including me six months from now — can read it and understand what the agent does.