fix(sdk): the build-an-agent skill stops teaching the deprecated commit shape when ordered operations are on

[mmabrouk]

Context

The playground bundles a build-an-agent skill into every builder agent. Its body and its
references/config-schema.md still taught the old commit format — workflow_revision.delta.set
with wholesale list replacement, plus four copy-paste JSON examples of that shape — while the
commit_revision tool, on a deployment with AGENTA_WORKFLOWS_ORDERED_OPERATIONS_ENABLED on,
serves a schema and description for the ordered form only (read_config for a
base_revision_id, then delta.operations with add_item / remove_item / anchored
edit_text).

A live agent read both, followed the skill's example over the tool description, sent a
one-element skills list under delta.set, and wiped the user's existing skill. op_catalog
already records why this happens, in the comment on the delta arm: a model that sees both shapes
picks a different one from call to call. The catalog closed that hole for the tool schema; the
skill was still open.

Changes

The skill content is now flag-conditional, on the same predicate the catalog uses. With the flag
on, the commit teaching describes only the ordered form; with it off, the legacy teaching is
byte-identical to what shipped, because flag-off deployments really do work that way. Neither
state mentions the other's shape.

Before (ordered deployment, what the skill told the agent to send):

{"workflow_revision": {"message": "Add a code-review-checklist skill.",
  "delta": {"set": {"parameters": {"agent": {"skills": [{"name": "code-review-checklist", "...": "..."}]}}}}}}

After:

{"workflow_revision": {"base_revision_id": "019c4f1e-7a2b-73c8-9f10-2b6d5a1c8e04",
  "delta": {"operations": [{"operation": "add_item", "target": ["parameters", "agent", "skills"],
                            "value": {"name": "code-review-checklist", "...": "..."}}]}}}

• agenta/sdk/agents/flags.py (new): ordered_operations_enabled() moves to a leaf module so
  the skill and the catalog read one definition. op_catalog re-exports the private names it
  always had, so test_ordered_operations_flag.py keeps importing them from there. The adapter
  cannot import the platform package itself — it reaches the SDK singleton and is deliberately
  kept off the eager import path.
• agenta_builtins.py: SKILL.md and references/config-schema.md are assembled from a common
  spine plus the passages that describe how a commit is made. The ordered arm teaches the
  read-then-commit loop, the target grammar, the seven operations, worked examples for the five
  things a builder agent actually commits (instructions, add a skill, edit a skill body, remove a
  skill, add a tool), and the failure modes from the contracts: a stale base_revision_id
  answers 409 and you re-read, target_not_found, text_not_unique, a read refused with
  output_too_large returns children, and next_step rather than retryable is the recovery
  field. It also drops the derived-message teaching (message is off the ordered schema) and
  adds read_config to the wired-tools list, where it exists.
• One fix that applies in both arms: the skill said a platform tool entry is something you
  commit, and the legacy example resent three of them inside tools. The server refuses any
  platform-kind entry on an agent's commit (platform_tool_not_committable), so that example
  was a guaranteed refusal, and it contradicted the legacy tool description. The entries are out
  of the example and the rule is stated where the tool types are documented.

The playbooks under agent_templates/ needed no change: their delta.set.parameters.agent.tools
references are test_run's uncommitted delta, which keeps the legacy shape in both flag states.

Tests

New oss/tests/pytest/unit/agents/test_build_an_agent_commit_teaching.py reads the skill in both
flag states (one subprocess each, since the flag is read at import) and asserts:

• the ordered commit surface never says delta.set, delta.remove, or wholesale — the class
  detector for this incident;
• a bundled file may name delta.set only on a line that also names test_run;
• every ordered example validates against commit_revision's real resolved input schema, which
  is closed at every level, and the five examples cover the five operations an agent commits;
• the ordered reference documents every operation and the ordered failure modes;
• the mirror: with the flag off, the reference still teaches the merge semantics and names
  nothing from the ordered form.

Green in both flag states: the SDK unit suite (oss/tests/pytest/unit, 2003 passed; the one
failure, test_streaming.py::test_cli_stream_terminal_only_on_empty_request, fails identically
on the unmodified branch) and the API unit suite (2085 passed), including
test_static_catalog.py, test_build_kit_overlay.py, and test_ordered_operations_flag.py.
ruff format and ruff check clean on every touched file.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview	Aug 7, 2026 5:11pm

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 303f12a8-1733-40a5-a458-4bd5d83f47a4

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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.}