Skip to main content
Hybrid workflows combine the best of both worlds — deterministic shell/Python steps from job workflows and multi-agent collaboration from agent workflows, all in a single YAML file.

​
Quick Start

pipeline.yaml
type: hybrid
name: release-pipeline
description: Shell + AI in one workflow

agents:
  researcher:
    name: Researcher
    role: Research Analyst
    instructions: Provide concise research findings
    model: gpt-4o-mini

steps:
  - name: Check environment
    run: python --version

  - name: Generate notes
    agent:
      role: Technical Writer
      prompt: Generate release notes for v1.2.0
      model: gpt-4o-mini
    output_file: RELEASE_NOTES.md

  - name: Research best practices
    workflow:
      agent: researcher
      action: Research release management best practices

  - name: Parallel checks
    parallel:
      - run: echo "Lint passed"
      - run: echo "Security scan passed"

praisonai workflow run pipeline.yaml
praisonai workflow run pipeline.yaml --dry-run

​
How It Works

The HybridWorkflowExecutor delegates deterministic and agent-centric steps to JobWorkflowExecutor, while handling multi-agent workflow: and parallel: steps itself.

​
Step Types

Hybrid workflows support all step types from both engines:

​
From Job Workflows

KeyTypeDescription
run:ShellShell command
python:ScriptPython script file
script:InlineInline Python code
action:ActionNamed actions (3-tier resolution)
agent:AI AgentSingle agent via Agent.chat()
judge:Quality GateEvaluate content with threshold
approve:ApprovalHuman or auto approval gate

​
Hybrid-Only Steps

KeyTypeDescription
workflow:Multi-AgentExecute a named agent from the agents: block
parallel:ParallelRun multiple sub-steps concurrently

​
Multi-Agent Steps (workflow:)

Reference agents defined in the top-level agents: block: 
type: hybrid
agents:
  researcher:
    name: Researcher
    role: Research Analyst
    goal: Gather comprehensive information
    instructions: Provide factual, well-sourced findings
    model: gpt-4o-mini

  writer:
    name: Writer
    role: Content Writer
    goal: Write clear documentation
    instructions: Write professional, concise content
    model: gpt-4o-mini

steps:
  - name: Research topic
    workflow:
      agent: researcher
      action: Research best practices for documentation
  
  - name: Write documentation
    workflow:
      agent: writer
      action: Write a getting-started guide
workflow: config:
FieldDescription
agentReference to an agent in the agents: block
actionThe task/prompt for the agent to execute

​
Parallel Steps (parallel:)

Run multiple sub-steps simultaneously: 
- name: Run all checks
  parallel:
    - run: echo "Running lint..."
    - run: echo "Running type check..."
    - run: echo "Running security scan..."
    - agent:
        role: Reviewer
        prompt: Check for code quality issues
Each sub-step inside parallel: can be any supported step type — shell, script, agent, etc.

​
Dry Run

praisonai workflow run pipeline.yaml --dry-run

╭────────────── 🔀 Hybrid Workflow — DRY RUN ──────────────╮
│ release-pipeline                                          │
│ Shell + AI in one workflow                                │
╰──────────────────────────────────────────────────────────╯

  ● Check environment — shell: python --version
  ● Generate notes — agent: Technical Writer (model: gpt-4o-mini)
  ● Research — workflow: agent=researcher
  ● Parallel checks — parallel: 3 steps
  ● Quality check — judge: threshold=7.0
  ● Approve — approve: risk=medium

🔀 Dry run complete — 6 steps planned

​
Full Example

hybrid-release.yaml
type: hybrid
name: hybrid-release-pipeline
description: Complete release with shell, AI, and multi-agent steps

agents:
  researcher:
    name: Researcher
    role: Research Analyst
    instructions: Provide concise research findings
    model: gpt-4o-mini

flags:
  skip-tests: { description: "Skip tests" }
  auto-approve: { description: "Auto-approve deployment" }

steps:
  # Deterministic: check environment
  - name: Check environment
    run: python --version

  # Agent: generate release notes
  - name: Generate release notes
    agent:
      role: Technical Writer
      instructions: Write clear, concise release notes
      prompt: Generate release notes for v1.2.0
      model: gpt-4o-mini
    output_file: RELEASE_NOTES.md

  # Parallel: run multiple checks
  - name: Parallel checks
    parallel:
      - run: echo "Lint check passed"
      - run: echo "Type check passed"
      - run: echo "Security scan passed"

  # Multi-agent: research step
  - name: Research best practices
    workflow:
      agent: researcher
      action: Research release management best practices

  # Judge: quality gate
  - name: Quality check
    judge:
      input_file: RELEASE_NOTES.md
      criteria: Complete, clear, professional tone
      threshold: 7.0
      on_fail: warn

  # Approve: human sign-off
  - name: Approve release
    approve:
      description: Review and approve the release
      risk_level: medium
      auto_approve: "{{ flags.auto_approve }}"

  # Deterministic: build
  - name: Build package
    run: echo "Building..."
    if: "{{ not flags.skip_tests }}"

  # Final notification
  - name: Done
    run: echo "✅ Release complete!"

praisonai workflow run hybrid-release.yaml --dry-run
praisonai workflow run hybrid-release.yaml --auto-approve

​
Comparison: Job vs Hybrid

Job WorkflowsHybrid Workflows
Typetype: jobtype: hybrid
Deterministic steps✅✅
Agent steps✅ agent, judge, approve✅
Multi-agent❌✅ workflow:
Parallel❌✅ parallel:
agents: block❌✅ Named agent definitions
Use caseCI/CD, automationComplex pipelines mixing automation + AI

Job Workflows

Deterministic + agent steps

Custom Actions

YAML-defined, file-based actions

All Systems

Compare all 8 PraisonAI systems