Skip to main content
Validate team YAML for runtime compatibility, handoffs, and installed frameworks without LLM calls or API keys. Run this as a preflight step before AgentTeam.start() or a workflow run.

​
Quick Start

1

Define your team

# agents.yaml
framework: praisonai
roles:
  researcher:
    role: Researcher
    handoff:
      to: writer
  writer:
    role: Writer
2

Run preflight (no API keys required)

praisonai doctor runtime --team agents.yaml
3

Start the team when checks pass

from praisonaiagents import Agent, AgentTeam, Task

researcher = Agent(name="researcher", instructions="Research topics")
writer = Agent(name="writer", instructions="Write content")
task = Task(description="Research and write", agent=researcher)

team = AgentTeam(agents=[researcher, writer], tasks=[task])
team.start()  # safe to run after preflight passes

​
How It Works

praisonai doctor runtime --team parses your team YAML and checks:
  • Known runtime IDs and installed packages
  • Required capabilities (handoffs, tools, cli_backend, etc.)
  • Handoff target existence and compatibility
  • Mixed-runtime warnings across the team
Resolution order (mirrors the framework):
  1. Agent-level runtime: wins.
  2. Otherwise falls back to top-level framework: (default praisonai).
  3. When framework: autogen, version comes from autogen_version: or $AUTOGEN_VERSION:
    • v0.4 → autogen_v4 (if available)
    • v0.2 → autogen
    • auto (default) → prefers autogen_v4 if installed, else autogen

​
Runtime Capability Matrix

Runtime IDDisplay NameHandoff supportTool loop
praisonaiPraisonAI AgentsYesYes
crewaiCrewAINoYes
autogenAutoGen v0.2NoYes
autogen_v4AutoGen v0.4YesYes
ag2AG2 (AutoGen Next)NoYes
Capability names referenced by the checker: agent_creation, tool_execution, handoff_support, context_sharing, cli_backend, sequential_execution, hierarchical_execution, group_chat.

​
Configuration

​
CLI flags

FlagTypeDescription
--teamstringTeam YAML file to validate
--workflowstringWorkflow YAML file to validate (placeholder — returns SKIP)
--jsonflagEmit JSON for CI integration
--deepflagEnable deeper probes (accepted; runtime checks do not branch on it today)

​
Exit codes

CodeMeaning
0No issues found
1Issues detected (or team file missing) — non-zero blocks CI
2Internal error
# Basic team validation
praisonai doctor runtime --team agents.yaml

# JSON output for CI
praisonai doctor runtime --team team.yaml --json

# Workflow placeholder (returns SKIP — not yet implemented)
praisonai doctor runtime --workflow workflow.yaml

​
What the Checker Detects

Check ID prefixWhat it catchesSeverity
runtime.yaml_parseYAML file fails to parseCRITICAL
runtime.unknown_runtime.{role}Agent’s runtime: value isn’t a known runtime IDHIGH
runtime.unavailable.{role}Runtime package not installed in current envHIGH
runtime.missing_capabilities.{role}Agent needs a capability the runtime doesn’t provideHIGH
runtime.handoff_unsupported.{role}Agent has handoff: but runtime doesn’t support handoffsHIGH
runtime.handoff_target_missing.{role}Handoff target role name doesn’t exist in the YAMLHIGH
runtime.handoff_target_incompatible.{role}Handoff target uses a runtime that may not support tool loopsMEDIUM
runtime.mixed_runtimesMultiple runtimes in one team — informational warningMEDIUM
runtime.mixed_handoff_incompatibleMixed runtime team has handoffs routed through incompatible runtimesHIGH

​
Common Patterns

​
Good team YAML (passes)

framework: praisonai
roles:
  researcher:
    role: Researcher
    handoff:
      to: writer
  writer:
    role: Writer

​
Bad team YAML (multiple failures)

framework: crewai
roles:
  researcher:
    role: Researcher
    handoff:
      to: ghost   # handoff_target_missing AND handoff_unsupported (crewai)
  writer:
    runtime: autogen
    role: Writer
    # mixed_runtimes + mixed_handoff_incompatible

​
CI integration

- name: Runtime preflight
  run: |
    pip install praisonai
    praisonai doctor runtime --team agents.yaml --json

​
Programmatic API

from praisonai.cli.features.doctor.checks.runtime_checks import lint_runtime_team

results = lint_runtime_team("agents.yaml")
for r in results:
    print(r.id, r.status, r.message)
# Empty list means no issues
The same praisonai doctor runtime command also handles legacy cli_backend migration (--fix, --execute). See Runtime Config Migration for migration flags.

​
Best Practices

Add praisonai doctor runtime --team agents.yaml to CI and local scripts before AgentTeam.start() or praisonai workflow run.
JSON output integrates cleanly with GitHub Actions and other CI systems — exit code 1 blocks the pipeline when compatibility issues are found.
Only praisonai and autogen_v4 support handoffs. Mixed-runtime teams with handoffs through crewai, autogen, or ag2 fail preflight.

Doctor CLI

Full reference for praisonai doctor subcommands and check categories

AgentTeam

Multi-agent orchestration with AgentTeam and Task

PraisonAI Agents Framework

Framework options including handoffs and runtime selection

Runtime Config Migration

Migrate legacy cli_backend fields with praisonai doctor runtime —fix