Execution & Extension Systems

Complete comparison of PraisonAI's 9 systems: Job Workflows, Agent Workflows, Hybrid Workflows, Recipes, Slash Commands, Tools, Skills, Plugins, and Hooks

PraisonAI has 9 distinct systems across two categories: Execution Systems (things that run) and Extension Systems (things that extend agent capabilities).

from praisonaiagents import Agent

# Simplest path — Agent Workflow
agent = Agent(name="researcher", instructions="Research AI trends")
agent.start("Summarise the latest LLM papers")

The user picks a workflow or extension; each system attaches jobs, recipes, tools, or hooks to the same agent core.

How It Works

Quick Start

1. Run an agent workflow

   The default execution path — one agent, one prompt:

   from praisonaiagents import Agent
   
   agent = Agent(name="researcher", instructions="Research AI trends")
   agent.start("Summarise the latest LLM papers")

2. Run a job workflow from YAML

   Mix shell steps and agent steps in a deterministic pipeline:

   type: job
   name: release
   steps:
     - name: Build
       run: uv build
     - name: Changelog
       agent:
         role: Technical Writer
         prompt: Generate changelog
         model: gpt-4o-mini

   praisonai workflow run release.yaml

At a Glance

Execution Systems

Extension Systems

Execution Systems

1. Job Workflows

Ordered step execution mixing deterministic automation and AI agent steps.

Discriminator: type: job in YAML | Engine: JobWorkflowExecutor

Routing: Honored by both the CLI (praisonai workflow run ...) and the programmatic wrapper (AgentsGenerator.generate_crew_and_kickoff() / .agenerate_crew_and_kickoff()). The sync path is now scope-isolated for every process: value — generate_crew_and_kickoff() wraps adapter.run(...) in scoped_bridge() for sequential and hierarchical; _run_yaml_workflow wraps workflow.start(...) in scoped_bridge() for workflow. A stuck coroutine in any one run cannot park the shared default loop for other tenants. See Async Bridge → Per-run auto-scoping.

Deterministic steps: run: (shell), python: (script), script: (inline Python), action: (custom/built-in)

Agent-centric steps: agent: (AI agent), judge: (quality gate), approve: (approval gate)

type: job
name: smart-release
steps:
  - name: Build
    run: uv build
  - name: Generate changelog
    agent:
      role: Technical Writer
      prompt: Generate changelog
      model: gpt-4o-mini
    output_file: CHANGELOG.md
  - name: Quality check
    judge:
      input_file: CHANGELOG.md
      threshold: 8.0
      on_fail: warn

Key features: 3-tier action resolution, custom CLI flags, conditional steps, --dry-run, agent/judge/approve steps

2. Agent Workflows

LLM-powered agent pipelines — AI agents collaborate on tasks.

Discriminator: No type field (default) | Engine: Agent Workflow Engine

topic: Research AI Trends
roles:
  researcher:
    role: AI Researcher
    goal: Find latest papers
    tools:
      - internet_search

praisonai workflow run research.yaml

Key features: Agents with roles/goals/backstories, tool integration, multi-agent collaboration, non-deterministic

2.5. Hybrid Workflows

Combines job workflow steps (deterministic + agent) with multi-agent collaboration steps.

Discriminator: type: hybrid in YAML | Engine: HybridWorkflowExecutor

Routing: Honored by both the CLI (praisonai workflow run ...) and the programmatic wrapper (AgentsGenerator.generate_crew_and_kickoff() / .agenerate_crew_and_kickoff()). The sync path is now scope-isolated for every process: value — generate_crew_and_kickoff() wraps adapter.run(...) in scoped_bridge() for sequential and hierarchical; _run_yaml_workflow wraps workflow.start(...) in scoped_bridge() for workflow. A stuck coroutine in any one run cannot park the shared default loop for other tenants. See Async Bridge → Per-run auto-scoping.

Supports all job workflow step types plus:

• workflow: — execute a named agent from the agents: block
• parallel: — run multiple sub-steps concurrently

type: hybrid
agents:
  researcher:
    role: Research Analyst
    instructions: Provide concise findings
