> ## Documentation Index > Fetch the complete documentation index at: https://docs.praison.ai/llms.txt > Use this file to discover all available pages before exploring further. # Hybrid Workflows > Combine deterministic steps, AI agent steps, and multi-agent workflows in a single pipeline 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 ```yaml pipeline.yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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" ``` ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai workflow run pipeline.yaml praisonai workflow run pipeline.yaml --dry-run ``` *** ## How It Works ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} flowchart LR H["HybridWorkflowExecutor"] --> J["JobWorkflowExecutor"] H --> W["Multi-Agent Engine"] J --> D["run / python / script / action"] J --> A["agent / judge / approve"] W --> MA["workflow / parallel"] style H fill:#8B5CF6,color:#fff style J fill:#10B981,color:#fff style W fill:#6366F1,color:#fff ``` 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 | Key | Type | Description | | ---------- | ------------ | --------------------------------- | | `run:` | Shell | Shell command | | `python:` | Script | Python script file | | `script:` | Inline | Inline Python code | | `action:` | Action | Named actions (3-tier resolution) | | `agent:` | AI Agent | Single agent via `Agent.chat()` | | `judge:` | Quality Gate | Evaluate content with threshold | | `approve:` | Approval | Human or auto approval gate | ### Hybrid-Only Steps | Key | Type | Description | | ----------- | ----------- | ---------------------------------------------- | | `workflow:` | Multi-Agent | Execute a named agent from the `agents:` block | | `parallel:` | Parallel | Run multiple sub-steps concurrently | *** ## Multi-Agent Steps (`workflow:`) Reference agents defined in the top-level `agents:` block: ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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**: | Field | Description | | -------- | -------------------------------------------- | | `agent` | Reference to an agent in the `agents:` block | | `action` | The task/prompt for the agent to execute | *** ## Parallel Steps (`parallel:`) Run multiple sub-steps simultaneously: ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} - 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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 ```yaml hybrid-release.yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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!" ``` ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai workflow run hybrid-release.yaml --dry-run praisonai workflow run hybrid-release.yaml --auto-approve ``` *** ## Comparison: Job vs Hybrid | | Job Workflows | Hybrid Workflows | | ----------------------- | ----------------------------- | ---------------------------------------- | | **Type** | `type: job` | `type: hybrid` | | **Deterministic steps** | ✅ | ✅ | | **Agent steps** | ✅ `agent`, `judge`, `approve` | ✅ | | **Multi-agent** | ❌ | ✅ `workflow:` | | **Parallel** | ❌ | ✅ `parallel:` | | **`agents:` block** | ❌ | ✅ Named agent definitions | | **Use case** | CI/CD, automation | Complex pipelines mixing automation + AI | *** ## Related Deterministic + agent steps YAML-defined, file-based actions Compare all 8 PraisonAI systems