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

# Getting started - GitHub Copilot SDK for Laravel

> Build your first Copilot-powered Laravel command and learn the core Laravel Copilot SDK workflow.

## Build your first Copilot-powered Laravel app

In this guide, you build a command-line assistant with the Laravel Copilot SDK.
You start with a single prompt, then move to sessions, events, and tools.

## Prerequisites

Before you begin, make sure you have:

* GitHub Copilot CLI installed and authenticated
* PHP `8.4+`
* Laravel `13.x`

Verify the CLI is available:

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

## Install the SDK

Install the package with Composer:

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

Optional configuration:

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

If needed, set the CLI path in your `.env`:

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

## Send your first message

Create a command and call `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());
    }
}
```

Run the command:

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

## Keep context with sessions

Use `Copilot::start()` when you need multiple prompts in one conversation:

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

## Handle session events

Register an event handler with `on()` to inspect assistant messages and failures:

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

## Add a custom tool

Define a tool with a JSON schema and a 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);
```

## Build an interactive assistant

Combine sessions, events, and tools into an interactive Artisan command:

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

Run the command:

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

## How tools work

When you define a tool, you provide:

1. What the tool does.
2. Which parameters it accepts.
3. Which handler code should run.

Copilot decides when to call the tool based on user input. The SDK executes your handler and returns the result back to Copilot.

## Explore more features

### Connect to MCP servers

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

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

### Create custom agents

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

### Customize the system message

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

## Connect to an external CLI server

Run the Copilot CLI in server mode:

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

Then set the URL in `.env`:

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

When `COPILOT_URL` is set, the SDK connects to that server instead of starting a new CLI process.

## Telemetry and observability

Configure telemetry in `config/copilot.php`:

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

Or configure it directly:

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

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

## Learn more

* [Authentication](/en/packages/laravel-copilot-sdk/auth)
* [MCP](/en/packages/laravel-copilot-sdk/mcp)
* [Custom providers](/en/packages/laravel-copilot-sdk/custom-providers)
* [Telemetry](/en/packages/laravel-copilot-sdk/telemetry)
* [Session config](/en/packages/laravel-copilot-sdk/session-config)
* [SessionEvent](/en/packages/laravel-copilot-sdk/session-event)
* [Laravel Copilot SDK overview](/en/packages/laravel-copilot-sdk)
* [Official SDK repository](https://github.com/github/copilot-sdk)

## Next steps

<Columns cols={2}>
  <Card title="Authentication" href="/en/packages/laravel-copilot-sdk/auth">
    Choose the right auth method for local and CI environments.
  </Card>

  <Card title="Tools" href="/en/packages/laravel-copilot-sdk/tools">
    Let Copilot call your application code.
  </Card>

  <Card title="Session config" href="/en/packages/laravel-copilot-sdk/session-config">
    Configure models, hooks, MCP servers, and runtime behavior.
  </Card>

  <Card title="MCP" href="/en/packages/laravel-copilot-sdk/mcp">
    Connect pre-built tools from MCP servers.
  </Card>

  <Card title="Custom providers" href="/en/packages/laravel-copilot-sdk/custom-providers">
    Integrate additional provider and model strategies.
  </Card>

  <Card title="Telemetry" href="/en/packages/laravel-copilot-sdk/telemetry">
    Export traces for debugging and observability.
  </Card>
</Columns>

You now covered the core Laravel Copilot SDK flow from single prompts to tool-enabled sessions.

<Info>
  Source references: [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), and [GitHub Copilot SDK](https://github.com/github/copilot-sdk).
</Info>