Agent design canvas

# Agent design canvas — worked example

A returns assistant that can issue a refund

Illustrative scenario, not a claimed customer incident.

A returns assistant reads a customer's message, finds the relevant policy, looks up the order and recommends a refund. Then someone asks whether it can issue the refund as well. On a diagram that is one more connection; in the world, the system can now move money. The canvas below is that system, after the refund tool has been connected.

System: Returns assistant
Owner: ⟨the engineer who owns this design⟩
Date: ⟨date⟩
Status: In design — not yet reviewed

---

## Does this need an agent at all?

**Open.** Reading an unstructured message, working out which of several policies
applies, noticing that a shipment was partial, deciding whether the request is even
about a return. The next step depends on what the previous one found.

**Closed.** Given an identified order, a policy version and an amount, issuing the
refund is a fixed sequence. That is a function. It is called by the agent; it is not
part of the agent's reasoning.

## What it is for, and where it stops

**Purpose.** Reads a customer's return request, identifies the order, applies the
published returns policy, and recommends or issues a refund within the window that
policy defines.

**Non-goals.** It does not amend an order. It does not cancel a subscription. It does
not contact a bank. It does not act on an order it could not identify. It does not
refund outside the published policy, even where a person plainly deserves it — that
case goes to a person, by design.

## What must be true before it acts

Before `issue_refund` may be called, all five must be established:

- the order, identified by id, not by description
- the state of that order, read at the time of the decision
- the policy clause that permits the refund, **with the version it came from**
- the amount that clause allows
- the absence of a prior refund against the same order

Each is carried as a reference. The clause is `returns-policy@⟨version⟩ §⟨clause⟩`, not
a summary of it.

## What each tool may do

| Tool | Job | Enforces itself | Acts as |
|---|---|---|---|
| `find_order` | Read one order by id | Read-only; no cross-customer lookup | service identity, read scope |
| `read_policy` | Return a clause by id and version | Read-only; refuses an unversioned request | service identity, read scope |
| `issue_refund` | Move money against one order | Re-reads the cited clause and the order state; refuses an amount above what the clause allows; refuses a second refund against the same order | its own identity, write scope, every call recorded |

The refund tool does not trust the arguments it was called with. It re-checks the
evidence it was handed, because the caller is a model and the caller's reasoning is not
a control.

## What it does when it is uncertain

- **The policy does not cover this case.** Hand over, naming the case and the clauses
  considered. Never a best guess dressed as a decision.
- **The order state is ambiguous** — a partial shipment, a return in transit. Hand
  over with the ambiguity stated.
- **Two policy versions disagree.** Refuse and raise; this is a content problem, not a
  customer problem.
- **The refund tool times out** and the outcome is unknown. Do not retry. Read the
  state of the action first, then decide. ⟨name the person or queue that receives each
  hand-over — an unrouted hand-over is a refusal with extra steps⟩

## What you can see afterwards

Per run: the customer's request; the order id; every policy clause read, with version;
every tool call with arguments, result and duration; the point at which it chose to act
rather than hand over, and on what basis; the outcome, including a refusal or a
hand-over.

Kept because a dispute about a refund is settled by evidence, and "the system decided
to" is not evidence. ⟨set a retention period here, and check it against your own data
policy⟩

---

Blank version of this template · https://learning.thelivingcraft.ai/resources/templates/agent-design-canvas