feat(sdk): let a builder tool call carry the agent's own note by mmabrouk · Pull Request #5747 · Agenta-AI/agenta

mmabrouk · 2026-08-05T17:37:53Z

Context

When a build-kit agent commits a change or runs a test, the playground shows the call and its arguments. It does not show why the agent made it. The user watching a tool call scroll past has to read a JSON payload and infer the intent.

This adds one optional field the model writes and the human reads: a sentence or two saying what this call does and why.

Changes

Builder ops opt in with accepts_description on the catalog entry. commit_revision and test_run carry it. An op whose calls no human ever sees gains nothing from it, so it stays off by default.

The field rides at the top level of the arguments, beside the op's own payload object, because it describes the call and not the payload:

{"description": "Adding the release checklist skill so I can run the checks myself.",
 "workflow_revision": {"delta": {"operations": [...]}}}

The endpoint never sees it. The runner deletes it from the model's arguments at dispatch, before it builds the request, so no endpoint schema changes and no persisted record grows a field. The strip runs at dispatch and not earlier for one reason: the recorded call keeps the full arguments, so the frontend shows the note on both the live path and the replay path.

The list of fields to strip lives on the resolved tool spec as ephemeralArgs, next to the schema that offers the field. One list means the schema and the strip cannot drift apart, and both dispatch modes call the same strip.

This is not the commit message and not the persisted description. The commit message describes the change in the revision history and is derived by the server from the operations. This describes the call in the conversation and is never saved. The catalog caps it at 500 characters, which is long enough for two sentences and short enough that it can never become a payload channel. The frontend truncates at the same number and shows that it truncated.

The playground renders it under the tool name in the activity list, in secondary text. It is model-authored text, so it is presented as the agent's own account of the call and never as a fact about what happened.

Tests / notes

test_op_catalog_description.py in the SDK, 13 tests: which ops carry the field, where it sits in the schema, and that ephemeral_args matches what the schema offers.
tool-direct.test.ts in the runner, 55 tests, including the strip on both dispatch modes and the recorded call keeping the field.
toolDisplay.test.ts in the web app covers extraction and truncation.
Reviewers should confirm the strip cannot be skipped on a new dispatch path. That is the failure that would leak a model-authored field into a request body.

What to QA

In the playground, ask an agent to commit a change. The tool call shows the agent's note under the call name.
Reload the conversation. The note is still there, which is the replay path.
Check a long note. It cuts off at 500 characters and shows that it was cut.
Regression: the commit itself still works, and the revision history shows the derived commit message rather than this note.

This targets agent-config-editing-s5 and is part of the agent-config-editing stack. Read the stack bottom up.

Added by the E2E campaign and review fix rounds (5 Aug, evening)

Description truncation now counts code points, matching the catalog's maxLength; an emoji at the boundary is no longer split into a broken surrogate.

vercel · 2026-08-05T17:38:01Z

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

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

coderabbitai · 2026-08-05T17:38:02Z

📝 Walkthrough

Summary by CodeRabbit

New Features
- Tool calls can include an optional description of up to 500 characters.
- Descriptions appear beneath tool activity entries, with an indicator when shortened.
- Descriptions are retained for activity records and approvals but excluded from dispatched requests.
Bug Fixes
- Unresolved run-context values now fail safely instead of sending incomplete requests.
Tests
- Added coverage for description handling, display, truncation, and request dispatch behavior.

Walkthrough

The change adds opt-in ephemeral descriptions to selected platform operations. Metadata flows through callback specifications to the runner, which strips descriptions before dispatch while retaining them for records. The web interface displays trimmed descriptions beneath tool activity rows.

Changes

Ephemeral descriptions

