fix: publish agents.yaml JSON Schema + wire editor autocomplete/validation

[praisonai-triage-agent]

Fixes #3427

Summary

Adds first-class editor support for the agents.yaml authoring surface by publishing a JSON Schema derived from YAMLConfig and wiring the # yaml-language-server: $schema= header into scaffolded agent files. Authoring-time tooling only — runtime parsing/execution is unchanged.

Changes (wrapper-only: praisonai/config/ + CLI)

• config/schema.py: add AGENTS_SCHEMA_URL, AGENTS_SCHEMA_HEADER, and generate_agents_schema() (decorates YAMLConfig.model_json_schema() with $schema/$id/title metadata, mirroring the CLI-config schema convention).
• config/agents.schema.json: committed, published artefact (served at the stable raw URL, same hosting pattern as config.schema.json); added to [tool.setuptools.package-data].
• cli/commands/validate.py: extend the existing validate schema command with --agents (emit JSON to stdout) and --output/-o (write a local file for offline/pinned editor setups).
• auto.py: prepend the # yaml-language-server header when scaffolding agents.yaml. A leading YAML comment is ignored by yaml.safe_load, so execution is unaffected.

Usage

praisonai validate schema --agents              # print schema to stdout
praisonai validate schema -o agents.schema.json # write local file for your editor

Tests

tests/unit/test_agents_schema_publish.py:

• generate_agents_schema() exposes roles/agents/tasks/tools/llm/workflow.
• Committed agents.schema.json matches the model (stale-artefact guard).
• A scaffolded agents.yaml starts with the header and still round-trips through ConfigValidator.

All 4 new tests pass; 57 related auto-generator/validation tests pass with no regressions. Fully backwards-compatible.

Generated with Claude Code

[MervinPraison]

@coderabbitai review

[MervinPraison]

/review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[qodo-code-review]

Qodo reviews are paused for this user.

Troubleshooting steps vary by plan Learn more →

On a Teams plan?
Reviews resume once this user has a paid seat and their Git account is linked in Qodo.
Link Git account →

Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center?
These require an Enterprise plan - Contact us
Contact us →

[coderabbitai]

Warning

Review limit reached

@MervinPraison, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 19 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 14df5b0d-7c4f-4d8a-82c7-0ce99a6535cc

📥 Commits

Reviewing files that changed from the base of the PR and between 54b4334 and fda4d24.

📒 Files selected for processing (7)

• src/praisonai/praisonai/auto.py
• src/praisonai/praisonai/cli/commands/validate.py
• src/praisonai/praisonai/config/__init__.py
• src/praisonai/praisonai/config/agents.schema.json
• src/praisonai/praisonai/config/schema.py
• src/praisonai/pyproject.toml
• src/praisonai/tests/unit/test_agents_schema_publish.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/issue-3427-20260727-0902

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

Adds published editor-schema support for agents.yaml.

• Generates and packages an agents.yaml JSON Schema aligned with runtime-normalized agent forms.
• Extends the validation CLI to print or save the schema.
• Adds the schema directive to newly scaffolded agents.yaml files.
• Adds consistency and round-trip tests for the schema artifact and generated YAML.

Confidence Score: 4/5

The PR appears safe to merge, with only the previously reported header-diagnostic weakness remaining.

The schema/runtime compatibility issue is addressed, while header failures still continue without a user-visible diagnostic under default logging.

Files Needing Attention: src/praisonai/praisonai/auto.py

Important Files Changed

Filename	Overview
src/praisonai/praisonai/config/schema.py	Generates the editor schema and relaxes agent requirements and collection forms to reflect runtime normalization.
src/praisonai/praisonai/config/agents.schema.json	Adds the committed schema artifact consumed by YAML-aware editors.
src/praisonai/praisonai/auto.py	Prepends the schema directive while preserving atomic YAML generation.
src/praisonai/praisonai/cli/commands/validate.py	Adds CLI options to emit the agents schema to stdout or a local file.
src/praisonai/tests/unit/test_agents_schema_publish.py	Verifies schema metadata, artifact freshness, normalized forms, header wiring, and YAML validation.

_{Reviews (2): Last reviewed commit: "fix: align published agents schema with ..." | Re-trigger Greptile}

