> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Workflow YAML Framework Field
> How the framework: key in YAML chooses an execution backend
The `framework:` key in YAML picks which execution backend runs your agents — but the rules differ between **agents.yaml** and **workflow YAML**.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, PraisonAIAgents
agent = Agent(name="Writer", instructions="Write helpful posts")
PraisonAIAgents(agents=[agent]).start("Write about caching")
```
The user picks a YAML file; `framework:` selects the backend that runs the workflow.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
subgraph "Choosing framework:"
YAML[📄 YAML File] --> Type{Workflow YAML?}
Type -->|"steps:/type:job"| WF[🛠️ Workflow Engine]
Type -->|otherwise| AG[🧑🤝🧑 AgentsGenerator]
WF --> WFCheck{adapter SUPPORTS_WORKFLOW?}
WFCheck -->|True| Ok1[✅ Run]
WFCheck -->|False| Err[❌ ValueError]
AG --> Reg[📚 Registry]
Reg --> Run[✅ Resolve adapter and run]
end
classDef yaml fill:#6366F1,stroke:#7C90A0,color:#fff
classDef ok fill:#10B981,stroke:#7C90A0,color:#fff
classDef err fill:#8B0000,stroke:#7C90A0,color:#fff
classDef proc fill:#189AB4,stroke:#7C90A0,color:#fff
class YAML yaml
class Ok1,Run ok
class Err err
class WF,AG,Reg,Type,WFCheck proc
```
## Quick Start
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
framework: crewai
topic: Write a blog post
roles:
writer:
role: Writer
goal: Write engaging posts
backstory: Senior editor
tasks:
draft:
description: Write a post about {topic}
expected_output: A 500-word post
```
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agents.yaml
```
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
framework: praisonai
type: job
steps:
- id: research
agent: researcher
- id: write
agent: writer
depends_on: [research]
```
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai workflow.yaml
```
***
## Which file uses which?
| YAML shape | Engine | `framework:` choices |
| -------------------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------- |
| `roles:` / `topic:` (agents.yaml) | `AgentsGenerator` + registry | Any registered adapter (`crewai`, `praisonai`, `autogen`, plus entry-point plugins) |
| `steps:` + `workflow:` (workflow YAML) | Native Workflow engine | Any adapter whose `SUPPORTS_WORKFLOW = True` (built-in `praisonai` qualifies) |
| `type: job` / `type: hybrid` (workflow YAML) | Native Workflow engine | Any adapter whose `SUPPORTS_WORKFLOW = True` (built-in `praisonai` qualifies) |
Workflow YAML dispatch requires an adapter whose `SUPPORTS_WORKFLOW = True`. The built-in `praisonai` adapter has it. Third-party adapters opt in by setting the flag on their subclass — see [Capability Flags](/docs/features/framework-adapter-plugins#capability-flags).
If `framework:` is omitted, agents.yaml defaults via `FrameworkAdapterRegistry.pick_default()` and workflow YAML defaults to `praisonai`.
***
## What you'll see if the framework isn't workflow-capable
Selecting a framework whose adapter has `SUPPORTS_WORKFLOW = False` raises:
```
ValueError: framework='crewai' in workflow YAML is not supported for workflow execution.
The workflow engine requires an adapter whose SUPPORTS_WORKFLOW flag is set (the native 'praisonai' adapter does).
Use a non-workflow agents.yaml with a supported registered framework, or set framework: praisonai. Frameworks supporting workflow execution: praisonai.
```
The trailing list names every registered adapter whose `SUPPORTS_WORKFLOW` flag is `True`, so it grows as you install workflow-capable plugins.
***
## Make a custom framework workflow-capable
Set `SUPPORTS_WORKFLOW = True` on your adapter subclass to accept workflow YAML dispatch:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import BaseFrameworkAdapter
class MyWorkflowFrameworkAdapter(BaseFrameworkAdapter):
name = "myframework"
SUPPORTS_WORKFLOW = True
def is_available(self) -> bool:
return True
def run(self, config, llm_config, topic, *,
tools_dict=None, agent_callback=None,
task_callback=None, cli_config=None) -> str:
return f"myframework ran: {topic}"
```
Once registered, `myframework` is accepted in workflow YAML and appears in the "Frameworks supporting workflow execution" list. See [Capability Flags](/docs/features/framework-adapter-plugins#capability-flags).
***
## What to do
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
Need[I need a non-praisonai framework] --> Q{What YAML do I want?}
Q -->|Linear roles/tasks| AY[Use agents.yaml]
Q -->|Workflow steps/job/hybrid| WY[Stay on framework: praisonai]
AY --> CL[praisonai --framework crewai agents.yaml]
WY --> NX[Build a CrewAI-side workflow externally]
classDef start fill:#6366F1,stroke:#7C90A0,color:#fff
classDef ok fill:#10B981,stroke:#7C90A0,color:#fff
classDef ask fill:#F59E0B,stroke:#7C90A0,color:#fff
class Need start
class Q ask
class AY,WY,CL,NX ok
```
***
## Programmatic check
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.framework_adapters.workflow_framework import (
validate_workflow_framework,
framework_from_config,
)
cfg = {"framework": "praisonai", "steps": []}
fw = framework_from_config(cfg) # "praisonai"
validate_workflow_framework(fw) # no-op when valid; raises ValueError otherwise
```
`framework_from_config({})` returns `"praisonai"` (safe default). `framework_from_config({"framework": "CrewAI"})` returns `"crewai"` (lowercased before validation).
`validate_workflow_framework()` reads the adapter's `SUPPORTS_WORKFLOW` flag from the default registry. Pass `registry=` to test against an isolated registry:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.framework_adapters.registry import FrameworkAdapterRegistry
reg = FrameworkAdapterRegistry()
reg.register("myframework", MyWorkflowFrameworkAdapter)
validate_workflow_framework("myframework", registry=reg) # passes when SUPPORTS_WORKFLOW = True
```
***
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant CLI
participant AgentsGenerator
participant WorkflowEngine
User->>CLI: praisonai workflow.yaml
CLI->>AgentsGenerator: load YAML
AgentsGenerator->>AgentsGenerator: detect steps:/type:job
AgentsGenerator->>WorkflowEngine: route to workflow runner
WorkflowEngine->>WorkflowEngine: validate_workflow_framework(fw)
alt adapter SUPPORTS_WORKFLOW = True
WorkflowEngine-->>User: ✅ execute
else adapter SUPPORTS_WORKFLOW = False
WorkflowEngine-->>User: ❌ ValueError
end
```
***
## Best Practices
If you need CrewAI, AutoGen, or a custom framework, write your config as `roles:`/`topic:` agents.yaml. The `framework:` key there accepts any registered adapter.
The default is `praisonai`, so you can omit the `framework:` key entirely in workflow YAML. This avoids accidentally setting an unsupported value.
Call `validate_workflow_framework(fw)` immediately after parsing config if you're building tooling around workflow YAML. It raises `ValueError` with an actionable message before any execution starts. Pass `registry=` to validate against an isolated registry in tests.
A custom adapter cannot run workflow YAML until it sets `SUPPORTS_WORKFLOW = True` (class-level). Leaving it `False` keeps the adapter agents.yaml-only and blocks workflow dispatch with a clear error.
Use `list_framework_choices()` from `praisonai.framework_adapters.registry` to populate dropdowns or CLI help text — it includes entry-point plugins automatically.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.framework_adapters.registry import list_framework_choices
choices = list_framework_choices()
print(choices) # ['crewai', 'praisonai', 'autogen', 'my_plugin']
```
***
## Related
Add new execution backends via Python entry points
Full workflow YAML reference