A conversation design template that survives contact with engineering
Every section a design needs: turns, branches, tool calls, escalation and sign-off, each with a filled-in fragment from a card-dispute flow.
A conversation design template is a structured specification of one agent flow: the goal and scope, the audience, the channels, the voice, the happy path written turn by turn, the branches where things go wrong, the tool calls behind each answer, the escalation rule, and a record of who approved what. Fill it in and you have a document engineering can build from and a client can sign.
Most templates you find cover half of this. They are strong on persona and sample dialogue, and silent on the two things the build team asks about in the first meeting: which systems the agent calls, and what it says when those systems fail. That is why so many designs get admired in the workshop and quietly rewritten in the sprint. The template below treats tool calls and failure paths as first-class sections, which is why it survives contact with engineering.
How do you use this template?
Work through the sections in order, in whatever document tool your team already opens. Each section below has two parts: what to write, and a filled-in fragment from a card-dispute flow at Aldergate Bank, a fictional retail bank. For the method behind the sections, read how to design an AI agent conversation, step by step.
The template, section by section
1. Metadata
Name the flow precisely, give it an owner, a status, a version, and links to sibling flows. One flow per document: “the support bot” is a whole programme of flows. This is the boring section that saves you in month three, when someone asks which version the client actually saw.
Aldergate example. Card dispute, v0.4, status: in review. Owner: Priya Nair, product. Last changed 14 July 2026. Related flows: lost or stolen card; unrecognised subscription charge.
2. Brief: goal and scope
One sentence of goal, then two lists: what this flow does, and what it explicitly does not. The does-not list is the more important of the two; it is where scope arguments go to die. When it changes, date the change and make it visible.
Aldergate example. Goal: a cardholder can dispute a debit-card transaction and leave knowing exactly what happens next. Does: identify the transaction, check eligibility, file the case, offer a card block. Does not: credit cards, status of existing disputes, merchant refunds, provisional credit decisions.
3. Audience
Describe who talks to the agent, what they already know, and the state they arrive in. Write it as facts the wording has to respect. A marketing persona with a stock photo gives the wording nothing to obey.
Aldergate example. Signed-in retail cardholders who have spotted a charge they do not recognise. Usually on a phone, often anxious, and in most cases not actually defrauded: an unrecognised charge is frequently a merchant billing under a different trading name, or a family member’s purchase. The opening turns de-escalate; they do not presume fraud.
4. Channels
List where the flow ships and what each channel can render. Every constraint written here removes a future argument. If one channel is text-only, every rich turn needs a plain-text twin, written now, before the build improvises one.
Aldergate example. Web chat inside the signed-in banking app, with buttons, cards, and forms available. SMS fallback: plain text only, so the transaction-picker card becomes a numbered list. Voice is out of scope for v1.
5. Voice
Give traits with counterweights, and say how tone shifts by situation. “Friendly” alone is untestable; “calm but not casual” can be checked against a sentence. Note the words the agent must not use before the facts confirm them.
Aldergate example. Calm but not casual; precise but not legalistic. When fraud looks likely, warmth drops and the wording turns procedural. The agent never says “fraud” before the eligibility check confirms the category; until then it is “a charge you didn’t authorise”.
6. The happy path, turn by turn
Write the conversation out as example turns, customer and agent back and forth, from the first message to the resolution. This is the section people skip and the section that decides everything, because the examples set the standard the build is measured against. Mark the turns where the agent needs data before it can answer.
Aldergate example (first four turns):
Customer: “There’s a charge on my card I don’t recognise.”
Agent: “I can help with that. Give me a moment to pull up your recent transactions.” [calls lookup_recent_transactions] “Is it this one: NOVA*STREAM, 12.99, on 16 July?”
Customer: “Yes, that one. I never bought that.”
Agent: “That merchant bills as NOVA*STREAM for the Vantage TV app, which catches a lot of people out. Does that explain it, or would you like to dispute the charge?”
7. Branch inventory, by type
List every branch, each labelled happy, edge, sad, or adversarial, and each forking from a named turn. Then read the list as a coverage check: a type with zero branches usually means nobody has designed for it yet. We made the longer argument in the happy path is not a design.
Aldergate example. Edge: the charge is still pending and cannot be disputed yet (forks at turn 4); the trading-name explanation resolves it and no dispute is filed. Sad: the transaction lookup times out; the 120-day dispute window has passed. Adversarial: the customer wants to dispute a charge their history shows they make every month; a caller probing for someone else’s transactions.
8. The tool contract table
This is the table engineering reads first. For every tool the agent depends on: what it does, its inputs and where each one comes from (asked in conversation, inferred from context, or fixed by the system), whether it writes anything, and what the agent says when it fails. A tool without a failure line is an undesigned turn waiting to happen in production.
Aldergate example.
| Tool | What it does | Inputs (source) | Writes? | If it fails |
|---|---|---|---|---|
| lookup_recent_transactions | Last 90 days of card transactions | account (context); card last four (asked, only if the customer holds several cards) | No | “I can’t pull up your transactions right now”; offer the call-back branch |
| check_dispute_eligibility | Confirms the charge is settled and inside the window | transaction id (context, from the lookup) | No | File nothing; promise manual review, never guess |
| create_dispute_case | Opens the case and returns a reference | transaction id (context); reason (asked, mapped from plain language); confirmation (asked) | Yes, after an explicit confirmation turn | Apologise and escalate; never invent a reference number |
| block_card | Freezes the card immediately | card id (context); confirmation (asked) | Yes, and hard to undo | Escalate at once: a failed block is a security event; do not retry |
9. Escalation
State when the agent hands off to a human, and write out the hand-off turn. Triggers must be enumerable: “when the customer is upset” is a mood, “after the third failed attempt to identify the transaction” is a trigger. The hand-off is the last turn of the flow. Say what the human receives with it, so the customer never has to repeat themselves, and stop there.
Aldergate example. Escalate when create_dispute_case or block_card fails, when the customer says the card is lost or in someone else’s hands, or after the third failed attempt to identify the transaction. Hand-off turn: “I’m bringing in a colleague from our disputes team now. They’ll have everything we’ve covered, so you won’t need to repeat yourself.”
10. Open questions
List the decisions nobody has made yet, each with an owner and a date. An honest open-questions section is what separates a design from a wish, and each answered question usually becomes a branch in the next revision.
Aldergate example. When a pending charge settles, do we file automatically or ask the customer to return? (Ops, by 22 July.) Does the agent mention provisional credit at all, and who signs off on that wording? (Legal, by 25 July.)
11. Approval record
Record who approved which version, when, and what the approval covers. Approval should cover the example conversations themselves; a sign-off on a flowchart commits nobody to anything. This record is what you point at in month four, when memory and the document disagree. There is a longer piece on making that stick in getting a client to sign off on an agent design.
Aldergate example. v0.3 approved by the Head of Cards on 2 July 2026, covering the conversations, branches, and tool contracts. v0.4 reopened to add the SMS text twins; re-approval pending.
Do you need a tool for this, or will a doc do?
A doc will do, and starting in one today beats waiting for tooling. Every section above works in a page of Notion, Confluence, or Word. What a doc does badly is everything after the first draft: branches written in prose become unreadable past a handful of paths, the tool table drifts from what engineering actually builds, version history degenerates into filenames, and the approval lives in an email thread nobody can find.
We built Klate as the tool shaped like this template. The brief, the typed branches (happy, edge, sad, adversarial), the reusable tool library with every parameter marked as asked, inferred, or fixed, the explicit escalation turn, the version history, and the approval record are all first-class objects; none of them is a heading you maintain by hand. An approver signs off on the conversations themselves from an emailed link, no account needed. Each tool call carries its contract and example values, which is what engineering wants from you at this stage.
Take the template either way. If you run it in a doc and the branches start fighting you, the free plan holds five designs, which is enough to find out whether the method sticks.
