Skip to main content
Placeholders like {topic} are substituted in your YAML strings; literal JSON or dicts in the same string are left alone.

​
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.
Will SubstituteWon’t Substitute
{topic}{"key":"value"}
{user_input}{1,2,3}
{task_name}{}
{model_config}{ spaced }

​
Where It Applies

The brace-safe substitutor processes these YAML fields:
FieldDescriptionExample
roleAgent role definition"Expert in {topic}"
goalAgent objective"Research {topic} thoroughly"
backstoryAgent background"You specialize in {topic}"
descriptionTask description"Analyze {topic} data"
expected_outputExpected result"Report on {topic} findings"
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"}}}
Migration note: Before the latest release, YAML strings with literal {...} could silently leave {topic} unsubstituted. Now they work as expected — no YAML changes required.

​
Best Practices

Stick to {topic} for the main input variable — it’s the standard CLI/API parameter:
roles:
  analyst:
    role: Data analyst for {topic}
    goal: Analyze {topic} comprehensively
    # Clear, consistent naming
No escaping needed for JSON examples in prompts:
roles:
  developer:
    backstory: |
      You write APIs that return {"success": true, "data": [...]} 
      and handle errors like {"error": "not found", "code": 404}.
      Focus on {topic} implementations.
For variables beyond {topic}, use the Python API:
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"
)
Then use {style} and {deadline} in your YAML.

Async Crew Kickoff

Native async execution with template substitution

Agent Configuration

Complete guide to agent YAML structure