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'])

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;
use Revolution\Copilot\Enums\UIAutoModeSwitchResponse;
use Revolution\Copilot\Types\AutoModeSwitchRequest;
use Revolution\Copilot\Types\ExitPlanModeRequest;
use Revolution\Copilot\Types\ExitPlanModeResult;
use Revolution\Copilot\Types\McpAuthRequest;
use Revolution\Copilot\Types\McpAuthToken;

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

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

    // Nome per una nuova sessione locale (il runtime lo rifiuta se combinato con cloud).
    // Le sessioni con nome vengono salvate subito, quindi puoi elencarle e riprenderle prima che venga eseguito qualsiasi turno.
    // Non deve essere vuoto né contenere spazi iniziali o finali, caratteri di controllo o virgolette doppie.
    // Massimo 100 unità di codice UTF-16.
    name: 'issue-triage',

    clientName: 'my-app',

    // Indica che la sessione è guidata da un utente umano per abilitare la telemetria analitica dei messaggi utente (default dell'SDK: false).
    // I messaggi automatici sono esclusi. Viene ignorato per le sessioni cloud e quando si riprende una sessione in esecuzione.
    interactiveUser: true,

    // 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']];
    },

    // Fornisce un token dall'host quando un server MCP richiede l'autenticazione OAuth
    onMcpAuthRequest: function (McpAuthRequest $request, array $context): ?McpAuthToken {
        $accessToken = $credentialProvider->tokenFor($request->serverName);

        return $accessToken === null
            ? null
            : new McpAuthToken(accessToken: $accessToken, tokenType: 'Bearer');
    },

    // 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 UIAutoModeSwitchResponse::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',

    // Root di discovery esplicite per skill, agenti, hook e file di istruzioni
    skillDirectories: [],
    agentDirectories: [],
    hookDirectories: [],
    instructionDirectories: [],

    // Richiede il GitHub cache store in sola lettura
    enableGitHubCacheStore: true,

    // 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);

Root di discovery

skillDirectories, agentDirectories, hookDirectories e instructionDirectories sono root di sola discovery per skill, agenti personalizzati, hook su file e istruzioni personalizzate. Non concedono all’agente un accesso generale ai file. Per aggiungere posizioni con accesso ai file ordinario, usa additionalDirectories. Puoi impostare le root di discovery indipendentemente dal fatto che enableConfigDiscovery sia abilitato o meno. L’SDK risolve i percorsi relativi una sola volta, rispetto alla workingDirectory effettiva nel momento in cui li imposti. Le root non si spostano se la working directory cambia in seguito. Omettere una chiave o passare null lascia invariate le sorgenti di discovery predefinite. Passare [] rimuove solo le root impostate esplicitamente dall’SDK. Le impostazioni di disabilitazione per singola sorgente e le Managed Settings per skill, agenti, hook e istruzioni continuano ad applicarsi. 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. L’SDK invia le stesse opzioni di sessione sia nel payload RPC di creazione sia in quello di ripresa. Questo include provider e modelli BYOK, memoria, enableMcpApps, interactiveUser, enableGitHubCacheStore, root di discovery e handler come onMcpAuthRequest, onExitPlanModeRequest e onAutoModeSwitchRequest. Alla ripresa, passali in ResumeSessionConfig o in un array con le stesse chiavi. Le closure e gli oggetti provider non vengono salvati, quindi forniscili di nuovo a ogni ripresa.

Provider di canvas

Il supporto ai canvas è sperimentale.

Dichiara i canvas con canvases e gestisci le richieste di apertura e di azione con un canvasHandler. Il runtime chiama il tuo handler tramite reverse RPC quando l’agente apre un canvas o invoca una delle sue azioni. Imposta requestCanvasRenderer: true per aderire come renderer, così il runtime espone al modello gli strumenti agente per i canvas su questa connessione. È disattivato di default, così i chiamanti dell’SDK che non possono visualizzare i canvas non ne vengono influenzati.

use Revolution\Copilot\Support\CanvasError;
use Revolution\Copilot\Support\CanvasHandler;
use Revolution\Copilot\Types\CanvasDeclaration;
use Revolution\Copilot\Types\Rpc\CanvasAction;
use Revolution\Copilot\Types\Rpc\CanvasProviderInvokeActionRequest;
use Revolution\Copilot\Types\Rpc\CanvasProviderOpenRequest;
use Revolution\Copilot\Types\Rpc\CanvasProviderOpenResult;
use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    canvases: [
        new CanvasDeclaration(
            id: 'editor',
            displayName: 'Editor',
            description: 'Opens and edits project files.',
            actions: [
                new CanvasAction(name: 'format', description: 'Format the open file.'),
            ],
        ),
    ],
    canvasHandler: new class extends CanvasHandler
    {
        public function open(CanvasProviderOpenRequest $request): CanvasProviderOpenResult|array
        {
            return new CanvasProviderOpenResult(
                url: 'https://app.example.test/canvas/'.$request->instanceId,
                title: 'Project editor',
            );
        }

        public function invoke(CanvasProviderInvokeActionRequest $request): mixed
        {
            if ($request->actionName !== 'format') {
                throw CanvasError::noHandler();
            }

            return ['formatted' => true];
        }
    },
    requestCanvasRenderer: true,
);

