開始使用 - GitHub Copilot SDK for Laravel

建立第一個支援 Copilot 的 Laravel 應用程式

本指南將透過 Laravel Copilot SDK 建立一個命令列助理。從送出單一 prompt 開始，接著進入 session、事件、工具。

前置條件

開始前請確認以下事項。

已安裝 GitHub Copilot CLI，並已完成認證
PHP 8.4+
Laravel 13.x

確認 CLI 是否可用。

copilot --version

安裝 SDK

以 Composer 安裝套件。

composer require revolution/laravel-copilot-sdk

如有需要可公開設定。

php artisan vendor:publish --tag=copilot-config

需要時可於 .env 設定 CLI 路徑。

COPILOT_CLI_PATH=copilot

送出第一個訊息

建立指令並呼叫 Copilot::run()。

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Revolution\Copilot\Facades\Copilot;

class CopilotDemo extends Command
{
    protected $signature = 'copilot:demo';
    protected $description = 'Demo Copilot SDK';

    public function handle()
    {
        $response = Copilot::run(prompt: 'What is 2 + 2?');

        $this->info($response->content());
    }
}

執行指令。

php artisan copilot:demo

在 session 中保持脈絡

若要於單一對話中使用多個 prompt，可使用 Copilot::start()。

use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;

Copilot::start(function (CopilotSession $session) {
    $response = $session->sendAndWait(prompt: 'What is 2 + 2?');
    $this->info('Answer: '.$response->content());

    $response = $session->sendAndWait(prompt: 'Now multiply that by 3');
    $this->info('Answer: '.$response->content());
});

處理 session 事件

透過 on() 註冊事件 handler，可確認助理的訊息或失敗狀態。

use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionEvent;

Copilot::start(function (CopilotSession $session) {
    $session->on(function (SessionEvent $event): void {
        if ($event->isAssistantMessage()) {
            $this->info($event->content());
        } elseif ($event->failed()) {
            $this->error($event->errorMessage() ?? 'Unknown error');
        }
    });

    $session->sendAndWait(prompt: 'Tell me a short Laravel joke');
});

加入自訂工具

以 JSON schema 與 handler 定義工具。

use Illuminate\JsonSchema\JsonSchema;
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionConfig;
use Revolution\Copilot\Types\Tool;

$parameters = JsonSchema::object([
    'topic' => JsonSchema::string()
        ->description('Topic to look up')
        ->required(),
])->toArray();

$config = new SessionConfig(
    tools: [
        Tool::define(
            name: 'lookup_fact',
            description: 'Returns a fact for a topic.',
            parameters: $parameters,
            handler: function (array $params): array {
                $topic = $params['topic'] ?? '';

                return [
                    'textResultForLlm' => "Fact for {$topic}",
                    'resultType' => 'success',
                    'sessionLog' => "lookup_fact: {$topic}",
                    'toolTelemetry' => [],
                ];
            },
        ),
    ],
);

Copilot::start(function (CopilotSession $session) {
    $response = $session->sendAndWait(
        prompt: 'Use lookup_fact to tell me something about Laravel.'
    );

    $this->info($response->content());
}, config: $config);

建立互動式助理

結合 session、事件、工具，即可建立互動式的 Artisan 指令。

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\JsonSchema\JsonSchema;
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionConfig;
use Revolution\Copilot\Types\SessionEvent;
use Revolution\Copilot\Types\Tool;
use Revolution\Copilot\Types\ToolResultObject;

use function Laravel\Prompts\error;
use function Laravel\Prompts\info;
use function Laravel\Prompts\note;
use function Laravel\Prompts\spin;
use function Laravel\Prompts\text;

class CopilotAssistant extends Command
{
    protected $signature = 'copilot:assistant';
    protected $description = 'Interactive Copilot assistant';

    public function handle()
    {
        $facts = [
            'PHP' => 'A popular general-purpose scripting language for web development.',
            'Laravel' => 'A web application framework with expressive, elegant syntax.',
            'Composer' => 'Dependency manager for PHP.',
        ];

        $parameters = JsonSchema::object([
            'topic' => JsonSchema::string()
                ->description('Topic to look up')
                ->required(),
        ])->toArray();

        $config = new SessionConfig(
            tools: [
                Tool::define(
                    name: 'lookup_fact',
                    description: 'Returns a fun fact about a given topic.',
                    parameters: $parameters,
                    handler: function (array $params) use ($facts) {
                        $topic = $params['topic'] ?? '';
                        $fact = $facts[$topic] ?? "No fact available for {$topic}.";

                        return new ToolResultObject(
                            textResultForLlm: $fact,
                            resultType: 'success',
                            sessionLog: "lookup_fact: {$topic}",
                            toolTelemetry: [],
                        );
                    },
                ),
            ],
        );

        Copilot::start(function (CopilotSession $session) {
            info('Copilot assistant');
            info("Session: {$session->id()}");
            info("Try: Use lookup_fact to tell me about Laravel");

            $session->on(function (SessionEvent $event): void {
                if ($event->isAssistantMessage()) {
                    note($event->content());
                } elseif ($event->failed()) {
                    error($event->errorMessage() ?? 'Unknown error');
                }
            });

            while (true) {
                $prompt = text(
                    label: 'You',
                    placeholder: 'Ask me anything...',
                    required: true,
                    hint: 'Ctrl+C to exit',
                );

                spin(
                    callback: fn () => $session->sendAndWait($prompt),
                    message: 'Thinking...',
                );

                echo "\n";
            }
        }, config: $config);
    }
}

