Skip to main content
praisonai doctor runtime detects legacy cli_backend fields in your agent YAML and migrates them to the new models.default.runtime field.

​
Quick Start

1

Scan only

Run a scan to detect legacy configuration without making any changes:
praisonai doctor runtime
Output:
⚠ WARN: Found 2 legacy configuration(s) using cli_backend.
  Run `praisonai doctor runtime --fix` to preview changes.
2

Preview fix (dry-run)

Preview what changes will be made before applying them:
praisonai doctor runtime --fix
Output:
--- agents.yaml (original)
+++ agents.yaml (migrated)
@@ -1,4 +1,6 @@
-cli_backend: claude-code
+models:
+  default:
+    runtime: claude-code
 roles:
   researcher:
-    cli_backend: openai-gpt
+    models:
+      default:
+        runtime: openai-gpt

Run with --fix --execute to apply changes.
3

Apply fix with backup

Apply the migration and create a timestamped backup:
praisonai doctor runtime --fix --execute
A backup is created at agents.backup.20240115_143022.yaml alongside your original file.
4

Target a specific file

praisonai doctor runtime --fix --execute --file my-agents.yaml

​
What Gets Migrated

The cli_backend field at the top level and inside roles.<role_name> is migrated to models.default.runtime. 
cli_backend: claude-code
roles:
  researcher:
    cli_backend: openai-gpt
    role: Research specialist
    goal: Find information
    backstory: Expert researcher
    tasks:
      research:
        description: Research the topic
        expected_output: Summary
Known backend ID mapping:
Legacy cli_backend valueMigrated runtime value
claude-codeclaude-code
openai-gptopenai-gpt
anthropicanthropic
geminigemini
any other valuepreserved as-is

​
How It Works

​
Flags Reference

FlagDefaultPurpose
--file, -f TEXTauto-detect agents.yaml/agents.yml/config.yaml/config.yml in cwdConfig file to check
--fixFalseEnable migration mode
--dry-run / --execute--dry-runPreview changes vs apply changes
--team TEXT—Team YAML file to validate
--workflow TEXT—Workflow YAML file to validate
--jsonFalseJSON output
--deepFalseEnable deeper probes
Behavior summary:
  • Without --fix: Reports WARN with count of legacy configs found.
  • With --fix (dry-run): Shows a preview diff; suggests --fix --execute.
  • With --fix --execute: Writes migrated YAML and leaves a <stem>.backup.<YYYYMMDD_HHMMSS>.yaml backup.
  • If --file is specified but file does not exist: ERROR, severity HIGH.
  • If no config file is found: SKIP.

​
Writing a Custom Rule

Implement DoctorContractProtocol to add your own migration rules: 
from praisonaiagents.runtime import DoctorContractProtocol, Finding, register_rule

class MyRule:
    @property
    def rule_id(self) -> str:
        return "my_org.deprecate_foo"

    def collect_findings(self, config):
        if "foo" in config:
            return [Finding(
                rule_id=self.rule_id,
                severity="warning",
                message="`foo` is deprecated, use `bar` instead",
                fix_description="Rename foo → bar"
            )]
        return []

    def apply_fix(self, config):
        if "foo" in config:
            config["bar"] = config.pop("foo")
        return config

register_rule(MyRule())

​
Plugin Registration via Entry Point

For distribution as a package, register via the praisonai.doctor_contracts entry-point group: 
[project.entry-points."praisonai.doctor_contracts"]
my_org_foo = "my_pkg.rules:MyRule"
Plugins registered this way are auto-discovered when get_rules() is called — no manual register_rule() needed.

​
Finding Dataclass

from praisonaiagents.runtime import Finding

Finding(
    rule_id="my_org.rule",
    severity="warning",          # "warning" | "error" | "info"
    message="Description of the issue",
    fix_description="What the fix will do",  # optional
    context={"key": "value"},                # optional metadata
)

​
Programmatic API

import yaml
from praisonaiagents.runtime import collect_findings, apply_fixes

with open("agents.yaml") as f:
    config = yaml.safe_load(f)

# Inspect findings
findings = collect_findings(config)
for finding in findings:
    print(f"[{finding.severity}] {finding.rule_id}: {finding.message}")

# Apply all fixes
migrated = apply_fixes(config)

with open("agents.yaml", "w") as f:
    yaml.dump(migrated, f)

​
Best Practices

Run praisonai doctor runtime --fix (default dry-run) before --execute. Verify the diff is what you expect — especially for complex YAML with deeply nested roles.
Even though --execute creates a backup, commit or stage your agents.yaml in version control before migrating. This gives you a clean diff to review in your VCS history.
The .backup.<timestamp>.yaml file is left next to the migrated file. Delete it once you’ve confirmed the migrated config works as expected.
Use pyproject.toml entry-points rather than register_rule() in application code. Entry-point rules are discoverable by any consumer of the praisonaiagents.runtime package without requiring code changes.

Doctor CLI

Full reference for praisonai doctor health checks and subcommands

CLI Backend Protocol

The cli_backend field and CLI backend registration system