[docs] Add agent workflow interface inventory#4821
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughAdds an agent-workflows interface inventory, expands the documentation layout into public-edge, cross-service, and in-service contract pages, and updates existing design docs to reference the inventory plus revised ChangesAgent workflow interface inventory
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~30 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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. Comment |
mmabrouk
force-pushed
the
docs/agent-workflow-interface-inventory
branch
from
6c2a74f to
8d79e58
Compare
mmabrouk
force-pushed
the
docs/agent-workflow-interface-inventory
branch
from
8d79e58 to
cf0ceee
Compare
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
mmabrouk
force-pushed
the
docs/agent-workflow-interface-inventory
branch
from
cf0ceee to
a6a9236
Compare
mmabrouk
force-pushed
the
docs/agent-workflow-interface-inventory
branch
from
a6a9236 to
e6549ae
Compare
mmabrouk
force-pushed
the
docs/agent-workflow-interface-inventory
branch
from
e6549ae to
2d80f90
Compare
| | `tools` | `ToolConfig[]` | `[]` | Runnable tools: `builtin`, `gateway`, `code`, or `client`. See [Tool models and resolution](../in-service/tool-models-and-resolution.md). | | ||
| | `mcp_servers` | `MCPServerConfig[]` | `[]` | Declared MCP servers; secret env resolved from the vault at run time. See [MCP models and resolution](../in-service/mcp-models-and-resolution.md). | | ||
| | `harness` | `"pi" \| "claude" \| "agenta"` | `"pi"` | The coding agent to drive. | | ||
| | `sandbox` | `"local" \| "daytona"` | `"local"` | Where it runs. | |
There was a problem hiding this comment.
instead we should have an optional uri that points to sidecar and provide an address of the thing (the sandbox should probably use this uri to determine where to route the request). if the uri is not set then we use the environment variabels
There was a problem hiding this comment.
Noted as a design follow-up (added to docs/design/agent-workflows/scratch/implementation-queue.md), not yet scheduled. The idea: an optional uri in the agent config that points at the sidecar and provides its address — the sandbox uses it to route the request, and we fall back to the env vars when it's unset. Routes near the sidecar-deployment / sidecar-trust work. Not editing the schema page now to avoid colliding with the running contract-versioning work on this surface.
There was a problem hiding this comment.
Implemented: uri replaces sandbox (allowlist-gated routing) — PR #4836.
| | `mcp_servers` | `MCPServerConfig[]` | `[]` | Declared MCP servers; secret env resolved from the vault at run time. See [MCP models and resolution](../in-service/mcp-models-and-resolution.md). | | ||
| | `harness` | `"pi" \| "claude" \| "agenta"` | `"pi"` | The coding agent to drive. | | ||
| | `sandbox` | `"local" \| "daytona"` | `"local"` | Where it runs. | | ||
| | `permission_policy` | `"auto" \| "deny"` | `"auto"` | How a gating harness (Claude Code) handles tool-use prompts in a headless run. | |
There was a problem hiding this comment.
this is wrong. we were supposed to have a general harness_kwargs where the user can set {"claude":{whatever we want to add to claude) if this is specific.
on the other hand we had permissions that determined how the sidecar delt with certain action. permission_policy what supposed to be that. while harness_kwargs is where the user can set permission or anything else for the different harnesses passed by key
There was a problem hiding this comment.
Routed, and thanks for the correction. The intent: a general per-harness harness_kwargs bag ({"claude": {…}}) where the author sets per-harness options including permissions, while permission_policy is the sidecar action-permission (how the sidecar handles a tool action), not a harness option. That's a design direction overlapping the in-flight contract-versioning / capability-config surface, so it's routed there; the inventory's current permission_policy/Claude-options wording will be corrected once that settles. Not editing the agent-config-schema page now (running work owns it).
There was a problem hiding this comment.
Implemented: harness_kwargs per-harness bag (was harness_options); permission_policy stays the sidecar action-permission, on AgentConfig — PR #4840.
| | Field | Type | Default | Meaning | | ||
| |---|---|---|---| | ||
| | `agents_md` | string (textarea) | hello-world prompt | The agent's system prompt, its AGENTS.md. | | ||
| | `model` | string (`grouped_choice`) | `"gpt-5.5"` | Model the agent runs on. A plain id (`"gpt-5.5"`) or a structured `{provider, connection}` ref. See [Model connection resolution](../in-service/model-connection-resolution.md). | |
There was a problem hiding this comment.
this is wrong, we never provide a string here, it is always structured. we should use the ModelRef which would include the provider, model, connectin.. etc..
There was a problem hiding this comment.
Routed. model as a structured ModelRef (provider, model, connection, …) is exactly the direction of the in-flight provider-model-auth / agent-model-picker work (ModelRef already landed via PR #4815; the picker is docs/design/agent-workflows/projects/agent-model-picker/). The inventory still describes model as a bare string for back-compat coercion; that wording will be corrected once that surface settles. Not editing the agent-config-schema page now to avoid colliding with the running contract-versioning work on the same surface.
There was a problem hiding this comment.
Implemented: model is always a structured ModelRef now (free-text path dropped) — PR #4839.
| |---|---|---|---| | ||
| | `agents_md` | string (textarea) | hello-world prompt | The agent's system prompt, its AGENTS.md. | | ||
| | `model` | string (`grouped_choice`) | `"gpt-5.5"` | Model the agent runs on. A plain id (`"gpt-5.5"`) or a structured `{provider, connection}` ref. See [Model connection resolution](../in-service/model-connection-resolution.md). | | ||
| | `tools` | `ToolConfig[]` | `[]` | Runnable tools: `builtin`, `gateway`, `code`, or `client`. See [Tool models and resolution](../in-service/tool-models-and-resolution.md). | |
There was a problem hiding this comment.
we should also allow here embedref like skills. these would allow creating tools as workflows and embedding them.
There was a problem hiding this comment.
Noted as a design follow-up (added to the implementation queue), not yet scheduled. The idea: allow an EmbedRef in tools (the way skills already accepts SkillConfig | EmbedRef), so a tool can be authored as a workflow and embedded/inlined by the backend before the runner sees it. Overlaps the tool-definition + skills-embed surface. Parking it in the queue for triage rather than editing the inventory now.
There was a problem hiding this comment.
Designed: embedref tools-as-workflows — PR #4837 (runnable→callback, non-runnable→client; simplified).
Rewrite sandbox-permission.md with the code-verified enforcement matrix:
network egress IS enforced on Daytona (provider.ts daytonaNetworkFields ->
networkBlockAll/networkAllowList), is NOT enforceable on local (run-plan.ts
rejects restricted+strict), and the filesystem boundary is enforced nowhere;
code/gateway tools and the stdio MCP bridge run on the runner host so they
bypass the sandbox even on Daytona. Drops the stale 'declared, not enforced'
framing.
Align runtime-ports.md and harness-adapters.md to the strong-page template
(cross-link, tests-that-move-with-it). Correct the Claude skills claim: Claude
carries inline skills on the wire and the runner materializes them under
.claude/skills (the old wire_skills()->{} override is gone, pinned by
test_claude_carries_skills_for_project_local_materialization).
Claude-Session: https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc
…apters.md, fix two doc inaccuracies The inventory re-documented material already in documentation/protocol.md and documentation/ports-and-adapters.md with no links. Add reciprocal cross-links framed by ownership: the inventory owns the 'what crosses / what can break / what to check' review lens; the documentation/ docs own the field-by-field narrative. Links added on service-to-agent-runner, agent-messages, workflow-invoke, browser-protocol-adapter, backend-adapter, neutral-runtime-dtos (and protocol.md / ports-and-adapters.md back). Fix two clear, code-verified inaccuracies: - protocol.md said skills are 'bundled directory names to force-load (agenta, Pi only)'. They are resolved inline packages (full SKILL.md content, @ag.embed inlined server-side) declared in the agent config; all three harnesses wire them (Claude inherits the base wire_skills; the runner materializes them under .claude/skills). Verified against dtos.py and harness adapter tests. - ports-and-adapters.md cited a stale line number (app.py:49 is now an import, not the SandboxAgentBackend build); drop the brittle :49 suffix. - Replace the stale 'declared, not enforced' sandbox-permission framing in agent-config-schema.md and service-to-agent-runner.md with the real matrix (network enforced on Daytona) plus a link to the matrix. The tool gateway, Composio, connections, and MCP are described as EXISTING and UNCHANGED by this doc PR. Claude-Session: https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc
One row per interface with Interface | Blast radius | Owner file(s) | Status | Tests, so a reviewer can find the boundary a diff touches before opening a page. Status is derived from each page's prose (stable / evolving / declared-not-wired). The /load-session shell endpoint is intentionally omitted because a sibling change is removing it. Claude-Session: https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
🧹 Nitpick comments (2)
docs/design/agent-workflows/interfaces/in-service/model-connection-resolution.md (1)
40-42: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winLink the capability matrix instead of repeating counts.
This paragraph is likely to drift as harness support changes. Point readers to the canonical capability table rather than hard-coding provider totals here.
♻️ Proposed wording tweak
- Each harness publishes what it can reach: Pi reaches eight direct providers; Claude reaches Anthropic across direct, custom, bedrock, and vertex. Unnamed default connections degrade tolerantly to an empty env rather than failing the run. + Each harness publishes its reachable providers in the capability matrix; link that matrix here instead of repeating the counts. Unnamed default connections degrade tolerantly to an empty env rather than failing the run.docs/design/agent-workflows/interfaces/README.md (1)
47-47: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winMark the agent-config row as evolving.
The PR notes say
agent-config-schema.mdis still absorbing contract-versioning follow-ups, sostableoverstates how settled this surface is.evolvingwould better match the inventory's own status definitions.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: de4eea18-84f0-4646-a4d6-db878bd48406
📒 Files selected for processing (30)
docs/design/agent-workflows/README.mddocs/design/agent-workflows/documentation/ports-and-adapters.mddocs/design/agent-workflows/documentation/protocol.mddocs/design/agent-workflows/interfaces/README.mddocs/design/agent-workflows/interfaces/cross-service/README.mddocs/design/agent-workflows/interfaces/cross-service/runner-to-harness.mddocs/design/agent-workflows/interfaces/cross-service/runner-to-mcp-server.mddocs/design/agent-workflows/interfaces/cross-service/runner-to-tool-callback.mddocs/design/agent-workflows/interfaces/cross-service/service-and-runner-trace-export.mddocs/design/agent-workflows/interfaces/cross-service/service-to-agent-runner.mddocs/design/agent-workflows/interfaces/cross-service/service-to-vault-and-tool-providers.mddocs/design/agent-workflows/interfaces/in-service/README.mddocs/design/agent-workflows/interfaces/in-service/agent-service-handler.mddocs/design/agent-workflows/interfaces/in-service/backend-adapter.mddocs/design/agent-workflows/interfaces/in-service/browser-protocol-adapter.mddocs/design/agent-workflows/interfaces/in-service/harness-adapters.mddocs/design/agent-workflows/interfaces/in-service/mcp-models-and-resolution.mddocs/design/agent-workflows/interfaces/in-service/model-connection-resolution.mddocs/design/agent-workflows/interfaces/in-service/neutral-runtime-dtos.mddocs/design/agent-workflows/interfaces/in-service/permission-responder.mddocs/design/agent-workflows/interfaces/in-service/runner-engine-internals.mddocs/design/agent-workflows/interfaces/in-service/runtime-ports.mddocs/design/agent-workflows/interfaces/in-service/sandbox-permission.mddocs/design/agent-workflows/interfaces/in-service/tool-models-and-resolution.mddocs/design/agent-workflows/interfaces/public-edge/README.mddocs/design/agent-workflows/interfaces/public-edge/agent-config-schema.mddocs/design/agent-workflows/interfaces/public-edge/agent-load-session.mddocs/design/agent-workflows/interfaces/public-edge/agent-messages.mddocs/design/agent-workflows/interfaces/public-edge/workflow-inspect.mddocs/design/agent-workflows/interfaces/public-edge/workflow-invoke.md
| "data": { | ||
| "id": "call_zEoV...", // the LLM tool_call_id, echoed back for correlation | ||
| "type": "function", | ||
| "function": { | ||
| "name": "tools.composio.github.create_issue.my_conn", // resolved tool slug | ||
| "arguments": { "title": "..." } // sent as an object, not a JSON string | ||
| } |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Don’t narrow the callback arguments contract.
ToolCallFunction.arguments can still be a JSON string at the boundary, so the example should not claim object-only input.
Suggested wording
- "arguments": { "title": "..." } // sent as an object, not a JSON string
+ "arguments": { "title": "..." } // JSON string or object; router normalizes it📝 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.
| "data": { | |
| "id": "call_zEoV...", // the LLM tool_call_id, echoed back for correlation | |
| "type": "function", | |
| "function": { | |
| "name": "tools.composio.github.create_issue.my_conn", // resolved tool slug | |
| "arguments": { "title": "..." } // sent as an object, not a JSON string | |
| } | |
| "data": { | |
| "id": "call_zEoV...", // the LLM tool_call_id, echoed back for correlation | |
| "type": "function", | |
| "function": { | |
| "name": "tools.composio.github.create_issue.my_conn", // resolved tool slug | |
| "arguments": { "title": "..." } // JSON string or object; router normalizes it | |
| } |
| // tracing (see service-and-runner-trace-export.md) | ||
| "trace": { "traceparent": "...", "endpoint": "...", "authorization": "...", "captureContent": true } | ||
| } |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
git ls-files 'docs/design/agent-workflows/interfaces/cross-service/*' | sed 's#^`#FILE` #'
printf '\n--- baggage search ---\n'
rg -n --no-heading '\bbaggage\b|traceparent|captureContent|authorization' docs/design/agent-workflows/interfaces/cross-service
printf '\n--- trace-related file contents (selected) ---\n'
for f in \
docs/design/agent-workflows/interfaces/cross-service/service-to-agent-runner.md \
docs/design/agent-workflows/interfaces/cross-service/service-and-runner-trace-export.md
do
echo "FILE: $f"
wc -l "$f"
doneRepository: Agenta-AI/agenta
Length of output: 2976
🏁 Script executed:
#!/bin/bash
set -euo pipefail
git ls-files 'docs/design/agent-workflows/interfaces/cross-service/*' | sed 's#^`#FILE` #'
printf '\n--- baggage search ---\n'
rg -n --no-heading '\bbaggage\b|traceparent|captureContent|authorization' docs/design/agent-workflows/interfaces/cross-service
printf '\n--- trace-related file contents (selected) ---\n'
for f in \
docs/design/agent-workflows/interfaces/cross-service/service-to-agent-runner.md \
docs/design/agent-workflows/interfaces/cross-service/service-and-runner-trace-export.md
do
echo "FILE: $f"
wc -l "$f"
doneRepository: Agenta-AI/agenta
Length of output: 2976
🏁 Script executed:
#!/bin/bash
set -euo pipefail
sed -n '48,78p' docs/design/agent-workflows/interfaces/cross-service/service-to-agent-runner.md
printf '\n---\n'
sed -n '1,28p' docs/design/agent-workflows/interfaces/cross-service/service-and-runner-trace-export.md
printf '\n---\n'
sed -n '28,60p' docs/design/agent-workflows/interfaces/cross-service/service-and-runner-trace-export.mdRepository: Agenta-AI/agenta
Length of output: 4460
🏁 Script executed:
#!/bin/bash
set -euo pipefail
sed -n '48,78p' docs/design/agent-workflows/interfaces/cross-service/service-to-agent-runner.md
printf '\n---\n'
sed -n '1,28p' docs/design/agent-workflows/interfaces/cross-service/service-and-runner-trace-export.md
printf '\n---\n'
sed -n '28,60p' docs/design/agent-workflows/interfaces/cross-service/service-and-runner-trace-export.mdRepository: Agenta-AI/agenta
Length of output: 4460
Keep the /run trace block aligned. service-and-runner-trace-export.md includes baggage in the request contract, but this schema omits it. Add it here or remove it from the other doc so the wire shape stays consistent.
| A `Message` is `{role, content}`, where `content` is a plain string or a list of | ||
| `ContentBlock`. A bare string normalizes to one `text` block; a list of all-text blocks | ||
| collapses back to a string. The Python model is snake_case, the wire (`to_wire`) is | ||
| camelCase, and `from_raw` accepts either, so inbound coercion is forgiving. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Don’t say all-text lists collapse back to a string.
dtos.py preserves list-shaped content; to_wire() emits a list and from_raw() only coerces each element. If that normalization is intended, the implementation needs to change too; otherwise trim this sentence.
♻️ Proposed doc fix
- A bare string normalizes to one text block; a list of all-text blocks collapses back to a string.
+ A bare string normalizes to one text block; a list stays a list of `ContentBlock`s.📝 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.
| A `Message` is `{role, content}`, where `content` is a plain string or a list of | |
| `ContentBlock`. A bare string normalizes to one `text` block; a list of all-text blocks | |
| collapses back to a string. The Python model is snake_case, the wire (`to_wire`) is | |
| camelCase, and `from_raw` accepts either, so inbound coercion is forgiving. | |
| A `Message` is `{role, content}`, where `content` is a plain string or a list of | |
| `ContentBlock`. A bare string normalizes to one `text` block; a list stays a list of | |
| `ContentBlock`s. The Python model is snake_case, the wire (`to_wire`) is | |
| camelCase, and `from_raw` accepts either, so inbound coercion is forgiving. |
| **Decision extraction.** `extractApprovalDecisions(request)` scans the message history for | ||
| `tool_result` blocks whose output is `{approved: boolean}`, and indexes each by both its | ||
| `toolCallId` and its `toolName`. The tool name is the fallback because a cold replay can mint | ||
| a fresh permission id each turn, so the stable anchor is the name. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Clarify the cross-turn fallback order.
The implementation prefers toolCallId first and only falls back to toolName when the id is missing, so calling the name “the stable anchor” is backwards and may mislead future changes.
🛠️ Proposed wording fix
- The tool name is the fallback because a cold replay can mint a fresh permission id each turn, so the stable anchor is the name.
+ `toolCallId` is the primary match; `toolName` is only the fallback when the id is missing or rewritten on replay.📝 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.
| **Decision extraction.** `extractApprovalDecisions(request)` scans the message history for | |
| `tool_result` blocks whose output is `{approved: boolean}`, and indexes each by both its | |
| `toolCallId` and its `toolName`. The tool name is the fallback because a cold replay can mint | |
| a fresh permission id each turn, so the stable anchor is the name. | |
| **Decision extraction.** `extractApprovalDecisions(request)` scans the message history for | |
| `tool_result` blocks whose output is `{approved: boolean}`, and indexes each by both its | |
| `toolCallId` and its `toolName`. `toolCallId` is the primary match; `toolName` is only the fallback when the id is missing or rewritten on replay. |
| The route negotiates transport from the `Accept` header. `text/event-stream` returns a | ||
| Vercel UI Message Stream framed as SSE. Anything else returns a `WorkflowBatchResponse` | ||
| with one assistant message in `data.outputs`. The browser always sends | ||
| `Accept: text/event-stream`. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify the browser/chat clients always send Accept: text/event-stream.
rg -nP 'Accept.*text/event-stream|text/event-stream|application/x-ndjson|application/jsonl' \
web/packages/agenta-playground/src/state/execution/agentRequest.ts \
web/oss/src/components/AgentChatSlice/AgentChatPanel.tsx \
sdks/python/agenta/sdk/decorators/routing.py -C 3Repository: Agenta-AI/agenta
Length of output: 7088
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== agentRequest.ts context =="
sed -n '220,250p' web/packages/agenta-playground/src/state/execution/agentRequest.ts
echo
echo "== executionHeadersAtom definition and uses =="
rg -n "executionHeadersAtom|headersFactory|Accept:" web/packages/agenta-playground/src -C 2Repository: Agenta-AI/agenta
Length of output: 7219
Default the Accept header before merging overrides
web/packages/agenta-playground/src/state/execution/agentRequest.ts sets Accept: "text/event-stream" by default, but headersFactory is spread afterward and can override it. Either move the default after the merge or soften the docs from “always sends” to “sends by default.”
| "data": { | ||
| "revision": { | ||
| "data": { | ||
| "uri": "agenta:builtin:agent:v0", |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Don't pin the builtin URI yet.
services/oss/src/agent/app.py still says the handler is registered directly and gets an auto user:custom:... URI today; agenta:builtin:agent:v0 is still the target state. Showing the builtin value here makes the inspect contract look live before that binding lands.
| - the turn history from `data.inputs.messages` (or `data.messages`), | ||
| - the agent config and run selection from `data.parameters`, | ||
| - the trace and reference context from the envelope itself. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Resolve the message-history source ordering.
This page says history comes from data.inputs.messages here, but later says data.messages is primary and inputs.messages is fallback. That leaves the /invoke contract ambiguous, and it also conflicts with docs/design/agent-workflows/documentation/protocol.md. Pick one ordering and keep both docs aligned.
Also applies to: 38-40
Spin off a design workspace for remote/HTTP MCP support, requested in PR #4821 review (comments 3470094826 + 3469961290). The SDK already models transport:http + url + named secrets and serializes them to the /run wire; the deferral is a single skip in the runner's toAcpMcpServers. Documents the secret-to-header injection path (reusing the existing named-secret resolution, no new vault route), why HTTP is plausibly simpler than stdio, and how it fits the MCP resolver and wire. Claude-Session: https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc
Design workspace for an optional `uri` on the agent run config that names the sidecar (agent runner) address. When set, the service routes `/run` there; when unset, it falls back to AGENTA_AGENT_RUNNER_URL / the local runner. Spun out of PR #4821 review comment 3469613625. Design only, no code. Key decisions: `uri` is a RunSelection field (where a run goes, like `sandbox`), not the neutral AgentConfig, and not a `/run` wire field (consumed service-side in select_backend; golden fixtures untouched). A caller-supplied address is gated by a server-side allowlist, default-off, because the service ships resolved secrets + bearer tokens to whatever URL it picks. Claude-Session: https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc
Design workspace for an optional `uri` on the agent run config that names the sidecar (agent runner) address. When set, the service routes `/run` there; when unset, it falls back to AGENTA_AGENT_RUNNER_URL / the local runner. Spun out of PR #4821 review comment 3469613625. Design only, no code. Key decisions: `uri` is a RunSelection field (where a run goes, like `sandbox`), not the neutral AgentConfig, and not a `/run` wire field (consumed service-side in select_backend; golden fixtures untouched). A caller-supplied address is gated by a server-side allowlist, default-off, because the service ships resolved secrets + bearer tokens to whatever URL it picks. Claude-Session: https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc
Spin off a design workspace for remote/HTTP MCP support, requested in PR #4821 review (comments 3470094826 + 3469961290). The SDK already models transport:http + url + named secrets and serializes them to the /run wire; the deferral is a single skip in the runner's toAcpMcpServers. Documents the secret-to-header injection path (reusing the existing named-secret resolution, no new vault route), why HTTP is plausibly simpler than stdio, and how it fits the MCP resolver and wire. Claude-Session: https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc
…ess_kwargs Move harness/sandbox/permission_policy from the separate RunSelection DTO into AgentConfig (one agent definition, under data.parameters.agent). Retire RunSelection. Rename the per-harness options bag harness_options -> harness_kwargs. The /run wire is unchanged (golden fixtures untouched). PR #4821 review comments 2/7/8. Claude-Session: https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc
Design workspace for an optional `uri` on the agent run config that names the sidecar (agent runner) address. When set, the service routes `/run` there; when unset, it falls back to AGENTA_AGENT_RUNNER_URL / the local runner. Spun out of PR #4821 review comment 3469613625. Design only, no code. Key decisions: `uri` is a RunSelection field (where a run goes, like `sandbox`), not the neutral AgentConfig, and not a `/run` wire field (consumed service-side in select_backend; golden fixtures untouched). A caller-supplied address is gated by a server-side allowlist, default-off, because the service ships resolved secrets + bearer tokens to whatever URL it picks. Claude-Session: https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc
Spin off a design workspace for remote/HTTP MCP support, requested in PR #4821 review (comments 3470094826 + 3469961290). The SDK already models transport:http + url + named secrets and serializes them to the /run wire; the deferral is a single skip in the runner's toAcpMcpServers. Documents the secret-to-header injection path (reusing the existing named-secret resolution, no new vault route), why HTTP is plausibly simpler than stdio, and how it fits the MCP resolver and wire. Claude-Session: https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc
…ess_kwargs Move harness/sandbox/permission_policy from the separate RunSelection DTO into AgentConfig (one agent definition, under data.parameters.agent). Retire RunSelection. Rename the per-harness options bag harness_options -> harness_kwargs. The /run wire is unchanged (golden fixtures untouched). PR #4821 review comments 2/7/8. Claude-Session: https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc
Design workspace for an optional `uri` on the agent run config that names the sidecar (agent runner) address. When set, the service routes `/run` there; when unset, it falls back to AGENTA_AGENT_RUNNER_URL / the local runner. Spun out of PR #4821 review comment 3469613625. Design only, no code. Key decisions: `uri` is a RunSelection field (where a run goes, like `sandbox`), not the neutral AgentConfig, and not a `/run` wire field (consumed service-side in select_backend; golden fixtures untouched). A caller-supplied address is gated by a server-side allowlist, default-off, because the service ships resolved secrets + bearer tokens to whatever URL it picks. Claude-Session: https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc
Spin off a design workspace for remote/HTTP MCP support, requested in PR #4821 review (comments 3470094826 + 3469961290). The SDK already models transport:http + url + named secrets and serializes them to the /run wire; the deferral is a single skip in the runner's toAcpMcpServers. Documents the secret-to-header injection path (reusing the existing named-secret resolution, no new vault route), why HTTP is plausibly simpler than stdio, and how it fits the MCP resolver and wire. Claude-Session: https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc
…ess_kwargs Move harness/sandbox/permission_policy from the separate RunSelection DTO into AgentConfig (one agent definition, under data.parameters.agent). Retire RunSelection. Rename the per-harness options bag harness_options -> harness_kwargs. The /run wire is unchanged (golden fixtures untouched). PR #4821 review comments 2/7/8. Claude-Session: https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc
Design workspace for an optional `uri` on the agent run config that names the sidecar (agent runner) address. When set, the service routes `/run` there; when unset, it falls back to AGENTA_AGENT_RUNNER_URL / the local runner. Spun out of PR #4821 review comment 3469613625. Design only, no code. Key decisions: `uri` is a RunSelection field (where a run goes, like `sandbox`), not the neutral AgentConfig, and not a `/run` wire field (consumed service-side in select_backend; golden fixtures untouched). A caller-supplied address is gated by a server-side allowlist, default-off, because the service ships resolved secrets + bearer tokens to whatever URL it picks. Claude-Session: https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc
dosubot
Bot
added
size:XXL
…ess_kwargs Move harness/sandbox/permission_policy from the separate RunSelection DTO into AgentConfig (one agent definition, under data.parameters.agent). Retire RunSelection. Rename the per-harness options bag harness_options -> harness_kwargs. The /run wire is unchanged (golden fixtures untouched). PR #4821 review comments 2/7/8. Claude-Session: https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc
Design workspace for an optional `uri` on the agent run config that names the sidecar (agent runner) address. When set, the service routes `/run` there; when unset, it falls back to AGENTA_AGENT_RUNNER_URL / the local runner. Spun out of PR #4821 review comment 3469613625. Design only, no code. Key decisions: `uri` is a RunSelection field (where a run goes, like `sandbox`), not the neutral AgentConfig, and not a `/run` wire field (consumed service-side in select_backend; golden fixtures untouched). A caller-supplied address is gated by a server-side allowlist, default-off, because the service ships resolved secrets + bearer tokens to whatever URL it picks. Claude-Session: https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc
Spin off a design workspace for remote/HTTP MCP support, requested in PR #4821 review (comments 3470094826 + 3469961290). The SDK already models transport:http + url + named secrets and serializes them to the /run wire; the deferral is a single skip in the runner's toAcpMcpServers. Documents the secret-to-header injection path (reusing the existing named-secret resolution, no new vault route), why HTTP is plausibly simpler than stdio, and how it fits the MCP resolver and wire. Claude-Session: https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc
Spin off a design workspace for remote/HTTP MCP support, requested in PR #4821 review (comments 3470094826 + 3469961290). The SDK already models transport:http + url + named secrets and serializes them to the /run wire; the deferral is a single skip in the runner's toAcpMcpServers. Documents the secret-to-header injection path (reusing the existing named-secret resolution, no new vault route), why HTTP is plausibly simpler than stdio, and how it fits the MCP resolver and wire. Claude-Session: https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc
Add a plan-feature workspace under docs/design/agent-workflows/projects/embedref-tools/ for allowing an @ag.embed reference in the agent config tools field, the way skills already supports it. Researches the generic embed resolver, the tool taxonomy, and the _agenta.* platform catalog; proposes a callback-executor workflow tool variant plus an embed-as-content stepping stone. Design only, spun from PR #4821 review comment 3469653315. Claude-Session: https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc
Add a plan-feature workspace under docs/design/agent-workflows/projects/embedref-tools/ for allowing an @ag.embed reference in the agent config tools field, the way skills already supports it. Researches the generic embed resolver, the tool taxonomy, and the _agenta.* platform catalog; proposes a callback-executor workflow tool variant plus an embed-as-content stepping stone. Design only, spun from PR #4821 review comment 3469653315. Claude-Session: https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc
Add a plan-feature workspace under docs/design/agent-workflows/projects/embedref-tools/ for allowing an @ag.embed reference in the agent config tools field, the way skills already supports it. Researches the generic embed resolver, the tool taxonomy, and the _agenta.* platform catalog; proposes a callback-executor workflow tool variant plus an embed-as-content stepping stone. Design only, spun from PR #4821 review comment 3469653315. Claude-Session: https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc
2 participants
Context
Agent workflow review work currently has to jump between protocol, architecture, runner, and adapter docs to understand which interface a change touches. We need a lightweight map that names those boundaries and points reviewers to the owning files.
Changes
Adds
docs/design/agent-workflows/interfaces/as a review-oriented inventory, organized by blast radius:Each category has its own folder, with one file per interface or closely related interface group.
Scope / risk
Docs-only change. No code, no tests, no migrations. The only thing that could regress is a broken cross-reference, and those were checked during authoring.
Tests / notes
Verified the new links and scanned the new docs for banned docs-style terms and em dashes.
How to QA
Prerequisites: No stack needed. A browser or a Markdown reader is enough.
Steps:
docs/design/agent-workflows/interfaces/README.mdand verify the three category sections (Public edge, Cross-service, In-service) each link to a populated subfolder.Expected result: Every linked file opens and describes a real boundary in the codebase. No 404 links.
Automated tests: None. This is docs-only; there are no automated tests to run.
Edge cases: Confirm the
agent-load-session.mdfile exists (it is referenced frompublic-edge/README.md); it will be deleted in the follow-on chore PR (#4828).