YAML Template Variables

Use {topic} and other placeholders safely in YAML — even alongside JSON or dict literals

from praisonaiagents import Agent

agent = Agent(name="writer", instructions="Write about {topic} in {style} style.")
agent.start("Write a blog post", topic="AI agents", style="casual")

The user passes runtime values; {topic} and similar placeholders expand in YAML strings while JSON literals stay intact.

graph LR
    subgraph "Brace-Safe Template System"
        A[📄 YAML String] --> B[🔍 Brace-safe substitutor]
        B --> C[✅ Final Prompt]
    end

    subgraph "Processing"
        D["{topic}"] --> E["replaced with input"]
        F["{\"key\":\"value\"}"] --> G["preserved as-is"]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff
    classDef preserve fill:#189AB4,stroke:#7C90A0,color:#fff

    class A input
    class B process
    class C output
    class D,F input
    class E preserve
    class G preserve

Quick Start

1. Basic Template Substitution

   Create an agents.yaml with a simple {topic} placeholder:

   roles:
     writer:
       role: Content writer for {topic}
       goal: Create engaging content about {topic}
       backstory: You are an expert writer specializing in {topic}.
   
       tasks:
         write_article:
           description: Write about {topic}
           expected_output: A comprehensive article about {topic}

   Run with: praisonai "AI agents"

2. JSON Literals + Variables Together

   Mix JSON examples in backstory with {topic} placeholders safely:

   roles:
     writer:
       role: Technical writer for {topic}
       backstory: |
         You write WordPress posts about {topic}. Use blocks like
         <!-- wp:heading {"level":2} --> and return JSON like
         {"status":"ok"} when asked. Focus on {topic} exclusively.
       goal: Produce an article about {topic}.
   
       tasks:
         technical_post:
           description: Write a technical post about {topic} with code examples
           expected_output: |
             Markdown post about {topic} including:
             - Code blocks with {"config": "examples"}
             - JSON snippets like {"result": true}
             - Clear focus on {topic}

   Both {topic} and the JSON literals work correctly.

How It Works

The template system uses a precise regex pattern to identify which braces to substitute:

Pattern: \{([a-zA-Z_][a-zA-Z0-9_]*)\} — only Python-identifier-shaped placeholders are touched.

Where It Applies

The brace-safe substitutor processes these YAML fields:

Available variables:

• {topic} — main input from CLI or Python API
• Any other keys passed via kwargs in the Python API

Common Patterns

WordPress/Gutenberg Blocks

roles:
  content_creator:
    backstory: |
      You create WordPress content about {topic}. Use Gutenberg blocks:
      <!-- wp:heading {"level":2} -->
      <!-- wp:paragraph -->
      Return structured data like {"publish": true, "category": "tech"}.

API Response Examples

roles:
  api_designer:
    goal: Design APIs for {topic}
    backstory: |
      You design REST APIs about {topic}. Example responses:
      {"data": [...], "status": "success", "topic": "{topic}"}
      Always focus on {topic}-related endpoints.

Configuration Snippets

roles:
  devops:
    role: DevOps engineer for {topic}
    tasks:
      deploy_config:
        description: |
          Create deployment config for {topic} service.
          Use JSON like {"env": "prod", "replicas": 3}.
        expected_output: |
          YAML deployment manifest for {topic} with:
          {"resources": {"limits": {"cpu": "500m"}}}

Best Practices

roles:
  analyst:
    role: Data analyst for {topic}
    goal: Analyze {topic} comprehensively
    # Clear, consistent naming

roles:
  developer:
    backstory: |
      You write APIs that return {"success": true, "data": [...]} 
      and handle errors like {"error": "not found", "code": 404}.
      Focus on {topic} implementations.

from praisonai import PraisonAI

# Custom variables in addition to {topic}
ai = PraisonAI(agent_file="agents.yaml")
result = ai.run(
    topic="machine learning",
    style="academic",
    deadline="next week"
)

Related