Package com.github.copilot.sdk.json

Class SessionConfig

java.lang.Object
com.github.copilot.sdk.json.SessionConfig
public class SessionConfig extends Object
Configuration for creating a new Copilot session.

This class provides options for customizing session behavior, including model selection, tool registration, system message customization, and more. All setter methods return this for method chaining.

Example Usage


 var config = new SessionConfig().setModel("gpt-5").setStreaming(true).setSystemMessage(
 		new SystemMessageConfig().setMode(SystemMessageMode.APPEND).setContent("Be concise in your responses."));

 var session = client.createSession(config).get();
Since:
1.0.0
See Also:

  • Constructor Details

    • SessionConfig

      public SessionConfig()

  • Method Details

    • getSessionId

      public String getSessionId()
      Gets the custom session ID.
      Returns:
      the session ID, or null to generate automatically

    • setSessionId

      public SessionConfig setSessionId(String sessionId)
      Sets a custom session ID.

      If not provided, a unique session ID will be generated automatically.

      Parameters:
      sessionId - the custom session ID
      Returns:
      this config instance for method chaining

    • getClientName

      public String getClientName()
      Gets the client name used to identify the application using the SDK.
      Returns:
      the client name, or null if not set

    • setClientName

      public SessionConfig setClientName(String clientName)
      Sets the client name to identify the application using the SDK.

      This value is included in the User-Agent header for API requests.

      Parameters:
      clientName - the client name
      Returns:
      this config instance for method chaining

    • getModel

      public String getModel()
      Gets the AI model to use.
      Returns:
      the model name

    • setModel

      public SessionConfig setModel(String model)
      Sets the AI model to use for this session.

      Examples: "gpt-5", "claude-sonnet-4.5", "o3-mini".

      Parameters:
      model - the model name
      Returns:
      this config instance for method chaining

    • getReasoningEffort

      public String getReasoningEffort()
      Gets the reasoning effort level.
      Returns:
      the reasoning effort level ("low", "medium", "high", or "xhigh")

    • setReasoningEffort

      public SessionConfig setReasoningEffort(String reasoningEffort)
      Sets the reasoning effort level for models that support it.

      Valid values: "low", "medium", "high", "xhigh". Only applies to models where capabilities.supports.reasoningEffort is true.

      Parameters:
      reasoningEffort - the reasoning effort level
      Returns:
      this config instance for method chaining

    • getTools

      public List<ToolDefinition> getTools()
      Gets the custom tools for this session.
      Returns:
      the list of tool definitions

    • setTools

      public SessionConfig setTools(List<ToolDefinition> tools)
      Sets custom tools that the assistant can invoke during the session.

      Tools allow the assistant to call back into your application to perform actions or retrieve information.

      Parameters:
      tools - the list of tool definitions
      Returns:
      this config instance for method chaining
      See Also:

    • getSystemMessage

      public SystemMessageConfig getSystemMessage()
      Gets the system message configuration.
      Returns:
      the system message config

    • setSystemMessage

      public SessionConfig setSystemMessage(SystemMessageConfig systemMessage)
      Sets the system message configuration.

      The system message controls the behavior and personality of the assistant. Use SystemMessageMode.APPEND to add instructions while preserving default behavior, or SystemMessageMode.REPLACE to fully customize.

      Parameters:
      systemMessage - the system message configuration
      Returns:
      this config instance for method chaining
      See Also:

    • getAvailableTools

      public List<String> getAvailableTools()
      Gets the list of allowed tool names.
      Returns:
      the list of available tool names

    • setAvailableTools

      public SessionConfig setAvailableTools(List<String> availableTools)
      Sets the list of tool names that are allowed in this session.

      When specified, only tools in this list will be available to the assistant.

      Parameters:
      availableTools - the list of allowed tool names
      Returns:
      this config instance for method chaining

    • getExcludedTools

      public List<String> getExcludedTools()
      Gets the list of excluded tool names.
      Returns:
      the list of excluded tool names

    • setExcludedTools

      public SessionConfig setExcludedTools(List<String> excludedTools)
      Sets the list of tool names to exclude from this session.

      Tools in this list will not be available to the assistant.

      Parameters:
      excludedTools - the list of tool names to exclude
      Returns:
      this config instance for method chaining

    • getProvider

      public ProviderConfig getProvider()
      Gets the custom API provider configuration.
      Returns:
      the provider configuration

    • setProvider

      public SessionConfig setProvider(ProviderConfig provider)
      Sets a custom API provider for BYOK (Bring Your Own Key) scenarios.

      This allows using your own OpenAI, Azure OpenAI, or other compatible API endpoints instead of the default Copilot backend.

      Parameters:
      provider - the provider configuration
      Returns:
      this config instance for method chaining
      See Also:

    • getOnPermissionRequest

      public PermissionHandler getOnPermissionRequest()
      Gets the permission request handler.
      Returns:
      the permission handler

    • setOnPermissionRequest

      public SessionConfig setOnPermissionRequest(PermissionHandler onPermissionRequest)
      Sets a handler for permission requests from the assistant.

      When the assistant needs permission to perform certain actions, this handler will be invoked to approve or deny the request.

      Parameters:
      onPermissionRequest - the permission handler
      Returns:
      this config instance for method chaining
      See Also:

    • getOnUserInputRequest

      public UserInputHandler getOnUserInputRequest()
      Gets the user input request handler.
      Returns:
      the user input handler

    • setOnUserInputRequest

      public SessionConfig setOnUserInputRequest(UserInputHandler onUserInputRequest)
      Sets a handler for user input requests from the agent.

      When provided, enables the ask_user tool for the agent to request user input.

      Parameters:
      onUserInputRequest - the user input handler
      Returns:
      this config instance for method chaining
      See Also:

    • getHooks

      public SessionHooks getHooks()
      Gets the hook handlers configuration.
      Returns:
      the session hooks

    • setHooks

      public SessionConfig setHooks(SessionHooks hooks)
      Sets hook handlers for session lifecycle events.

      Hooks allow you to intercept and modify tool execution behavior.

      Parameters:
      hooks - the hooks configuration
      Returns:
      this config instance for method chaining
      See Also:

    • getWorkingDirectory

      public String getWorkingDirectory()
      Gets the working directory for the session.
      Returns:
      the working directory path

    • setWorkingDirectory

      public SessionConfig setWorkingDirectory(String workingDirectory)
      Sets the working directory for the session.
      Parameters:
      workingDirectory - the working directory path
      Returns:
      this config instance for method chaining

    • isStreaming

      public boolean isStreaming()
      Returns whether streaming is enabled.
      Returns:
      true if streaming is enabled

    • setStreaming

      public SessionConfig setStreaming(boolean streaming)
      Sets whether to enable streaming of response chunks.

      When enabled, the session will emit AssistantMessageDeltaEvent events as the response is generated, allowing for real-time display of partial responses.

      Parameters:
      streaming - true to enable streaming
      Returns:
      this config instance for method chaining

    • getMcpServers

      public Map<String,McpServerConfig> getMcpServers()
      Gets the MCP server configurations.
      Returns:
      the MCP servers map

    • setMcpServers

      public SessionConfig setMcpServers(Map<String,McpServerConfig> mcpServers)
      Sets MCP (Model Context Protocol) server configurations.

      MCP servers extend the assistant's capabilities by providing additional context sources and tools.

      Parameters:
      mcpServers - the MCP servers configuration map
      Returns:
      this config instance for method chaining

    • getCustomAgents

      public List<CustomAgentConfig> getCustomAgents()
      Gets the custom agent configurations.
      Returns:
      the list of custom agent configurations

    • setCustomAgents

      public SessionConfig setCustomAgents(List<CustomAgentConfig> customAgents)
      Sets custom agent configurations.

      Custom agents allow extending the assistant with specialized behaviors and capabilities.

      Parameters:
      customAgents - the list of custom agent configurations
      Returns:
      this config instance for method chaining
      See Also:

    • getAgent

      public String getAgent()
      Gets the name of the custom agent to activate at session start.
      Returns:
      the agent name, or null if not set

    • setAgent

      public SessionConfig setAgent(String agent)
      Sets the name of the custom agent to activate when the session starts.

      Must match the name of one of the agents in setCustomAgents(List).

      Parameters:
      agent - the agent name to pre-select
      Returns:
      this config instance for method chaining

    • getInfiniteSessions

      public InfiniteSessionConfig getInfiniteSessions()
      Gets the infinite sessions configuration.
      Returns:
      the infinite sessions config

    • setInfiniteSessions

      public SessionConfig setInfiniteSessions(InfiniteSessionConfig infiniteSessions)
      Sets the infinite session configuration for persistent workspaces and automatic compaction.

      When enabled (default), sessions automatically manage context limits and persist state to a workspace directory. The workspace contains checkpoints/, plan.md, and files/ subdirectories.

      Parameters:
      infiniteSessions - the infinite sessions configuration
      Returns:
      this config instance for method chaining
      See Also:

    • getSkillDirectories

      public List<String> getSkillDirectories()
      Gets the skill directories.
      Returns:
      the list of skill directory paths

    • setSkillDirectories

      public SessionConfig setSkillDirectories(List<String> skillDirectories)
      Sets the skill directories for loading custom skills.

      Skills are loaded from SKILL.md files in subdirectories of the specified directories. Each skill subdirectory should contain a SKILL.md file with YAML frontmatter defining the skill metadata.

      Parameters:
      skillDirectories - the list of skill directory paths
      Returns:
      this config instance for method chaining

    • getDisabledSkills

      public List<String> getDisabledSkills()
      Gets the disabled skill names.
      Returns:
      the list of disabled skill names

    • setDisabledSkills

      public SessionConfig setDisabledSkills(List<String> disabledSkills)
      Sets the list of skill names to disable.

      Skills in this list will not be applied to the session, even if they are found in the skill directories.

      Parameters:
      disabledSkills - the list of skill names to disable
      Returns:
      this config instance for method chaining

    • getConfigDir

      public String getConfigDir()
      Gets the custom configuration directory.
      Returns:
      the config directory path

    • setConfigDir

      public SessionConfig setConfigDir(String configDir)
      Sets a custom configuration directory for the session.

      This allows using a specific directory for session configuration instead of the default location.

      Parameters:
      configDir - the configuration directory path
      Returns:
      this config instance for method chaining

    • getEnableConfigDiscovery

      public Boolean getEnableConfigDiscovery()
      Gets whether automatic configuration discovery is enabled.
      Returns:
      true to enable discovery, false to disable, or null to use the runtime default

    • setEnableConfigDiscovery

      public SessionConfig setEnableConfigDiscovery(Boolean enableConfigDiscovery)
      Sets whether to automatically discover MCP server configurations and skill directories from the working directory.

      When true, the CLI scans the working directory for .mcp.json, .vscode/mcp.json and skill directories, and merges them with explicitly provided setMcpServers(Map) and setSkillDirectories(List), with explicit values taking precedence on name collision.

      Parameters:
      enableConfigDiscovery - true to enable discovery, false to disable, or null to use the runtime default
      Returns:
      this config instance for method chaining

    • getIncludeSubAgentStreamingEvents

      public Boolean getIncludeSubAgentStreamingEvents()
      Gets whether sub-agent streaming events are included.
      Returns:
      true to include sub-agent streaming events, false to suppress them, or null to use the runtime default

    • setIncludeSubAgentStreamingEvents

      public SessionConfig setIncludeSubAgentStreamingEvents(Boolean includeSubAgentStreamingEvents)
      Sets whether to include sub-agent streaming events in the event stream.

      When true, streaming delta events from sub-agents (e.g., assistant.message_delta with agentId set) are forwarded to this connection. When false, only non-streaming sub-agent events and subagent.* lifecycle events are forwarded; streaming deltas from sub-agents are suppressed. Default: true.

      Parameters:
      includeSubAgentStreamingEvents - true to include streaming events, false to suppress
      Returns:
      this config instance for method chaining

    • getModelCapabilities

      public ModelCapabilitiesOverride getModelCapabilities()
      Gets the model capabilities override.
      Returns:
      the model capabilities override, or null if not set

    • setModelCapabilities

      public SessionConfig setModelCapabilities(ModelCapabilitiesOverride modelCapabilities)
      Sets per-property overrides for model capabilities, deep-merged over runtime defaults.

      Use this to override specific model capabilities (such as vision support) for this session. Only non-null fields in the override are applied; unset fields retain their runtime defaults.

      Parameters:
      modelCapabilities - the model capabilities override
      Returns:
      this config instance for method chaining
      See Also:

    • getOnEvent

      public Consumer<SessionEvent> getOnEvent()
      Gets the event handler registered before the session.create RPC is issued.
      Returns:
      the event handler, or null if not set

    • setOnEvent

      public SessionConfig setOnEvent(Consumer<SessionEvent> onEvent)
      Sets an event handler that is registered on the session before the session.create RPC is issued.

      Equivalent to calling CopilotSession.on(Consumer) immediately after creation, but executes earlier in the lifecycle so no events are missed. Using this property rather than CopilotSession.on() guarantees that early events emitted by the CLI during session creation (e.g. session.start) are delivered to the handler.

      Parameters:
      onEvent - the event handler to register before session creation
      Returns:
      this config instance for method chaining

    • getCommands

      public List<CommandDefinition> getCommands()
      Gets the slash commands registered for this session.
      Returns:
      the list of command definitions, or null

    • setCommands

      public SessionConfig setCommands(List<CommandDefinition> commands)
      Sets slash commands registered for this session.

      When the CLI has a TUI, each command appears as /name for the user to invoke. The handler is called when the user executes the command.

      Parameters:
      commands - the list of command definitions
      Returns:
      this config instance for method chaining
      See Also:

    • getOnElicitationRequest

      public ElicitationHandler getOnElicitationRequest()
      Gets the elicitation request handler.
      Returns:
      the elicitation handler, or null

    • setOnElicitationRequest

      public SessionConfig setOnElicitationRequest(ElicitationHandler onElicitationRequest)
      Sets a handler for elicitation requests from the server or MCP tools.

      When provided, the server will route elicitation requests to this handler and report elicitation as a supported capability.

      Parameters:
      onElicitationRequest - the elicitation handler
      Returns:
      this config instance for method chaining
      See Also:

    • clone

      public SessionConfig clone()
      Creates a shallow clone of this SessionConfig instance.

      Mutable collection properties are copied into new collection instances so that modifications to those collections on the clone do not affect the original. Other reference-type properties (like provider configuration, system messages, hooks, infinite session configuration, and handlers) are not deep-cloned; the original and the clone will share those objects.

      Returns:
      a clone of this config instance