SessionConfig
You can configure many behaviors with theSessionConfig class.
Use it with Copilot::run(prompt: '...', config: $config) or Copilot::start(function (CopilotSession $session) { ... }, config: $config).
If you only need simple options like a model ID, you can pass an array instead of using SessionConfig: Copilot::run(prompt: '...', config: ['model' => 'auto']).
use Revolution\Copilot\Enums\ReasoningEffort;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ElicitationContext;
use Revolution\Copilot\Types\InfiniteSessionConfig;
use Revolution\Copilot\Types\Rpc\ModelCapabilitiesOverride;
use Revolution\Copilot\Types\Rpc\ModelCapabilitiesOverrideLimits;
use Revolution\Copilot\Types\Rpc\ModelCapabilitiesOverrideSupports;
use Revolution\Copilot\Types\SessionConfig;
use Revolution\Copilot\Types\SessionEvent;
use Revolution\Copilot\Types\SystemMessageConfig;
use Revolution\Copilot\Types\UserInputRequest;
$config = new SessionConfig(
// Model to use
model: 'auto',
// Fixed session ID when creating a new session
sessionId: 'session-123',
clientName: 'my-app',
// Reasoning level (only for supported models)
reasoningEffort: ReasoningEffort::HIGH,
// Override model capabilities. Deep-merged with runtime defaults.
// modelCapabilities: new ModelCapabilitiesOverride(
// supports: new ModelCapabilitiesOverrideSupports(vision: true, reasoningEffort: true),
// limits: new ModelCapabilitiesOverrideLimits(max_prompt_tokens: 200000),
// ),
// Array format is also supported
// modelCapabilities: ['supports' => ['vision' => true]],
// Override config directory
configDirectory: '',
// Enable auto-discovery of MCP settings and skill directories
// Auto-detects .mcp.json and .vscode/mcp.json from the working directory,
// then merges them with explicitly provided mcpServers and skillDirectories.
// Explicit values win on name conflicts.
enableConfigDiscovery: true,
// Custom tools
tools: [...],
// System message
systemMessage: new SystemMessageConfig(
content: 'You are a helpful assistant for Laravel developers.',
),
// Replace mode (fully replace the system prompt)
// systemMessage: new SystemMessageConfig(
// mode: 'replace',
// content: 'Entire custom system prompt',
// ),
// Customize mode (override by section)
// systemMessage: new SystemMessageConfig(
// mode: 'customize',
// sections: [
// 'tone' => new SectionOverride(action: SectionOverrideAction::REPLACE, content: 'Always respond in Japanese.'),
// 'safety' => new SectionOverride(action: SectionOverrideAction::REMOVE),
// 'custom_instructions' => new SectionOverride(action: SectionOverrideAction::APPEND, content: 'Additional instructions here.'),
// ],
// content: 'Optional extra content like append mode',
// ),
// Custom provider
provider: new ProviderConfig(),
// Per-session GitHub token (multi-tenant support)
// Specifies a token per session, separate from the client-level github_token
gitHubToken: $user->github_token,
onPermissionRequest: function (array $request) {
// Handle permission requests
},
onUserInputRequest: function (UserInputRequest $request) {
// Handle user input requests (ask_user)
},
// Elicitation request handler
// Lets you receive form-based UI dialog requests from the agent
onElicitationRequest: function (ElicitationContext $context) {
// Handle elicitation request
return ['action' => 'accept', 'content' => ['field' => 'value']];
},
// Session hooks
hooks: [],
// Working directory
workingDirectory: '',
// Enable streaming
streaming: true,
// Whether to include sub-agent streaming events in the main stream (default: true)
includeSubAgentStreamingEvents: true,
// Allowed built-in tools
availableTools: ['read_file', 'write_file'],
// Or excluded tools
excludedTools: ['shell'],
// MCP server configuration
mcpServers: [
'github' => [
'type' => 'http',
'url' => 'https://api.githubcopilot.com/mcp/',
],
],
// Custom agents
customAgents: [
[
'name' => 'reviewer',
'displayName' => 'Code Reviewer',
'description' => 'Reviews code for best practices',
'prompt' => 'You are an expert code reviewer.',
],
],
// Default agent configuration. Applied to the built-in agent when no custom agent is selected.
// excludedTools: list of tools to exclude from the default agent.
// Custom sub-agents can still use excluded tools.
defaultAgent: ['excludedTools' => ['tool_name']],
// Agent activated at session start. Must match customAgents.name.
agent: 'reviewer',
// Skill directories
skillDirectories: [],
// Disabled skills
disabledSkills: [],
// Infinite session configuration (enabled by default)
infiniteSessions: new InfiniteSessionConfig(
enabled: true,
backgroundCompactionThreshold: 0.80, // Start compaction at 80% context usage
bufferExhaustionThreshold: 0.95, // Block at 95% until compaction finishes
),
// Disable infinite sessions
// infiniteSessions: new InfiniteSessionConfig(enabled: false),
// Register event handlers before the session creation RPC.
// Use this to avoid missing early events such as session.start.
// Equivalent to calling $session->on($handler) later, but earlier in the lifecycle.
onEvent: function (SessionEvent $event) {
// Receive all session events
},
);
$response = Copilot::run('...', config: $config);
ResumeSessionConfig.
It is almost the same as SessionConfig, but has small differences.
In ResumeSessionConfig, specify only the options you want to change.
All other settings are inherited from the original session start.
For cloud execution, see Cloud Sessions; for plugin directories, see Plugin Directories.
For the latest updates, see the GitHub repository.