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

[patniko]

Summary

Adds an optional agent field to SessionConfig and ResumeSessionConfig across all four SDKs that allows specifying which custom agent should be active when a session starts.

Problem

Users had to create a session and then make a separate session.rpc.agent.select() call to activate a specific custom agent. The CLI supports --agent MyAgent but the SDK had no equivalent. This was a frequently requested feature.

Solution

Add agent?: string to session config in all 4 SDKs. The value must match the name of one of the agents in customAgents. The runtime will select the specified agent when the session starts, equivalent to calling session.rpc.agent.select() after creation.

Example (TypeScript)

const session = await client.createSession({
    customAgents: [
        { name: "researcher", prompt: "You are a research assistant." },
        { name: "editor", prompt: "You are a code editor." },
    ],
    agent: "researcher", // Pre-select the researcher agent
    onPermissionRequest: approveAll,
});

Changes

SDK (all 4 languages)

• Types: Added agent field to SessionConfig and ResumeSessionConfig
• Client: Wired agent into session.create and session.resume RPC payloads
• Node.js: agent?: string in SessionConfig, passed in client.ts
• Python: agent: str in SessionConfig, passed in client.py
• Go: Agent string in SessionConfig, passed in client.go
• .NET: Agent property in SessionConfig, updated records and call sites in Client.cs

Documentation

• Added "Selecting an Agent at Session Creation" section with examples in all 4 languages to docs/guides/custom-agents.md
• Updated session config reference table with new agent parameter
• Updated docs/guides/session-persistence.md resume options table
• Updated docs/getting-started.md with a tip about the new parameter

Tests

• Added unit tests verifying agent is forwarded in both session.create and session.resume RPC calls

Runtime note

The runtime side (copilot-agent-runtime) needs a corresponding change to read the agent field from SessionCreateRequest/SessionResumeRequest and call selectCustomAgent() during session initialization. Until then, the SDK will send the field but the runtime will ignore it. This is backward-compatible — the field is optional and unknown fields are safely ignored by JSON-RPC.

Closes #317
Closes #410
Closes #547

[Copilot]

Pull request overview

This PR adds an optional agent field to session configuration across all four SDK languages (Node.js, Python, Go, .NET), enabling users to pre-select a custom agent when creating or resuming a session. This eliminates the need for a separate session.rpc.agent.select() call after session creation, matching the CLI's --agent flag functionality.

Changes:

• Added agent field to SessionConfig and ResumeSessionConfig types in all four SDKs, wired into the session.create and session.resume RPC payloads
• Added unit tests in Node.js verifying agent is forwarded in both session.create and session.resume requests
• Updated documentation with a new "Selecting an Agent at Session Creation" section in custom-agents.md, plus updates to session-persistence.md and getting-started.md

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
nodejs/src/types.ts	Added agent?: string to SessionConfig and included it in ResumeSessionConfig Pick type
nodejs/src/client.ts	Wired config.agent into session.create and session.resume RPC payloads
nodejs/test/client.test.ts	Added unit tests for agent forwarding in create and resume requests
python/copilot/types.py	Added agent: str to SessionConfig and ResumeSessionConfig TypedDicts
python/copilot/client.py	Wired agent into session.create and session.resume payloads
go/types.go	Added Agent string to SessionConfig, ResumeSessionConfig, and wire format request structs
go/client.go	Wired config.Agent into CreateSession and ResumeSessionWithOptions
dotnet/src/Types.cs	Added Agent property to SessionConfig and ResumeSessionConfig with copy constructors
dotnet/src/Client.cs	Added Agent to CreateSessionRequest/ResumeSessionRequest records and call sites
docs/guides/custom-agents.md	New section with examples in all 4 languages for agent pre-selection
docs/guides/session-persistence.md	Added agent to resume options table
docs/getting-started.md	Added tip about agent parameter in custom agents section

[github-actions]

Cross-SDK Consistency Review ✅

I've reviewed this PR for consistency across all four SDK implementations (Node.js, Python, Go, and .NET).

✅ Excellent consistency in implementation:

All four SDKs properly implement the agent parameter:

• ✅ Type definitions in both SessionConfig and ResumeSessionConfig with appropriate naming conventions (camelCase/snake_case/PascalCase)
• ✅ Client methods forward the parameter in both create and resume operations
• ✅ Wire protocol uses consistent JSON field name "agent" with proper optional handling
• ✅ Comprehensive documentation with examples in all 4 languages

⚠️ Minor inconsistency: Unit test coverage

Node.js and Python include unit tests verifying the agent parameter is forwarded:

• nodejs/test/client.test.ts: Tests session.create and session.resume RPC payloads contain the agent field
• python/test_client.py: Tests session.create and session.resume RPC payloads contain the agent field

Go and .NET are missing equivalent unit tests:

• .NET only tests property cloning in CloneTests.cs, but doesn't verify RPC payload forwarding
• Go has no new unit tests for this feature

Suggestion: Consider adding unit tests similar to Node.js/Python for Go and .NET to verify the Agent field is correctly forwarded in the session.create and session.resume RPC requests. This would ensure feature parity in test coverage and prevent regressions.

Overall Assessment

This is a well-executed cross-SDK feature addition with excellent consistency in the API design, implementation, and documentation. The missing unit tests in Go/.NET are a minor gap but don't affect the functionality itself.

Generated by SDK Consistency Review Agent for issue #722 · ◷

[github-actions]

✅ Cross-SDK Consistency Review: APPROVED

This PR demonstrates excellent cross-SDK consistency. The agent parameter has been properly implemented across all four SDK implementations with appropriate language-specific conventions.

Verified Consistency

API Design ✅

All SDKs expose the same functionality with proper naming conventions:

• Node.js: agent?: string (camelCase, optional)
• Python: agent: str (snake_case in code, NotRequired via TypedDict total=False)
• Go: Agent string (PascalCase, zero-value = empty)
• .NET: Agent property (PascalCase, nullable)

Feature Parity ✅

All SDKs implement the feature identically:

• ✅ Added to both SessionConfig and ResumeSessionConfig
• ✅ Forwarded in both session creation and resume RPCs
• ✅ Proper wire format ("agent" JSON field with omitempty semantics)
• ✅ Tests verify the parameter is forwarded correctly

Documentation ✅

• ✅ Examples provided for all 4 languages in docs/features/custom-agents.md
• ✅ Session config reference tables updated across all relevant docs
• ✅ Consistent descriptions and usage patterns

Language-Specific Implementation Notes

The PR properly accounts for each language's idioms:

• .NET: Clone methods updated to copy the new property (verified with dedicated tests)
• Go: Correct JSON struct tags (json:"agent,omitempty")
• TypeScript: Uses Pick utility type to derive ResumeSessionConfig from SessionConfig
• Python: Uses TypedDict with total=False for optional fields

Summary

No consistency issues found. This PR maintains perfect feature parity across all SDK implementations and follows established patterns in the codebase. The implementation is ready from a cross-SDK consistency perspective. 🎯

Generated by SDK Consistency Review Agent for issue #722 · ◷