Playbook (per-intent responsibilities)

The playbook moves an agent's detailed responsibilities out of the system prompt and serves them on demand, per intent, through a built-in playbook tool. The prompt carries only the intent menu; the model fetches the full instructions for whichever intent the current request actually matches — and it can fetch several in one turn when a request spans more than one.

Use it when an agent has more than one job and each job has real procedure behind it: a front-desk agent that greets, intakes complaints, and gathers requirements; a finance agent that reconciles, disputes, and reports. Stuffing all of that into one prompt makes every turn pay for every job. The playbook makes each turn pay only for the jobs it does.

Declaring a playbook

agents:
  greeter_agent:
    name: "greeter_agent"
    agent_type: llm
    model: gemini-2.5-pro
    prompt: |
      You are the front-desk greeter for a customer-support agency.
      Your detailed responsibilities are NOT written here — load them
      with the playbook tool before responding.
    playbook:
      - intent: greeting
        description: any hello / first contact from a customer
        responsibility: |-
          Greet the customer warmly and by name when they gave one.
          Summarize what they need in one sentence, then ask exactly
          one clarifying question that moves their request forward.
        variables:
          - customer_name
      - intent: complaint_intake
        description: customer is upset or reporting a problem
        responsibility: |-
          Acknowledge the customer's feelings before anything else.
          Collect three facts: what happened, when it happened, and the
          order or account reference. Never promise timelines.

Field	Required	Description
`intent`	yes	Short token naming the job (lowercased). Becomes an enum value on the tool, so the model can never invent one.
`responsibility`	yes	The full, thorough instructions for this intent. This is the text the model receives when it loads the section.
`description`	no	One line describing when to use this intent — it renders in the tool's menu, which is what the model reads to choose.
`variables`	no	Facts the agent must establish before finishing this section (e.g. `customer_name`, `scope`, `deadline`). Appended to the loaded responsibility as a checklist.

How it behaves at runtime

The playbook tool is registered automatically at start-up, scoped to the declaring agent — no other agent can see or call it.
The tool's description is the intent menu: each intent with its when-to-use line and required variables. The model reads the menu and loads the section it needs.
A request that spans intents gets multiple loads in one turn — a "hello, my invoice is double-charged" greets and runs complaint intake.
A wrong intent guess costs one retry, not a dead end: the error names the available intents.
Loaded responsibilities are there to be executed with the agent's tools, not recited — the agent's structured output reports work done, never a description of the procedure.

Pairing rule (important)

The playbook and a prescriptive prompt fight each other. If the prompt still contains the full job description, the model follows the prompt and has no reason to load anything. When an agent has a playbook:

the prompt carries identity and the output contract only ("who you are", "return JSON with these keys");
the playbook carries the how — every procedure, rule, and checklist.

Editing live

Playbook sections are ordinary agent config: edit them in Studio (or PATCH /api/yaml/agents/{name}) and they apply to the agent's next run — re-registration replaces the tool's sections in place. The Playground has the same editor, so you can tune a responsibility and re-run in seconds before committing it.