Skip to content

feat(frontend): reference a workflow as an agent tool (type:"reference")#4877

Merged
mmabrouk merged 2 commits into
big-agentsfrom
fe-feat/agent-embedref-tools-onbig
Jun 27, 2026
Merged

feat(frontend): reference a workflow as an agent tool (type:"reference")#4877
mmabrouk merged 2 commits into
big-agentsfrom
fe-feat/agent-embedref-tools-onbig

Conversation

@ardaerzin

Copy link
Copy Markdown
Contributor

Context

An agent's tools could not be authored as a workflow. Backend PR #4860 added the @ag.reference syntax: a tool that points at a stored workflow, which Agenta runs server-side as a callback. This is the frontend for it.

Changes

A workflow can be referenced as a tool two ways:

  • A "Reference a workflow" section in the tool selector, with a + that opens a searchable workflow-picker drawer. Picking one adds the reference tool with the workflow's input schema.
  • Inline @-mentions in the instructions editor: a typeahead inserts a reference chip and registers the tool (dedup-guarded). Hovering a chip shows a read-only details card.

Reference tools render with a workflow icon and are classified distinctly from builtin/gateway/code tools.

The tools[] entry the FE emits:

{ "@ag.reference": {"@ag.references": {"workflow": {"slug": "summarize"}}},
  "name": "summarize", "description": "...", "input_schema": {...} }

Notes

What to QA

  • In an agent's tools, open the tool selector. "Reference a workflow" has a + that opens a drawer; pick a workflow; it shows up as a workflow tool.
  • In the instructions, type @ and pick a workflow. A chip inserts and the tool is added. Picking one already added does not duplicate it.
  • Hover a chip: a card shows the name, kind, and description.
  • Regression: builtin/gateway/code tools still add and render as before.

@vercel

vercel Bot commented Jun 26, 2026

Copy link
Copy Markdown

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

Project Deployment Actions Updated (UTC)
agenta-documentation Ready Ready Preview, Comment Jun 27, 2026 5:06pm

Request Review

@coderabbitai

coderabbitai Bot commented Jun 26, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c08ef336-29e9-44cc-af6b-bea13b42b2fc

📥 Commits

Reviewing files that changed from the base of the PR and between 80ee74c and ad3e468.

📒 Files selected for processing (10)
  • web/oss/src/components/DrillInView/OSSdrillInUIProvider.tsx
  • web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/AgentConfigControl.tsx
  • web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/ToolItemControl.tsx
  • web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/ToolSelectorPopover.tsx
  • web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/WorkflowReferenceSelector.tsx
  • web/packages/agenta-entity-ui/src/DrillInView/index.ts
  • web/packages/agenta-ui/src/drill-in/context.ts
  • web/packages/agenta-ui/src/drill-in/context/DrillInUIContext.tsx
  • web/packages/agenta-ui/src/drill-in/context/index.ts
  • web/packages/agenta-ui/src/drill-in/index.ts
✅ Files skipped from review due to trivial changes (1)
  • web/packages/agenta-ui/src/drill-in/context/index.ts
🚧 Files skipped from review as they are similar to previous changes (9)
  • web/packages/agenta-ui/src/drill-in/index.ts
  • web/packages/agenta-ui/src/drill-in/context.ts
  • web/packages/agenta-entity-ui/src/DrillInView/index.ts
  • web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/ToolSelectorPopover.tsx
  • web/packages/agenta-ui/src/drill-in/context/DrillInUIContext.tsx
  • web/oss/src/components/DrillInView/OSSdrillInUIProvider.tsx
  • web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/ToolItemControl.tsx
  • web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/WorkflowReferenceSelector.tsx
  • web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/AgentConfigControl.tsx

📝 Walkthrough

Summary by CodeRabbit

  • New Features
    • Added support for referencing workflows as tools in the drill-in UI.
    • Users can now browse workflows, choose a revision or environment, and add them as selectable tools.
    • Workflow-referenced tools now display clearer labels, icons, and details in tool lists.
  • Bug Fixes
    • Improved tool handling so workflow references are shown separately from built-in tools.
    • Added safer schema handling when adding workflow references to avoid breaking edits.

Walkthrough

Adds workflow-reference tool support to DrillIn. New types define the bridge and payload shapes, OSS provider code supplies workflow revision and environment data, and the UI now lets users pick, add, list, and render reference-type tools.

Changes

Workflow Reference Tool Feature

