Recipe Registry

Publish, pull, and manage recipes in local or remote registries

from praisonaiagents import Agent

agent = Agent(name="recipe-agent", instructions="Use recipes from the recipe registry.")
agent.start("Load the customer-support recipe and start handling tickets.")

The user pulls a published recipe bundle and the agent runs that workflow for their request.

Publish and share .praison recipe bundles from a local folder or remote HTTP registry.

from praisonai.recipe.registry import get_registry

registry = get_registry()
registry.publish("./my-agent-1.0.0.praison")
registry.pull("my-agent", output_dir="./recipes")

How It Works

Quick Start

1. Simple Usage

   Use the default local registry at ~/.praison/registry:

   from praisonai.recipe.registry import get_registry
   
   registry = get_registry()
   
   result = registry.publish("./my-agent-1.0.0.praison")
   print(f"Published: {result['name']}@{result['version']}")
   
   pulled = registry.pull("my-agent", output_dir="./recipes")
   print(f"Pulled to: {pulled['path']}")
   
2. With Configuration

   Connect to a remote HTTP registry with token authentication:

   import os
   from praisonai.recipe.registry import get_registry
   
   registry = get_registry(
       "http://localhost:7777",
       token=os.environ.get("PRAISONAI_REGISTRY_TOKEN"),
   )
   
   for recipe in registry.search("agent"):
       print(f"{recipe['name']}: {recipe['description']}")
   

---

How It Works

Local registries store bundles on disk with atomic writes and checksum verification. HTTP registries expose the same operations over REST — get_registry() picks the right backend from a path or URL.

Prefer the command line? The Registry CLI covers praisonai registry list, serve, and status for the same local registry.

Operation	Purpose
publish()	Upload a .praison bundle
pull()	Download a recipe by name and version
list_recipes()	List available recipes
search()	Find recipes by name, description, or tags

---

Configuration Options

Option	Type	Default	Description
registry	str	local path	Filesystem path or HTTP(S) URL
token	str	None	Auth token for remote registries
force	bool	False	Overwrite existing version on publish
verify_checksum	bool	True	Verify bundle integrity on pull
timeout	int	30	HTTP request timeout (seconds)

Environment variables

Variable	Description
PRAISONAI_REGISTRY_TOKEN	Default token for HTTP registry authentication
PRAISONAI_REGISTRY_URL	Default registry URL for scripts

---

Common Patterns

CLI workflow

# Publish a recipe
praisonai recipe publish ./my-recipe --json

# Pull a recipe
praisonai recipe pull my-recipe@1.0.0 -o ./recipes

# List and search
praisonai recipe list --json
praisonai recipe search "video"

# Remote registry
praisonai recipe list --registry http://localhost:7777 --token "$PRAISONAI_REGISTRY_TOKEN"

Error handling

from praisonai.recipe.registry import (
    get_registry,
    RecipeNotFoundError,
    RegistryAuthError,
)

registry = get_registry()

try:
    registry.pull("nonexistent-recipe")
except RecipeNotFoundError as e:
    print(f"Recipe not found: {e}")
except RegistryAuthError as e:
    print(f"Authentication failed: {e}")

---

Best Practices

Version recipes with semantic versioning

Tag each publish with a clear version (1.0.0, 1.1.0). Use force=True only when intentionally replacing a broken release.

Use remote registries for team sharing

Point get_registry() at a shared HTTP registry so teammates pull the same bundles without copying files manually.

Load tokens from environment variables

Never hardcode registry tokens. Set PRAISONAI_REGISTRY_TOKEN in your shell or deployment secrets.

Verify checksums on pull

Keep verify_checksum=True (default) in production so corrupted or tampered bundles are rejected before execution.

---

Related

Modular Recipes

Compose recipes from reusable components with the include pattern

Recipe Serve

Run recipes over HTTP for production deployments