Execution & Extension Systems

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

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")

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

System	CLI	What Runs	Deterministic	Needs API Key
Job Workflows	`praisonai workflow run`	Shell, Python, actions, agent steps	Mostly ✅	Only for agent steps
Agent Workflows	`praisonai workflow run`	LLM agents collaborating	❌	✅
Hybrid Workflows	`praisonai workflow run`	Job + multi-agent steps	Mixed	✅
Recipes	`praisonai recipe run`	LLM agents + lifecycle	❌	✅
Slash Commands	`/cmd` in REPL	Handler functions	✅	❌

Extension Systems

System	Scope	What It Provides
Tools	Per-agent	Callable functions (`@tool`, `BaseTool`)
Skills	Per-agent	Declarative expertise (`SKILL.md` + prompts)
Plugins	System-wide	Bundled tools + hooks + skills + recipes
Hooks & Callbacks	System-wide	Lifecycle interception and notification

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()) 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

Job Workflows

Step types, agent steps, flags, conditionals

Custom Actions

YAML-defined, file-based, and built-in actions

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

Agent Workflows

Agent definitions, tasks, process types

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()) 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"

Hybrid Workflows

Multi-agent + deterministic steps in one pipeline

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

Recipes

Recipe structure, lifecycle, governance

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.

Tools Guide

Built-in tools, custom tools, tool classes

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:

Category	Hooks
Lifecycle	`ON_INIT`, `ON_SHUTDOWN`
Agent	`BEFORE_AGENT`, `AFTER_AGENT`
LLM	`BEFORE_LLM`, `AFTER_LLM`
Tools	`BEFORE_TOOL`, `AFTER_TOOL`
Messages	`BEFORE_MESSAGE`, `AFTER_MESSAGE`

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

	Job Workflows	Hybrid	Agent Workflows	Recipes	Tools	Skills	Plugins	Hooks
Type	Execution	Execution	Execution	Execution	Extension	Extension	Extension	Extension
AI-powered	Optional	✅	✅	✅	N/A	N/A	N/A	N/A
Scope	Project-local	Project-local	Project-local	External	Per-agent	Per-agent	System-wide	System-wide
Deterministic	Mostly ✅	Mixed	❌	❌	✅	N/A	✅	✅

Distribution & Lifecycle

	Job Workflows	Agent Workflows	Recipes	Tools	Skills	Plugins
Registry	❌	❌	✅	✅ (entry_points) †	❌	✅ (pip) †
pack/publish	❌	❌	✅	❌	❌	✅ (pip)
judge/optimize	❌	❌	✅	❌	❌	❌
HTTP serve	❌	❌	✅	❌	❌	❌
SBOM/audit	❌	❌	✅	❌	❌	❌
Versioned	❌	❌	✅	✅ (pip)	❌	✅ (pip)

† Built-ins win over entry-point plugins. The Tools and Plugins registries subclass the base PluginRegistry, so since PR #4176 an entry_points plugin whose name (case-insensitive) collides with a shipped built-in is skipped and the built-in is kept (a DEBUG line notes the collision). Runtime register(...) is the deliberate override path. See Plugin Precedence.

Execution Model

	Job Workflows	Hybrid	Agent Workflows	Recipes
Dry-run	✅	✅	❌	✅
Agent steps	✅ `agent`, `judge`, `approve`	✅	✅ (native)	✅ (native)
Multi-agent	❌	✅ `workflow:`, `parallel:`	✅	✅
Streaming	❌	❌	❌	✅ `--stream`
Background	❌	❌	❌	✅ `--background`
Replay	❌	❌	❌	✅ `export`/`replay`

Extensibility

	Job Workflows	Hybrid	Agent Workflows	Recipes
Custom actions	✅ YAML, file, built-in	✅ (via job engine)	❌	❌
Custom tools	✅ (agent steps)	✅	✅ Tool plugins	✅ `tools.py`
Conditionals	✅ `if:` expressions	✅ `if:`	❌ (LLM decides)	❌ (LLM decides)
CLI flags	✅ Custom `flags:`	✅	❌	❌
Env vars	✅ `${{ env.X }}`	✅	❌	✅ via config
Variables	✅ `vars:` + `--var`	✅	✅ `--var`	✅ `--var`, `--input`

Decision Guide

If you want to…	Use
Automate shell commands / CI/CD	Job Workflow
Create reusable build actions	Job Workflow + Custom Actions
Mix shell + single AI agent in a pipeline	Job Workflow (agent steps)
Add a quality gate to a pipeline	Job Workflow (`judge:` step)
Mix shell + multi-agent collaboration	Hybrid Workflow
Run checks in parallel	Hybrid Workflow (`parallel:` step)
Orchestrate AI agents on a task	Agent Workflow
Share an AI workflow as a package	Recipe
Improve AI output iteratively	Recipe (`judge`/`optimize`)
Serve an AI workflow as an API	Recipe (`serve`)
Generate a job workflow from a prompt	`praisonai workflow auto --type job`
Give an agent a new capability	Tool
Give an agent expertise / personality	Skill
Add logging / security / guardrails	Hook
Bundle tools + skills + hooks for distribution	Plugin
Quick interactive commands	Slash Command

