Introduzione - GitHub Copilot SDK for Laravel

Crea il tuo primo comando Laravel che usa Copilot e impara i flussi di lavoro fondamentali di Laravel Copilot SDK.

​

Costruisci la tua prima app Laravel con Copilot

In questa guida costruirai un assistente da riga di comando usando Laravel Copilot SDK. Partirai dall’invio di un singolo prompt e proseguirai con sessioni, eventi e strumenti.

​

Prerequisiti

Prima di iniziare, verifica quanto segue.

• GitHub Copilot CLI installato e autenticato
• PHP 8.4+
• Laravel 13.x

Verifica che il CLI sia disponibile.

copilot --version

​

Installare l’SDK

Installa il pacchetto con Composer.

composer require revolution/laravel-copilot-sdk

Pubblica la configurazione se necessario.

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

Se serve, imposta il percorso del CLI in .env.

COPILOT_CLI_PATH=copilot

​

Inviare il primo messaggio

Crea un comando e invoca 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());
    }
}

Esegui il comando.

php artisan copilot:demo

​

Mantenere il contesto in una sessione

Se vuoi usare più prompt in un’unica conversazione, usa 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());
});

​

Gestire gli eventi di sessione

Registra un handler eventi con on() per intercettare i messaggi dell’assistente o i fallimenti.

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');
});

​

Aggiungere uno strumento personalizzato

Definisci uno strumento con uno schema JSON e un 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);

​

Creare un assistente interattivo

Combinando sessioni, eventi e strumenti puoi creare un comando Artisan interattivo.

<?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);
    }
}

Esegui il comando.

php artisan copilot:assistant

​

Come funzionano gli strumenti

Quando definisci uno strumento specifichi tre cose.

1. Cosa fa lo strumento.
2. Quali parametri accetta.
3. Quale codice handler eseguire.

Copilot decide di invocare lo strumento in base all’input dell’utente, l’SDK esegue l’handler e restituisce il risultato.

​

Funzionalità da provare successivamente

​

Collegare un server MCP

use Revolution\Copilot\Types\SessionConfig;

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

​

Creare un agente personalizzato

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

​

Personalizzare il messaggio di sistema

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

​

Collegarsi a un server CLI esterno

Avvia Copilot CLI in modalità server.

copilot --headless --port 4321

Poi imposta l’URL di destinazione in .env.

COPILOT_URL=tcp://127.0.0.1:4321

Se imposti COPILOT_URL, l’SDK non avvia un nuovo processo CLI ma si collega al server esistente.

​

Telemetria e osservabilità

Configura la telemetria in config/copilot.php.

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

Oppure configurala direttamente.

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

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

​

Approfondimenti

• Autenticazione
• MCP
• Provider personalizzati
• Telemetria
• SessionConfig
• SessionEvent
• Panoramica Laravel Copilot SDK
• Repository dell’SDK ufficiale

​

Prossimi passi

Autenticazione

Scegli il metodo di autenticazione adatto a locale e CI.

SessionConfig

Configura modello, hook, server MCP e comportamento a runtime.

SessionEvent

Comprendi gli helper eventi specifici di Laravel e la gestione del ciclo di vita.

Richieste di permesso

Verifica il flusso di autorizzazione per eseguire gli strumenti con approvazione esplicita.

Strumenti

Invoca il codice dell’applicazione da Copilot.

MCP

Collega gli strumenti già pronti dei server MCP.

A questo punto hai esaminato tutti i flussi centrali di Laravel Copilot SDK: dal prompt singolo alle sessioni con integrazione di strumenti.

Riferimenti: Laravel Copilot SDK README, Laravel Copilot SDK Getting Started, GitHub Copilot SDK