Custom Providers

Atlas supports custom AI providers through Prism. Custom providers are registered at the Prism level and work transparently with Atlas.

Prism Reference

For detailed instructions on creating and registering custom providers, see the Prism Custom Providers documentation.

Using Custom Providers

Once a custom provider is registered with Prism, use it with Atlas like any built-in provider.

With Agents

// Define in agent class
public function provider(): string
{
    return 'my-custom-provider';
}

public function model(): string
{
    return 'custom-model-v1';
}

Override at Runtime

Atlas::agent('my-agent')
    ->withProvider('my-custom-provider', 'custom-model')
    ->chat('Hello');

Direct Prism Usage

// Text generation
Atlas::text()
    ->using('my-custom-provider', 'custom-model')
    ->withPrompt('Hello')
    ->asText();

// Images
Atlas::image()
    ->using('my-custom-provider', 'custom-model')
    ->withPrompt('A sunset')
    ->generate();

// Embeddings
Atlas::embeddings()
    ->using('my-custom-provider', 'custom-model')
    ->fromInput('Text to embed')
    ->asEmbeddings();

Provider Options

Pass provider-specific options using withProviderMeta():

// Anthropic prompt caching
Atlas::agent('my-agent')
    ->withProviderMeta('anthropic', ['cacheType' => 'ephemeral'])
    ->chat('Hello');

// OpenAI options
Atlas::text()
    ->using('openai', 'gpt-4o')
    ->withProviderMeta('openai', [
        'presence_penalty' => 0.5,
        'frequency_penalty' => 0.3,
    ])
    ->withPrompt('Hello')
    ->asText();

Provider Resolution Order

When determining which provider to use:

1. withProvider() override (highest priority)
2. Agent's provider() method

If neither is set, an exception is thrown.

// Agent defines 'openai', but override to 'anthropic'
Atlas::agent('my-agent')
    ->withProvider('anthropic', 'claude-sonnet-4-20250514')
    ->chat('Hello');

API Reference

// Agent provider configuration (override in agent class)
public function provider(): ?string;                  // Provider name (e.g., 'openai', 'anthropic')
public function model(): ?string;                     // Model name (e.g., 'gpt-4o', 'claude-sonnet-4-20250514')
public function clientOptions(): array;               // HTTP client options
public function providerOptions(): array;             // Provider-specific options

// Runtime provider override
Atlas::agent('agent')
    ->withProvider(string $provider, ?string $model = null)  // Override provider and optionally model
    ->withModel(string $model)                               // Override model only
    ->withProviderOptions(array $options)                    // Provider-specific options
    ->chat(string $input);

// Direct Prism usage with providers
Atlas::text()->using(string $provider, string $model);
Atlas::image()->using(string $provider, string $model);
Atlas::audio()->using(string $provider, string $model);
Atlas::embeddings()->using(string $provider, string $model);
Atlas::moderation()->using(string $provider, string $model);

// Provider-specific options (via withProviderMeta or withProviderOptions)
// Anthropic:
->withProviderOptions(['cacheType' => 'ephemeral'])           // Prompt caching

// OpenAI:
->withProviderOptions([
    'presence_penalty' => 0.5,    // -2.0 to 2.0
    'frequency_penalty' => 0.3,   // -2.0 to 2.0
    'logit_bias' => [],           // Token biases
    'user' => 'user-123',         // End-user identifier
])

// Provider resolution order:
// 1. withProvider() override (highest priority)
// 2. Agent's provider() method
// 3. Exception if neither set

Next Steps

• Chat — Chat configuration
• Streaming — Stream responses
• Error Handling — Handle provider errors