> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Recipe Create

> Create AI agent recipes from natural language goals

Create complete agent recipes automatically from a simple goal description.

<Info>
  The AI analyzes your goal and generates optimized agents, tools, and workflows.
</Info>

## Quick Start

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai recipe create "Build a web scraper for news articles"
```

This creates a ready-to-run recipe folder with just **2 files**:

<CardGroup cols={2}>
  <Card title="agents.yaml" icon="robot">
    Agent definitions, workflow steps, and optional metadata
  </Card>

  <Card title="tools.py" icon="wrench">
    Custom functions and dynamic variables
  </Card>
</CardGroup>

<Tip>
  The simplified 2-file structure reduces complexity. Metadata for registry publishing is now an optional block inside `agents.yaml`.
</Tip>

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
flowchart TD
    A["🎯 Your Goal"] --> B["🧠 AI Analysis"]
    B --> C["📝 Generate agents.yaml"]
    B --> D["🔧 Create tools.py"]
    C --> E["📁 Recipe Folder"]
    D --> E
    E --> F["🔄 Optimization Loop"]
    F --> G{"Score >= 8?"}
    G -->|No| H["💡 Apply Improvements"]
    H --> F
    G -->|Yes| I["✅ Ready to Use"]
    
    style A fill:#8B0000,color:#fff
    style B fill:#189AB4,color:#fff
    style C fill:#8B0000,color:#fff
    style D fill:#189AB4,color:#fff
    style E fill:#8B0000,color:#fff
    style F fill:#189AB4,color:#fff
    style G fill:#8B0000,color:#fff
    style H fill:#189AB4,color:#fff
    style I fill:#189AB4,color:#fff
```

## Options

| Option          | Short | Description                      | Default           |
| --------------- | ----- | -------------------------------- | ----------------- |
| `--output`      | `-o`  | Output directory                 | Current directory |
| `--no-optimize` |       | Skip optimization loop           | `false`           |
| `--iterations`  |       | Max optimization iterations      | `3`               |
| `--threshold`   |       | Score threshold to stop          | `8.0`             |
| `--agents`      |       | Custom agent definitions         | Auto-generated    |
| `--tools`       |       | Custom tools per agent           | Auto-selected     |
| `--agent-types` |       | Agent types (image, audio, etc.) | Auto-detected     |

## Examples

<Tabs>
  <Tab title="Basic">
    Create a simple recipe:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai recipe create "Summarize PDF documents"
    ```
  </Tab>

  <Tab title="Research">
    Create a research agent:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai recipe create "Research latest AI papers and create a summary report"
    ```
  </Tab>

  <Tab title="Data Processing">
    Create a data pipeline:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai recipe create "Analyze CSV sales data and generate insights"
    ```
  </Tab>

  <Tab title="Web Tasks">
    Create a web automation recipe:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai recipe create "Scrape product prices from e-commerce sites"
    ```
  </Tab>
</Tabs>

## Custom Agents and Tools

Define your own agents instead of letting AI decide:

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
flowchart LR
    A["🎯 Your Goal"] --> B{"Customization?"}
    B -->|No| C["🤖 AI Generates"]
    B -->|Yes| D["📋 Your Agents"]
    C --> E["📁 Recipe"]
    D --> E
    
    style A fill:#8B0000,color:#fff
    style B fill:#189AB4,color:#fff
    style C fill:#8B0000,color:#fff
    style D fill:#189AB4,color:#fff
    style E fill:#8B0000,color:#fff
```

<Tabs>
  <Tab title="Custom Agents">
    Define agents with roles and goals:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai recipe create "Research AI" \
      --agents "researcher:role=AI Researcher,goal=Find papers;writer:role=Writer,goal=Summarize" \
      --no-optimize
    ```
  </Tab>

  <Tab title="Custom Tools">
    Assign specific tools to agents:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai recipe create "Research AI" \
      --tools "researcher:internet_search,arxiv;writer:write_file" \
      --no-optimize
    ```
  </Tab>

  <Tab title="Agent Types">
    Use specialized agent types:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai recipe create "Generate images" \
      --agents "artist:role=Image Creator,goal=Create product images" \
      --agent-types "artist:image" \
      --no-optimize
    ```
  </Tab>

  <Tab title="Combined">
    Full customization:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai recipe create "Research and visualize" \
      --agents "researcher:role=Researcher;artist:role=Visualizer" \
      --tools "researcher:internet_search;artist:write_file" \
      --agent-types "artist:image" \
      --no-optimize
    ```
  </Tab>
</Tabs>

### Format Reference

<AccordionGroup>
  <Accordion title="--agents format" icon="robot">
    ```
    name:role=X,goal=Y,backstory=Z;name2:role=A,goal=B
    ```

    * Separate agents with `;`
    * Separate properties with `,`
    * Use `=` for key-value pairs
  </Accordion>

  <Accordion title="--tools format" icon="wrench">
    ```
    agent:tool1,tool2;agent2:tool3,tool4
    ```

    * Separate agents with `;`
    * Separate tools with `,`
  </Accordion>

  <Accordion title="--agent-types format" icon="tag">
    ```
    agent:image;agent2:audio
    ```

    Available types: `image`, `audio`, `video`, `deep_research`, `ocr`, `router`
  </Accordion>
</AccordionGroup>

***

## Skip Optimization

For quick prototyping, skip the optimization loop:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai recipe create "Simple calculator" --no-optimize
```

## Custom Optimization

Fine-tune the optimization process:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai recipe create "Complex research task" \
  --iterations 5 \
  --threshold 9.0