Layer / File(s)	Summary
Platform description contract `sdks/python/agenta/sdk/agents/platform/op_catalog.py`, `sdks/python/agenta/sdk/agents/platform/platform_tools.py`, `sdks/python/agenta/sdk/agents/tools/models.py`, `sdks/python/oss/tests/pytest/unit/agents/platform/*`	`PlatformOp` supports opt-in descriptions. Resolved schemas expose an optional 500-character field. Callback specifications serialize ephemeral arguments as `ephemeralArgs`.
Runner dispatch filtering `services/runner/src/protocol.ts`, `services/runner/src/tools/*.ts`, `services/runner/tests/unit/tool-direct.test.ts`	The runner removes declared top-level ephemeral arguments before direct and gateway dispatch. Tests cover immutability, nested values, `args_into`, handler mode, and undeclared descriptions.
Tool-call description display `web/oss/src/components/AgentChatSlice/assets/toolDisplay.ts`, `web/oss/src/components/AgentChatSlice/components/ToolActivity.tsx`, `web/oss/src/components/AgentChatSlice/assets/toolDisplay.test.ts`	The web interface extracts and trims descriptions, limits them to 500 Unicode code points, and displays shortened values with an indicator.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Model
  participant PlatformOp
  participant Runner
  participant API
  participant ToolActivity
  Model->>PlatformOp: provide optional description
  PlatformOp->>Runner: send resolved ephemeralArgs metadata
  Runner->>API: dispatch request without ephemeral description
  Runner->>ToolActivity: retain tool input for recorded activity
  ToolActivity->>ToolActivity: extract and render description

Possibly related PRs

Agenta-AI/agenta#4936: Shares op_catalog.py and commit_revision tooling changes.
Agenta-AI/agenta#5068: Introduces the related platform tool and callback specification pipeline.
Agenta-AI/agenta#5074: Extends the related resolved tool specification and runner relay paths.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 57.14% which is insufficient. The required threshold is 60.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the main change: adding an agent-authored note to builder tool calls.
Description check	✅ Passed	The description directly explains the feature, its behavior across SDK, runner, and web layers, and the related tests.

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

Create stacked PR
Commit on current branch

🛠️ Fix failing CI checks 💡

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch agent-config-editing-s4

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

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

mmabrouk · 2026-08-05T17:43:59Z

+ *
+ * Returns `args` unchanged when there is nothing to strip, so the common path allocates nothing.
+ */
+export function stripEphemeralArgs(


The strip happens at dispatch. It does not happen earlier.

The recorded call keeps the full arguments. The frontend reads the note from the recorded call, on the live path and on the replay path.

If you strip the field earlier, the note disappears from the conversation after a reload.

mmabrouk · 2026-08-05T17:44:00Z

+  // `description`, R12). This runs BEFORE the dispatch fork so both modes strip identically, and
+  // before `assembleBody` so an `args_into` op cannot deep-set the note inside its payload. The
+  // recorded call and the approval card keep the full arguments; only the request loses them.
+  const dispatchArgs = stripEphemeralArgs(req.args, spec.ephemeralArgs);


This call precedes the fork between the two dispatch modes. Both modes therefore strip the same fields.

The call also precedes assembleBody. An op with args_into writes the arguments into a payload object. A strip after that step could leave the note inside the payload.

mmabrouk · 2026-08-05T20:04:18Z

@coderabbitai review

coderabbitai · 2026-08-05T20:04:24Z

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

coderabbitai

Actionable comments posted: 1

🧹 Nitpick comments (1)

web/oss/src/components/AgentChatSlice/assets/toolDisplay.ts (1)

86-91: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Reduce the new multi-line comments.

Neither comment documents a bug, race, or ordering constraint. Replace each with one short line or remove it.

web/oss/src/components/AgentChatSlice/assets/toolDisplay.ts#L86-L91: reduce the helper comment to one short line.

web/oss/src/components/AgentChatSlice/assets/toolDisplay.test.ts#L5-L6: reduce the test-context comment to one short line.

As per coding guidelines, “Keep in-code comments to at most one short line; use longer comments only for genuinely surprising constraints such as bugs, races, or ordering requirements.”

Source: Coding guidelines

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7bbfb00b-9ec4-4752-aad7-c41c4f234b1e

📥 Commits

Reviewing files that changed from the base of the PR and between fc8740d and 216ab63.

📒 Files selected for processing (12)

sdks/python/agenta/sdk/agents/platform/op_catalog.py
sdks/python/agenta/sdk/agents/platform/platform_tools.py
sdks/python/agenta/sdk/agents/tools/models.py
sdks/python/oss/tests/pytest/unit/agents/platform/test_op_catalog.py
sdks/python/oss/tests/pytest/unit/agents/platform/test_op_catalog_description.py
services/runner/src/protocol.ts
services/runner/src/tools/direct.ts
services/runner/src/tools/relay.ts
services/runner/tests/unit/tool-direct.test.ts
web/oss/src/components/AgentChatSlice/assets/toolDisplay.test.ts
web/oss/src/components/AgentChatSlice/assets/toolDisplay.ts
web/oss/src/components/AgentChatSlice/components/ToolActivity.tsx

mmabrouk · 2026-08-05T21:56:27Z

@coderabbitai review

coderabbitai · 2026-08-05T21:56:33Z

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

coderabbitai · 2026-08-05T21:56:36Z

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

coderabbitai

Actionable comments posted: 1

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 86055eba-8a93-4b56-b1e9-92fe45bcd89b

📥 Commits

Reviewing files that changed from the base of the PR and between 8886dd9 and 829b266.

📒 Files selected for processing (12)

sdks/python/agenta/sdk/agents/platform/op_catalog.py
sdks/python/agenta/sdk/agents/platform/platform_tools.py
sdks/python/agenta/sdk/agents/tools/models.py
sdks/python/oss/tests/pytest/unit/agents/platform/test_op_catalog.py
sdks/python/oss/tests/pytest/unit/agents/platform/test_op_catalog_description.py
services/runner/src/protocol.ts
services/runner/src/tools/direct.ts
services/runner/src/tools/relay.ts
services/runner/tests/unit/tool-direct.test.ts
web/oss/src/components/AgentChatSlice/assets/toolDisplay.test.ts
web/oss/src/components/AgentChatSlice/assets/toolDisplay.ts
web/oss/src/components/AgentChatSlice/components/ToolActivity.tsx

🚧 Files skipped from review as they are similar to previous changes (11)

web/oss/src/components/AgentChatSlice/components/ToolActivity.tsx
sdks/python/agenta/sdk/agents/tools/models.py
services/runner/src/tools/relay.ts
web/oss/src/components/AgentChatSlice/assets/toolDisplay.ts
services/runner/tests/unit/tool-direct.test.ts
sdks/python/oss/tests/pytest/unit/agents/platform/test_op_catalog.py
services/runner/src/tools/direct.ts
services/runner/src/protocol.ts
sdks/python/agenta/sdk/agents/platform/op_catalog.py
sdks/python/agenta/sdk/agents/platform/platform_tools.py
sdks/python/oss/tests/pytest/unit/agents/platform/test_op_catalog_description.py

mmabrouk

lgtm

github-actions · 2026-08-06T11:44:44Z

Railway Preview Environment


Status	Destroyed (PR closed)

Updated at 2026-08-07T09:42:44.561Z

Builder ops accept an optional ephemeral description. The runner strips it from the arguments before dispatch on both branches (spec-level strip, before assembleBody, so args_into cannot fold it into the payload). The agent chat tool card shows it. Also corrects a misleading assembleBody docstring: an unresolved binding throws, it is not left unset.

…e catalog cap (CodeRabbit)

…isplay override under Claude)