執行指令。

php artisan copilot:assistant

工具的運作原理

定義工具時需指定以下 3 點。

工具的功能。
接受哪些參數。
執行哪段 handler 程式。

Copilot 會依使用者輸入判斷是否呼叫工具，並由 SDK 執行 handler 回傳結果。

接下來可嘗試的功能

指定圖片生成的浮水印

圖片生成必須針對每個 session 個別啟用。指定實驗性的 watermark 選項後，可要求在生成或編輯的圖片上顯示「Made with AI」標籤。

use Revolution\Copilot\Types\ImageGenerationConfig;
use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    imageGeneration: new ImageGenerationConfig(
        enabled: true,
        watermark: true,
    ),
);

watermark 會在此 session 中覆寫使用者的設定。省略時會套用使用者的設定（預設為 false）。冷恢復（cold resume）後請重新指定。此選項不會啟用圖片生成，也不會強制套用企業政策。

連接 MCP 伺服器

use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    mcpServers: [
        'github' => [
            'type' => 'http',
            'url' => 'https://api.githubcopilot.com/mcp/',
        ],
    ],
);

建立自訂 agent

use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    customAgents: [
        [
            'name' => 'pr-reviewer',
            'displayName' => 'PR Reviewer',
            'description' => 'Reviews pull requests for best practices',
            'prompt' => 'You are an expert code reviewer. Focus on security, performance, and maintainability.',
        ],
    ],
);

自訂系統訊息

use Revolution\Copilot\Types\SessionConfig;
use Revolution\Copilot\Types\SystemMessageConfig;

$config = new SessionConfig(
    systemMessage: new SystemMessageConfig(
        content: 'You are a helpful assistant for our engineering team. Always be concise.',
    ),
);

連接至外部 CLI 伺服器

以伺服器模式啟動 Copilot CLI。

copilot --headless --port 4321

接著於 .env 設定連線的 URL。

COPILOT_URL=tcp://127.0.0.1:4321

設定 COPILOT_URL 後，SDK 不會啟動新的 CLI 程序，而會連接至既有伺服器。

遙測與可觀測性

於 config/copilot.php 設定遙測。

'telemetry' => [
    'otlpEndpoint' => 'http://localhost:4318',
],

或直接設定。

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\TelemetryConfig;

Copilot::useStdio([
    'telemetry' => new TelemetryConfig(
        otlpEndpoint: 'http://localhost:4318',
    ),
]);

進一步學習

下一步

認證

選擇適合本機環境與 CI 的認證方式。

SessionConfig

設定模型、hook、MCP 伺服器與執行時行為。

SessionEvent

了解 Laravel 專屬的事件輔助工具與生命週期處理。

權限請求

確認以明確授權執行工具的權限流程。

工具

從 Copilot 呼叫應用程式程式碼。

MCP

連接 MCP 伺服器的既有工具。

至此已完整走過 Laravel Copilot SDK 從單次 prompt 到工具整合 session 的核心流程。

參考：Laravel Copilot SDK README、Laravel Copilot SDK Getting Started、GitHub Copilot SDK

GitHub Copilot

SDK

AI SDK

VOICEVOX

入門套件

Feed 與 RSS

中介層

開始使用 - GitHub Copilot SDK for Laravel

建立第一個支援 Copilot 的 Laravel 應用程式

前置條件

安裝 SDK

送出第一個訊息

在 session 中保持脈絡

處理 session 事件

加入自訂工具

建立互動式助理

工具的運作原理

接下來可嘗試的功能

指定圖片生成的浮水印

連接 MCP 伺服器

建立自訂 agent

自訂系統訊息

連接至外部 CLI 伺服器

遙測與可觀測性

進一步學習

下一步

認證

SessionConfig

SessionEvent

權限請求

工具

MCP

​建立第一個支援 Copilot 的 Laravel 應用程式

​前置條件

​安裝 SDK

​送出第一個訊息

​在 session 中保持脈絡

​處理 session 事件

​加入自訂工具

​建立互動式助理

​工具的運作原理

​接下來可嘗試的功能

​指定圖片生成的浮水印

​連接 MCP 伺服器

​建立自訂 agent

​自訂系統訊息

​連接至外部 CLI 伺服器

​遙測與可觀測性

​進一步學習

​下一步

認證

SessionConfig

SessionEvent

權限請求

工具

MCP

建立第一個支援 Copilot 的 Laravel 應用程式

前置條件

安裝 SDK

送出第一個訊息

在 session 中保持脈絡

處理 session 事件

加入自訂工具

建立互動式助理

工具的運作原理

接下來可嘗試的功能

指定圖片生成的浮水印

連接 MCP 伺服器

建立自訂 agent

自訂系統訊息

連接至外部 CLI 伺服器

遙測與可觀測性

進一步學習

下一步