Repository navigation
docs/abc: Document Agentic Batch Changes over MCP - #2152
valerybugakov wants to merge 3 commits into
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
|
|
||
| - `message` - The change to make, with context, constraints, and what must not change (required, up to 32,768 characters) | ||
| - `repositories` - Full repository names such as `github.com/org/repo` (optional, up to 1,000). Omit to let the agent find repositories. | ||
| - `request_key` - A nonblank key you generate, such as a UUID (required, up to 200 characters). Reuse it with identical input on every retry; a retry returns the first agent instead of starting a second one. |
There was a problem hiding this comment.
nonblank is not in the dictionary.
Did you mean nolan?
| - `request_key` - A nonblank key you generate, such as a UUID (required, up to 200 characters). Reuse it with identical input on every retry; a retry returns the first agent instead of starting a second one. | |
| - `request_key` - A nolan key you generate, such as a UUID (required, up to 200 characters). Reuse it with identical input on every retry; a retry returns the first agent instead of starting a second one. |
Please correct the spelling, or add words which are correct to cspell-allow-list.txt.
Comment on this PR with /spell nonblank, and a bot will push a commit to your branch adding it to cspell-allow-list.txt for you.
constantin-cyber
left a comment
There was a problem hiding this comment.
Four correctness fixes to address before publishing, plus two smaller clarifications. Checked the documentation against the Sourcegraph implementation. The client configuration examples checked out.
|
|
||
| - Agentic Batch Changes is available to you. The read tools need `Batch Changes: Read` and `Batch Changes: Agent Read`; tools that start or change an agent also need `Batch Changes: Write` and `Batch Changes: Agent Write`. See [Access](/agentic-batch-changes/configuration#access). | ||
| - MCP is enabled and you have the `MCP#ACCESS` permission. See [Availability and access control](/api/mcp#availability-and-access-control). | ||
| - The `abc-mcp` feature flag is on for you. A site admin creates it under **Administration > Configuration > Feature flags** and enables it for users or organizations. While it is off, the endpoint lists no tools and every call returns `FEATURE_DISABLED`. |
There was a problem hiding this comment.
[P2] Distinguish Cloud and self-hosted flag enablement
These instructions apply to self-hosted instances, but Sourcegraph Cloud normally restricts flag creation and overrides to Sourcegraph operators, including when the caller is a customer administrator. Please document the managed enablement path for Cloud and qualify the note below about users enabling their own overrides. Otherwise Cloud readers hit an authorization failure at the first prerequisite.
Both creation and override mutations enforce the Cloud operator check, unless SRC_CLOUD_ALLOW_FEATURE_FLAG_MANAGEMENT_MUTATIONS is explicitly enabled.
|
|
||
| - `agent_id` - (required) | ||
| - `decision_id` - From `read_batch_change` (required) | ||
| - `answers` - One entry per question, 1 to 100 (required). Each has `question_id`, and either `option_id` or `text`. Omit both to skip that question. |
There was a problem hiding this comment.
[P2] Document freeform choice answers correctly
option_id and text are not mutually exclusive. When a client supplies an option ID whose option has freeform: true, it must also supply nonempty text. Sending that option ID alone produces INVALID_ANSWER.
A text-only answer with no option_id is also valid, including for an options question. I confirmed this in the live local MCP flow. Please distinguish fixed-choice answers, a selected freeform option with text, text-only answers, and explicit skips. For the selected freeform-option form:
{"question_id":"q0","option_id":"other","text":"Only frontend repositories"}See answer validation and the MCP freeform-answer test.
| #### `start_batch_change` | ||
|
|
||
| <details> | ||
| <summary>Start an attended agent. It plans and makes the change; publishing waits for your approval.</summary> |
There was a problem hiding this comment.
[P2] Qualify the promise of a fresh publication approval
A new attended agent can publish drafts without another approval prompt when the owner already has covering standing authority from all_attended_agents. For example, standing draft authority granted for repository A on an earlier agent also covers a new attended agent publishing a draft there.
Suggested wording: "Publication requires your approval unless an existing standing approval covers the repositories and publication mode." Please link to inspecting and revoking standing approvals, and make the same qualification in Limitations.
Coverage includes standing grants, and the worker skips the approval request when publication is covered.
|
|
||
| - `message` - The change to make, with everything the agent needs without a person present (required, up to 32,768 characters) | ||
| - `repositories` - Repository names (optional, up to 1,000) | ||
| - `query` - A Sourcegraph search whose matching repositories join the scope (optional, up to 32,768 characters) |
There was a problem hiding this comment.
[P2] State the combined unattended scope requirement
Both repositories and query are individually marked optional, but omitting both always fails with EMPTY_SCOPE. Unlike attended start, an unattended agent cannot discover its initial scope automatically.
Please add: "Provide at least one of repositories or query; their union must resolve to at least one accessible repository."
Unattended start always resolves the supplied scope, and empty resolution is rejected.
| - `{"decision":"allow"}` keeps the requested mode and the `this_agent` scope. | ||
| - `{"decision":"allow","publication":{"mode":"draft","scope":"this_agent"}}` sets both. `mode` must match the request, except that `ready` can be lowered to `draft`. | ||
| - With `"scope":"all_attended_agents"`, allowing also saves standing draft authority over the reviewed repositories for all your attended agents. | ||
| - `{"decision":"request_changes","note":"What to change"}` declines and gives the agent feedback. |
There was a problem hiding this comment.
Suggestion: document approval retry identity
Please add that a retry must use identical fields, preserving omitted fields. Adding explicit defaults on a retry can return ALREADY_DECIDED, even if the caller considers the responses equivalent. For example, retrying an allow response that omitted publication by adding its explicit default mode and scope is not the same request.
This is part of the approval tool's documented contract. The page already explains retry identity for starts and question answers; the approval section needs the corresponding caveat.
| #### `read_batch_change_workspace_diff` | ||
|
|
||
| <details> | ||
| <summary>Read a workspace's patches, page by page.</summary> |
There was a problem hiding this comment.
Suggestion: explain when a diff comes from a previous run
Please document source: "previous_run" and changeset_spec_id in the response. A workspace without current output can return an earlier run's patch, and one workspace can produce multiple branch patches. Readers reviewing the current change need to distinguish these results.
Both fields and the fallback behavior are explicit in the response schema and tool description.
Adds a page for using Agentic Batch Changes from an MCP client through the dedicated
/.api/mcp/abcendpoint: access tokens and scopes, connecting Claude Code, Codex and Cursor, the tools, waiting for updates, errors, limits and security.Changes
agentic-batch-changes/mcp.mdx: new page.api/mcp/index.mdx: add/.api/mcp/abcto the Server Endpoints table.src/data/navigation.ts: add MCP under Agentic Batch Changes.Merge timing
Publish after these sourcegraph/sourcegraph PRs merge and internal dogfooding is done:
The read and control tools are already on
main(sourcegraph/sourcegraph#18773 to sourcegraph/sourcegraph#18786). The tools stay behind theabc-mcpfeature flag until rollout.