SessionConfig

Die Klasse SessionConfig ermöglicht vielfältige Einstellungen. Sie wird wie folgt verwendet: Copilot::run(prompt: '...', config: $config) oder Copilot::start(function (CopilotSession $session) { ... }, config: $config). Wenn Sie – etwa nur ein Modell setzen wollen – die Klasse SessionConfig gar nicht benötigen, ist auch die Angabe als Array möglich: 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(
    // Zu verwendendes Modell
    model: 'auto',

    // Feste Session-ID beim Erstellen einer neuen Session
    sessionId: 'session-123',

    // Name für eine neue lokale Session (die Runtime lehnt ihn in Kombination mit cloud ab).
    // Benannte Sessions werden sofort persistiert, sodass Sie sie schon vor dem ersten Turn auflisten und fortsetzen können.
    // Darf nicht leer sein und keine führenden oder nachgestellten Leerzeichen, Steuerzeichen oder doppelten Anführungszeichen enthalten.
    // Maximal 100 UTF-16-Codeeinheiten.
    name: 'issue-triage',

    clientName: 'my-app',

    // Als von einem Menschen gesteuerte Session markieren, um Analytics-Telemetrie für Benutzernachrichten zu aktivieren (SDK-Standard: false).
    // Automatisierte Nachrichten sind ausgenommen. Wird bei Cloud-Sessions und beim Fortsetzen einer laufenden Session ignoriert.
    interactiveUser: true,

    // Reasoning-Level. Nur bei unterstützten Modellen einstellbar.
    reasoningEffort: ReasoningEffort::HIGH,

    // Override der Modell-Capabilities. Wird deep-merged in die Runtime-Standardwerte.
    // modelCapabilities: new ModelCapabilitiesOverride(
    //     supports: new ModelCapabilitiesOverrideSupports(vision: true, reasoningEffort: true),
    //     limits: new ModelCapabilitiesOverrideLimits(max_prompt_tokens: 200000),
    // ),
    // Auch als Array angebbar
    // modelCapabilities: ['supports' => ['vision' => true]],

    // config-Verzeichnis überschreiben
    configDirectory: '',

    // Automatische Erkennung von MCP-Konfigurationen und Skill-Verzeichnissen aktivieren
    // Findet .mcp.json oder .vscode/mcp.json automatisch im Arbeitsverzeichnis
    // und merged sie mit explizit angegebenen mcpServers und skillDirectories
    // (bei Namenskonflikt hat die explizite Angabe Vorrang)
    enableConfigDiscovery: true,

    // Benutzerdefinierte Tools
    tools: [...],

    // System-Nachricht
    systemMessage: new SystemMessageConfig(
        content: 'You are a helpful assistant for Laravel developers.',
    ),

    // System-Nachricht: replace-Modus (System-Prompt vollständig ersetzen)
    // systemMessage: new SystemMessageConfig(
    //     mode: 'replace',
    //     content: 'カスタムシステムプロンプト全体',
    // ),

    // System-Nachricht: customize-Modus (abschnittsweise überschreiben)
    // 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: 'appendモード同様の追加コンテンツ（オプション）',
    // ),

    // Benutzerdefinierter Provider
    provider: new ProviderConfig(),

    // GitHub-Token pro Session (Multi-Tenant)
    // Unabhängig vom github_token auf Client-Ebene lässt sich das Token pro Session festlegen
    gitHubToken: $user->github_token,

    // Betriebsmodus der Remote-Session
    // 'off' - nur lokal (Standard)
    // 'export' - Session-Events an GitHub exportieren (ohne Remote-Steering)
    // 'on' - Export und Remote-Steering aktiviert
    remoteSession: \Revolution\Copilot\Enums\RemoteSessionMode::Export,

    // Cloud-Session (Session in der Cloud statt lokal erzeugen)
    // Optional Repository-Informationen verknüpfen
    cloud: new \Revolution\Copilot\Types\CloudSessionOptions(
        repository: new \Revolution\Copilot\Types\CloudSessionRepository(
            owner: 'myorg',
            name: 'myrepo',
            branch: 'main',
        ),
    ),

    onPermissionRequest: function (array $request) {
        // Berechtigungsanfrage verarbeiten
    },

    onUserInputRequest: function (UserInputRequest $request) {
        // Benutzereingabe-Anfrage verarbeiten (ask_user)
    },

    // Handler für Elicitation-Requests
    // Wenn gesetzt, können formularbasierte UI-Dialog-Requests des Agenten empfangen werden
    onElicitationRequest: function (ElicitationContext $context) {
        // Elicitation-Request verarbeiten
        return ['action' => 'accept', 'content' => ['field' => 'value']];
    },

    // Token vom Host bereitstellen, wenn ein MCP-Server eine OAuth-Authentifizierung anfordert
    onMcpAuthRequest: function (McpAuthRequest $request, array $context): ?McpAuthToken {
        $accessToken = $credentialProvider->tokenFor($request->serverName);

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

    // Handler für den Plan-Mode-Beendigungs-Request
    // Wenn gesetzt, antwortet das SDK per Reverse-RPC. Ohne Angabe werden Requests automatisch genehmigt.
    onExitPlanModeRequest: function (ExitPlanModeRequest $request) {
        // Planinhalt prüfen und genehmigen/ablehnen
        return new ExitPlanModeResult(approved: true, selectedAction: $request->recommendedAction);
    },

    // Handler für Auto-Mode-Umschaltanfragen
    // Entscheidet, ob bei Erreichen eines Rate-Limits in den Auto-Modus gewechselt wird. Ohne Angabe gilt "no".
    onAutoModeSwitchRequest: function (AutoModeSwitchRequest $request) {
        // "yes", "yes_always", "no" oder einen UIAutoModeSwitchResponse-Case zurückgeben
        return UIAutoModeSwitchResponse::Yes;
    },

    // Session-Hooks
    hooks: [],

    // Arbeitsverzeichnis
    workingDirectory: '',

    // Streaming aktivieren
    streaming: true,

    // Ob Streaming-Events der Sub-Agenten in den Hauptstream einbezogen werden (Standard: true)
    includeSubAgentStreamingEvents: true,

    // Verfügbare Built-in-Tools
    availableTools: ['read_file', 'write_file'],

    // Alternativ: auszuschließende Tools
    excludedTools: ['shell'],

    // MCP-Server-Konfiguration
    mcpServers: [
        'github' => [
            'type' => 'http',
            'url' => 'https://api.githubcopilot.com/mcp/',
        ],
    ],

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

    // Konfiguration des Standard-Agenten. Wird verwendet, wenn kein Custom-Agent gewählt ist.
    // excludedTools: Liste der Tools, die dem Standard-Agenten entzogen werden.
    // Für Custom-Sub-Agenten bleiben sie verfügbar.
    defaultAgent: ['excludedTools' => ['tool_name']],

    // Beim Session-Start zu aktivierender Agent. Muss mit dem name eines customAgents übereinstimmen.
    agent: 'reviewer',

    // Explizite Discovery-Roots für Skills, Agenten, Hooks und Instruktionsdateien
    skillDirectories: [],
    agentDirectories: [],
    hookDirectories: [],
    instructionDirectories: [],

    // Den schreibgeschützten GitHub Cache Store anfordern
    enableGitHubCacheStore: true,

    // Deaktivierte Skills
    disabledSkills: [],

    // Konfiguration für Infinite Sessions. Standardmäßig aktiviert.
    infiniteSessions: new InfiniteSessionConfig(
        enabled: true,
        backgroundCompactionThreshold: 0.80, // Kompaktierung startet bei 80 % Kontextauslastung
        bufferExhaustionThreshold: 0.95,     // Blockiert bei 95 %, bis die Kompaktierung abgeschlossen ist
    ),

    // Infinite Sessions deaktivieren
    // infiniteSessions: new InfiniteSessionConfig(enabled: false),

    // Event-Handler vor dem Session-Erzeugungs-RPC registrieren.
    // Wird verwendet, damit frühe Events wie session.start nicht verloren gehen.
    // Entspricht einem späteren Aufruf von $session->on($handler), wird jedoch früher im Lebenszyklus registriert.
    onEvent: function (SessionEvent $event) {
        // Alle Session-Events empfangen
    },
);

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

Discovery-Roots

skillDirectories, agentDirectories, hookDirectories und instructionDirectories sind reine Discovery-Roots für Skills, Custom-Agenten, Datei-Hooks und benutzerdefinierte Instruktionen. Sie gewähren dem Agenten keinen allgemeinen Dateizugriff. Um reguläre Orte für den Dateizugriff hinzuzufügen, verwenden Sie additionalDirectories. Discovery-Roots lassen sich unabhängig davon setzen, ob enableConfigDiscovery aktiviert ist. Das SDK löst relative Pfade einmalig auf, und zwar relativ zu dem workingDirectory, das beim Setzen gilt. Die Roots verschieben sich nicht, wenn sich das Arbeitsverzeichnis später ändert. Wird ein Schlüssel weggelassen oder null übergeben, bleiben die Standard-Discovery-Quellen unverändert. Die Übergabe von [] entfernt nur die Roots, die das SDK explizit gesetzt hat. Deaktivierungseinstellungen pro Quelle sowie Managed Settings für Skills, Agenten, Hooks und Instruktionen gelten weiterhin. Beim Fortsetzen einer Session verwenden Sie die Klasse ResumeSessionConfig. Sie ist fast identisch mit SessionConfig, weist aber geringfügige Unterschiede auf. In ResumeSessionConfig geben Sie nur die Optionen an, die Sie ändern möchten. Alle übrigen Einstellungen der ursprünglich gestarteten Session werden übernommen. Das SDK sendet dieselben Session-Optionen sowohl im Create- als auch im Resume-RPC-Payload. Dazu gehören BYOK-Provider und -Modelle, Memory, enableMcpApps, interactiveUser, enableGitHubCacheStore, Discovery-Roots sowie Handler wie onMcpAuthRequest, onExitPlanModeRequest und onAutoModeSwitchRequest. Übergeben Sie sie beim Fortsetzen in ResumeSessionConfig oder in einem Array mit denselben Schlüsseln. Closures und Provider-Objekte werden nicht persistiert. Geben Sie sie daher bei jedem Fortsetzen erneut an.

Canvas-Provider

Die Canvas-Unterstützung ist experimentell.

Deklarieren Sie Canvases mit canvases und verarbeiten Sie Open- und Action-Requests mit einem canvasHandler. Die Runtime ruft Ihren Handler per Reverse-RPC auf, wenn der Agent ein Canvas öffnet oder eine seiner Actions ausführt. Setzen Sie requestCanvasRenderer: true, um sich als Renderer anzumelden. Die Runtime stellt dem Modell dann für diese Verbindung Canvas-Agent-Tools bereit. Standardmäßig ist dies deaktiviert, damit SDK-Aufrufer, die keine Canvases anzeigen können, nicht beeinträchtigt werden.

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

Verwandte Optionen:

requestExtensions: true meldet sich für die Extension-Oberfläche an. Die Runtime bindet dann Tools zur Extension-Verwaltung in die Sessions dieser Verbindung ein. Standardmäßig deaktiviert.
extensionInfo: new ExtensionInfo(source: 'github-app', name: 'my-extension') legt eine stabile Extension-ID für Canvas-Provider auf dieser Verbindung fest. Die Runtime verwendet ${source}:${name} anstelle der verbindungsspezifischen ID. Auch als Array angebbar.

Übergeben Sie beim Fortsetzen canvases und canvasHandler erneut. Der canvasHandler läuft nur innerhalb des PHP-Prozesses. Das SDK sendet im RPC-Payload nur die Metadaten der Deklaration. ResumeSessionConfig akzeptiert außerdem openCanvases, einen Snapshot der Canvases, die beim Beenden der Session geöffnet waren. Die Runtime stellt damit den Canvas-Zustand wieder her, sodass Sie sie nicht erneut öffnen müssen. Die aktuell geöffneten Canvases erhalten Sie mit $session->openCanvases(). Das SDK hält diese Liste mit den Events session.canvas.opened und session.canvas.closed synchron.

Session-Dateisystem-Provider

Skill- und Dateisystem-Callbacks

Mit skillProvider laden Sie Skills aus einer anwendungseigenen Quelle. Die Callbacks gehören zur jeweiligen Session und werden nicht an die Copilot-Runtime serialisiert. Cloud-Sessions unterstützen keine benutzerdefinierten Skill-Provider.

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 stellt das Cancellation-Token des Callbacks bereit. Der Abbruch ist kooperativ. Ihre Callbacks sollten das Signal beobachten und laufende Arbeit selbst abbrechen. Anstelle des Callback-Arrays können Sie auch Revolution\Copilot\Contracts\SkillProvider implementieren. sessionFsProvider verwendet dieselbe sessionbezogene Konfiguration. Die Text-Callbacks sind readFile(path) und writeFile(path, content, mode). Für Binärdateien stellen Sie sowohl readFileBytes(path) als auch writeFileBytes(path, bytes, mode) bereit oder implementieren SessionFsBinaryProvider. Diese Callbacks erhalten und liefern die Original-Bytes. Das SDK übernimmt die Base64-Kodierung auf der JSON-RPC-Leitung. Beschränken Sie den Dateisystemzugriff auf die Pfade, die Ihre Anwendung bewusst freigeben möchte.

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),
    ],
);