[MervinPraison]

@claude You are the FINAL architecture reviewer. If the branch is under MervinPraison/PraisonAI (not a fork), you are able to make modifications to this branch and push directly. SCOPE: Focus ONLY on Python packages (praisonaiagents, praisonai). Do NOT modify praisonai-rust or praisonai-ts. Read ALL comments above from Gemini, Qodo, CodeRabbit, and Copilot carefully before responding.

Phase 1: Review per AGENTS.md

1. Protocol-driven: check heavy implementations vs core SDK
2. Backward compatible: ensure zero feature regressions
3. Performance: no hot-path regressions
4. SDK value: review in depth whether the change genuinely adds value to the SDK — never add features for the sake of adding them. It must strengthen the SDK (simpler, more user-friendly, robust, world-class, secure). If it does not clearly add value, request changes or recommend rejecting/closing rather than merging scope creep
5. Do not bloat the Agent class with additional params — only if absolutely required; we already support many params.
6. Repo routing: agent-callable tools → PraisonAI-Tools; lifecycle plugins → PraisonAI-Plugins; optional sandbox backends → PraisonAI-Plugins (praisonai.sandbox entry point) — request changes if wrongly added to praisonaiagents/

Phase 2: FIX Valid Issues
7. For any VALID bugs or architectural flaws found by Gemini, CodeRabbit, Qodo, Copilot, or any other reviewer: implement the fix
8. Also independently identify and fix any gaps or issues you find in the changed code — do not rely only on prior reviewer feedback
9. Push all code fixes directly to THIS branch (do NOT create a new PR)
10. Comment a summary of exact files modified and what you skipped

Phase 3: Final Verdict
11. If all issues are resolved, approve the PR / close the Issue
12. If blocking issues remain, request changes / leave clear action items

[praisonai-triage-agent]

Claude finished @MervinPraison's task —— View job

---

Claude — Final Architecture Review (PR #3437) ✅

Phase 1 — Architecture verdict: ✅ Correctly scoped. Wrapper-only (praisonai/config/ + CLI), no praisonaiagents/ changes, no Agent-class bloat, no new runtime deps. Backward-compatible — the leading YAML comment is ignored by safe_load, so execution is unaffected. Genuine authoring-time value (editor autocomplete/validation), no scope creep.

Phase 2 — Valid issues fixed (pushed to this branch as ab13eea12):

• Greptile P1 (valid) — published schema was stricter than the runtime. The runtime (agents_generator.py) accepts list-form roles/agents (_list_to_dict), auto-fills role/goal from the agent key, and maps instructions→backstory — but YAMLConfig marks those required and object-only, so editors would flag valid, executable YAML as invalid. generate_agents_schema() now post-processes the published artefact to match the runtime contract (drops AgentConfig.required; roles/agents accept dict or list). The strict YAMLConfig used by ConfigValidator is untouched.
• Greptile P2 (valid) — silent header failure. Replaced except Exception: pass in auto.py with a logger.debug(...) so a dropped # yaml-language-server directive is diagnosable (still non-fatal).
• Regenerated agents.schema.json.
• Added a runtime-parity guard test (test_published_schema_matches_runtime_contract).

Files modified

• config/schema.py — _relax_agent_config_for_editor() + _allow_list_form_agents(); wired into generate_agents_schema().
• config/agents.schema.json — regenerated.
• auto.py:1118 — silent pass → logger.debug.
• tests/unit/test_agents_schema_publish.py — new parity test.

Skipped: No changes to the strict validator (correct — editor schema should be a superset of the runtime contract, not identical to the strict form). No top-level additionalProperties:false was added, so the scaffolded dependencies key remains accepted. No praisonai-rust/praisonai-ts touched (out of scope).

Tests: ✅ 5/5 new schema-publish tests pass; 82/82 across schema + agents_yaml_validation + auto_generator + enhanced_auto + validation_feedback — no regressions.

Phase 3 — Verdict: ✅ Approve. All reviewer-flagged issues are valid and now resolved; the published schema is a faithful superset of the runtime contract. No blocking issues remain.

_{Job run · branch claude/issue-3427-20260727-0902}