Skip to main content

​
Agent playbooks: trigger-driven live guidance

A playbook is an authored guidance card: a trigger phrase set plus the recommended action an agent should take when that phrase lands on a live call. When the transcript of an in-progress call contains the trigger, the card appears on the agent’s live panel; when the agent acts on it (or dismisses it), that outcome is recorded so QA can measure adherence. Because card definitions are deterministic literals, the same trigger in the same transcript always fires the same card — which is what makes playbook adherence measurable at all.

​
Playbook definition shape

Each card bundles a trigger and a response:
  • A trigger — a bounded list of literal terms matched case-insensitively (by default) with word-boundary awareness, combinable as any (fire on any term — competitor mentions, objection cues) or all (fire only once every term has been seen — compound intents like “refund” plus “cancel”). Matching can be restricted to the agent’s turns, the customer’s turns, or either.
  • A rendered title, guidance body, and an optional checklist of steps the agent is expected to complete.
  • Metadata: a stable slug id, a category (competitor, objection, intent, compliance, keyword, or custom) for reporting facets, and a priority (low, normal, high) for panel ordering.
Raw regex would be a hazard in the serve event loop, so triggers are literal terms only — a deliberate constraint, not a limitation for the supported trigger classes.

​
Where the library lives

A tenant owns one playbook library per organization, stored in your organization settings under the voice namespace (organizations.settings.voice.agent_playbooks) — configuration, not a new database table. The library has a master enabled switch and up to 200 cards; reads and writes run through dedicated endpoints and every card carries its own per-card enabled flag. A malformed or empty blob simply evaluates to the dormant empty library, so nothing fires until you author and enable cards. Admins manage the library through: Both are admin-scoped (owner/admin plus voice write scope), and the create/update audit trail records the enabled card count each time the library changes.

​
The stream evaluator

Guidance reaches a live call through a per-call Server-Sent Events channel: GET /voice/calls/{callId}/playbook/stream The agent’s CTI panel subscribes. A deterministic loop taps the same live transcript channel the agent-assist copilot and compliance monitor already use, evaluates every final transcript turn against the enabled cards, publishes each newly matched card to the call’s playbook channel, and the controller fans it out to every connected viewer of that call. A card fires at most once per call — a one-shot cue, not a per-turn nag. The frame sequence mirrors the agent-assist stream: a connected handshake, a status frame (already-terminal calls close immediately), playbook events carrying the fired card, the matched terms, and the matched speaker as provenance, 15-second keepalive comments, and an end frame on terminal status or the 30-minute hard cap (reconnect and resume). Failures degrade, they don’t propagate: a Redis or database hiccup closes the guidance layer while the call and transcript continue untouched.

​
Adherence

Firing a card is only half the loop — the other half is scoring whether the agent acted: Outcomes advance through shown → acknowledged → followed | dismissed. The loop writes the initial shown record the first time a card fires; the agent’s panel posts the terminal outcome. Records persist on the call itself, in call-log metadata under playbook_adherence, so the QA and supervisor surfaces can aggregate per-card, per-agent adherence: which guidance actually gets followed, and which cards agents routinely dismiss.

​
Lifecycle

  1. Author — an admin defines cards with trigger terms, guidance text, and an optional checklist.
  2. Enable — the library’s master switch plus per-card flags control which cards can fire, on which queues and agents.
  3. Evaluate live — the stream evaluator matches each final transcript turn deterministically and fires each card once per call.
  4. Adhere and score — agents acknowledge, follow, or dismiss; the adherence record lands on the call log and rolls up into QA reporting.

​
How playbooks differ from the other guidance layer

Playbooks deliberately overlap with two other surfaces, and the distinction matters:
  • Versus agent-assist whisper coaching (the guide): the copilot generates probabilistic LLM suggestions per turn — useful for open-ended drafting, irreproducible by nature. A playbook card fires deterministically on literal terms, which is what makes the adherence scoring above auditable. They run side by side on the same transcript channel; many teams keep the copilot for drafting and playbooks for the compliance-critical cues (“competitor mention → battle-card”, “refund + cancel → retention checklist”).
  • Versus QA evaluation playbooks (quality-evaluation-lifecycle): QA scorecards judge a call after it ends. Playbook cards intervene during the call. The two meet on the reporting side — live adherence and post-call reviewer scores both feed the supervisor picture — but they never share code paths.