Teams & handoffs
Several agents on one line, and a call that passes from one to another when the caller asks for something else.
A line can have a team: several agents, and a call that passes from one to another when the caller asks for something else. The caller keeps talking; the agent on the call changes.
What is a team?#
The agents a call of one line may pass between. One of them answers. Each of the others says, in a sentence, what it takes.
/** You handle charges, invoices and refunds for Brightside Dental. */
@agent({ takes: "a question about a charge, an invoice or a refund" })
export default class Billing extends Agent {}
app.line("+1 415 555 0134", {
greeting: "Brightside Dental. How can I help?",
answers: FrontDesk,
team: [Billing],
});
That is all it takes. The agent on the call is offered one tool per teammate, named by its class:
transfer_to_billing. Nobody writes that tool. The model calls it when the caller brings up what
Billing takes, and from then on the call is Billing's.
A caller who only says "Hello?" is passed to nobody: the agent that answered keeps the call.
How a pass goes#
The caller brings it up#
"I was charged twice for my cleaning." The model calls transfer_to_billing.
The call changes hands#
The next agent takes the call: its instructions, its tools, its state. Its onCall runs, as it does
when a call starts.
The conversation goes on#
What was said so far stays with the call. The caller is not told about the pass, and does not repeat anything.
Passing the call from a tool#
A tool can pass the call itself, with what the next agent should know:
/** The caller disputes one charge and you know which invoice. */
@tool()
disputeCharge(invoice: string) {
return this.call.handoff(Billing, { invoice });
}
The next agent reads it in onCall:
override onCall(call: Call) {
const invoice = this.call.handed?.invoice;
const patient = this.call.shared.patient;
}
| what it is | |
|---|---|
this.call.handoff(Agent, data) |
pass the call to a teammate, with what it should know |
this.call.handed |
what the agent before this one passed along; undefined for the agent that answered |
this.call.shared |
an object the agents of one call share: what the first wrote, the next reads. It ends with the call |
A line that chooses who answers#
answers may be a function. It runs as the call comes in, while the caller hears the greeting, and
returns the agent of the team that serves this call:
app.line("+1 415 555 0134", {
greeting: "Brightside Dental. How can I help?",
answers: async (call) => {
if (clinic.isClosed(call.today)) {
return AfterHours;
}
return FrontDesk;
},
fallback: FrontDesk,
team: [AfterHours, Billing],
});
fallback is the agent the number is pointed at. It answers when the function returns nothing,
throws, takes more than a second, or names an agent that is not of the team. The call's log then has
a routed line saying why.
What to know#
| A call is passed three times at most | the fourth pass is refused, and the agent on the call answers itself |
| Each tool has a name of its own | two agents of one team that declare a tool of the same name are refused when the app loads |
| The voice changes with the agent | a spoken call takes the model and the voice of the agent it was passed to, from its next sentence; a written call keeps the model it opened on |
| The call is the first agent's | it is listed and judged under the agent that answered |
Test a pass with a golden: the caller's line, and
"tools": ["transfer_to_billing"]as what must have been called. A second golden with"not_tools"checks that "Hello?" passes to nobody.