pinecallDocs
Key concepts / Teams & handoffs

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.

agents/billing/agent.ts
/** 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.ts
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:

agents/front-desk/agent.ts
/** 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:

agents/billing/agent.ts
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.ts
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.

Next steps#