Gesamten Session-Zustand mit `sessionFs` delegieren

Setzen Sie die Client-Option sessionFs (Alias session_fs), um den gesamten Session-Zustand der Copilot CLI – einschließlich der Session-State-Dateien und der SQLite-Datenbank pro Session – in Ihren eigenen Speicher zu verlagern. Ist sie gesetzt, muss jede Session-Konfiguration eine createSessionFsProvider-Factory bereitstellen. Das SDK ruft die Factory sowohl für createSession() als auch für resumeSession() auf, nachdem die Session-ID bekannt ist und bevor der Request an die Runtime gesendet wird.

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', // oder windows
    'capabilities' => ['sqlite' => true, 'binary' => true], // optional
]]);

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

Mit der Copilot-Facade setzen Sie session_fs in config/copilot.php. initialCwd, sessionStatePath und conventions (posix oder windows) sind Pflichtangaben. Fehlende Felder oder ein ungültiger conventions-Wert lösen eine InvalidArgumentException aus. createSessionFsProvider ist eine Closure. Sie funktioniert auch mit Arrays, fromArray() und toArray() von SessionConfig und ResumeSessionConfig. Der zurückgegebene Provider kann ein Objekt oder ein Array von Callables sein. Jede optionale Fähigkeit hat ein eigenes Interface:

