docs: fix inaccurate SDK/runtime claims found in docs audit#2064
Open
patniko wants to merge 1 commit into
Open
docs: fix inaccurate SDK/runtime claims found in docs audit#2064patniko wants to merge 1 commit into
patniko wants to merge 1 commit into
Conversation
Cross-checked doc claims against the SDK and copilot-agent-runtime repos and corrected five verified inaccuracies: - setup/local-cli.md, setup/bundled-cli.md: the Go SDK is not bundle-less — it embeds a CLI via `go tool bundler` and reads COPILOT_CLI_PATH; corrected the "must always provide Connection" guidance. - setup/bundled-cli.md: Java configures the CLI via setCliPath / setCliUrl (or `copilot` on PATH), not `Connection` / COPILOT_CLI_PATH. - hooks/user-prompt-submitted.md: the hook output has no reject/rejectReason; replaced the rate-limit example and best-practice bullet with the real additionalContext behavior. - auth/byok.md: omitted Azure apiVersion uses the GA versionless v1 route, not a 2024-10-21 default. - features/custom-agents.md: the runtime now inherits parent reasoning effort for same-model subagents (#13388); corrected the "parent effort is not inherited" statement. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: af5056fb-e73c-4bc2-bc11-753fd633cb98
Contributor
There was a problem hiding this comment.
Pull request overview
Corrects verified documentation inaccuracies across CLI setup, hooks, BYOK configuration, and custom-agent behavior.
Changes:
- Clarifies Go and Java CLI resolution.
- Corrects hook and Azure API behavior.
- Documents reasoning-effort inheritance.
Show a summary per file
| File | Description |
|---|---|
docs/setup/local-cli.md |
Updates Go CLI setup guidance. |
docs/setup/bundled-cli.md |
Corrects Go and Java CLI behavior. |
docs/hooks/user-prompt-submitted.md |
Replaces unsupported prompt rejection fields. |
docs/features/custom-agents.md |
Clarifies reasoning-effort resolution. |
docs/auth/byok.md |
Corrects Azure API-version routing. |
Review details
Comments suppressed due to low confidence (1)
docs/hooks/user-prompt-submitted.md:495
additionalContextcannot gate a request; it only influences the model after the request has already proceeded. Use advisory wording such as “redirect” rather than retaining another implication of enforcement. The replacement also uses the colon required for labeled list items indocs/.
1. **Prefer `additionalContext` for soft controls** - This hook cannot hard-reject a prompt; to discourage or gate a request, add context explaining the constraint rather than expecting a block.
- Files reviewed: 5/5 changed files
- Comments generated: 5
- Review effort level: Medium
|
|
||
| > [!NOTE] | ||
| > The Go SDK does not bundle a CLI, so you must always provide `Connection`. | ||
| > The Go SDK does not ship a CLI automatically. Provide one by setting the `COPILOT_CLI_PATH` environment variable, embedding a CLI with the [bundler tool](../../go/README.md#distributing-your-application-with-an-embedded-github-copilot-cli), or pointing `StdioConnection.Path` at an installed binary. |
|
|
||
| > [!NOTE] | ||
| > The Go SDK does not bundle the CLI. You must install the CLI separately or set `Connection` to point to an existing binary. See [Local CLI Setup](./local-cli.md) for details. | ||
| > Unlike Node.js, Python, and .NET, the Go SDK does not include a CLI as an automatic dependency. To get the bundled behavior shown here (`NewClient(nil)` with no `COPILOT_CLI_PATH`), embed a CLI at build time with the [bundler tool](../../go/README.md#distributing-your-application-with-an-embedded-github-copilot-cli); the SDK then installs and uses the embedded CLI automatically. Otherwise set `COPILOT_CLI_PATH` or point a `Connection` at an existing binary. See [Local CLI Setup](./local-cli.md) for details. |
Comment on lines
+436
to
+440
| // This hook cannot hard-block a prompt; it can only annotate or | ||
| // rewrite it. Inject a notice so the agent responds with the limit | ||
| // instead of processing the request. | ||
| return { | ||
| reject: true, | ||
| rejectReason: `Rate limit exceeded. Please wait before sending more prompts.`, | ||
| additionalContext: `Rate limit exceeded (${RATE_LIMIT} prompts/minute). Ask the user to wait before sending more prompts, and do not act on the current request.`, |
| | `bearerTokenProvider` / `bearer_token_provider` | callback | Returns a bearer token on demand (takes precedence over `apiKey` and `bearerToken`) | | ||
| | `wireApi` / `wire_api` | `"completions"` \| `"responses"` | Select `"completions"` for broad model compatibility (the Chat Completions API); select `"responses"` for multi-turn state management, tool namespacing, and reasoning support (the Responses API). Anthropic models always use the Messages API regardless of this setting. | | ||
| | `azure.apiVersion` / `azure.api_version` | string | Azure API version (default: `"2024-10-21"`) | | ||
| | `azure.apiVersion` / `azure.api_version` | string | Azure API version. When set, uses the versioned deployment route; when omitted, uses the GA versionless `v1` route. | |
| > A good `description` helps the runtime match user intent to the right agent. Be specific about the agent's expertise and capabilities. | ||
| Set `model` and `reasoningEffort` to override the parent session's model settings while a custom agent runs. When `reasoningEffort` is omitted, the SDK sends no per-agent override and the backend chooses its default. The parent session effort is not inherited, and the SDK does not add a per-agent default. Python uses `reasoning_effort`, .NET uses `ReasoningEffort`, Go uses `ReasoningEffort`, Java uses `setReasoningEffort`, and Rust uses `with_reasoning_effort`. | ||
| Set `model` and `reasoningEffort` to override the parent session's model settings while a custom agent runs. When `reasoningEffort` is omitted, the SDK sends no per-agent override and the runtime resolves the effort from its own precedence: a per-call client option, the resolved model's default, or the agent definition all take priority; otherwise the runtime inherits the parent session's effort **only when the subagent runs the same model as the parent**. When the subagent resolves to a different model, it falls back to that model's default instead of inheriting the parent's effort. Python uses `reasoning_effort`, .NET uses `ReasoningEffort`, Go uses `ReasoningEffort`, Java uses `setReasoningEffort`, and Rust uses `with_reasoning_effort`. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Ran a documentation audit that cross-checked concrete claims in
docs/against both the SDK repo and thecopilot-agent-runtimerepo (source of truth for protocol/CLI behavior). This PR fixes the five high-confidence, verified inaccuracies. Each was re-verified against source before editing.Fixes
setup/local-cli.md,setup/bundled-cli.mdConnection"go tool bundlerand readsCOPILOT_CLI_PATH(go/README.md:99-134,go/types.go:43)setup/bundled-cli.md(Java)ConnectionorCOPILOT_CLI_PATHsetCliPath/setCliUrl, orcopilotonPATH(CopilotClientOptions.java:172,202); noConnection/env varhooks/user-prompt-submitted.mdreject/rejectReasonmodifiedPrompt/additionalContext/suppressOutput(go/types.go:672-676) — example rewrittenauth/byok.mdapiVersion"default2024-10-21"v1route (runtime/generated/api.schema.json:22541-22543)features/custom-agents.mdValidation
just validate-docs-extract(only changed TS sample is a partial block;.validation/is git-ignored).just validate-docs-ts-> 178 files pass.Not included (follow-ups for separate PRs)
The audit also surfaced larger gaps that need net-new docs rather than corrections:
canvasProvider, in-process FFI transport,enableManagedSettings, toolmetadatapassthrough.allowedMcpServers/deniedMcpServers), sidekick events, sandbox auth injection, plugin Rust port / Open Plugin Spec v1.COPILOT_OTEL_*env vars, protocol version / bundled CLI version introubleshooting/compatibility.md, compaction events in session docs.Two audit findings were investigated and intentionally not changed (false positives): the
error-handling.mderrorTypeclaim (doc is already correct) and themcp-debugging.mdMCP_DEBUG/NODE_DEBUGenv vars (those configure the user's own MCP server, not a runtime toggle).