Headless YAML Runs

Run multi-agent YAML teams unattended with per-agent metrics, output files, and reliable exit codes

Headless YAML runs execute an agent team from agents.yaml with no prompts, then report usage, write files, and exit with a code your CI can trust.

Quick Start

1. Create agents.yaml

   framework: praisonai
   topic: risk
   roles:
     analyst:
       role: Analyst
       goal: Analyse the risk
       backstory: Expert analyst
       llm: openai/gpt-4o-mini
       tasks:
         analyst_task:
           description: Analyse the risk
           expected_output: Markdown summary
     writer:
       role: Writer
       goal: Write the report
       backstory: Technical writer
       llm: openai/gpt-4o-mini
       tasks:
         writer_task:
           description: Write the report
           expected_output: Markdown
           output_file: out/risk_report.md

2. Run it

   export OPENAI_API_KEY=your-openai-key
   praisonai agents.yaml --trust --metrics

   You get out/risk_report.md and a per-agent usage table.

Flags

Three flags make a YAML run suitable for scripts.

Equivalent approval switches for other entry points: praisonai run --approval bypass, --autonomy full_auto, or PRAISONAI_AUTO_APPROVE=true. There is no --no-approve flag; use --trust.

Per-Agent Metrics

--metrics prints one row per agent, a TOTAL row, and the model name.

          Agent Metrics (model: openai/gpt-4o-mini)
┌──────────┬───────┬────────┬───────┬───────┬──────────┐
│ Agent    │ Input │ Output │ Total │ Calls │ Time (s) │
├──────────┼───────┼────────┼───────┼───────┼──────────┤
│ Analyst  │    10 │      5 │    15 │     1 │     0.12 │
│ Writer   │    10 │      5 │    15 │     1 │     0.11 │
│ TOTAL    │    20 │     10 │    30 │     2 │     0.23 │
└──────────┴───────┴────────┴───────┴───────┴──────────┘

--metrics-json prints JSON to stdout only. It takes no path; redirect to save a file.

praisonai agents.yaml --trust --metrics-json > metrics.json

{
  "agents": [
    {
      "name": "Analyst",
      "input_tokens": 10,
      "output_tokens": 5,
      "total_tokens": 15,
      "calls": 1,
      "latency_s": 0.123
    }
  ],
  "total": {
    "input_tokens": 10,
    "output_tokens": 5,
    "total_tokens": 15,
    "calls": 1,
    "latency_s": 0.123
  },
  "model": "openai/gpt-4o-mini"
}

Task output_file

framework: praisonai writes a task’s result to output_file and creates missing parent folders.

tasks:
  writer_task:
    description: Write the report
    expected_output: Markdown
    output_file: out/risk_report.md   # out/ is created automatically

A bare filename such as flat.md writes to the working directory. See Save Output for every output option.

Exit Codes

Failed runs exit non-zero so CI can detect them.

Stale files from a previous run do not count as written. Tasks that never ran (skipped workflow branches) are not counted as missing files.

Sandbox Environment Variables

Set these to run inside a locked-down container with one OpenAI-compatible endpoint and no outbound access.

Full Example

export OPENAI_BASE_URL=http://sandbox-llm:8000/v1
export OPENAI_API_KEY=placeholder
export OPENAI_MODEL_NAME=gpt-4o-mini
export PRAISONAI_NO_UPDATE_CHECK=1
export PRAISONAI_TELEMETRY_DISABLED=true
export LITELLM_LOCAL_MODEL_COST_MAP=True

praisonai agents.yaml --trust --metrics-json > metrics.json
if [ $? -eq 0 ]; then
  echo "Run succeeded"; cat out/risk_report.md
else
  echo "Run failed"
fi

Common Pitfalls

Best Practices

Related