Modular Recipes

Compose recipes from reusable components with the include pattern

Modular Recipe Composition

Build complex workflows by composing smaller, reusable recipes together. The include: pattern enables DRY (Don’t Repeat Yourself) recipe development.

If you publish a recipe that needs custom tools, prefer declaring them under the tools_sources: / override_files: directives in TEMPLATE.yaml — those load without requiring users to set PRAISONAI_ALLOW_TEMPLATE_TOOLS. Implicit tools.py loading is disabled by default for security (GHSA-xcmw-grxf-wjhj). See Security Environment Variables for details.

Overview

Instead of duplicating common functionality across recipes, extract it into a standalone recipe and include it where needed:

# Main recipe includes the reusable publisher
roles:
  content_writer:
    role: Content Writer
    goal: Write articles
    # ... writer configuration

includes:
  - wordpress-publisher  # Reuse the publisher recipe

Usage Patterns

1. Include in Steps Format

For workflows using the steps: format:

name: Content Pipeline
steps:
  - agent: content_writer
    action: "Write article about {{topic}}"
  
  - include: wordpress-publisher
    input: "{{previous_output}}"

2. Include in Roles Format

For recipes using the roles: format (agents.yaml style), use the includes: section:

framework: praisonai
topic: "AI News"

roles:
  topic_gatherer:
    role: Topic Researcher
    goal: Find news topics
    tasks:
      find_topics:
        description: Search for AI news

  content_writer:
    role: Content Writer
    goal: Write articles
    tasks:
      write:
        description: Write about {{previous_output}}

# Include another recipe as the final step
includes:
  - wordpress-publisher

3. Include with Configuration

Pass custom input to included recipes:

includes:
  - recipe: wordpress-publisher
    input: "{{previous_output}}"

Python API

Include Class

from praisonaiagents import AgentFlow, Include, include

# Using convenience function
workflow = AgentFlow(
    name="Content Pipeline",
    steps=[
        content_writer_agent,
        include("wordpress-publisher", input="{{previous_output}}")
    ]
)
result = workflow.run("Write about AI")

Direct Class Usage

from praisonaiagents.workflows import Include

step = Include(
    recipe="wordpress-publisher",
    input="Custom input here"
)

call_recipe Tool

Give agents the ability to call other recipes as a tool:

from agent_recipes import call_recipe
from praisonaiagents import Agent

# Create an orchestrator agent with recipe-calling ability
orchestrator = Agent(
    name="Orchestrator",
    instructions="Coordinate content publishing workflows",
    tools=[call_recipe]
)

# The agent can now invoke:
# call_recipe("wordpress-publisher", "ARTICLE_TITLE: Test\nARTICLE_CONTENT: ...")

run_recipe Function

Programmatically execute recipes:

from agent_recipes import run_recipe

result = run_recipe(
    recipe_name="wordpress-publisher",
    input_data="ARTICLE_TITLE: My Title\nARTICLE_CONTENT: ...",
    output="status"  # Options: silent, status, trace, verbose, debug, json
)
print(result['output'])

Creating Reusable Recipes

Recipe Structure

wordpress-publisher/
├── TEMPLATE.yaml     # Recipe metadata
├── agents.yaml       # Workflow definition
├── tools.py          # Custom tools
└── README.md         # Documentation

Example: wordpress-publisher

agents.yaml:

framework: praisonai
topic: "Publish article to WordPress"

roles:
  publisher:
    role: WordPress Publisher
    goal: Validate and publish blog post
    tools:
      - create_wp_post
    tasks:
      validate_and_publish:
        description: |
          {{previous_output}}
          
          Extract ARTICLE_TITLE and ARTICLE_CONTENT:
          - Call create_wp_post with the extracted values
          - Report the published post ID
        expected_output: |
          Published post with ID and confirmation

Cycle Detection

The include system automatically detects circular includes:

# recipe-a includes recipe-b
# recipe-b includes recipe-a
# → Error: "Circular include detected"

Best Practices

1. Single Responsibility: Each recipe should do one thing well
2. Clear Contracts: Document expected input/output formats
3. Defensive Parsing: Handle missing or malformed input gracefully
4. Idempotent Operations: Avoid side effects on retries

Available Recipes

List all available recipes:

praisonai templates list

Key reusable recipes:

• wordpress-publisher - Publish content to WordPress
• transcript-generator - Generate transcripts from media
• data-transformer - Transform data between formats

Related

• Workflows - Workflow fundamentals
• YAML Workflows - YAML workflow syntax
• Recipe Registry - Browse available recipes