Layer / File(s) Summary
WorkflowReference type contracts and re-exports
web/packages/agenta-ui/src/drill-in/context/DrillInUIContext.tsx, web/packages/agenta-ui/src/drill-in/context/index.ts, web/packages/agenta-ui/src/drill-in/context.ts, web/packages/agenta-ui/src/drill-in/index.ts, web/packages/agenta-entity-ui/src/DrillInView/index.ts
Defines the workflow-reference UI, payload, and bridge types; extends DrillInUIComponents with workflowReference; re-exports the new types through the drill-in package entry points.
OSS WorkflowReferenceBridge implementation and provider wiring
web/oss/src/components/DrillInView/OSSdrillInUIProvider.tsx
Builds workflow revision and environment hooks, maps API results into workflow-reference UI shapes, creates the workflowReference bridge, and injects it into DrillInUIProvider through both OSS provider branches.
WorkflowReferenceSelector drawer
web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/WorkflowReferenceSelector.tsx
Implements the workflow picker drawer with search, revision or environment reference selection, confirmation payload creation, reset behavior, and cancel or add actions.
ToolSelectorPopover: Reference a workflow entry
web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/ToolSelectorPopover.tsx
Adds the workflow-reference catalog entry, its enabling callback, the popover close-and-open handler, and the conditional UI section that launches the selector.
ToolItemControl: reference tool detection and rendering
web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/ToolItemControl.tsx
Detects reference tools, extracts reference metadata, renders the reference header variant, keeps reference tools collapsed, and disables schema validation for them in both editor paths.
AgentConfigControl: add and display reference tools
web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/AgentConfigControl.tsx
Consumes workflowReference from DrillIn UI, derives reference slugs for deduplication, labels reference tools, appends reference tools with resolved input schemas, filters already referenced workflows, and renders the selector drawer.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 46.67% 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
Title check ✅ Passed The title clearly summarizes the main change: adding workflow references as agent tools.
Description check ✅ Passed The description matches the change set and explains the new workflow-reference authoring flow.
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.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch fe-feat/agent-embedref-tools-onbig

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 mmabrouk force-pushed the feat/agent-embedref-tools branch from 7162a4d to 4bb6f16 Compare June 26, 2026 14:29
@mmabrouk mmabrouk force-pushed the fe-feat/agent-embedref-tools-onbig branch from 58f2737 to dd0bfa8 Compare June 27, 2026 14:57
@mmabrouk mmabrouk force-pushed the fe-feat/agent-embedref-tools-onbig branch from dd0bfa8 to 80ee74c Compare June 27, 2026 15:02
@mmabrouk mmabrouk changed the title feat(frontend): reference a workflow as an agent tool (@ag.reference) feat(frontend): reference a workflow as an agent tool (type:"reference") Jun 27, 2026
@mmabrouk mmabrouk added the needs-review Agent updated; awaiting Mahmoud's review label Jun 27, 2026
@mmabrouk

Copy link
Copy Markdown
Member

Reworked the FE onto the new #4860 schema (type:"reference", marker dropped)

Took over this branch (thanks @ardaerzin) and rebuilt the frontend on top of #4860's new commit af95f2700d, which removed the @ag.reference marker and changed ReferenceToolConfig to {ref_by, slug, version?, environment?, name, description, input_schema}. This branch is rebased onto the new feat/agent-embedref-tools tip; the diff is web-only (10 files).

Each FE task from plan.md → "Tasks on #4877" → what changed:

  1. Author as type:"reference", not the marker. AgentConfigControl.handleAddWorkflowReference now emits {type:"reference", ref_by, slug, version?, environment?, name, description, input_schema}. Detection (describeTool, toolReferenceSlug, ToolItemControl.inferIsReferenceTool) keys on type === "reference" instead of the @ag.reference marker.
  2. Environment-or-variant + version selector. WorkflowReferenceSelector is now a two-step drawer: pick a workflow (the slug) → pick an axis (Variant | Environment) → on Variant pick Latest or a specific revision (version), on Environment pick an environment. The WorkflowReferenceBridge gained useWorkflowRevisions + useWorkflowEnvironments, implemented in OSSdrillInUIProvider against the workflow-revisions query and the app-environments atoms. Confirming emits exactly the ReferenceToolConfig shape above.
  3. Embed hidden from the tool UI. There is no @ag.embed option in the tool picker; embed stays backend-only (the skills @ag.embed control is a separate feature and is untouched).
  4. Retitled away from "@ag.reference".

