Custom providers

Configure custom BYOK providers in Laravel Copilot SDK, including OpenAI-compatible endpoints, Ollama, and Azure OpenAI.

Custom providers

Custom providers (BYOK: Bring Your Own Key) let you connect to OpenAI-compatible API endpoints using your own API key. Local providers such as Ollama are also supported.

ProviderConfig

The ProviderConfig class has the following properties.

Property	Type	Description
baseUrl	string	Required. URL of the API endpoint
type	string|null	Provider type: openai (default), azure, or anthropic
wireApi	string|null	API format (openai/azure only): completions (default) or responses
apiKey	string|null	API key. Not required for local providers such as Ollama
bearerToken	string|null	For Bearer token authentication. Takes priority over apiKey
azure	array|null	Azure-specific options, for example ['apiVersion' => '2024-10-21']

Basic usage

When using a custom provider, the model parameter is required.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ProviderConfig;
use Revolution\Copilot\Types\SessionConfig;

$response = Copilot::run(
    prompt: 'Hello!',
    config: new SessionConfig(
        model: 'gpt-4', // Required when using a custom provider
        provider: new ProviderConfig(
            baseUrl: 'https://my-api.example.com/v1',
            apiKey: config('services.openai.key'),
        ),
    ),
);

You can also use array format.

$response = Copilot::run(
    prompt: 'Hello!',
    config: [
        'model' => 'gpt-4',
        'provider' => [
            'baseUrl' => 'https://my-api.example.com/v1',
            'apiKey' => config('services.openai.key'),
        ],
    ],
);

Ollama (local provider)

For local providers such as Ollama, apiKey is not required.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ProviderConfig;
use Revolution\Copilot\Types\SessionConfig;

$response = Copilot::run(
    prompt: 'Hello!',
    config: new SessionConfig(
        model: 'deepseek-coder-v2:16b',
        provider: new ProviderConfig(
            type: 'openai',
            baseUrl: 'http://localhost:11434/v1',
        ),
    ),
);

Azure OpenAI

When using Azure OpenAI, keep these points in mind:

• Always set type to azure (not openai)
• Set baseUrl to host only (do not include path like /openai/v1)

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ProviderConfig;
use Revolution\Copilot\Types\SessionConfig;

$response = Copilot::run(
    prompt: 'Hello!',
    config: new SessionConfig(
        model: 'gpt-4',
        provider: new ProviderConfig(
            type: 'azure', // Always use 'azure' for Azure endpoints
            baseUrl: 'https://my-resource.openai.azure.com', // Host only
            apiKey: config('services.azure.openai_key'),
            azure: [
                'apiVersion' => '2024-10-21',
            ],
        ),
    ),
);

Important notes

When you use a custom provider, model is required. If you omit it, the SDK returns an error.

• For Azure endpoints (*.openai.azure.com), always use type: 'azure'.
• Set baseUrl to host only. The SDK builds request paths automatically.

onListModels handler

In BYOK mode with a custom provider, you can make client->listModels() call a custom handler instead of the CLI server.

Configure it with listModelsUsing(). Because the client may be re-initialized, always set listModelsUsing() before calling listModels().

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ModelInfo;

$models = Copilot::client()->listModelsUsing(function (): array {
    // Return models available from your custom provider
    return [
        ['id' => 'my-model-1', 'name' => 'My Model 1', 'version' => '1.0'],
        ['id' => 'my-model-2', 'name' => 'My Model 2', 'version' => '2.0'],
    ];
})->listModels();

Pass null to remove the handler and return to default CLI server behavior.

// Remove the handler and return to default behavior (query CLI server)
$models = Copilot::client()->listModelsUsing(null)->listModels();

When listModelsUsing() is set, listModels() does not require a CLI server connection and does not use cache.

For the latest updates, see the GitHub repository.