Playbooks

Playbooks are reusable instructions that are automatically included in all prompt and tool nodes of your agent. They help maintain consistency and reduce repetition across your agent's behavior.

Overview

Playbooks are defined using EditorJS blocks format and support:

• EditorJS blocks for rich content structure

• EJS templating for dynamic content

• Placeholders for runtime values

• Multiple files for better organization

• Platform integration for web-based editing

Configuration

Add the playbooks directory to your minded.json:

{
  "playbooks": ["./src/playbooks"]
}

Creating Playbooks

Create YAML files in your playbooks directory using the EditorJS blocks structure:

# src/playbooks/general.yaml
id: general-playbooks
name: General Customer Service
blocks:
  - type: header
    data:
      text: Customer Service Guidelines
      level: 2
  - type: paragraph
    data:
      text: 'You are a helpful customer service agent for {memory.companyName}.'
  - type: paragraph
    data:
      text: 'Always be polite and professional in your responses.'
  - type: paragraph
    data:
      text: 'Current time: {system.currentTime}'
  - type: paragraph
    data:
      text: 'User location: {memory.userLocation}'

Block Types

Playbooks support various EditorJS block types:

Header Block

- type: header
  data:
    text: 'Section Title'
    level: 2 # 1-6 for h1-h6

Paragraph Block

- type: paragraph
  data:
    text: 'Your paragraph content here'

List Block

- type: list
  data:
    style: unordered # or "ordered"
    items:
      - 'First item'
      - 'Second item'
      - 'Third item'

Quote Block

- type: quote
  data:
    text: 'Important note or quote'
    caption: 'Optional caption'

Code Block

- type: code
  data:
    code: |
      function example() {
        return "code example";
      }

Delimiter Block

- type: delimiter
  data: {}

Using Templates

EJS Templates

Use EJS syntax (<%= %>) for dynamic content evaluated at compile time:

- type: paragraph
  data:
    text: 'Today is <%= new Date().toDateString() %>'
- type: paragraph
  data:
    text: 'Environment: <%= process.env.NODE_ENV %>'

Placeholders

Use placeholders for runtime values from the agent's state:

Memory placeholders ({memory.key}):

- type: paragraph
  data:
    text: 'Hello {memory.customerName},'
- type: paragraph
  data:
    text: 'Your order {memory.orderId} is being processed.'

System placeholders ({system.key}):

- type: paragraph
  data:
    text: 'Current time: {system.currentTime}' # Returns new Date().toISOString()

These placeholders are automatically replaced with values from the agent's memory and system context when the playbooks are compiled.

Using Memory Values in Playbooks

Placeholders in playbooks are replaced with values from the agent's memory state:

const updateCustomerTool: Tool<typeof inputSchema, any> = {
  name: 'updateCustomer',
  description: 'Update customer information',
  input: inputSchema,
  isGlobal: true,
  execute: async ({ input, state }) => {
    return {
      memory: {
        memory: state.memory,
        customer: input,
        customerName: input.name,
        userLocation: input.location,
      },
    };
  },
};

Nested Values

Placeholders support nested object access from the memory state:

- type: paragraph
  data:
    text: 'Customer: {memory.customer.name}'
- type: paragraph
  data:
    text: 'Email: {memory.customer.email}'
- type: paragraph
  data:
    text: 'Order status: {memory.order.status}'

These values are resolved from nested properties in the agent's memory, for example: memory.customer.name.

Complete Example

# src/playbooks/customer-service.yaml
id: customer-service-guidelines
name: Customer Service Guidelines
blocks:
  - type: header
    data:
      text: Customer Service Best Practices
      level: 1
  - type: paragraph
    data:
      text: 'You are representing {companyName} as a professional customer service agent.'
  - type: list
    data:
      style: unordered
      items:
        - 'Always greet customers warmly'
        - 'Listen actively to their concerns'
        - 'Provide clear and helpful solutions'
        - 'Follow up to ensure satisfaction'
  - type: quote
    data:
      text: "The customer's experience is our top priority"
      caption: 'Company motto'
  - type: paragraph
    data:
      text: 'Current session started: <%= new Date().toISOString() %>'

Best Practices

1. Organize by purpose: Create separate files for different aspects (general, domain-specific, compliance, etc.)

2. Use meaningful IDs: Each playbook must have a unique ID

3. Structure content logically: Use headers, lists, and quotes to organize information

4. Keep blocks focused: Each block should contain a single concept or instruction

5. Document placeholders: Comment which parameters your playbooks expect

6. Test thoroughly: Verify that all placeholders are being populated correctly

Example Structure

src/playbooks/
├── general.yaml          # General behavior guidelines
├── compliance.yaml       # Regulatory compliance rules
├── brand-voice.yaml      # Brand-specific communication style
└── domain-specific.yaml  # Domain-specific instructions

Platform Integration

When using the Minded platform:

1. Playbooks are editable through the web interface using a rich text editor

2. Changes are synchronized with your Git repository

3. The platform uses the same EditorJS blocks format

4. Local YAML files are automatically converted to the blocks format

5. All templating features work the same in both local and platform environments

Migration from Content Format

If you have existing playbooks using the old content format, convert them to blocks:

Old format:

content: |
  # Customer Service
  Always be polite and professional.
  Current time: <%= new Date().toISOString() %>

New format:

blocks:
  - type: header
    data:
      text: Customer Service
      level: 1
  - type: paragraph
    data:
      text: Always be polite and professional.
  - type: paragraph
    data:
      text: 'Current time: <%= new Date().toISOString() %>'