Judgment call — please confirm: I did not carry over the marker-era Lexical @-mention editor plugin (the in-instructions @ag.reference typeahead + chip subsystem, ~900 lines under agenta-ui/src/Editor/plugins/reference/*). It existed only to author the now-removed marker and cannot express the env/variant/version axes. Reference authoring is now solely the tool-selector drawer. If an in-editor shortcut is still wanted, it would need to emit the new type:"reference" shape.

What I need from review:

  • (a) Code review of the FE rework (bridge + selector + AgentConfigControl/ToolItemControl detection/emission).
  • (b) UX check of the new env/variant/version drawer flow.
  • (c) Confirm the editor-plugin removal decision in the judgment call above.

Notes for the maintainer:

@mmabrouk

Copy link
Copy Markdown
Member

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jun 27, 2026

Copy link
Copy Markdown
✅ 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.

Author a workflow reference as a type:"reference" tool (the @ag.reference
marker is dropped). The tool selector's "Reference a workflow" drawer now
picks an axis (variant or environment), a workflow slug, and either a pinned
version (variant axis) or an environment, emitting ReferenceToolConfig
{ref_by, slug, version?, environment?, name, description, input_schema}.
Removes the marker-era @-mention editor plugin; embed stays backend-only and
out of the tool UI.

Claude-Session: https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 8


ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: f7bfbcb1-5a84-47d6-9e57-b38d84524140

📥 Commits

Reviewing files that changed from the base of the PR and between af95f27 and 80ee74c.

📒 Files selected for processing (10)
  • web/oss/src/components/DrillInView/OSSdrillInUIProvider.tsx
  • web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/AgentConfigControl.tsx
  • web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/ToolItemControl.tsx
  • web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/ToolSelectorPopover.tsx
  • web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/WorkflowReferenceSelector.tsx
  • web/packages/agenta-entity-ui/src/DrillInView/index.ts
  • web/packages/agenta-ui/src/drill-in/context.ts
  • web/packages/agenta-ui/src/drill-in/context/DrillInUIContext.tsx
  • web/packages/agenta-ui/src/drill-in/context/index.ts
  • web/packages/agenta-ui/src/drill-in/index.ts

Comment on lines +193 to +196
...revisions.map((r) => ({
label: r.label ? `v${r.version} — ${r.label}` : `v${r.version}`,
value: r.version,
})),

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Reflow this option label so the web checks pass.

This is the formatter error currently failing the TypeScript lint/format jobs for this file. As per coding guidelines, "Frontend changes require running pnpm lint-fix within the web folder before committing."

🧰 Tools
🪛 GitHub Actions: 11 - check code styling / 2_TypeScript lint.txt

[error] 194-194: prettier/prettier error: Replace formatting around template string. (Rule: prettier/prettier)

🪛 GitHub Actions: 11 - check code styling / TypeScript lint

[error] 194-194: Prettier formatting failed (eslint plugin). Rule: prettier/prettier. Replace ·?·v${r.version}·—·${r.label} with a properly line-broken template string.

🪛 GitHub Check: TypeScript lint

[failure] 194-194:
Replace ·?·v${r.version}·—·${r.label}`` with ⏎············································?·v${r.version}·—·${r.label}`⏎···········································`

Sources: Coding guidelines, Linters/SAST tools, Pipeline failures

Comment on lines +134 to +136
/** Resolve the referenced workflow's input JSON-schema to pre-fill the tool's `input_schema`.
* Returns null when unavailable; the caller falls back to an empty object schema. */
resolveInputSchema: (workflow: WorkflowReferenceUI) => Promise<Record<string, unknown> | null>

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Thread the selected reference target into resolveInputSchema.

This contract only passes the workflow identity, but downstream the tool payload can also pin a version or bind to an environment. As written, a reference to an older revision or environment-specific deployment can only resolve the schema for the workflow’s default/latest revision, so the emitted input_schema can drift from the actual referenced target.

Suggested contract change
-    resolveInputSchema: (workflow: WorkflowReferenceUI) => Promise<Record<string, unknown> | null>
+    resolveInputSchema: (
+        workflow: WorkflowReferenceUI,
+        selection: Pick<WorkflowReferencePayload, "refBy" | "version" | "environment">
+    ) => Promise<Record<string, unknown> | null>
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
/** Resolve the referenced workflow's input JSON-schema to pre-fill the tool's `input_schema`.
* Returns null when unavailable; the caller falls back to an empty object schema. */
resolveInputSchema: (workflow: WorkflowReferenceUI) => Promise<Record<string, unknown> | null>
/** Resolve the referenced workflow's input JSON-schema to pre-fill the tool's `input_schema`.
* Returns null when unavailable; the caller falls back to an empty object schema. */
resolveInputSchema: (
workflow: WorkflowReferenceUI,
selection: Pick<WorkflowReferencePayload, "refBy" | "version" | "environment">
) => Promise<Record<string, unknown> | null>

Comment on lines +11 to +15
type WorkflowReferenceBridge,
type WorkflowReferenceUI,
type WorkflowRevisionUI,
type WorkflowEnvironmentUI,
type WorkflowReferencePayload,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Please rerun the required web autofix/format step before merge.

This frontend change set is still failing the TypeScript formatting check in CI. Please run pnpm lint-fix in web and commit the resulting formatting updates. As per coding guidelines, "Frontend changes require running pnpm lint-fix within the web folder before committing".

Sources: Coding guidelines, Pipeline failures

@mmabrouk mmabrouk force-pushed the feat/agent-embedref-tools branch from af95f27 to 63318ac Compare June 27, 2026 15:16
@mmabrouk mmabrouk force-pushed the fe-feat/agent-embedref-tools-onbig branch from 80ee74c to 20f6636 Compare June 27, 2026 15:16
- reset axis state (refBy/version/environment) when the chosen workflow changes
- gate the workflow list empty-state on not-loading (real workflowsLoading)
- read fresh config after the async schema lookup so concurrent edits aren't clobbered
- store the workflow display name (not the slug) on the reference tool
- dedupe references by type:"reference" slug only, never gateway function names
- prettier-format the version-option label
@mmabrouk

Copy link
Copy Markdown
Member

🤖 The AI agent says:

Addressed the CodeRabbit review on this PR plus the failing TypeScript format + lint check.

Failing required check (format + lint)

Fixed. WorkflowReferenceSelector.tsx:196 was a prettier-format failure (the long version-option label ternary). Ran prettier --write + eslint --fix; prettier --check now passes on all three touched files. This also unblocks #4884 (stacked on this branch) — it has been re-pushed onto the new tip so its checks re-run on a base that includes the fix.

CodeRabbit findings

  1. WorkflowReferenceSelector.tsx — axis state not reset on workflow change → Fixed. Added a dedicated effect keyed on the selected workflow id that resets refBy/version/environment, so a previous workflow's pick can't bleed into a new reference. The open-effect now only resets search + selection.
  2. DrillInUIContext/resolveInputSchema — version/environment pin not threaded → Acknowledged, deferred. Threading the pin correctly is a larger refactor blocked by backend constraints: a per-variant version ref requires a variant ref (the backend returns HTTP 400 for workflow-ref + version alone), and there is no environment→deployed-revision lookup exposed by the bridge. The input schema is generally stable across a workflow's revisions, so the current latest-schema prefill is a safe approximation; forcing a version ref now would 400 and fall back to an empty schema (worse than today). Left for a follow-up that adds variant resolution + an environment-deployment endpoint.
  3. AgentConfigControl.tsx — stale tools snapshot after the async schema lookup → Fixed. The reference handler now reads the freshest config via a ref after the await and writes through onChange, so a concurrent add/remove isn't clobbered. Dropped the stale tools/handleAddTool closure deps.
  4. AgentConfigControl.tsx — slug stored in the name field (rendered "slug / slug") → Fixed. The reference tool now stores the workflow display name (wf.name, falling back to slug), so ToolHeader reads "Name / slug".
  5. AgentConfigControl.tsx — dedup matched gateway function.name → Fixed. toolReferenceSlug now returns a slug only for type:"reference" tools (undefined otherwise), so an unrelated gateway tool with the same name can no longer shadow a workflow at either dedup site (the add-guard and the referenceable-workflow pool).
  6. WorkflowReferenceSelector.tsx — empty-state shown during the initial fetch → Fixed. The list now shows a spinner while loading and the empty-state only when not loading. Wired the OSS bridge's workflowsLoading to the real workflowsListQueryStateAtom.isPending (it had been hardcoded false).

Gates

  • @agenta/entity-ui type-check (with @agenta/ui / @agenta/entities / @agenta/shared) clean.
  • @agenta/entity-ui unit suite: 126/126 green.
  • prettier --check + eslint clean on all touched files.
  • web/ diff is exactly 3 files: OSSdrillInUIProvider.tsx, AgentConfigControl.tsx, WorkflowReferenceSelector.tsx.

@mmabrouk

Copy link
Copy Markdown
Member

🤖 The AI agent says: re-requesting a review now that the review feedback and the format/lint failure are addressed.

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jun 27, 2026

Copy link
Copy Markdown

@mmabrouk Taking another pass now on the updated PR, including the addressed feedback and the format/lint fixes.

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

@mmabrouk mmabrouk changed the base branch from feat/agent-embedref-tools to big-agents June 27, 2026 18:12
@mmabrouk mmabrouk marked this pull request as ready for review June 27, 2026 18:13
@dosubot dosubot Bot added the size:XL This PR changes 500-999 lines, ignoring generated files. label Jun 27, 2026
@mmabrouk mmabrouk merged commit b9b4adf into big-agents Jun 27, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

feature Frontend needs-review Agent updated; awaiting Mahmoud's review size:XL This PR changes 500-999 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants