0% completed
The Design Worksheet
On This Page
The Nine Rows
Our Running Example: Desk So Far
What a Usable Answer Looks Like
How the Rows Depend on Each Other
What the Worksheet Does Not Do
Key Takeaways
Practice Questions
A city's building permit form asks the same questions about a garden shed and an apartment block: where it stands, how tall it is, what it connects to, and who is responsible. Some of the shed's answers are "none". The form does not make a building good, but no question can be forgotten, and an inspector can see which answer is missing.
An agent design needs the same kind of form, because a question such as "whose authority does this refund use?" often goes unasked until something goes wrong. What must every agent design answer, and how can you tell a usable answer from one that only sounds complete?
The Nine Rows
The design worksheet is a list of nine questions that every agent design must answer. Each case study and full design in this course fills it in. A row that the course has not yet taught stays blank and does not send the reader to another lesson.
| Row | The question it answers |
|---|---|
| Goal and done condition | What is the agent for, and what fact shows that a task is finished? |
| Autonomy per action | For each action, does the agent suggest, ask for confirmation, act and report, or act silently? |
| Tools, marked read or write | What can it read, and what can it change? |
| Context and memory | What does each call contain, and what is stored for later? |
| Topology | Is this one agent or several, and how are they arranged? |
| Guardrails and the security audit | What can stop it, and what could an attacker make it do? |
| Identity | Whose authority does it use, within which scope, and what does the audit line (the log entry for each write) record? |
| Evals | Which repeatable test tasks (evals) and graders tell you that a change made it better or worse? |
| Cost | How many tokens and how much time does a typical run use, and what is the limit? |
Only the fifth row asks how many agents the design uses and how they pass work to each other, an arrangement called the topology. Most others ask what the agent may do and how you would know what it did.
Our Running Example: Desk So Far
Desk's worksheet so far uses only what the course has taught, and its blank rows show what is still undecided.
| Row | Desk so far |
|---|---|
| Goal and done condition | Resolve each support message under the refund policy. A task is done when the reply is sent, any approved refund exists in the payment system, and the ticket is closed |
| Autonomy per action | Request a refund and close the ticket: confirm. Every read and the other two writes run without waiting |
| Tools, marked read or write | Read: look up the order, read the support tickets, check the payment records, read the refund policy, look up the customer, search the help articles. Write: reply to the customer, request a refund, escalate to an employee, close the ticket |
| Context and memory | Left blank |
| Topology | One single agent |
| Guardrails and the security audit | A refund above 200 dollars needs an employee's approval. Stop after 25 steps. Security audit left blank |
| Identity | Left blank |
| Evals | Left blank |
| Cost | Suppose 6,000 tokens at the start and 1,800 per step: a 6-step run sends 63,000 tokens, and the limit of 25 steps caps a run at 690,000 |
What a Usable Answer Looks Like
A usable answer is one that a second engineer could test against a running system. Each weak answer below could appear in a real design document, and each leaves the decision unmade.
| Row | Weak answer | Usable answer | Why the difference matters |
|---|---|---|---|
| Goal and done condition | "Customers are satisfied" | "The refund record exists, and the ticket is closed" | A reply with no tool calls is only the model's claim, so the done condition must name a fact in the environment |
| Autonomy per action | "Medium autonomy" | "Refund: confirm. Lookups: run without waiting" | Autonomy belongs to each action, and one level for the whole agent hides the risky one |
| Tools | "Access to the order system" | "Look up the order: read. Request a refund: write" | A write needs decisions that a read does not need, such as approval and retry handling |
| Context and memory | "Remembers customers" | "Stores the reply preference, and adds it to each call" | Memory that nobody specified cannot be deleted, audited, or kept out of a call |
| Topology | "A team of agents" | "One single agent, with no reason yet for more" | Anthropic reports that multi agent systems use about 15 times the tokens of a chat interaction, so more than one agent requires a stated reason |
| Guardrails and audit | "Follows the refund policy" | "The refund tool holds any amount above 200 dollars" | A sentence in the instructions asks the model to obey, while code enforces the limit whatever the model decides |
| Identity | "Uses the service account" | "Refunds only this customer's orders; the audit line records the case, the customer, and any employee who approved" | A shared account cannot show who is responsible for a write |
| Evals | "We will test it" | "20 to 50 tasks drawn from real support failures, the starting size that Anthropic suggests" | A number of tasks and their source can be checked, and an intention cannot |
| Cost | "Should be affordable" | "63,000 tokens for a typical run, 690,000 at the limit" | The token count is known before any price is applied, so the bill can be calculated at any price |
The goal row deserves the most care, because the other rows depend on it. If the done condition cannot be read from the environment, verification has nothing to read, and evals have nothing to score.
How the Rows Depend on Each Other
A change to one row usually forces a change in others, and the worksheet makes that visible. Suppose a product manager asks for one new Desk tool, "change the shipping address". This small addition changes several rows:
| Row | What the new tool changes |
|---|---|
| Tools | An eleventh tool, marked write |
| Autonomy per action | A new decision: must the customer confirm an address change before Desk makes it? |
| Guardrails and the security audit | A new risk: a customer message could cause Desk to send goods to an attacker's address |
| Identity | A new question: whose authority permits a change to this customer's data? |
| Evals | New tasks, including tasks in which the agent should refuse the change |
| Cost | Suppose the tool's description adds 200 tokens to the base. A 6-step run sends that description 6 times, so it rises from 63,000 to 64,200 tokens |
Three rows have no arrow: this one tool does not change the goal, the memory design, or the topology. To review any proposed change, ask which rows it changes and whether those rows were updated.
What the Worksheet Does Not Do
The worksheet records decisions, and it does not make them correct. A complete worksheet can still describe a poor design, as a complete permit form can describe a poor building. Its value is that a wrong answer is written down where someone can dispute it.
A blank means that nobody has decided yet, while "none" is a decision. A Desk variant with no memory should say "none: each ticket is handled from its own records", because that sentence can be challenged and a blank cannot.
A simpler design needs less of the worksheet. A direct call that sorts messages might answer most rows with "none", but it still needs a done condition, an eval, and a cost. Those lines are cheaper to write than a later discovery that nobody defined them. If one row is slow to answer for a small system, the system often does something riskier than its authors realized.
Key Takeaways
- The nine rows are goal and done condition, autonomy per action, tools marked read or write, context and memory, topology, guardrails and the security audit, identity, evals, and cost.
- A usable answer can be tested against a running system by a second engineer.
- The done condition must name a fact in the environment, because other rows depend on it.
- A change to one row usually forces changes to others, so ask which rows each change affects.
- A blank means undecided, while "none" is a decision that someone can challenge.
You now have the vocabulary, the loop, the reliability formula, the first decision, and the form that records every other decision. The reference page that follows, The Pattern Map, lists every pattern and where the course fills in Desk's blank rows.
Practice Questions
1. A design says, "Done when the agent reports that the refund is complete." Why is that not a usable done condition?
<details><summary>Show answer</summary>It names the model's claim rather than a fact. The agent could report a refund after the tool returned an error. A usable condition reads the environment: the refund record exists in the payment system, for the right amount and order.
</details>2. What is the difference between "left blank" and "none" in the memory row?
<details><summary>Show answer</summary>A blank means undecided, and "none" is a decision. "None" states that the agent stores nothing between tasks, which someone can test or dispute. A blank says that the question is still open.
</details>3. Suppose a team adds a tool that sends a customer a discount code. Name three rows that it changes, other than the tools row.
<details><summary>Show answer</summary>Autonomy, guardrails, and evals. The team must decide whether Desk suggests each code or sends it after confirmation, what limit stops it from sending too many, and which tasks test correct use and refusal. Identity and cost change as well.
</details>4. A team writes "medium autonomy" for its agent. What should the row say instead?
<details><summary>Show answer</summary>A level for each action. For Desk, a refund and a close require confirmation, while reads run without waiting. One level for the whole agent hides that its actions carry different risks.
</details>Reading Progress
0%
On This Page
The Nine Rows
Our Running Example: Desk So Far
What a Usable Answer Looks Like
How the Rows Depend on Each Other
What the Worksheet Does Not Do
Key Takeaways
Practice Questions