v3 Agents Tutorial — build, test, ship an HR bot
This is a hands-on tutorial for builders who are new to v3 agents and want to go from "empty bot" to "tested and ready to ship" — not by clicking around, but by understanding why each surface exists and how to use it well.
We'll build one bot end-to-end: hr-helper, an HR assistant that handles leave, payroll, and policy questions for an employee audience. By the end you'll have written agent prompts, attached real tools, designed routing rules, run a regression dataset, and debugged a failure trace.
By the end of this tutorial you'll be able to
- Write a v3 agent prompt that produces consistent behavior (and know why a vague one doesn't).
- Add tools to an agent and write tool descriptions the LLM actually picks correctly.
- Decide when a routing rule is the right answer vs a trigger vs a conversation rule.
- Design a multi-agent setup without overlapping responsibilities.
- Build a regression dataset and test your bot before every release.
- Read an execution trace when something goes wrong and fix the root cause in minutes.
Each chapter takes 5–10 minutes to read and includes a Try it exercise and at least one Nexus tip showing how Copilot can do the heavy lifting for you.
Prerequisites
- A v3 bot you can edit. If you don't have one, create a fresh bot in Studio and toggle AI Agents → Switch to v3.
- Access to AI Trust Centre (top-level menu — used in chapters 5 and 6).
- Nexus open in the right-side panel of your bot — most chapters have a "Nexus tip" callout you can try inline. (Don't have it visible? See Nexus overview.)
- Familiarity with the v3 surfaces. If you're brand new, skim the v3 Agents overview first — 5 minutes, and the rest of this tutorial will land better.
Meet the bot we're building
hr-helper is a super agent with three specialised agents underneath it:
| Agent | What it owns |
|---|---|
leave-agent | Leave balance lookup, leave applications, leave policy questions |
payroll-agent | Salary slip download, payroll dates, tax declarations |
policy-agent | All other HR policies — code of conduct, expense rules, work-from-home, grievance procedures |
The super agent owns the welcome message, the fallback when nothing matches, and routing between the three agents.
A note on terminology. v3 has three tiers — super agent (orchestrator and router), agents (specialists for one task each, like
leave-agent), and sub-agents (children of an agent, used for reusable nested tasks like "verify identity"). This tutorial builds at the super-agent + agents layer; we'll only mention sub-agents when they're the right tool.
What hr-helper will do
- Tell an employee their current leave balance and walk them through applying for leave.
- Surface payroll information (next pay date, tax forms, salary slip download).
- Answer policy questions from the HR knowledge base.
- Escalate to a human HR partner when it can't help or when the user explicitly asks.
What hr-helper will not do
- Quote salary numbers from memory (always fetch from payroll system).
- Approve leave or make policy exceptions — those go to HR partners.
- Discuss another employee's data, even if the user has manager privileges (kept simple for the tutorial — real-world bots add an authorization tool here).
- Speculate about company strategy, layoffs, or anything not in the HR knowledge base.
Why "out of scope" matters as much as "in scope". The refusals you write into the prompt are what stops the bot from hallucinating in production. We'll come back to this in chapter 1 — Writing your agent prompt.
How the chapters fit together
| Chapter | You'll add to hr-helper |
|---|---|
| 1. Writing your agent prompt | Super agent identity + the three agent prompts |
| 2. Adding tools & writing descriptions | get_leave_balance API, payroll workflow, policy KB tool |
| 3. Routing rules & triggers | Triggers on each agent + 2 Routing Logic rules |
| 4. Designing the agent tree | When to split / merge agents; shared memory across the three |
| 5. Testing your bot | A 12-case dataset in AI Trust Centre |
| 6. Debugging issues | Reading traces; fixing a real failure |
Each chapter ends with a "snapshot" of what the bot looks like at that point, so you can skip ahead if you only need part of the flow.
Don't want to click through Studio to create the agents? Open Nexus and ask:
"Create three agents on this bot:
leave-agent(handles leave balance and applications),payroll-agent(handles salary slips and pay dates),policy-agent(handles all other HR policies). Give each a one-line trigger description."
Nexus will use the bot_ai_agents_expert to create the agents and write a first draft of each trigger description. You'll refine the prompts and tools as you go through the tutorial — but the scaffold is one prompt away.
Before touching Studio, write down on paper:
- Three questions your bot must answer well. Be specific — "What's my leave balance?" beats "leave questions."
- Three questions your bot must refuse or escalate. These become your refusal rules in chapter 1.
If you can't list three of each in two minutes, your scope isn't sharp enough yet. Talk to whoever asked for the bot before continuing.
A note on style
You'll see two kinds of callouts throughout the tutorial:
- :::tip[Nexus tip] — "Ask Nexus to do X for you." Concrete prompts you can paste into Copilot to skip the manual click-through.
- :::note[Try it] — "Do this exercise on your own bot before continuing." Five minutes max each. Skipping these makes the next chapter harder.
We'll also link out to the v3 Agents reference docs whenever a topic deserves a deeper dive. The tutorial teaches you the thinking; the reference docs are the spec.
Reference: v3 Agents overview · Super agent (reference)