[Custom Agents] Preselecting agent does not work

[vatsa-msft]

Bug

When agent is provided in createSession config to pre-select a custom agent, the agent is not active from start.

Versions

• SDK: @github/copilot-sdk 0.2.0 / 0.2.1
• Runtime: @github/copilot 1.0.17

Expected Behavior

Per the docs:

You can pass agent in the session config to pre-select which custom agent should be active when the session starts. This is equivalent to calling session.rpc.agent.select() after creation.

https://github.com/github/copilot-sdk/blob/main/docs/features/custom-agents.md#selecting-an-agent-at-session-creation

Both approaches should produce the same result — the selected agent's prompt is used as the active system prompt from the first message.

Actual Behavior

• agent= in session config: The LLM receives the systemMessage content (or the SDK default prompt). The agent's prompt is not injected. Confirmed by inspecting the system field in the LLM API request.
• rpc.agent.select() after creation: The LLM receives the agent's prompt as expected. Confirmed by a marker string in the agent's prompt appearing in the LLM's first response.

Reproduction

session = await client.create_session(
    on_permission_request=PermissionHandler.approve_all,
    system_message={"mode": "replace", "content": "You are a helpful assistant."},
    custom_agents=[
        {
            "name": "researcher",
            "prompt": "You are a researcher. Begin every response with RESEARCHER_ACTIVE.",
        },
    ],
    agent="researcher",  # Pre-select
)

response = await session.send_and_wait("Hello")
# Expected: response starts with "RESEARCHER_ACTIVE"
# Actual: response does NOT contain "RESEARCHER_ACTIVE" — agent prompt not injected

Workaround

Call rpc.agent.select() after session creation:

  session = await client.create_session(...)
  await session.rpc.agent.select(SessionAgentSelectParams(name="researcher"))
  response = await session.send_and_wait("Hello")
  # Works: response starts with "RESEARCHER_ACTIVE"

Notes

• This may be related to how systemMessage: { mode: "replace" } interacts with agent selection. It's possible replace mode overwrites the agent's prompt. However, the docs do not mention this interaction, and rpc.agent.select() correctly overrides the system message regardless of mode.

[github-actions]

Investigation Summary

I've confirmed this is a genuine bug. Here's what I found:

What I Investigated

• nodejs/src/client.ts (lines 723–724) and python/copilot/client.py (lines 1261–1263): Both SDKs correctly include agent: config.agent / payload["agent"] = agent in the session.create RPC payload.
• nodejs/src/types.ts (lines 1163–1165) and docs/features/custom-agents.md: The docs explicitly state that agent in session config is "equivalent to calling session.rpc.agent.select() after creation, but avoids the extra API call and ensures the agent is active from the very first prompt."
• nodejs/test/e2e/agent_and_compact_rpc.test.ts: There are no existing tests for agent pre-selection at session creation time — only tests for rpc.agent.select() called after creation.

Root Cause

The SDK transmits the agent field correctly to the CLI — the issue lies in how the CLI handles this field during session initialization. When agent is included in the session.create request alongside systemMessage: { mode: "replace" }, the CLI does not inject the agent's prompt as the active system message. However, when rpc.agent.select() is called after session creation, the CLI correctly overrides the system message with the agent's prompt.

This confirms the documented equivalence between the two approaches doesn't hold, at least when combined with systemMessage: { mode: "replace" }. This is a bug regardless of whether the root cause is in the CLI's session initialization or in a gap in the interaction contract between systemMessage.mode and agent pre-selection.

Workaround

Continue using the workaround you identified:

session = await client.create_session(...)
await session.rpc.agent.select(SessionAgentSelectParams(name="researcher"))

This will be addressed by fixing the CLI behavior so that the agent field in session creation is treated equivalently to calling rpc.agent.select() immediately after.

Generated by Bug Handler for issue #1018 · ◷