AI Playbooks

AI Playbooks are versioned, reusable configurations that define how your AI assistant behaves. Think of them as "templates" for AI behavior that you can create, refine, and track over time.

What are AI Playbooks?

A Playbook is a complete set of instructions that defines:

• Identity & Personality: Who your AI is and how it presents itself
• Tone & Style: How formal or casual, how empathetic, how detailed
• Goals & Priorities: What the AI should focus on
• Constraints: What the AI should never do or mention
• Safety Rules: When to escalate, how to handle sensitive topics
• Tool Permissions: Which tools the AI can use
• Model Settings: Which AI model to use and how to configure it

Playbooks are versioned, meaning every change creates a new version while keeping the old ones for reference. This lets you:

• Track what changed and when
• Roll back to previous versions if needed
• Compare how different versions perform
• Maintain an audit trail of AI behavior changes

Why Use Playbooks?

Consistency Across Assistants

Create a "Sales Playbook" and apply it to multiple assistants. When you update the playbook, all assistants using it automatically get the improvements.

Version Control

Every playbook change creates a new version. You can see:

• What changed between versions
• Who made the change
• When it was changed
• How it performed

A/B Testing

Test different playbook versions to see which performs better, then activate the winner.

Compliance & Auditing

Maintain a complete history of AI behavior changes for compliance and auditing purposes.

Creating a Playbook

1. Go to AI Playbooks in the navigation

2. Click Create Playbook

3. Fill in the playbook details:

   • Name: A descriptive name (e.g., "Sales Intake", "Customer Support")
   • Identity: Base prompt, persona, and display name
   • Tone: Formality level, empathy level, verbosity
   • Goals: Primary and secondary objectives
   • Constraints: What to never mention or do
   • Safety: Escalation triggers and PII handling
   • Tools: Which tools the AI can use
   • Model: AI model and settings

4. Click Save Draft to create a draft version, or Publish to create and activate it immediately

Playbook Versions

Every playbook has versions. When you make changes:

1. Edit the playbook
2. Save Draft to create a new draft version, or Publish to create and activate a new published version
3. The system tracks:
   • Version number (v1, v2, v3, etc.)
   • What changed
   • Who made the change
   • When it was created
   • Which model and code version was used

Viewing Version History

Click on a playbook to see:

• All versions (draft and published)
• What changed in each version
• When each version was created
• Which version is currently active

Activating a Version

To switch to a different version:

1. Open the playbook
2. Go to Versions
3. Find the version you want
4. Click Activate

The active version is used by all assistants that have this playbook assigned.

Assigning Playbooks to Assistants

1. Go to Assistants
2. Edit an assistant
3. In the Playbook dropdown, select a playbook
4. Save

The assistant will now use the playbook's active version for all conversations.

Version Tracking

Every playbook version includes metadata that helps you track:

• Model: Which AI model was used (e.g., "gpt-4o-mini")
• Provider: Which provider (e.g., "openai")
• Playbook Version: The version string (e.g., "sales_intake_v3")
• Prompt Version: The prompt/schema version (e.g., "playbook.compile.v1.0")
• Code Version: The code version when created (e.g., "git:8f3c9c2")
• Generated At: When the version was created

This metadata helps you:

• Reproduce results from specific versions
• Debug issues by knowing exactly what code/model was used
• Track performance changes across versions
• Maintain compliance records

Best Practices

Naming Playbooks

Use clear, descriptive names:

• ✅ "Sales Intake Playbook"
• ✅ "Customer Support - Technical"
• ❌ "Playbook 1"
• ❌ "Test"

Version Management

• Draft versions are for testing and refinement
• Published versions are for production use
• Keep draft versions until you're confident they work
• Use descriptive changelog notes when publishing

Testing Changes

1. Create a draft version with your changes
2. Test it with a few conversations
3. Compare performance to the current version
4. If better, publish and activate it

Rollback Strategy

If a new version causes issues:

1. Go to the playbook's version history
2. Find the last working version
3. Click Activate to roll back

Troubleshooting

Playbook Not Taking Effect

• Ensure the playbook is activated (not just saved as draft)
• Check that the assistant has the playbook assigned
• Verify the assistant is being used (check routing rules)

Version Confusion

• The active version is shown in the playbook list
• Check the version history to see all versions
• Draft versions are not used until published and activated

Changes Not Reflecting

• Playbook changes only affect new conversations
• Existing conversations continue using the version that was active when they started
• Clear your browser cache if the UI seems stale

Related Documentation

• Assistants Overview - Learn about assistants
• Assistant Configuration - Configure assistant settings
• Conversation Intelligence - Analyze playbook performance