feat(sdk): let a builder tool call carry the agent's own note

mmabrouk commented Aug 5, 2026

View reviewed changes

Comment thread sdks/python/agenta/sdk/agents/platform/op_catalog.py

mmabrouk commented Aug 5, 2026

View reviewed changes

Comment thread sdks/python/agenta/sdk/agents/platform/op_catalog.py

coderabbitai Bot reviewed Aug 5, 2026

View reviewed changes

Comment thread web/oss/src/components/AgentChatSlice/assets/toolDisplay.ts Outdated

mmabrouk force-pushed the agent-config-editing-s5 branch from fc8740d to dabe419 Compare August 5, 2026 21:19

mmabrouk force-pushed the agent-config-editing-s4 branch from 216ab63 to 447c544 Compare August 5, 2026 21:19

vercel Bot deployed to Preview August 5, 2026 21:21 View deployment

mmabrouk force-pushed the agent-config-editing-s5 branch from dabe419 to 8886dd9 Compare August 5, 2026 21:48

mmabrouk force-pushed the agent-config-editing-s4 branch from 447c544 to 829b266 Compare August 5, 2026 21:48

vercel Bot deployed to Preview August 5, 2026 21:50 View deployment

coderabbitai Bot reviewed Aug 5, 2026

View reviewed changes

Comment thread web/oss/src/components/AgentChatSlice/assets/toolDisplay.test.ts

mmabrouk commented Aug 6, 2026

View reviewed changes

mmabrouk force-pushed the agent-config-editing-s5 branch from 8886dd9 to df3dc1e Compare August 6, 2026 11:10

mmabrouk force-pushed the agent-config-editing-s4 branch from 829b266 to f07fa00 Compare August 6, 2026 11:10

