Building Your First Playbook

tutorial beginner · 12 min · February 14, 2026 · shiftagent team

What is a playbook?

A playbook is a structured file that defines a business process your AI agents can execute. Think of it as a recipe: it specifies the ingredients (inputs), the steps (actions), the decision points (conditionals), and what “done” looks like (success criteria).

Playbooks are stored as YAML files in your tenant’s git repository, under the playbooks/ directory. Because they live in git, they have version history, can be reviewed through pull requests, and can be rolled back instantly if something goes wrong.

Playbook anatomy

Every playbook has four sections:

Metadata

name: merchant-onboarding
version: 1.0.0
vertical: payments
risk_level: low
description: "Complete merchant onboarding workflow"

The metadata identifies the playbook and sets its operational parameters. The risk_level determines the default approval requirements — low runs autonomously, medium may require approval, high always requires human sign-off.

Triggers

trigger:
  event: merchant_application_submitted
  conditions:
    - application_status: "pending"
    - business_type: { in: ["llc", "corporation", "sole_proprietor"] }

Triggers define when the playbook starts. They can be event-based (responding to system events) or scheduled (running on a cron schedule). Conditions filter which events activate the playbook.

Steps

steps:
  - id: verify_business
    action: lookup_business_registry
    inputs:
      ein: "{{ trigger.business_ein }}"
      state: "{{ trigger.business_state }}"
    outputs:
      - registry_result
    on_failure:
      action: escalate
      message: "Business verification failed for {{ trigger.business_name }}"

  - id: run_risk_check
    action: assess_merchant_risk
    inputs:
      business_data: "{{ verify_business.registry_result }}"
      application: "{{ trigger.application }}"
    outputs:
      - risk_score
      - risk_factors

Steps are the core of the playbook. Each step has:

  • id — unique identifier for referencing in other steps
  • action — the tool or skill the agent uses
  • inputs — data passed to the action, using {{ }} template syntax to reference previous step outputs or trigger data
  • outputs — named values produced by the step, available to subsequent steps
  • on_failure — what to do if the step fails (escalate, retry, skip, or abort)

Decision points

  - id: route_application
    type: decision
    condition: "{{ run_risk_check.risk_score }}"
    branches:
      - when: { lte: 30 }
        goto: auto_approve
      - when: { between: [31, 70] }
        goto: manual_review
      - when: { gte: 71 }
        goto: decline_application

Decision points create conditional branches in the workflow. The agent evaluates the condition and follows the matching branch. This is how playbooks handle different scenarios without separate playbooks for each case.

Your first playbook

Let’s build a simple playbook that handles incoming support emails:

name: support-email-triage
version: 1.0.0
risk_level: low

trigger:
  event: email_received
  conditions:
    - to: "support@*"

steps:
  - id: classify
    action: classify_email
    inputs:
      subject: "{{ trigger.email_subject }}"
      body: "{{ trigger.email_body }}"
      sender: "{{ trigger.sender_email }}"
    outputs:
      - category
      - urgency
      - suggested_response

  - id: route
    type: decision
    condition: "{{ classify.urgency }}"
    branches:
      - when: "critical"
        goto: escalate_immediately
      - when: "high"
        goto: draft_and_review
      - otherwise:
        goto: auto_respond

  - id: auto_respond
    action: send_email
    inputs:
      to: "{{ trigger.sender_email }}"
      subject: "Re: {{ trigger.email_subject }}"
      body: "{{ classify.suggested_response }}"

  - id: draft_and_review
    action: draft_email
    inputs:
      to: "{{ trigger.sender_email }}"
      body: "{{ classify.suggested_response }}"
    approval_required: true

  - id: escalate_immediately
    action: create_urgent_task
    inputs:
      title: "URGENT: {{ trigger.email_subject }}"
      description: "{{ trigger.email_body }}"
      assignee: "on-call"

Deploying your playbook

  1. Save the YAML file in your tenant’s playbooks/ directory
  2. Commit and push to your tenant branch
  3. The agent automatically picks up the new playbook on its next execution cycle
  4. Test by triggering the event (send a test email, submit a test application, etc.)

Best practices

  • Start simple. Your first playbook should have 3-5 steps. Add complexity as you learn what the agent handles well.
  • Use decision points for risk. Low-risk actions can be autonomous. High-risk actions should require approval. Let the playbook’s structure reflect this.
  • Version deliberately. Increment the version number with every meaningful change. The version appears in audit logs and helps debug issues.
  • Test in staging. Every tenant has a staging branch. Deploy playbook changes there first, trigger them manually, and verify the results before promoting to production.
  • Let the agent improve. When an agent encounters an edge case, it can propose a playbook improvement as a git commit. Review these proposals — they often capture operational knowledge that would otherwise be lost.
playbooksyamlgitautomationtutorial