> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# SessionConfig

> Configura strumenti, MCP, hook, agenti ed eventi del ciclo di vita con SessionConfig di Laravel Copilot SDK.

## SessionConfig

Con la classe `SessionConfig` puoi effettuare varie configurazioni.

Si usa come `Copilot::run(prompt: '...', config: $config)` o `Copilot::start(function (CopilotSession $session) { ... }, config: $config)`.
Quando la classe `SessionConfig` sarebbe eccessiva, ad esempio se vuoi solo specificare il modello, puoi anche passare un array. `Copilot::run(prompt: '...', config: ['model' => 'auto'])`

```php theme={null}
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionConfig;
use Revolution\Copilot\Types\SystemMessageConfig;
use Revolution\Copilot\Types\InfiniteSessionConfig;
use Revolution\Copilot\Types\UserInputRequest;
use Revolution\Copilot\Types\Rpc\ModelCapabilitiesOverride;
use Revolution\Copilot\Types\Rpc\ModelCapabilitiesOverrideSupports;
use Revolution\Copilot\Types\Rpc\ModelCapabilitiesOverrideLimits;
use Revolution\Copilot\Enums\ReasoningEffort;

$config = new SessionConfig(
    // Specifica il modello da usare
    model: 'auto',

    // Specifica un ID sessione fisso alla creazione di una nuova sessione
    sessionId: 'session-123',

    clientName: 'my-app',

    // Livello di reasoning. Configurabile solo con modelli che lo supportano.
    reasoningEffort: ReasoningEffort::HIGH,

    // Override delle capabilities del modello. Viene deep-merged sui default del runtime.
    // modelCapabilities: new ModelCapabilitiesOverride(
    //     supports: new ModelCapabilitiesOverrideSupports(vision: true, reasoningEffort: true),
    //     limits: new ModelCapabilitiesOverrideLimits(max_prompt_tokens: 200000),
    // ),
    // È possibile specificarlo anche come array
    // modelCapabilities: ['supports' => ['vision' => true]],

    // Sovrascrive la directory di config
    configDirectory: '',

    // Abilita il rilevamento automatico di configurazioni MCP e directory di skill
    // Rileva automaticamente .mcp.json o .vscode/mcp.json dalla working directory e
    // li fonde con gli mcpServers e skillDirectories specificati esplicitamente (in caso di conflitto di nome ha priorità la specifica esplicita)
    enableConfigDiscovery: true,

    // Strumenti personalizzati
    tools: [...],

    // Messaggio di sistema
    systemMessage: new SystemMessageConfig(
        content: 'You are a helpful assistant for Laravel developers.',
    ),

    // Messaggio di sistema: modalità replace (sostituisce completamente il system prompt)
    // systemMessage: new SystemMessageConfig(
    //     mode: 'replace',
    //     content: 'Intero system prompt personalizzato',
    // ),

    // Messaggio di sistema: modalità customize (override per sezione)
    // 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: 'Contenuto aggiuntivo analogo alla modalità append (opzionale)',
    // ),

    // Provider personalizzato
    provider: new ProviderConfig(),

    // Token GitHub per singola sessione (supporto multi-tenant)
    // Indipendentemente dal github_token a livello di client, puoi specificare il token per sessione
    gitHubToken: $user->github_token,

    // Modalità della sessione remota
    // 'off' - solo locale (default)
    // 'export' - esporta gli eventi della sessione su GitHub (nessuno steering remoto)
    // 'on' - abilita sia l'export sia lo steering remoto
    remoteSession: \Revolution\Copilot\Enums\RemoteSessionMode::Export,

    // Sessione cloud (crea la sessione nel cloud anziché in locale)
    // Opzionalmente puoi associare le informazioni del repository
    cloud: new \Revolution\Copilot\Types\CloudSessionOptions(
        repository: new \Revolution\Copilot\Types\CloudSessionRepository(
            owner: 'myorg',
            name: 'myrepo',
            branch: 'main',
        ),
    ),

    onPermissionRequest: function (array $request) {
        // Gestisce le richieste di permesso
    },

    onUserInputRequest: function (UserInputRequest $request) {
        // Gestisce le richieste di input utente. ask_user
    },

    // Handler per le richieste di elicitation
    // Se configurato, ricevi richieste di dialogo UI form-based dall'agente
    onElicitationRequest: function (ElicitationContext $context) {
        // Gestisce la richiesta di elicitation
        return ['action' => 'accept', 'content' => ['field' => 'value']];
    },

    // Handler per la richiesta di uscita dalla plan mode
    // Se configurato, ricevi la richiesta quando l'agente esce dalla plan mode
    onExitPlanModeRequest: function (ExitPlanModeRequest $request) {
        // Verifica il piano e approva/rifiuta
        return new ExitPlanModeResult(approved: true, selectedAction: $request->recommendedAction);
    },

    // Handler per la richiesta di cambio modalità automatico
    // Al raggiungimento del rate limit puoi scegliere se autorizzare il passaggio alla modalità auto
    onAutoModeSwitchRequest: function (AutoModeSwitchRequest $request) {
        // Restituisce uno tra "yes", "yes_always", "no"
        return 'yes';
    },

    // Hook di sessione
    hooks: [],

    // Working directory
    workingDirectory: '',

    // Abilita lo streaming
    streaming: true,

    // Se includere gli eventi di streaming dei sotto-agenti nello stream principale (default: true)
    includeSubAgentStreamingEvents: true,

    // Strumenti integrati utilizzabili
    availableTools: ['read_file', 'write_file'],

    // Oppure strumenti da escludere
    excludedTools: ['shell'],

    // Configurazione dei server MCP
    mcpServers: [
        'github' => [
            'type' => 'http',
            'url' => 'https://api.githubcopilot.com/mcp/',
        ],
    ],

    // Agenti personalizzati
    customAgents: [
        [
            'name' => 'reviewer',
            'displayName' => 'Code Reviewer',
            'description' => 'Reviews code for best practices',
            'prompt' => 'You are an expert code reviewer.',
        ],
    ],

    // Configurazione dell'agente predefinito. Configurazione dell'agente integrato usato quando non è selezionato un agente personalizzato.
    // excludedTools: elenco degli strumenti da escludere per l'agente predefinito.
    // I sotto-agenti personalizzati possono comunque usarli.
    defaultAgent: ['excludedTools' => ['tool_name']],

    // Specifica l'agente da attivare all'avvio della sessione. Deve corrispondere al name di customAgents.
    agent: 'reviewer',

    // Directory delle skill
    skillDirectories: [],

    // Skill disabilitate
    disabledSkills: [],

    // Configurazione delle sessioni infinite. Abilitata di default.
    infiniteSessions: new InfiniteSessionConfig(
        enabled: true,
        backgroundCompactionThreshold: 0.80, // avvia la compattazione quando l'uso del contesto raggiunge l'80%
        bufferExhaustionThreshold: 0.95,     // blocca al 95% finché la compattazione non è completata
    ),

    // Disabilita le sessioni infinite
    // infiniteSessions: new InfiniteSessionConfig(enabled: false),

    // Registra l'handler eventi prima dell'RPC di creazione della sessione.
    // Usalo per non perdere eventi precoci come session.start.
    // È equivalente a chiamare $session->on($handler) successivamente, ma registrato più presto nel ciclo di vita.
    onEvent: function (SessionEvent $event) {
        // Riceve tutti gli eventi di sessione
    },
);

$response = Copilot::run('...', config: $config);
```

Al momento della ripresa di una sessione si usa la classe `ResumeSessionConfig`. È quasi identica a `SessionConfig`, ma con qualche differenza. In ResumeSessionConfig specifichi solo i parametri che vuoi cambiare. Gli altri vengono ereditati dalle impostazioni dell'avvio della sessione originale.

Per l'esecuzione in cloud consulta [Cloud Sessions](/it/packages/laravel-copilot-sdk/cloud-sessions), per le Plugin Directory consulta [Plugin Directories](/it/packages/laravel-copilot-sdk/plugin-directories).

<Info>
  Per le informazioni più recenti fai riferimento al [repository GitHub](https://github.com/invokable/laravel-copilot-sdk).
</Info>


## Related topics

- [Cloud Sessions](/it/packages/laravel-copilot-sdk/cloud-sessions.md)
- [Agenti personalizzati](/it/packages/laravel-copilot-sdk/custom-agents.md)
- [Ripresa della sessione](/it/packages/laravel-copilot-sdk/resume.md)
- [Introduzione - GitHub Copilot SDK for Laravel](/it/packages/laravel-copilot-sdk/getting-started.md)
- [Eventi di streaming](/it/packages/laravel-copilot-sdk/streaming-events.md)