```

<Tip>
  Higher threshold (9-10) produces better quality but takes longer.
  Lower threshold (6-7) is faster but may need manual refinement.
</Tip>

## Specialized Agent Types

The AI automatically selects the right agent type based on your goal:

<AccordionGroup>
  <Accordion title="ImageAgent" icon="image">
    For image generation tasks (DALL-E, Stable Diffusion)

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai recipe create "Generate product images for store"
    ```
  </Accordion>

  <Accordion title="AudioAgent" icon="microphone">
    For text-to-speech and speech-to-text

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai recipe create "Create podcast narration"
    ```
  </Accordion>

  <Accordion title="VideoAgent" icon="video">
    For video generation (Sora, Runway)

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai recipe create "Create promotional video"
    ```
  </Accordion>

  <Accordion title="DeepResearchAgent" icon="magnifying-glass">
    For comprehensive research tasks

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai recipe create "Research market trends"
    ```
  </Accordion>

  <Accordion title="OCRAgent" icon="file-lines">
    For text extraction from images/documents

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai recipe create "Extract text from receipts"
    ```
  </Accordion>
</AccordionGroup>

## Quality Rules

The AI follows strict quality rules when generating recipes:

<AccordionGroup>
  <Accordion title="Environment Variables" icon="key">
    Only includes env vars that are **actually used**:

    * `OPENAI_API_KEY` - Always required (for LLM)
    * `TAVILY_API_KEY` - Only if using `tavily_search` or `tavily_extract`

    <Warning>
      Tools like `wiki_search`, `internet_search`, `read_file` do NOT need `TAVILY_API_KEY`
    </Warning>
  </Accordion>

  <Accordion title="Concrete Values in Actions" icon="bullseye">
    Actions use **concrete values**, not variables:

    ✅ **Good**: `"Use wiki_search to find information about Python programming"`

    ❌ **Bad**: `"Use wiki_search to find {{topic}}"` (variables don't substitute!)
  </Accordion>

  <Accordion title="Reliable Tools" icon="check">
    Prefers reliable, well-tested tools:

    **Recommended**: `wiki_search`, `tavily_search`, `internet_search`, `read_file`, `write_file`

    <Warning>
      Avoid `scrape_page`, `crawl4ai` - may have loading issues
    </Warning>
  </Accordion>

  <Accordion title="Specific Actions" icon="wand-magic-sparkles">
    Every action specifies which tool to use:

    ✅ **Good**: `"Use tavily_search to find the top 5 AI trends in 2024"`

    ❌ **Bad**: `"Research AI trends"` (too vague)
  </Accordion>

  <Accordion title="No Empty Fields" icon="trash">
    Omits unused fields entirely:

    * No `knowledge: []`
    * No `memory: false`
    * No `handoffs: []`
  </Accordion>
</AccordionGroup>

## Verified Quality Scores

Recipes generated with these rules achieve **high judge scores**:

| Task Type          | Tool Used               | Judge Score   |
| ------------------ | ----------------------- | ------------- |
| Wikipedia Research | `wiki_search`           | **9.83/10** ✅ |
| AI Trends Research | `tavily_search`         | **7.25/10** ✅ |
| Data Analysis      | `read_csv`, `write_csv` | **8.0+/10** ✅ |

<Tip>
  For best results, use `wiki_search` for factual research and `tavily_search` for current events.
</Tip>

## Output Structure

After creation, your recipe folder contains just **2 files**:

```
my-recipe/
├── agents.yaml      # Agent definitions + optional metadata
└── tools.py         # Custom functions and dynamic variables
```

### agents.yaml Example

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Optional: Metadata for registry/sharing
metadata:
  name: web-scraper
  version: "1.0.0"
  description: Scrape news articles from websites
  author: your-name
  license: Apache-2.0
  tags:
    - web
    - scraping
  requires:
    env:
      - OPENAI_API_KEY

framework: praisonai
topic: "Web Scraper for News"

agents:
  scraper:
    role: Web Scraper
    goal: Extract news articles from websites
    backstory: |
      Expert at web scraping with years of experience
      extracting structured data from websites.
    tools:
      - scrape_page
      - extract_links
      - my_custom_tool  # Defined in tools.py

steps:
  - agent: scraper
    action: "Scrape news from {{url}}"
    expected_output: "List of article titles and summaries"
```

### tools.py Example

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
"""Custom tools for this recipe."""

def my_custom_tool(url: str) -> str:
    """A custom tool for processing URLs."""
    return f"Processed: {url}"

# Dynamic variables
DEFAULT_URL = "https://news.example.com"
```

<Note>
  The `metadata` block is **optional**. It's only needed if you want to publish your recipe to the registry.
</Note>

## Run Your Recipe

After creation, run your recipe:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai recipe run my-recipe
```

Or with input:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai recipe run my-recipe --input '{"url": "https://news.example.com"}'
```

## Testing Your Recipe

After creating a recipe, test it with the workflow command:

<Steps>
  <Step title="Run with trace">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    cd my-recipe
    praisonai workflow run agents.yaml --save
    ```
  </Step>

  <Step title="Judge the run">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai recipe judge <trace-id> --context
    ```
  </Step>

  <Step title="Review scores">
    The judge evaluates:

    * **Task Achievement**: Did agents complete their goals?
    * **Context Flow**: Did information pass between agents?
    * **Output Quality**: Was the output useful?
  </Step>
</Steps>

<Tip>
  Use `--save` to capture traces, then `recipe judge` to get AI feedback on your recipe's performance.
</Tip>

## Next Steps

<CardGroup cols={2}>
  <Card title="Optimize Recipe" icon="chart-line" href="/docs/cli/recipe-optimize">
    Further improve your recipe with AI feedback
  </Card>

  <Card title="Recipe Registry" icon="database" href="/docs/cli/recipe-registry">
    Share and discover recipes
  </Card>
</CardGroup>