Interface	Ergänzt
`SessionFsProvider`	`readFile`, `writeFile`
`SessionFsBinaryProvider`	`readFileBytes`, `writeFileBytes` (erforderlich für `capabilities.binary`)
`SessionFsFilesystemProvider`	`appendFile`, `exists`, `stat`, `mkdir`, `readdir`, `readdirWithTypes`, `rm`, `rename`
`SessionFsSqliteCapableProvider`	`sqlite()`, das einen `SessionFsSqliteProvider` (`query`, `exists`) zurückgibt. Erforderlich für `capabilities.sqlite`
`SessionFsSqliteTransactionProvider`	`transaction()` auf dem SQLite-Provider

Erfüllt der Provider die deklarierten Fähigkeiten nicht, löst das SDK eine InvalidArgumentException aus. Der Aufruf einer Operation, die der Provider nicht unterstützt, liefert einen UNKNOWN-Fehler. Provider signalisieren Fehler durch das Werfen von Exceptions. Eine Exception mit dem code ENOENT (oder errno 2) wird zu ENOENT, alles andere zu UNKNOWN. Werfen Sie SessionFsSqliteTransactionFailure aus transaction(), um eine errorClass (busyOrLocked, fatal oder postCommitAmbiguous) zu melden. Ohne die Client-Option sessionFs ruft das SDK createSessionFsProvider nie auf, und der bestehende sessionFsProvider (readFile und writeFile) funktioniert weiterhin.