steps:
  - name: Setup
    run: echo "Starting..."
  - name: Research
    workflow:
      agent: researcher
      action: Research best practices
  - name: Parallel checks
    parallel:
      - run: echo "Lint passed"
      - run: echo "Tests passed"

3. Recipes

Packaged, distributable agent workflows with full lifecycle management.

CLI: praisonai recipe (separate command group) | Engine: recipe.run()

Discovery (5-tier): $PRAISONAI_RECIPE_PATH → ./recipes/ → ~/.praison/recipes/ → agent_recipes pip package → built-in

praisonai recipe run support-reply --input '{"ticket_id": "T-123"}'
praisonai recipe judge run-abc123 --yaml agents.yaml
praisonai recipe optimize my-recipe --iterations 5
praisonai recipe pack my-recipe
praisonai recipe publish my-recipe.praison
praisonai recipe serve my-recipe

Key features: pack/publish/pull/install, judge/optimize/apply lifecycle, policy packs, SBOM/audit, HTTP serving, trace replay

4. Slash Commands

Interactive commands in the PraisonAI REPL. User types /cmd — no YAML, no CLI invocation outside REPL.

Extension Systems

5. Tools

Functional actions that agents call to interact with the outside world.

Scope: Per-agent | Discovery: Lazy-loaded via praisonaiagents.tools.registry.py entry points

Implementation options:

• Function-based: @tool decorated functions
• Class-based: BaseTool or Pydantic classes for stateful operations
• External packages: Pip packages discovered via entry_points under the canonical praisonai.tools group. praisonaiagents.tools and praisonai.tool_sources are kept as deprecated one-cycle aliases (they still resolve, with a DeprecationWarning on first discovery).

from praisonaiagents import Agent
from praisonaiagents.tools import internet_search

agent = Agent(tools=[internet_search])

Key distinction: Tools are procedural — Python code that does something.

6. Skills

Declarative expertise modules — reusable prompts and knowledge.

Scope: Per-agent | Standard: Agent Skills (agentskills.io) | CLI: praisonai skill list/install/validate

.praison/skills/
├── code-review/
│   └── SKILL.md
├── seo-expert/
│   └── SKILL.md

Key distinction: Skills are declarative — SKILL.md + prompt templates, not code.

Skills can be generated autonomously using the Identify-Scrape-Synthesize (ISS) pattern.

7. Plugins

System-wide extension bundles — the marketplace unit.

Scope: System-wide | Manager: PluginManager (global registry + discovery) | Location: .praison/plugins/, pip packages

A plugin can bundle:

• Tools — adds new agent actions
• Skills — adds agent expertise templates
• Recipes — adds pre-defined agent teams
• Hooks — adds logging, security, monitoring
• Integrations — connects to Slack, Telegram, APIs

from praisonai import plugins
plugins.enable("slack")
# or via env: PRAISONAI_PLUGINS=slack,logging

Key distinction: Plugins are containers — they deliver tools, skills, hooks, and recipes as a single installable unit.

8. Hooks & Callbacks

Lifecycle interception (hooks) and notification (callbacks).

Hooks — middleware functions that can modify agent requests/responses:

Use for: Retries, caching, request modification, guardrails.

Callbacks — simple functions called after a Task completes. Cannot modify execution flow.

Use for: Logging, database updates, alerting.

How They Relate

Master Comparison

Identity & Scope

Distribution & Lifecycle

Execution Model

Extensibility

Decision Guide

Best Practices

Agent Execution Configuration

Control per-agent execution limits with ExecutionConfig:

Precedence ladder:

# Level 1: String preset
agent = Agent(execution="thorough")   # "fast" | "balanced" | "thorough" | "unlimited"

# Level 2: ExecutionConfig (full control)
agent = Agent(execution=ExecutionConfig(
    max_iter=50,
    max_rpm=100,
    context_compaction=True,
    max_budget=1.00,
))

# Preferred modern form — max_steps is the unified budget honoured by both loops
agent = Agent(execution=ExecutionConfig(max_steps=50))

max_steps is the unified outer-loop step budget honoured identically by both tool-execution loops. Detect truncation with agent.last_stop_reason == "max_steps". See Step Budget.

Source Files

Related