Recipes: Multi-Step AI Workflows

Recipes are declarative YAML specifications that orchestrate multi-step AI agent workflows. Define once, run anywhere, resume anytime.

Quick Example

name: "code-review"
version: "1.0.0"

context:
  file_path: "src/auth.py"

steps:
  - id: "analyze"
    agent: "foundation:zen-architect"
    prompt: "Analyze {{`{file_path}`}}"
    output: "issues"

  - id: "suggest"
    prompt: "Given {{`{issues}`}}, suggest fixes"
    output: "improvements"

Run it:

amplifier run "execute code-review.yaml with file_path=src/auth.py"

When to Use Recipes

Decision rule: If your workflow has 3+ distinct steps that build on each other, use a recipe.

Core Concepts

Sequential Execution

Recipes enforce strict sequential order through a Python for loop. Each step completes before the next begins. This ensures predictable execution and proper context accumulation.

Context Variables

Steps access previous results using {{`{variable}`}} syntax. Context grows as steps complete:

Initial: {file_path: "auth.py"}
After step 1: {file_path: "auth.py", issues: "..."}
After step 2: {file_path: "auth.py", issues: "...", improvements: "..."}

Agent Delegation

Each step spawns a fresh sub-agent with specific capabilities. The agent executes, returns results, and terminates. Next step gets a new agent instance.

Recipes and Bundles

Key insight: Recipes inherit the bundle they're executed with. The bundle determines which agents, tools, and providers are available to recipe steps.

Bundle Determines Available Agents

# Execute with recipes bundle (has foundation agents)
amplifier run --bundle recipes "execute my-recipe.yaml"
# Can use: foundation:zen-architect, foundation:bug-hunter, etc.

# Execute with custom bundle (different agents)
amplifier run --bundle my-custom-bundle "execute my-recipe.yaml"
# Can use: whatever agents your bundle provides

Agent references: Must match what's in the active bundle!

Per-Step Configuration Override

Steps can override providers, tools, and configuration:

steps:
  - id: "creative-step"
    agent: "foundation:zen-architect"
    agent_config:
      providers:
        - module: "provider-anthropic"
          config:
            model: "claude-opus-4"   # Use more capable model
            temperature: 0.9         # More creative
    prompt: "Brainstorm alternatives"

This step uses Opus with high temperature, while other steps use bundle defaults!

Loading Recipes Bundle

Full bundle (tool + agents + context):

amplifier run --bundle git+https://github.com/microsoft/amplifier-bundle-recipes@main

Behavior overlay (add to your bundle):

# In your bundle.md
includes:
  - bundle: foundation
  - bundle: git+https://github.com/microsoft/amplifier-bundle-recipes@main#subdirectory=behaviors/recipes.yaml

Just the tool (minimal):

tools:
  - module: tool-recipes
    source: git+https://github.com/microsoft/amplifier-bundle-recipes@main#subdirectory=modules/tool-recipes

What you get:

• Full bundle: tool-recipes + recipe-author + result-validator + @recipes: namespace
• Behavior: tool-recipes + agents (composable)
• Just tool: Execute recipes only (no creation agents)

Learn More

How to Run Recipes

Via Command Line

# Load recipes bundle and execute
amplifier run --bundle git+https://github.com/microsoft/amplifier-bundle-recipes@main \
  "execute examples/simple-analysis-recipe.yaml with file_path=README.md"

# Or if recipes is in your bundle
amplifier run "execute my-recipe.yaml with input=value"

Programmatically (In Your App)

Recipes are executed through the tool-recipes module like any other tool:

from amplifier_foundation.registry import load_bundle

# Load bundle with tool-recipes
bundle = await load_bundle("./bundle.md")
prepared = await bundle.prepare()
session = await prepared.create_session(session_id="my-session")

# Get recipes tool from coordinator
recipes_tool = session.coordinator.get("tools", "recipes")

# Execute a recipe
result = await recipes_tool.execute({
    "operation": "execute",
    "recipe_path": "code-review.yaml",
    "context": {"file_path": "src/auth.py"}
})

# Get results
final_context = result.output
print(final_context.get("final_report"))

Use cases for programmatic execution:

• Web apps triggering workflows
• Automated pipelines (CI/CD)
• Background job processing
• Custom orchestration systems

Through AI Agents

AI can execute recipes using the recipes tool:

amplifier run "Please run the code-review recipe on src/auth.py"

# AI will:
# 1. Recognize "recipe" intent
# 2. Use recipes tool
# 3. Execute recipe
# 4. Report results