[docs] Add agent workflow interface inventory

[mmabrouk]

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:

• public edge interfaces for browser and workflow-client contracts
• cross-service interfaces for service, sidecar, harness, tools, MCP, vault, and trace boundaries
• in-service interfaces for SDK ports, DTOs, adapters, config, permissions, and model resolution

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:

1. Open docs/design/agent-workflows/interfaces/README.md and verify the three category sections (Public edge, Cross-service, In-service) each link to a populated subfolder.
2. Click through three or four of the linked files and confirm the interface name, owning file path, and description make sense for a reviewer who doesn't know the PR.
3. Check that no file contains a broken relative link (GitHub renders these as 404 text in the preview).

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.md file exists (it is referenced from public-edge/README.md); it will be deleted in the follow-on chore PR (#4828).

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jun 24, 2026 8:19pm

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds 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 /run, skills, resolution, permission, and adapter descriptions.

Changes

Agent workflow interface inventory

Layer / File(s)	Summary
Inventory index and layout updates docs/design/agent-workflows/README.md, docs/design/agent-workflows/documentation/ports-and-adapters.md, docs/design/agent-workflows/interfaces/README.md, docs/design/agent-workflows/interfaces/cross-service/README.md, docs/design/agent-workflows/interfaces/in-service/README.md, docs/design/agent-workflows/interfaces/public-edge/README.md	The agent-workflows overview pages now describe a five-layer layout and point to the new interface inventory sections.
Cross-service contract docs docs/design/agent-workflows/documentation/protocol.md, docs/design/agent-workflows/interfaces/cross-service/runner-to-harness.md, docs/design/agent-workflows/interfaces/cross-service/runner-to-mcp-server.md, docs/design/agent-workflows/interfaces/cross-service/runner-to-tool-callback.md, docs/design/agent-workflows/interfaces/cross-service/service-and-runner-trace-export.md, docs/design/agent-workflows/interfaces/cross-service/service-to-agent-runner.md, docs/design/agent-workflows/interfaces/cross-service/service-to-vault-and-tool-providers.md	The /run protocol doc and cross-service interface pages define runner, MCP, tool callback, trace export, and vault/provider resolution contracts.
Public-edge API contracts docs/design/agent-workflows/interfaces/public-edge/agent-config-schema.md, docs/design/agent-workflows/interfaces/public-edge/agent-load-session.md, docs/design/agent-workflows/interfaces/public-edge/agent-messages.md, docs/design/agent-workflows/interfaces/public-edge/workflow-inspect.md, docs/design/agent-workflows/interfaces/public-edge/workflow-invoke.md	The public-edge pages define the agent config schema, load-session, messages, inspect, and invoke request and response contracts.
Runtime DTOs and ports docs/design/agent-workflows/interfaces/in-service/runtime-ports.md, docs/design/agent-workflows/interfaces/in-service/neutral-runtime-dtos.md, docs/design/agent-workflows/interfaces/in-service/runner-engine-internals.md	The runtime ports, neutral DTOs, and runner-engine internals define the shared in-process types, message normalization, and HTTP or CLI engine behavior.
Connection, tool, and MCP resolution docs/design/agent-workflows/interfaces/in-service/model-connection-resolution.md, docs/design/agent-workflows/interfaces/in-service/mcp-models-and-resolution.md, docs/design/agent-workflows/interfaces/in-service/tool-models-and-resolution.md	The model connection, MCP, and tool resolution pages define how config inputs become resolved connections, MCP servers, and tool specs.
Permission and sandbox policy docs/design/agent-workflows/interfaces/in-service/permission-responder.md, docs/design/agent-workflows/interfaces/in-service/sandbox-permission.md	The permission responder and sandbox permission pages define approval precedence, cross-turn matching, and network or filesystem enforcement rules.
Service handler and adapters docs/design/agent-workflows/interfaces/in-service/agent-service-handler.md, docs/design/agent-workflows/interfaces/in-service/backend-adapter.md, docs/design/agent-workflows/interfaces/in-service/browser-protocol-adapter.md, docs/design/agent-workflows/interfaces/in-service/harness-adapters.md	The service handler and adapter pages define the agent service flow and the backend, browser, and harness adapters used to execute it.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~30 minutes

Possibly related PRs

• Agenta-AI/agenta#4779: Updates the same agent-workflows /run protocol documentation and field-level contract narrative.
• Agenta-AI/agenta#4814: Implements the inline skill package shape referenced by the updated skills documentation.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: adding an agent workflow interface inventory in docs.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.
Description check	✅ Passed	The description matches the docs-only interface inventory changes and the new public-edge, cross-service, and in-service folders.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 docs/agent-workflow-interface-inventory

---

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

[mmabrouk]

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

[mmabrouk]

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.

[mmabrouk]

Implemented: uri replaces sandbox (allowlist-gated routing) — PR #4836.

[mmabrouk]

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

[mmabrouk]

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

[mmabrouk]

Implemented: harness_kwargs per-harness bag (was harness_options); permission_policy stays the sidecar action-permission, on AgentConfig — PR #4840.

[mmabrouk]

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

[mmabrouk]

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.

[mmabrouk]

Implemented: model is always a structured ModelRef now (free-text path dropped) — PR #4839.

[mmabrouk]

we should also allow here embedref like skills. these would allow creating tools as workflows and embedding them.

[mmabrouk]

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.

[mmabrouk]

Designed: embedref tools-as-workflows — PR #4837 (runnable→callback, non-runnable→client; simplified).