Opzioni correlate:

requestExtensions: true aderisce alla superficie delle estensioni. Il runtime collega quindi gli strumenti di gestione delle estensioni alle sessioni su questa connessione. Disattivato di default.
extensionInfo: new ExtensionInfo(source: 'github-app', name: 'my-extension') imposta un ID estensione stabile per i provider di canvas su questa connessione. Il runtime usa ${source}:${name} al posto dell’ID per connessione. Puoi passare anche un array.

Alla ripresa, passa di nuovo canvases e canvasHandler. Il canvasHandler viene eseguito solo all’interno del processo PHP. L’SDK invia nel payload RPC solo i metadati della dichiarazione. ResumeSessionConfig accetta anche openCanvases, uno snapshot dei canvas aperti al momento dell’interruzione della sessione. Il runtime lo usa per ripristinare lo stato dei canvas, quindi non devi riaprirli. Ottieni i canvas attualmente aperti con $session->openCanvases(). L’SDK mantiene questo elenco sincronizzato con gli eventi session.canvas.opened e session.canvas.closed.

Provider di filesystem della sessione

Callback per skill e filesystem

Usa skillProvider per caricare le skill da una sorgente gestita dall’applicazione. Le callback appartengono a quella sessione e non vengono serializzate verso il runtime di Copilot. Le sessioni cloud non supportano provider di skill personalizzati.

use Revolution\Copilot\Support\PermissionHandler;
use Revolution\Copilot\Types\SessionConfig;
use Revolution\Copilot\Types\SkillProviderCallOptions;

$config = new SessionConfig(
    onPermissionRequest: PermissionHandler::approveAll(),
    skillProvider: [
        'listSkills' => fn (SkillProviderCallOptions $options) => [
            ['name' => 'deployment', 'description' => 'Safe application deployments'],
        ],
        'readSkill' => fn (string $name, SkillProviderCallOptions $options) =>
            $name === 'deployment' ? '# Deployment checklist' : null,
    ],
);

SkillProviderCallOptions::$signal espone il token di annullamento della callback. L’annullamento è cooperativo. Le tue callback devono osservare il segnale e annullare autonomamente il lavoro in sospeso. Invece dell’array di callback puoi implementare Revolution\Copilot\Contracts\SkillProvider. sessionFsProvider usa la stessa configurazione a livello di sessione. Le callback testuali sono readFile(path) e writeFile(path, content, mode). Per supportare i file binari, fornisci sia readFileBytes(path) sia writeFileBytes(path, bytes, mode), oppure implementa SessionFsBinaryProvider. Queste callback ricevono e restituiscono i byte originali. L’SDK gestisce la codifica base64 sul canale JSON-RPC. Limita l’accesso al filesystem ai percorsi che la tua applicazione intende esporre.

use Illuminate\Support\Facades\Storage;
use Revolution\Copilot\Support\PermissionHandler;
use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    onPermissionRequest: PermissionHandler::approveAll(),
    sessionFsProvider: [
        'readFile' => fn (string $path) => Storage::disk('local')->get($path),
        'writeFile' => fn (string $path, string $content, ?int $mode = null) =>
            Storage::disk('local')->put($path, $content),
        'readFileBytes' => fn (string $path) => Storage::disk('local')->get($path),
        'writeFileBytes' => fn (string $path, string $bytes, ?int $mode = null) =>
            Storage::disk('local')->put($path, $bytes),
    ],
);

Delegare tutto lo stato della sessione con `sessionFs`

Imposta l’opzione client sessionFs (alias session_fs) per spostare l’intero stato della sessione di Copilot CLI, inclusi i file di stato della sessione e il database SQLite per sessione, nel tuo storage. Quando la imposti, ogni configurazione di sessione deve fornire una factory createSessionFsProvider. L’SDK chiama la factory sia per createSession() sia per resumeSession(), dopo che l’ID sessione è noto e prima che la richiesta venga inviata al runtime.

use Revolution\Copilot\Client;
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Support\PermissionHandler;
use Revolution\Copilot\Types\SessionConfig;

$client = new Client(['sessionFs' => [
    'initialCwd' => '/workspace',
    'sessionStatePath' => '/session-state',
    'conventions' => 'posix', // oppure windows
    'capabilities' => ['sqlite' => true, 'binary' => true], // opzionale
]]);

$session = $client->createSession(new SessionConfig(
    onPermissionRequest: PermissionHandler::approveAll(),
    createSessionFsProvider: fn (CopilotSession $session) => new MySessionFsProvider($session->id()),
));

