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

# 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.

```bash theme={null}
copilot --version
```

## Installare l'SDK

Installa il pacchetto con Composer.

```bash theme={null}
composer require revolution/laravel-copilot-sdk
```

Pubblica la configurazione se necessario.

```bash theme={null}
php artisan vendor:publish --tag=copilot-config
```

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

```dotenv theme={null}
COPILOT_CLI_PATH=copilot
```

## Inviare il primo messaggio

Crea un comando e invoca `Copilot::run()`.

```php theme={null}
<?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.

```bash theme={null}
php artisan copilot:demo
```

## Mantenere il contesto in una sessione

Se vuoi usare più prompt in un'unica conversazione, usa `Copilot::start()`.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
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 theme={null}
<?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.

```bash theme={null}
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

```php theme={null}
use Revolution\Copilot\Types\SessionConfig;

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

### Creare un agente personalizzato

```php theme={null}
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

```php theme={null}
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.

```bash theme={null}
copilot --headless --port 4321
```

Poi imposta l'URL di destinazione in `.env`.

```dotenv theme={null}
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`.

```php theme={null}
'telemetry' => [
    'otlpEndpoint' => 'http://localhost:4318',
],
```

Oppure configurala direttamente.

```php theme={null}
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\TelemetryConfig;

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

## Approfondimenti

* [Autenticazione](/it/packages/laravel-copilot-sdk/auth)
* [MCP](/it/packages/laravel-copilot-sdk/mcp)
* [Provider personalizzati](/it/packages/laravel-copilot-sdk/custom-providers)
* [Telemetria](/it/packages/laravel-copilot-sdk/telemetry)
* [SessionConfig](/it/packages/laravel-copilot-sdk/session-config)
* [SessionEvent](/it/packages/laravel-copilot-sdk/session-event)
* [Panoramica Laravel Copilot SDK](/it/packages/laravel-copilot-sdk)
* [Repository dell'SDK ufficiale](https://github.com/github/copilot-sdk)

## Prossimi passi

<Columns cols={2}>
  <Card title="Autenticazione" href="/it/packages/laravel-copilot-sdk/auth">
    Scegli il metodo di autenticazione adatto a locale e CI.
  </Card>

  <Card title="SessionConfig" href="/it/packages/laravel-copilot-sdk/session-config">
    Configura modello, hook, server MCP e comportamento a runtime.
  </Card>

  <Card title="SessionEvent" href="/it/packages/laravel-copilot-sdk/session-event">
    Comprendi gli helper eventi specifici di Laravel e la gestione del ciclo di vita.
  </Card>

  <Card title="Richieste di permesso" href="/it/packages/laravel-copilot-sdk/permission-request">
    Verifica il flusso di autorizzazione per eseguire gli strumenti con approvazione esplicita.
  </Card>

  <Card title="Strumenti" href="/it/packages/laravel-copilot-sdk/tools">
    Invoca il codice dell'applicazione da Copilot.
  </Card>

  <Card title="MCP" href="/it/packages/laravel-copilot-sdk/mcp">
    Collega gli strumenti già pronti dei server MCP.
  </Card>
</Columns>

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

<Info>
  Riferimenti: [Laravel Copilot SDK README](https://github.com/invokable/laravel-copilot-sdk/blob/main/README.md), [Laravel Copilot SDK Getting Started](https://github.com/invokable/laravel-copilot-sdk/blob/main/docs/getting-started.md), [GitHub Copilot SDK](https://github.com/github/copilot-sdk)
</Info>


## Related topics

- [GitHub Copilot SDK for Laravel](/it/packages/laravel-copilot-sdk/index.md)
- [GitHub Actions - GitHub Copilot SDK for Laravel](/it/packages/laravel-copilot-sdk/github-actions.md)
- [Testing - GitHub Copilot SDK for Laravel](/it/packages/laravel-copilot-sdk/fake.md)
- [Autenticazione - GitHub Copilot SDK for Laravel](/it/packages/laravel-copilot-sdk/auth.md)
- [Laravel Cloud - GitHub Copilot SDK for Laravel](/it/packages/laravel-copilot-sdk/laravel-cloud.md)