Empty-Modus für Multi-Tenant-Anwendungen

Setzen Sie den Client-mode auf empty, um Funktionen, die von der Host-Umgebung der Copilot CLI oder von sessionübergreifendem Zustand abhängen, standardmäßig zu deaktivieren. Der Standard ist copilot-cli, wodurch das bisherige Verhalten erhalten bleibt. Im Empty-Modus müssen Sie ein Persistenzziel festlegen: base_directory, session_fs oder eine externe Server-url.

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

Jede Session im Empty-Modus muss availableTools setzen. Mit ToolSet erstellen Sie quellenqualifizierte Tool-Filter (builtin:, custom:, mcp:). BuiltInTools::Isolated erlaubt nur Built-in-Tools, die auf eine einzelne Session beschränkt sind – ohne Zugriff auf das Host-Dateisystem, die Umgebung, das Netzwerk oder andere Sessions.

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

Tool-Namen müssen /^[a-zA-Z0-9_-]+$/ entsprechen oder die Wildcard * sein. Andernfalls löst ToolSet eine InvalidArgumentException aus. Der Empty-Modus wendet sichere Standardwerte an für Session-Telemetrie, persistente Speicherung von MCP-OAuth-Tokens, Embedding-Retrieval und -Cache, Instruktions-Discovery, Datei-Hooks, Git-Operationen auf dem Host, den Session Store, den GitHub Cache Store, Skills, Memory und den experimentellen Modus. Explizit gesetzte Session-Optionen haben Vorrang vor diesen Standardwerten. systemMessage im replace-Modus wird unverändert verwendet. Bei anderen Modi wird der Abschnitt environment_context entfernt. Außerdem setzt das SDK COPILOT_DISABLE_KEYTAR=1 für den CLI-Prozess.

