Skip to main content
The Specialists page shows how to create a Specialist. This page is about what to write in its four fields: the name, When to use, Instructions, and Handoff conditions. Each does a different job, and the AI Agent reads it at a different moment.

​
The When to use field

This is the field the AI Agent uses to pick a Specialist. When a ticket arrives it sees the name and When to use of every active Specialist, and nothing else. Its job is to separate this Specialist from its neighbours. Where two of them overlap, the AI has to guess. Say what the Specialist covers, then say what it does not, and name the borderline cases that belong somewhere else. Too vague
  • When a customer asks about a damaged product
  • When a customer wants to return something
  • When a customer has a problem with their order
Specific enough
Handles complaints about products that arrived damaged, faulty, or not as described, including warranty claims. Not for undamaged returns, missing items, delivery status, or size advice.
Steps do not belong here. This field decides which Specialist takes the ticket, and what happens next goes in the instructions. If no Specialist matches, the ticket is handled as a general request, or handed off when Ticket handling is set to Specialists only.

​
The Instructions field

Once the AI has picked a Specialist, it reads that Specialist’s instructions and handoff conditions in full, and can use every tool mentioned with @ in them. The AI follows these literally. Vague wording like “handle it appropriately” gives you vague behaviour. A rigid script has the opposite problem. It covers the tickets you thought of and leaves the AI improvising on everything else. Say what the outcome should be, then give rules for the cases you can predict.
  • One step per bullet, with the condition that triggers it and what the AI should do. Nest the sub-cases under the step they belong to. A flat list of the same content sends more tickets to the wrong Specialist.
  • Mention every tool the AI needs with @: Actions, Lookups, and Knowledge sources. A tool named in plain text cannot be called. This is the single biggest thing you can fix in a Specialist.
  • Say what to do when a lookup comes back empty, or when something you assumed turns out not to be true. “If the terms do not state a warranty period, do not quote one and continue with the claim.” Anything you leave out is decided by the AI’s judgement rather than yours.
  • Say what finished looks like. “Once you have the order and a description of the fault, create the claim.” That tells the AI when to stop, and gives it something to aim for on a ticket the instructions do not quite cover.
  • Keep “always” and “never” for rules with no exceptions, such as safety or legal wording.
  • Say what to do rather than what to avoid, where you can. “Check what you know against your tools, or ask the customer” works better than “do not make assumptions”.
  • Shorter is usually better. The best Specialists are rarely the longest.
You do not have to repeat rules that apply everywhere. Company configuration and channel guidelines sit on top of every Specialist, so each one only covers its own topic.
Some Specialists exist only to collect details and raise a manual action for a human, for example address changes where no integration exists. That is a good design. Write the instructions to gather exactly what the human needs, then use the manual action.

​
The Handoff conditions field

These decide when the AI stops and brings in a Human Agent. It reads them alongside the instructions and keeps applying them as the conversation goes on, so each one has to be something it can actually observe in the conversation or in a lookup result.
  • Observable facts, not moods. “The customer still asks for a refund after the standard answer.” “The case covers more than one order.” Anger and direct requests for a human belong in the company-wide handoff conditions, where they apply everywhere.
  • Do not repeat When to use. If everything the Specialist handles is also a handoff condition, it hands off every ticket before it replies.
  • Include “do not hand off when” rules. “A customer profile that is not found is missing data, not a reason to hand off.” A handful of sharp conditions plus a few exceptions works better than a long list.
This field takes prose only, so the @ picker is not available here. To force a handoff at one specific point, put @Handoff to human agent in the instructions instead. Some topics hand off most of their tickets by design, which is fine when it is deliberate.

​
Put these somewhere else

​
Fix common problems

​
Worked example: warranty claims

A consumer electronics shop with an order lookup, a warranty terms document, and an integration that creates claims.

Name

Warranty claims

When to use

Handles claims for products that stopped working or arrived faulty within the warranty period, including repair, replacement, and how to send a device in. Not for undamaged returns, order status, missing parcels, or questions about using a working device.

Instructions

  • Find the purchase with @Lookup: Order history using the order number or the customer’s email address.
    • If no order is found, ask for the order number or the email used at checkout, and nothing else.
  • Check the warranty period for the product category in @Knowledge: Warranty terms.
    • If the terms do not state a period for this product, do not quote one. Continue with the claim and say that the service team will confirm it.
  • If the purchase is outside the warranty period, say so, give the out-of-warranty repair option from @Knowledge: Warranty terms, and stop.
  • If the purchase is within warranty, collect what is still missing in one reply: a short description of the fault, when it started, and a photo or video if the fault is visible.
  • Once you have the order and the fault description, create the claim with @Action: Create warranty claim and tell the customer the claim number and what happens next.

Handoff conditions

  • The customer reports smoke, fire, a burning smell, or an injury from the device.
  • The customer asks for a refund instead of a repair or replacement.
  • The claim covers more than one order.
  • The customer disputes the warranty period after you have quoted it.
  • Do not hand off because the order is not found on the first try, or because no photo was attached.

​
Test it

Create an Automated Test for the main path and one for each handoff condition. A test can assert which Specialist handled the conversation, which tools were called, and whether a handoff happened. Nova can draft a test from a real ticket.