Skip to main content

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.

​
Personas

This guide describes the three primary personas who work with PraisonAI recipes, their responsibilities, and recommended workflows.

​
Persona 1: App Developer (Backend/Fullstack)

​
Role Description

Backend or fullstack developers who integrate AI capabilities into applications. They consume recipes created by others and focus on reliable integration.

​
Primary Goals

  • Integrate AI features quickly
  • Ensure reliability and error handling
  • Minimize infrastructure complexity
  • Meet performance requirements
  1. Model 1 (Embedded SDK) - For Python applications
  2. Model 3 (HTTP Sidecar) - For polyglot microservices
  3. Model 2 (CLI) - For scripts and automation

​
Typical Workflow

1

Discover Available Recipes

# List all recipes
praisonai recipe list

# Get recipe details
praisonai recipe info support-reply-drafter
2

Test Recipe Locally

# Dry run to validate
praisonai recipe run support-reply-drafter \
  --input '{"ticket_id": "T-123", "message": "Test"}' \
  --dry-run

# Full test run
praisonai recipe run support-reply-drafter \
  --input '{"ticket_id": "T-123", "message": "Test"}' \
  --json
3

Integrate into Application

from praisonai import recipe

def handle_support_ticket(ticket):
    result = recipe.run(
        "support-reply-drafter",
        input={
            "ticket_id": ticket.id,
            "message": ticket.customer_message
        },
        options={"timeout_sec": 30}
    )
    
    if result.ok:
        return result.output["draft"]
    else:
        logger.error(f"Recipe failed: {result.error}")
        return None
4

Add Error Handling

from praisonai.recipe import RecipeError, RecipeTimeoutError

try:
    result = recipe.run("my-recipe", input=data)
except RecipeTimeoutError:
    # Handle timeout
    return fallback_response()
except RecipeError as e:
    # Handle other errors
    logger.error(f"Recipe error: {e}")
    raise

​
Key Concerns

  • Latency: Monitor recipe execution time
  • Error handling: Graceful degradation when recipes fail
  • Observability: Logging, metrics, tracing
  • Testing: Mock recipes in unit tests

​
Persona 2: Platform/DevOps Engineer

​
Role Description

Engineers responsible for deploying, scaling, and operating recipe infrastructure. They manage servers, authentication, monitoring, and security.

​
Primary Goals

  • Reliable recipe server deployment
  • Secure multi-tenant access
  • Monitoring and alerting
  • Cost optimization
  1. Model 4 (Remote Runner) - Production deployments
  2. Model 5 (Event-Driven) - High-scale async processing

​
Typical Workflow

1

Configure Server

# serve.yaml (or agents.yaml)
host: 0.0.0.0
port: 8765
auth: api-key
api_key: ${PRAISONAI_API_KEY}

# Recipe filtering
recipes:
  - support-reply-drafter
  - meeting-action-items

# Performance
preload: true

# CORS for web clients
cors_origins: "https://app.example.com"
2

Deploy with Docker

FROM python:3.11-slim
RUN pip install praisonai[serve]
COPY serve.yaml /app/
WORKDIR /app
ENV PRAISONAI_API_KEY=${PRAISONAI_API_KEY}
ENV OPENAI_API_KEY=${OPENAI_API_KEY}
EXPOSE 8765
CMD ["praisonai", "recipe", "serve", "--config", "serve.yaml"]
3

Set Up Monitoring

# Health check endpoint
curl http://localhost:8765/health

# Prometheus metrics (if enabled)
curl http://localhost:8765/metrics
4

Configure Load Balancer

upstream recipe_servers {
    server recipe1:8765;
    server recipe2:8765;
    server recipe3:8765;
}

server {
    listen 443 ssl;
    location /v1/recipes {
        proxy_pass http://recipe_servers;
    }
}
5

Set Up Alerts

# alertmanager rules
groups:
  - name: recipe-server
    rules:
      - alert: RecipeServerDown
        expr: up{job="recipe-server"} == 0
        for: 1m
      - alert: HighLatency
        expr: recipe_request_duration_seconds > 10
        for: 5m

​
Key Concerns

  • Security: API key rotation, TLS, network policies
  • Scaling: Horizontal scaling, load balancing
  • Availability: Health checks, failover
  • Cost: Resource utilization, API costs

​
Persona 3: Recipe Author / Solutions Engineer

​
Role Description

Engineers who create and maintain recipes. They design AI workflows, configure agents, and ensure recipes meet business requirements.

​
Primary Goals

  • Create reusable, reliable recipes
  • Document inputs/outputs clearly
  • Ensure security and compliance
  • Optimize for performance and cost
1

Initialize Recipe Project

praisonai recipe init my-new-recipe
cd my-new-recipe
2

Define Recipe Schema

# TEMPLATE.yaml
schema_version: "1.0"
name: my-new-recipe
version: "1.0.0"
description: |
  Detailed description of what this recipe does.
author: your-name
license: Apache-2.0
tags: [category, use-case]

requires:
  env: [OPENAI_API_KEY]
  packages: []

tools:
  allow: [web_search]
  deny: [shell.exec, file.write]

config:
  input:
    query:
      type: string
      required: true
      description: The user's query
    context:
      type: string
      required: false
      description: Optional context

defaults:
  model: gpt-4o-mini
  temperature: 0.7

outputs:
  - name: result
    type: text
    description: The generated response
3

Define Workflow

# workflow.yaml
framework: praisonai
topic: My Recipe Workflow

roles:
  analyst:
    role: Data Analyst
    goal: Analyze the input and provide insights
    backstory: Expert data analyst
    tasks:
      analyze:
        description: Analyze {query} with context {context}
        expected_output: Structured analysis
4

Validate Recipe

praisonai recipe validate my-new-recipe
5

Test Recipe

# Dry run
praisonai recipe run my-new-recipe \
  --input '{"query": "test"}' \
  --dry-run

# Full test
praisonai recipe run my-new-recipe \
  --input '{"query": "test"}' \
  --json
6

Package and Distribute

# Create bundle
praisonai recipe pack my-new-recipe --output my-recipe.praison

# Share or deploy

​
Key Concerns

  • Schema design: Clear, well-documented inputs/outputs
  • Security: Tool restrictions, data handling policies
  • Testing: Comprehensive test cases
  • Versioning: Semantic versioning, changelog

​
Persona Collaboration

​
Next Steps