1. The ask
Provide a single, supported control that disables the SDK's built-in sub-agents, so a host can run a session that exposes only its own custom agents to the model.
Today the SDK offers only a name-by-name deny-list (SessionConfig.excludedBuiltinAgents) — there is no supported switch to turn the built-ins off in one call.
2. Why we need it
The host's built-in sub-agents caused a live-site incident. In production, a built-in sub-agent — auto-exposed by the SDK and never validated by the host — was invoked and defaulted to a model not provisioned in the host's environment; it returned repeated 400 "Unknown model" errors and failed the user's turn.
The host's mitigation is to disable the built-in sub-agents entirely and expose only the custom agents it has validated. That is why the host needs a reliable, supported way to turn built-in sub-agents off.
3. What the SDK offers today
Verified against the pinned SDK type definitions and the public custom-agents docs (citations in the Appendix).
excludedBuiltinAgents — a deny-list keyed on exact name. It works, but the host must enumerate and hardcode every built-in name; there is no wildcard and no "disable all" switch.customAgents — registers the host's own agents only. Neither the type definitions nor the docs state that customAgents disables built-ins, and an empty customAgents does not turn built-ins off (confirmed empirically).
4. What we're asking the SDK to support
A single, supported control that disables all built-in sub-agents at once — without the host enumerating their names (for example, a disableAllBuiltinAgents flag or a builtin:* wildcard on SessionConfig).
Why a dedicated control rather than the existing deny-list: the built-in roster is not guaranteed stable, so a name-based list forces the host to track it and re-patch whenever the SDK adds or renames a built-in. A single supported control removes that ongoing burden.
5. Nice to have
Not required for our case, but would round out the API:
- An allow-list for built-in agents (e.g.
availableBuiltinAgents), so a host can keep only a chosen subset enabled. The SDK already offers exactly this shape for tools (availableTools with builtin:* / builtin:<name> patterns) — an agent equivalent would be consistent.
- A discoverable roster API to enumerate built-in agent names, so hosts don't hardcode a list.
- Document the
customAgents ↔ built-in relationship — state explicitly whether customAgents (or an empty customAgents) affects the built-in set. Today it does not.
Appendix — sources
SDK type definitions (@github/copilot-sdk-next v1.0.6, types.d.ts):
SessionConfig.excludedBuiltinAgents?: string[] — deny-list by exact name.SessionConfig.availableTools / excludedTools — allow-list + deny-list for tools, with builtin:* / builtin:<name> patterns.SessionConfig.customAgents?: CustomAgentConfig[] — "Custom agent configurations for the session"; no built-in-disable semantics.
SDK public documentation — Custom agents (docs.github.com/en/copilot/how-tos/copilot-sdk/features/custom-agents): defines only how to author custom agents (name/description/tools/prompt/infer/skills). It defines no built-in-agent control and no "empty array disables built-ins" semantics.
Originating scenario — Reported as a live-site issue: with only the name-based deny-list available, the host had to disable the built-in set by enumerating the full roster, which was flagged as unmaintainable — hence this request to the SDK for a supported control.
1. The ask
Provide a single, supported control that disables the SDK's built-in sub-agents, so a host can run a session that exposes only its own custom agents to the model.
Today the SDK offers only a name-by-name deny-list (
SessionConfig.excludedBuiltinAgents) — there is no supported switch to turn the built-ins off in one call.2. Why we need it
The host's built-in sub-agents caused a live-site incident. In production, a built-in sub-agent — auto-exposed by the SDK and never validated by the host — was invoked and defaulted to a model not provisioned in the host's environment; it returned repeated
400 "Unknown model"errors and failed the user's turn.The host's mitigation is to disable the built-in sub-agents entirely and expose only the custom agents it has validated. That is why the host needs a reliable, supported way to turn built-in sub-agents off.
3. What the SDK offers today
Verified against the pinned SDK type definitions and the public custom-agents docs (citations in the Appendix).
excludedBuiltinAgents— a deny-list keyed on exact name. It works, but the host must enumerate and hardcode every built-in name; there is no wildcard and no "disable all" switch.customAgents— registers the host's own agents only. Neither the type definitions nor the docs state thatcustomAgentsdisables built-ins, and an emptycustomAgentsdoes not turn built-ins off (confirmed empirically).4. What we're asking the SDK to support
A single, supported control that disables all built-in sub-agents at once — without the host enumerating their names (for example, a
disableAllBuiltinAgentsflag or abuiltin:*wildcard onSessionConfig).Why a dedicated control rather than the existing deny-list: the built-in roster is not guaranteed stable, so a name-based list forces the host to track it and re-patch whenever the SDK adds or renames a built-in. A single supported control removes that ongoing burden.
5. Nice to have
Not required for our case, but would round out the API:
availableBuiltinAgents), so a host can keep only a chosen subset enabled. The SDK already offers exactly this shape for tools (availableToolswithbuiltin:*/builtin:<name>patterns) — an agent equivalent would be consistent.customAgents↔ built-in relationship — state explicitly whethercustomAgents(or an emptycustomAgents) affects the built-in set. Today it does not.Appendix — sources
SDK type definitions (
@github/copilot-sdk-nextv1.0.6,types.d.ts):SessionConfig.excludedBuiltinAgents?: string[]— deny-list by exact name.SessionConfig.availableTools/excludedTools— allow-list + deny-list for tools, withbuiltin:*/builtin:<name>patterns.SessionConfig.customAgents?: CustomAgentConfig[]— "Custom agent configurations for the session"; no built-in-disable semantics.SDK public documentation — Custom agents (docs.github.com/en/copilot/how-tos/copilot-sdk/features/custom-agents): defines only how to author custom agents (name/description/tools/prompt/infer/skills). It defines no built-in-agent control and no "empty array disables built-ins" semantics.
Originating scenario — Reported as a live-site issue: with only the name-based deny-list available, the host had to disable the built-in set by enumerating the full roster, which was flagged as unmaintainable — hence this request to the SDK for a supported control.