Best Practices

Start with Agent Workflows

For a single AI task, use an Agent in Python or a YAML agent workflow — no job steps required.

Use Job Workflows for CI/CD

When you need shell commands, conditionals, or quality gates, choose a job workflow with run:, agent:, or judge: steps.

Package with Recipes for distribution

Share workflows externally with praisonai recipe pack — includes lifecycle tools like judge and optimize.

Extend agents, not workflows

Add capabilities via Tools and Skills on the agent; use Plugins when bundling tools, hooks, and recipes for install.

Agent Execution Configuration

Control per-agent execution limits with ExecutionConfig:

ExecutionConfig SDK Reference

Full parameter reference for 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.

Option	Type	Default	Description
`max_steps`	`int \| None`	`None`	Unified tool-use budget honoured by both loops. `None` falls back to `max_iter`. Must be `>= 1`.
`max_iter`	`int`	`20`	Legacy per-loop iteration cap, used when `max_steps` is unset
`max_rpm`	`int \| None`	`None`	Max requests per minute (rate limit)
`max_execution_time`	`int \| None`	`None`	Max wall-clock seconds per run
`max_retry_limit`	`int`	`2`	Max LLM retries on error
`max_tool_calls_per_turn`	`int`	`10`	Max tool calls per single turn
`code_execution`	`bool`	`False`	Allow agent to execute generated code
`code_mode`	`str`	`"safe"`	`"safe"` or `"unsafe"` code execution mode
`code_tools`	`bool`	`False`	Allow code to call agent tools directly
`code_tools_allow`	`list \| None`	`None`	Allowlist of tool names callable from code
`context_compaction`	`bool`	`False`	Auto-compact context when approaching token limit
`max_context_tokens`	`int \| None`	`None`	Token limit before compaction triggers
`max_budget`	`float \| None`	`None`	Hard USD budget limit per run
`on_budget_exceeded`	`str`	`"stop"`	`"stop"` / `"warn"` / callable
`parallel_tool_calls`	`bool`	`False`	Execute batched tool calls in parallel. Single source of truth for this setting; `ToolConfig.parallel` is a deprecated alias for it.

context_compaction defaults to False but will default to True in the next release. Explicitly set context_compaction=False to preserve current behavior.

code_sandbox_mode still exists (default "sandbox") and round-trips through to_dict() / from_dict(), but it is inert — no execution path reads it. To isolate code the model runs, use AgentFlow(run_on=…) (shared sandbox) or Agent(sandbox=…) (explicit execute_code()). See Placement.

Source Files

System	Core Implementation	CLI
Job Workflows	`cli/features/job_workflow.py`	`cli/commands/workflow.py`
Hybrid Workflows	`cli/features/hybrid_workflow.py`	`cli/commands/workflow.py`
Agent Workflows	`cli/features/workflow.py`	`cli/commands/workflow.py`
Workflow Generation	`auto.py` (`JobWorkflowAutoGenerator`)	`workflow auto --type job`
Recipes	`recipe/core.py` + `cli/features/recipe.py`	`cli/commands/recipe.py`
Tools	`praisonaiagents/tools/`	Via agent config
Skills	`praisonaiagents/skills/`	`praisonai skill`
Plugins	`praisonaiagents/plugins/`	`praisonai plugin`
Hooks	`praisonaiagents/hooks/`	Programmatic
Slash Commands	In-memory registry	`/cmd` in REPL

Job Workflows

Deterministic + agent-centric steps

Hybrid Workflows

Job + multi-agent in one pipeline

​How It Works

​Quick Start

​At a Glance

​Execution Systems

​Extension Systems

​Execution Systems

​1. Job Workflows

Job Workflows

Custom Actions

​2. Agent Workflows

Agent Workflows

​2.5. Hybrid Workflows

Hybrid Workflows

​3. Recipes

Recipes

​4. Slash Commands

​Extension Systems

​5. Tools

Tools Guide

​6. Skills

​7. Plugins

​8. Hooks & Callbacks

​How They Relate

​Master Comparison

​Identity & Scope

​Distribution & Lifecycle

​Execution Model

​Extensibility

​Decision Guide

​Best Practices

​Agent Execution Configuration

ExecutionConfig SDK Reference

​Source Files

​Related

Job Workflows

Hybrid Workflows

How It Works

Quick Start

At a Glance

Execution Systems

Extension Systems

Execution Systems

1. Job Workflows

2. Agent Workflows

2.5. Hybrid Workflows

3. Recipes

4. Slash Commands

Extension Systems

5. Tools

6. Skills

7. Plugins

8. Hooks & Callbacks

How They Relate

Master Comparison

Identity & Scope

Distribution & Lifecycle

Execution Model

Extensibility

Decision Guide

Best Practices

Agent Execution Configuration

Source Files

Related