Skip to main content
from praisonaiagents import Agent

agent = Agent(name="endpoint-agent", instructions="Route requests to the right LLM endpoint.")
agent.start("Send this request to the OpenAI-compatible endpoint.")
Run recipe endpoints from Python or any HTTP client — list recipes, execute runs, and stream progress. 
from praisonai import recipe

result = recipe.run(
    "my-recipe",
    input={"query": "Hello, world!"},
    options={"timeout_sec": 60},
)
print(result.output if result.ok else result.error)
The user names a recipe and input; recipe.run or HTTP returns structured output or streaming progress.

​
How It Works

​
Quick Start

1

Run a recipe

from praisonai import recipe

recipes = recipe.list_recipes()
info = recipe.describe("my-recipe")

result = recipe.run(
    "my-recipe",
    input={"query": "Hello, world!"},
    options={"timeout_sec": 60},
)

if result.ok:
    print(f"Output: {result.output}")
else:
    print(f"Error: {result.error}")
2

Stream and handle errors

import os
from praisonai import recipe
from praisonai.recipe.exceptions import (
    RecipeError,
    RecipeNotFoundError,
    RecipeTimeoutError,
)

for event in recipe.run_stream(
    "my-recipe",
    input={"query": "Generate a story"},
):
    if event.event_type == "completed":
        print(event.data)

try:
    recipe.run("my-recipe", input={"query": "test"})
except RecipeNotFoundError as e:
    print(f"Recipe not found: {e.recipe}")
except RecipeTimeoutError as e:
    print(f"Timeout after {e.timeout_sec}s")
except RecipeError as e:
    print(f"Recipe error: {e}")

​
HTTP Client

Use the REST API from any language when the endpoint server is running (praisonai serve). 
import os
import requests

BASE_URL = os.getenv("PRAISON_ENDPOINT_URL", "http://localhost:8765")
API_KEY = os.getenv("PRAISON_API_KEY")  # optional when auth is enabled

headers = {"Content-Type": "application/json"}
if API_KEY:
    headers["X-API-Key"] = API_KEY

response = requests.post(
    f"{BASE_URL}/v1/recipes/run",
    headers=headers,
    json={
        "recipe": "my-recipe",
        "input": {"query": "Hello"},
        "options": {"dry_run": False},
    },
)
result = response.json()
print(result["output"])

curl -X POST http://localhost:8765/v1/recipes/run \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $PRAISON_API_KEY" \
  -d '{"recipe": "my-recipe", "input": {"query": "Hello"}}'

​
Response Models

FieldTypeDescription
okboolSuccess status
run_idstrUnique run identifier
outputAnyRecipe output
errorstr | NoneError message when failed
tracedictrun_id, session_id, trace_id for observability
Streaming events use event_type: started, progress, completed, or error.

​
Best Practices

Pass options={"timeout_sec": 30} (or higher) so long-running recipes fail predictably instead of hanging.
Reuse session_id across calls so conversation recipes retain context between requests.
Log result.trace["trace_id"] for debugging and observability correlation.
Use from praisonai import recipe when running in the same environment; use HTTP for remote or polyglot clients.

Endpoint Provider Registry

Register custom endpoint providers for serve and discovery

CLI Endpoints

Run and manage endpoints from the command line