feat: add agent parameter to session creation for pre-selecting custom agents

docs/features/custom-agents.md

@@ -219,6 +219,102 @@ await using var session = await client.CreateSessionAsync(new SessionConfig
 
 > **Tip:** A good `description` helps the runtime match user intent to the right agent. Be specific about the agent's expertise and capabilities.
 
+In addition to per-agent configuration above, you can set `agent` on the **session config** itself to pre-select which custom agent is active when the session starts. See [Selecting an Agent at Session Creation](#selecting-an-agent-at-session-creation) below.
+
+| Session Config Property | Type | Description |
+|-------------------------|------|-------------|
+| `agent` | `string` | Name of the custom agent to pre-select at session creation. Must match a `name` in `customAgents`. |
+
+## Selecting an Agent at Session Creation
+
+You can pass `agent` in the session config to pre-select which custom agent should be active when the session starts. The value must match the `name` of one of the agents defined in `customAgents`.
+
+This 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.
+
+<details open>
+<summary><strong>Node.js / TypeScript</strong></summary>
+
+<!-- docs-validate: skip -->
+```typescript
+const session = await client.createSession({
+    customAgents: [
+        {
+            name: "researcher",
+            prompt: "You are a research assistant. Analyze code and answer questions.",
+        },
+        {
+            name: "editor",
+            prompt: "You are a code editor. Make minimal, surgical changes.",
+        },
+    ],
+    agent: "researcher", // Pre-select the researcher agent
+});
+```
+
+</details>
+
+<details>
+<summary><strong>Python</strong></summary>
+
+<!-- docs-validate: skip -->
+```python
+session = await client.create_session({
+    "custom_agents": [
+        {
+            "name": "researcher",
+            "prompt": "You are a research assistant. Analyze code and answer questions.",
+        },
+        {
+            "name": "editor",
+            "prompt": "You are a code editor. Make minimal, surgical changes.",
+        },
+    ],
+    "agent": "researcher",  # Pre-select the researcher agent
+})
+```
+
+</details>
+
+<details>
+<summary><strong>Go</strong></summary>
+
+<!-- docs-validate: skip -->
+```go
+session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
+    CustomAgents: []copilot.CustomAgentConfig{
+        {
+            Name:   "researcher",
+            Prompt: "You are a research assistant. Analyze code and answer questions.",
+        },
+        {
+            Name:   "editor",
+            Prompt: "You are a code editor. Make minimal, surgical changes.",
+        },
+    },
+    Agent: "researcher", // Pre-select the researcher agent
+})
+```
+
+</details>
+
+<details>
+<summary><strong>.NET</strong></summary>
+
+<!-- docs-validate: skip -->
+```csharp
+var session = await client.CreateSessionAsync(new SessionConfig
+{
+    CustomAgents = new List<CustomAgentConfig>
+    {
+        new() { Name = "researcher", Prompt = "You are a research assistant. Analyze code and answer questions." },
+        new() { Name = "editor", Prompt = "You are a code editor. Make minimal, surgical changes." },
+    },
+    Agent = "researcher", // Pre-select the researcher agent
+});
+```
+
+</details>
+
 ## How Sub-Agent Delegation Works
 
 When you send a prompt to a session with custom agents, the runtime evaluates whether to delegate to a sub-agent:

docs/features/session-persistence.md

@@ -248,6 +248,7 @@ When resuming a session, you can optionally reconfigure many settings. This is u
 | `configDir` | Override configuration directory |
 | `mcpServers` | Configure MCP servers |
 | `customAgents` | Configure custom agents |
+| `agent` | Pre-select a custom agent by name |
 | `skillDirectories` | Directories to load skills from |
 | `disabledSkills` | Skills to disable |
 | `infiniteSessions` | Configure infinite session behavior |

docs/getting-started.md

@@ -1241,6 +1241,8 @@ const session = await client.createSession({
 });
 ```
 
+> **Tip:** You can also set `agent: "pr-reviewer"` in the session config to pre-select this agent from the start. See the [Custom Agents guide](./guides/custom-agents.md#selecting-an-agent-at-session-creation) for details.
+
 ### Customize the System Message
 
 Control the AI's behavior and personality:

dotnet/src/Client.cs

@@ -419,6 +419,7 @@ public async Task<CopilotSession> CreateSessionAsync(SessionConfig config, Cance
             config.McpServers,
             "direct",
             config.CustomAgents,
+            config.Agent,
             config.ConfigDir,
             config.SkillDirectories,
             config.DisabledSkills,
@@ -512,6 +513,7 @@ public async Task<CopilotSession> ResumeSessionAsync(string sessionId, ResumeSes
             config.McpServers,
             "direct",
             config.CustomAgents,
+            config.Agent,
             config.SkillDirectories,
             config.DisabledSkills,
             config.InfiniteSessions);
@@ -1407,6 +1409,7 @@ internal record CreateSessionRequest(
         Dictionary<string, object>? McpServers,
         string? EnvValueMode,
         List<CustomAgentConfig>? CustomAgents,
+        string? Agent,
         string? ConfigDir,
         List<string>? SkillDirectories,
         List<string>? DisabledSkills,
@@ -1450,6 +1453,7 @@ internal record ResumeSessionRequest(
         Dictionary<string, object>? McpServers,
         string? EnvValueMode,
         List<CustomAgentConfig>? CustomAgents,
+        string? Agent,
         List<string>? SkillDirectories,
         List<string>? DisabledSkills,
         InfiniteSessionConfig? InfiniteSessions);

dotnet/src/Types.cs

@@ -1197,6 +1197,7 @@ protected SessionConfig(SessionConfig? other)
         ClientName = other.ClientName;
         ConfigDir = other.ConfigDir;
         CustomAgents = other.CustomAgents is not null ? [.. other.CustomAgents] : null;
+        Agent = other.Agent;
         DisabledSkills = other.DisabledSkills is not null ? [.. other.DisabledSkills] : null;
         ExcludedTools = other.ExcludedTools is not null ? [.. other.ExcludedTools] : null;
         Hooks = other.Hooks;
@@ -1307,6 +1308,12 @@ protected SessionConfig(SessionConfig? other)
     /// </summary>
     public List<CustomAgentConfig>? CustomAgents { get; set; }
 
+    /// <summary>
+    /// Name of the custom agent to activate when the session starts.
+    /// Must match the <see cref="CustomAgentConfig.Name"/> of one of the agents in <see cref="CustomAgents"/>.
+    /// </summary>
+    public string? Agent { get; set; }
+
     /// <summary>
     /// Directories to load skills from.
     /// </summary>
@@ -1361,6 +1368,7 @@ protected ResumeSessionConfig(ResumeSessionConfig? other)
         ClientName = other.ClientName;
         ConfigDir = other.ConfigDir;
         CustomAgents = other.CustomAgents is not null ? [.. other.CustomAgents] : null;
+        Agent = other.Agent;
         DisabledSkills = other.DisabledSkills is not null ? [.. other.DisabledSkills] : null;
         DisableResume = other.DisableResume;
         ExcludedTools = other.ExcludedTools is not null ? [.. other.ExcludedTools] : null;
@@ -1476,6 +1484,12 @@ protected ResumeSessionConfig(ResumeSessionConfig? other)
     /// </summary>
     public List<CustomAgentConfig>? CustomAgents { get; set; }
 
+    /// <summary>
+    /// Name of the custom agent to activate when the session starts.
+    /// Must match the <see cref="CustomAgentConfig.Name"/> of one of the agents in <see cref="CustomAgents"/>.
+    /// </summary>
+    public string? Agent { get; set; }
+
     /// <summary>
     /// Directories to load skills from.
     /// </summary>

dotnet/test/CloneTests.cs

@@ -88,6 +88,7 @@ public void SessionConfig_Clone_CopiesAllProperties()
             Streaming = true,
             McpServers = new Dictionary<string, object> { ["server1"] = new object() },
             CustomAgents = [new CustomAgentConfig { Name = "agent1" }],
+            Agent = "agent1",
             SkillDirectories = ["/skills"],
             DisabledSkills = ["skill1"],
         };
@@ -105,6 +106,7 @@ public void SessionConfig_Clone_CopiesAllProperties()
         Assert.Equal(original.Streaming, clone.Streaming);
         Assert.Equal(original.McpServers.Count, clone.McpServers!.Count);
         Assert.Equal(original.CustomAgents.Count, clone.CustomAgents!.Count);
+        Assert.Equal(original.Agent, clone.Agent);
         Assert.Equal(original.SkillDirectories, clone.SkillDirectories);
         Assert.Equal(original.DisabledSkills, clone.DisabledSkills);
     }
@@ -242,4 +244,32 @@ public void Clone_WithNullCollections_ReturnsNullCollections()
         Assert.Null(clone.DisabledSkills);
         Assert.Null(clone.Tools);
     }
+
+    [Fact]
+    public void SessionConfig_Clone_CopiesAgentProperty()
+    {
+        var original = new SessionConfig
+        {
+            Agent = "test-agent",
+            CustomAgents = [new CustomAgentConfig { Name = "test-agent", Prompt = "You are a test agent." }],
+        };
+
+        var clone = original.Clone();
+
+        Assert.Equal("test-agent", clone.Agent);
+    }
+
+    [Fact]
+    public void ResumeSessionConfig_Clone_CopiesAgentProperty()
+    {
+        var original = new ResumeSessionConfig
+        {
+            Agent = "test-agent",
+            CustomAgents = [new CustomAgentConfig { Name = "test-agent", Prompt = "You are a test agent." }],
+        };
+
+        var clone = original.Clone();
+
+        Assert.Equal("test-agent", clone.Agent);
+    }
 }

go/client.go

@@ -502,6 +502,7 @@ func (c *Client) CreateSession(ctx context.Context, config *SessionConfig) (*Ses
 	req.MCPServers = config.MCPServers
 	req.EnvValueMode = "direct"
 	req.CustomAgents = config.CustomAgents
+	req.Agent = config.Agent
 	req.SkillDirectories = config.SkillDirectories
 	req.DisabledSkills = config.DisabledSkills
 	req.InfiniteSessions = config.InfiniteSessions
@@ -616,6 +617,7 @@ func (c *Client) ResumeSessionWithOptions(ctx context.Context, sessionID string,
 	req.MCPServers = config.MCPServers
 	req.EnvValueMode = "direct"
 	req.CustomAgents = config.CustomAgents
+	req.Agent = config.Agent
 	req.SkillDirectories = config.SkillDirectories
 	req.DisabledSkills = config.DisabledSkills
 	req.InfiniteSessions = config.InfiniteSessions

go/client_test.go

@@ -413,6 +413,60 @@ func TestResumeSessionRequest_ClientName(t *testing.T) {
 	})
 }
 
+func TestCreateSessionRequest_Agent(t *testing.T) {
+	t.Run("includes agent in JSON when set", func(t *testing.T) {
+		req := createSessionRequest{Agent: "test-agent"}
+		data, err := json.Marshal(req)
+		if err != nil {
+			t.Fatalf("Failed to marshal: %v", err)
+		}
+		var m map[string]any
+		if err := json.Unmarshal(data, &m); err != nil {
+			t.Fatalf("Failed to unmarshal: %v", err)
+		}
+		if m["agent"] != "test-agent" {
+			t.Errorf("Expected agent to be 'test-agent', got %v", m["agent"])
+		}
+	})
+
+	t.Run("omits agent from JSON when empty", func(t *testing.T) {
+		req := createSessionRequest{}
+		data, _ := json.Marshal(req)
+		var m map[string]any
+		json.Unmarshal(data, &m)
+		if _, ok := m["agent"]; ok {
+			t.Error("Expected agent to be omitted when empty")
+		}
+	})
+}
+
+func TestResumeSessionRequest_Agent(t *testing.T) {
+	t.Run("includes agent in JSON when set", func(t *testing.T) {
+		req := resumeSessionRequest{SessionID: "s1", Agent: "test-agent"}
+		data, err := json.Marshal(req)
+		if err != nil {
+			t.Fatalf("Failed to marshal: %v", err)
+		}
+		var m map[string]any
+		if err := json.Unmarshal(data, &m); err != nil {
+			t.Fatalf("Failed to unmarshal: %v", err)
+		}
+		if m["agent"] != "test-agent" {
+			t.Errorf("Expected agent to be 'test-agent', got %v", m["agent"])
+		}
+	})
+
+	t.Run("omits agent from JSON when empty", func(t *testing.T) {
+		req := resumeSessionRequest{SessionID: "s1"}
+		data, _ := json.Marshal(req)
+		var m map[string]any
+		json.Unmarshal(data, &m)
+		if _, ok := m["agent"]; ok {
+			t.Error("Expected agent to be omitted when empty")
+		}
+	})
+}
+
 func TestOverridesBuiltInTool(t *testing.T) {
 	t.Run("OverridesBuiltInTool is serialized in tool definition", func(t *testing.T) {
 		tool := Tool{

go/types.go

@@ -384,6 +384,9 @@ type SessionConfig struct {
 	MCPServers map[string]MCPServerConfig
 	// CustomAgents configures custom agents for the session
 	CustomAgents []CustomAgentConfig
+	// Agent is the name of the custom agent to activate when the session starts.
+	// Must match the Name of one of the agents in CustomAgents.
+	Agent string
 	// SkillDirectories is a list of directories to load skills from
 	SkillDirectories []string
 	// DisabledSkills is a list of skill names to disable
@@ -467,6 +470,9 @@ type ResumeSessionConfig struct {
 	MCPServers map[string]MCPServerConfig
 	// CustomAgents configures custom agents for the session
 	CustomAgents []CustomAgentConfig
+	// Agent is the name of the custom agent to activate when the session starts.
+	// Must match the Name of one of the agents in CustomAgents.
+	Agent string
 	// SkillDirectories is a list of directories to load skills from
 	SkillDirectories []string
 	// DisabledSkills is a list of skill names to disable
@@ -652,6 +658,7 @@ type createSessionRequest struct {
 	MCPServers        map[string]MCPServerConfig `json:"mcpServers,omitempty"`
 	EnvValueMode      string                     `json:"envValueMode,omitempty"`
 	CustomAgents      []CustomAgentConfig        `json:"customAgents,omitempty"`
+	Agent             string                     `json:"agent,omitempty"`
 	ConfigDir         string                     `json:"configDir,omitempty"`
 	SkillDirectories  []string                   `json:"skillDirectories,omitempty"`
 	DisabledSkills    []string                   `json:"disabledSkills,omitempty"`
@@ -685,6 +692,7 @@ type resumeSessionRequest struct {
 	MCPServers        map[string]MCPServerConfig `json:"mcpServers,omitempty"`
 	EnvValueMode      string                     `json:"envValueMode,omitempty"`
 	CustomAgents      []CustomAgentConfig        `json:"customAgents,omitempty"`
+	Agent             string                     `json:"agent,omitempty"`
 	SkillDirectories  []string                   `json:"skillDirectories,omitempty"`
 	DisabledSkills    []string                   `json:"disabledSkills,omitempty"`
 	InfiniteSessions  *InfiniteSessionConfig     `json:"infiniteSessions,omitempty"`

nodejs/src/client.ts

@@ -567,6 +567,7 @@ export class CopilotClient {
             mcpServers: config.mcpServers,
             envValueMode: "direct",
             customAgents: config.customAgents,
+            agent: config.agent,
             configDir: config.configDir,
             skillDirectories: config.skillDirectories,
             disabledSkills: config.disabledSkills,
@@ -654,6 +655,7 @@ export class CopilotClient {
             mcpServers: config.mcpServers,
             envValueMode: "direct",
             customAgents: config.customAgents,
+            agent: config.agent,
             skillDirectories: config.skillDirectories,
             disabledSkills: config.disabledSkills,
             infiniteSessions: config.infiniteSessions,

nodejs/src/types.ts

@@ -725,6 +725,13 @@ export interface SessionConfig {
      */
     customAgents?: CustomAgentConfig[];
 
+    /**
+     * Name of the custom agent to activate when the session starts.
+     * Must match the `name` of one of the agents in `customAgents`.
+     * Equivalent to calling `session.rpc.agent.select({ name })` after creation.
+     */
+    agent?: string;
+
     /**
      * Directories to load skills from.
      */
@@ -764,6 +771,7 @@ export type ResumeSessionConfig = Pick<
     | "configDir"
     | "mcpServers"
     | "customAgents"
+    | "agent"
     | "skillDirectories"
     | "disabledSkills"
     | "infiniteSessions"