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

# Primeros pasos - GitHub Copilot SDK for Laravel

> Crea tu primer comando Laravel con Copilot y aprende el flujo básico de Laravel Copilot SDK.

## Crear tu primera app Laravel compatible con Copilot

En esta guía crearás un asistente de línea de comandos con Laravel Copilot SDK.
Empezarás enviando un único prompt y avanzarás hacia sesiones, eventos y herramientas.

## Requisitos previos

Antes de empezar comprueba lo siguiente:

* Tener instalado y autenticado GitHub Copilot CLI
* PHP `8.4+`
* Laravel `13.x`

Verifica que el CLI está disponible:

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

## Instala el SDK

Instala el paquete con Composer.

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

Publica la configuración si lo necesitas:

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

Si es necesario, configura la ruta del CLI en `.env`:

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

## Envía tu primer mensaje

Crea un comando y llama a `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());
    }
}
```

Ejecuta el comando:

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

## Mantén el contexto con una sesión

Si vas a usar varios prompts en una misma conversación, utiliza `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());
});
```

## Procesa eventos de sesión

Registra un handler de eventos con `on()` para inspeccionar los mensajes del assistant y los fallos.

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

## Añade una herramienta personalizada

Define una herramienta con un JSON schema y 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);
```

## Crea un asistente interactivo

Al combinar sesiones, eventos y herramientas puedes crear un comando Artisan interactivo.

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

Ejecuta el comando:

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

## Cómo funcionan las herramientas

Al definir una herramienta indicas estos tres puntos:

1. Qué hace la herramienta.
2. Qué parámetros recibe.
3. Qué código del handler se ejecuta.

Copilot decide cuándo invocar la herramienta según el input del usuario, el SDK ejecuta el handler y devuelve el resultado.

## Prueba estas funciones a continuación

### Conecta un servidor MCP

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

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

### Crea un agente personalizado

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

### Personaliza el mensaje de 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.',
    ),
);
```

## Conecta con un servidor CLI externo

Levanta Copilot CLI en modo servidor:

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

Después configura la URL de conexión en `.env`:

```dotenv theme={null}
COPILOT_URL=tcp://127.0.0.1:4321
```

Si defines `COPILOT_URL`, el SDK no lanza un proceso CLI nuevo y se conecta al servidor existente.

## Telemetría y observabilidad

Configura la telemetría en `config/copilot.php`:

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

O configúrala directamente:

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

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

## Más recursos

* [Autenticación](/es/packages/laravel-copilot-sdk/auth)
* [MCP](/es/packages/laravel-copilot-sdk/mcp)
* [Proveedores personalizados](/es/packages/laravel-copilot-sdk/custom-providers)
* [Telemetría](/es/packages/laravel-copilot-sdk/telemetry)
* [SessionConfig](/es/packages/laravel-copilot-sdk/session-config)
* [SessionEvent](/es/packages/laravel-copilot-sdk/session-event)
* [Introducción a Laravel Copilot SDK](/es/packages/laravel-copilot-sdk)
* [Repositorio del SDK oficial](https://github.com/github/copilot-sdk)

## Siguientes pasos

<Columns cols={2}>
  <Card title="Autenticación" href="/es/packages/laravel-copilot-sdk/auth">
    Elige el método de autenticación más adecuado para tu entorno local y para CI.
  </Card>

  <Card title="SessionConfig" href="/es/packages/laravel-copilot-sdk/session-config">
    Configura modelo, hooks, servidores MCP y el comportamiento en tiempo de ejecución.
  </Card>

  <Card title="SessionEvent" href="/es/packages/laravel-copilot-sdk/session-event">
    Comprende los helpers de eventos específicos de Laravel y el manejo del ciclo de vida.
  </Card>

  <Card title="Solicitudes de permiso" href="/es/packages/laravel-copilot-sdk/permission-request">
    Revisa el flujo de permisos para ejecutar herramientas con aprobación explícita.
  </Card>

  <Card title="Herramientas" href="/es/packages/laravel-copilot-sdk/tools">
    Llama al código de tu aplicación desde Copilot.
  </Card>

  <Card title="MCP" href="/es/packages/laravel-copilot-sdk/mcp">
    Conecta herramientas listas para usar de servidores MCP.
  </Card>
</Columns>

Con esto has recorrido el flujo principal de Laravel Copilot SDK, desde un prompt aislado hasta una sesión con herramientas integradas.

<Info>
  Referencias: [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](/es/packages/laravel-copilot-sdk/index.md)
- [Laravel Boost Custom Agent for GitHub Copilot CLI](/es/packages/laravel-boost-copilot-cli.md)
- [GitHub Actions - GitHub Copilot SDK for Laravel](/es/packages/laravel-copilot-sdk/github-actions.md)
- [Tests - GitHub Copilot SDK for Laravel](/es/packages/laravel-copilot-sdk/fake.md)
- [Autenticación - GitHub Copilot SDK for Laravel](/es/packages/laravel-copilot-sdk/auth.md)