vercel Bot deployed to Preview August 6, 2026 11:11 View deployment

mmabrouk marked this pull request as ready for review August 6, 2026 11:35

dosubot Bot added size:L This PR changes 100-499 lines, ignoring generated files. Backend enhancement New feature or request Frontend SDK labels Aug 6, 2026

mmabrouk added the lgtm This PR has been approved by a maintainer label Aug 6, 2026

vercel Bot deployed to Preview August 6, 2026 12:40 View deployment

mmabrouk force-pushed the agent-config-editing-s5 branch from df3dc1e to 1a5e248 Compare August 6, 2026 13:19

mmabrouk force-pushed the agent-config-editing-s4 branch from dbc47ba to b364fbf Compare August 6, 2026 13:19

vercel Bot deployed to Preview August 6, 2026 13:21 View deployment

mmabrouk force-pushed the agent-config-editing-s5 branch from 1a5e248 to 8fe8b6c Compare August 6, 2026 14:14

mmabrouk force-pushed the agent-config-editing-s4 branch from b364fbf to 7f97902 Compare August 6, 2026 14:14

vercel Bot deployed to Preview August 6, 2026 14:16 View deployment

mmabrouk force-pushed the agent-config-editing-s5 branch from 8fe8b6c to 98b9826 Compare August 6, 2026 14:57

mmabrouk force-pushed the agent-config-editing-s4 branch from 7f97902 to bc0e91a Compare August 6, 2026 14:57

vercel Bot deployed to Preview August 6, 2026 14:59 View deployment

mmabrouk force-pushed the agent-config-editing-s5 branch from 98b9826 to 9abf2a0 Compare August 6, 2026 15:12

mmabrouk force-pushed the agent-config-editing-s4 branch from bc0e91a to 06525cc Compare August 6, 2026 15:13

vercel Bot deployed to Preview August 6, 2026 15:14 View deployment

mmabrouk force-pushed the agent-config-editing-s5 branch from 9abf2a0 to 2c90d37 Compare August 6, 2026 15:59

mmabrouk force-pushed the agent-config-editing-s4 branch from 06525cc to 521cdc4 Compare August 6, 2026 15:59

vercel Bot deployed to Preview August 6, 2026 16:01 View deployment

mmabrouk added 3 commits August 6, 2026 19:12

fix(frontend): description truncation counts code points, matching th…

957a937

…e catalog cap (CodeRabbit)

fix(frontend): canonical tool name unwraps the internal MCP prefix (d…

26f59ea

…isplay override under Claude)

mmabrouk force-pushed the agent-config-editing-s5 branch from 2c90d37 to 4a24d43 Compare August 6, 2026 17:12

mmabrouk force-pushed the agent-config-editing-s4 branch from 521cdc4 to 26f59ea Compare August 6, 2026 17:13

vercel Bot deployed to Preview August 6, 2026 17:14 View deployment

mmabrouk changed the base branch from agent-config-editing-s5 to release/v0.110.0 August 7, 2026 09:42

mmabrouk merged commit d4d1c4a into release/v0.110.0 Aug 7, 2026
63 checks passed

mmabrouk deleted the agent-config-editing-s4 branch August 7, 2026 10:20

mmabrouk added a commit that referenced this pull request Aug 7, 2026

Merge pull request #5747 from Agenta-AI/agent-config-editing-s4

38d1422

feat(sdk): let a builder tool call carry the agent's own note

Uh oh!

Conversation

mmabrouk commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Context

Changes

Tests / notes

What to QA

Added by the E2E campaign and review fix rounds (5 Aug, evening)

Uh oh!

vercel Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

Uh oh!

mmabrouk Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

mmabrouk Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mmabrouk commented Aug 5, 2026

Uh oh!

coderabbitai Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mmabrouk commented Aug 5, 2026

Uh oh!

coderabbitai Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Aug 5, 2026

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mmabrouk left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Railway Preview Environment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

mmabrouk commented Aug 5, 2026 •

edited

Loading

vercel Bot commented Aug 5, 2026 •

edited

Loading

coderabbitai Bot commented Aug 5, 2026 •

edited

Loading

coderabbitai Bot commented Aug 5, 2026 •

edited

Loading

coderabbitai Bot commented Aug 5, 2026 •

edited

Loading

github-actions Bot commented Aug 6, 2026 •

edited

Loading