Con la facade Copilot, imposta session_fs in config/copilot.php. initialCwd, sessionStatePath e conventions (posix o windows) sono obbligatori. Campi mancanti o un valore di conventions non valido lanciano una InvalidArgumentException. createSessionFsProvider è una Closure. Funziona anche con gli array, fromArray() e toArray() su SessionConfig e ResumeSessionConfig. Il provider restituito può essere un oggetto o un array di callable. Ogni capability opzionale ha la propria interfaccia:

Interfaccia	Aggiunge
`SessionFsProvider`	`readFile`, `writeFile`
`SessionFsBinaryProvider`	`readFileBytes`, `writeFileBytes` (richiesti da `capabilities.binary`)
`SessionFsFilesystemProvider`	`appendFile`, `exists`, `stat`, `mkdir`, `readdir`, `readdirWithTypes`, `rm`, `rename`
`SessionFsSqliteCapableProvider`	`sqlite()` che restituisce un `SessionFsSqliteProvider` (`query`, `exists`). Richiesto da `capabilities.sqlite`
`SessionFsSqliteTransactionProvider`	`transaction()` sul provider SQLite

Se il provider non soddisfa le capability dichiarate, l’SDK lancia una InvalidArgumentException. Chiamare un’operazione che il provider non supporta restituisce un errore UNKNOWN. I provider segnalano i fallimenti lanciando eccezioni. Un’eccezione con code uguale a ENOENT (o errno 2) diventa ENOENT. Qualsiasi altra diventa UNKNOWN. Lancia SessionFsSqliteTransactionFailure da transaction() per riportare un errorClass (busyOrLocked, fatal o postCommitAmbiguous). Senza l’opzione client sessionFs, l’SDK non chiama mai createSessionFsProvider e il sessionFsProvider esistente (readFile e writeFile) continua a funzionare.

Modalità empty per app multi-tenant

Imposta il mode del client su empty per disabilitare, di default, le funzionalità che dipendono dall’ambiente host di Copilot CLI o dallo stato condiviso tra sessioni. Il default è copilot-cli, che mantiene il comportamento esistente. In modalità empty devi impostare una destinazione di persistenza: base_directory, session_fs o l’url di un server esterno.

// config/copilot.php
'mode' => env('COPILOT_MODE', 'copilot-cli'),
'base_directory' => storage_path('app/copilot'),

Ogni sessione in modalità empty deve impostare availableTools. Usa ToolSet per costruire filtri di strumenti qualificati per sorgente (builtin:, custom:, mcp:). BuiltInTools::Isolated consente solo gli strumenti integrati confinati a una singola sessione, senza accesso al filesystem dell’host, all’ambiente, alla rete o ad altre sessioni.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Support\BuiltInTools;
use Revolution\Copilot\Support\ToolSet;

$response = Copilot::run(
    prompt: 'Summarize this text.',
    config: [
        'availableTools' => (new ToolSet)
            ->addBuiltIn(BuiltInTools::Isolated)
            ->addCustom('lookup_order')
            ->addMcp('search'),
    ],
);

I nomi degli strumenti devono corrispondere a /^[a-zA-Z0-9_-]+$/ oppure essere il carattere jolly *. In caso contrario ToolSet lancia una InvalidArgumentException. La modalità empty applica default sicuri a telemetria della sessione, archiviazione persistente dei token OAuth MCP, recupero e cache degli embedding, discovery delle istruzioni, hook su file, operazioni git sull’host, session store, GitHub cache store, skill, memoria e modalità sperimentale. Le opzioni di sessione impostate esplicitamente hanno la precedenza su questi default. systemMessage in modalità replace viene usato così com’è. Le altre modalità rimuovono la sezione environment_context. L’SDK imposta inoltre COPILOT_DISABLE_KEYTAR=1 per il processo CLI.

GitHub cache store

Imposta enableGitHubCacheStore: true per richiedere il GitHub cache store in sola lettura. La CLI registra lo strumento github_sql solo quando il suo feature flag GITHUB_CACHE_STORE è abilitato.

$config = new SessionConfig(enableGitHubCacheStore: true);

Per l’esecuzione in cloud consulta Cloud Sessions, per le Plugin Directory consulta Plugin Directories.

Per le informazioni più recenti fai riferimento al repository GitHub.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter kit

Feed e RSS

Middleware

SessionConfig

SessionConfig

Root di discovery

Provider di canvas

Provider di filesystem della sessione

Callback per skill e filesystem

Delegare tutto lo stato della sessione con `sessionFs`

Modalità empty per app multi-tenant

GitHub cache store

​SessionConfig

​Root di discovery

​Provider di canvas

​Provider di filesystem della sessione

​Callback per skill e filesystem

​Delegare tutto lo stato della sessione con sessionFs

​Modalità empty per app multi-tenant

​GitHub cache store

SessionConfig

Root di discovery

Provider di canvas

Provider di filesystem della sessione

Callback per skill e filesystem

Delegare tutto lo stato della sessione con `sessionFs`

Modalità empty per app multi-tenant

GitHub cache store