Praison AI

Debug Recipes

Step-by-step guide to debugging and troubleshooting recipes

Run validation and verbose recipe commands when a template fails in production.

python
from praisonaiagents import Agent

agent = Agent(name="Recipe Debugger", instructions="Explain recipe validation errors clearly.")
agent.start("Why did my recipe fail tool resolution?")

The user enables verbose mode, validates the recipe folder, and fixes configuration before re-running.

Diagram

Debug Recipe

📋 Failing Recipe

🔍 Validate & Verbose

✅ Fixed Run

How It Works

Diagram
RecipeCLIUserRecipeCLIUserpraisonai recipe validate ./my-recipeCheck schema and tool resolutionErrors and diagnosticsFixes to apply before re-running

How to Debug Recipe Execution

  1. Enable Verbose Mode
    bash
    praisonai recipe run my-recipe --verbose
  2. Check Recipe Validation
    bash
    praisonai recipe validate ./my-recipe
  3. View Recipe Info
    bash
    praisonai recipe info my-recipe
  4. Check Tool Resolution
    bash
    praisonai tools list

How to Use Recipe Doctor

  1. Run Doctor Command
    bash
    praisonai tools doctor
  2. Review Diagnostics

    The doctor command will show: – Missing tools – Invalid tool references – Configuration issues – Dependency problems

  3. Fix Issues

    Based on doctor output, fix the identified issues in your recipe files.

How to Debug Tool Resolution

When loading a template, PraisonAI now asks the full ToolResolver whether each referenced tool exists — not just the built-in TOOL_MAPPINGS. As of PR #2642, templates that reference tools registered via praisonai_tools, register_function, or entry-point plugins load without spurious “missing / needs install” warnings.

  1. List Available Tools
    bash
    praisonai tools list
  2. Resolve Specific Tool
    bash
    praisonai tools resolve shell_tool

How to Debug with Python

  1. Enable Debug Logging
    python
    import logging
logging.basicConfig(level=logging.DEBUG)

from praisonaiagents import Agent

agent = Agent(
    name="test",
    role="Test Agent",
    output="verbose",
)
  2. Test Agent Execution
    python
    result = agent.start("Test task")
print(result)

Common Issues and Solutions

IssueCauseSolution
Tool not foundTool not availableCheck praisonai tools list
Variable undefinedMissing variablePass with --var key=value
Recipe not foundWrong pathUse full path
Permission deniedFile accessCheck file permissions

Debug CLI Options

bash
praisonai recipe run <recipe> [DEBUG OPTIONS]

Debug Options:
  --verbose              Enable verbose logging

Best Practices

Validate first, then run verbose

praisonai recipe validate catches structural errors cheaply; reach for --verbose only when a valid recipe still misbehaves at run time.

Confirm tools resolve before blaming the recipe

praisonai tools list and praisonai tools resolve <name> show whether a referenced tool is actually available, which is the most common recipe failure.

Reproduce failures with debug logging in Python

Set logging.basicConfig(level=logging.DEBUG) and output="verbose" on the agent to surface the exact step that fails.

Related

Add Tools to Recipes

Fix tool resolution issues

 Manage Recipes

Update and edit recipes