GitHub Cache Store

Setzen Sie enableGitHubCacheStore: true, um den schreibgeschützten GitHub Cache Store anzufordern. Die CLI registriert das Tool github_sql nur, wenn ihr Feature-Flag GITHUB_CACHE_STORE aktiviert ist.

$config = new SessionConfig(enableGitHubCacheStore: true);

Details zur Cloud-Ausführung finden Sie unter Cloud Sessions, zu Plugin Directories unter Plugin Directories.

Aktuelle Informationen finden Sie im GitHub-Repository.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter Kits

Feeds und RSS

Middleware

SessionConfig

SessionConfig

Discovery-Roots

Canvas-Provider

Session-Dateisystem-Provider

Skill- und Dateisystem-Callbacks

Gesamten Session-Zustand mit `sessionFs` delegieren

Empty-Modus für Multi-Tenant-Anwendungen

GitHub Cache Store

​SessionConfig

​Discovery-Roots

​Canvas-Provider

​Session-Dateisystem-Provider

​Skill- und Dateisystem-Callbacks

​Gesamten Session-Zustand mit sessionFs delegieren

​Empty-Modus für Multi-Tenant-Anwendungen

​GitHub Cache Store

SessionConfig

Discovery-Roots

Canvas-Provider

Session-Dateisystem-Provider

Skill- und Dateisystem-Callbacks

Gesamten Session-Zustand mit `sessionFs` delegieren

Empty-Modus für Multi-Tenant-Anwendungen

GitHub Cache Store