> For the complete documentation index, see [llms.txt](https://docs.neuron-ai.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neuron-ai.dev/neuron-v3-es/proveedores/ai-provider.md).

# Proveedor de IA

Con Neuron puedes cambiar entre proveedores de LLM con una sola línea de código, sin ningún impacto en la implementación de tu agente.

### Anthropic

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
            parameters: [], // Añade parámetros personalizados (temperature, logprobs, etc)
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("¡Hola!"))
    ->getMessage();

echo $message->getContent();
// Hola, ¿en qué puedo ayudarte hoy?
```

#### Caché de prompts de Anthropic

El proveedor de Anthropic expone un método dedicado `systemPromptBlocks()` para aprovechar la caché del prompt del sistema. En lugar de usar el `instructions()` método en la clase Agent, puedes pasar la definición de prompts directamente a la instancia del proveedor con definición de tipo de caché.

```php
class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: 'ANTHROPIC_KEY',
            model: 'ANTHROPIC_MODEL'
        )->systemPromptBlocks([
            ['type' => 'text', 'text' => 'Instrucciones estáticas...', 'cache_control' => ['type' => 'ephemeral']],
            ['type' => 'text', 'text' => 'Contexto dinámico...']
        ]);
    }
}
```

### Anthropic en Google Vertex AI

Para usar este proveedor necesitas instalar el paquete Composer de autenticación de Google:

```shellscript
composer require google/auth
```

A continuación la sintaxis para usar `AnthropicVertex` en tu agente.

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\AnthropicVertex;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new AnthropicVertex(
            pathJsonCredentials: 'GOOGLE_FILE_CREDENTIALS_PATH',
            location: 'GOOGLE_LOCATION',
            projectId: 'GOOGLE_PROJECT_ID',
            model: 'ANTHROPIC_MODEL',
            parameters: [], // Añade parámetros personalizados (temperature, logprobs, etc)
        );
    }
}
```

### OpenAIResponses

Este componente utiliza la API más reciente de respuestas de OpenAI:

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\OpenAI\Responses\OpenAIResponses;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new OpenAIResponses(
            key: 'OPENAI_API_KEY',
            model: 'OPENAI_MODEL',
            parameters: [], // Añade parámetros personalizados (temperature, logprobs, etc)
            strict_response: false, // Salida estructurada estricta
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("¡Hola!"))
    ->getMessage();

echo $message->getContent();
// Hola, ¿en qué puedo ayudarte hoy?
```

### OpenAI

Este componente utiliza la antigua API de completions de OpenAI:

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\OpenAI\OpenAI;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new OpenAI(
            key: 'OPENAI_API_KEY',
            model: 'OPENAI_MODEL',
            parameters: [], // Añade parámetros personalizados (temperature, logprobs, etc)
            strict_response: false, // Salida estructurada estricta
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("¡Hola!"))
    ->getMessage();

echo $message->getContent();
// Hola, ¿en qué puedo ayudarte hoy?
```

### AzureOpenAI

Este proveedor te permite conectarte con modelos de OpenAI proporcionados en la plataforma en la nube de Azure.

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\AzureOpenAI;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new AzureOpenAI(
            key: 'AZURE_API_KEY',
            endpoint: 'AZURE_ENDPOINT',
            model: 'OPENAI_MODEL',
            version: 'AZURE_API_VERSION'
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("¡Hola!"))
    ->getMessage();

echo $message->getContent();
// Hola, ¿en qué puedo ayudarte hoy?
```

### OpenAILike

Esta clase simplifica la conexión con proveedores que ofrecen el mismo formato de datos que la API oficial de OpenAI.

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\OpenAILike;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new OpenAILike(
            baseUri: 'https://api.together.xyz/v1',
            key: 'API_KEY',
            model: 'MODEL',
            parameters: [], // Añade parámetros personalizados (temperature, logprobs, etc)
            strict_response: false, // Salida estructurada estricta
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("¡Hola!"))
    ->getMessage();

echo $message->getContent();
// Hola, ¿en qué puedo ayudarte hoy?
```

### Ollama

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Ollama\Ollama;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Ollama(
            url: 'OLLAMA_URL',
            model: 'OLLAMA_MODEL',
            parameters: [], // Añade parámetros personalizados (temperature, logprobs, etc)
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("¡Hola!"))
    ->getMessage();

echo $message->getContent();
// Hola, ¿en qué puedo ayudarte hoy?
```

### Gemini

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Gemini\Gemini;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Gemini(
            key: 'GEMINI_API_KEY',
            model: 'GEMINI_MODEL',
            parameters: [], // Añade parámetros personalizados (temperature, logprobs, etc)
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("¡Hola!"))
    ->getMessage();

echo $message->getContent();
// Hola, ¿en qué puedo ayudarte hoy?
```

### Gemini en Vertex AI

Para usar este proveedor necesitas instalar el paquete Composer de autenticación de Google:

```bash
composer require google/auth
```

A continuación la sintaxis para usar `GeminiVertex` en tu agente.

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Gemini\GeminiVertex;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new GeminiVertex(
            pathJsonCredentials: 'GOOGLE_FILE_CREDENTIALS_PATH',
            location: 'GOOGLE_LOCATION',
            projectId: 'GOOGLE_PROJECT_ID',
            model: 'GEMINI_MODEL',
            parameters: [], // Añade parámetros personalizados (temperature, logprobs, etc)
        );
    }
}
```

### Mistral

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Mistral\Mistral;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Mistral(
            key: 'MISTRAL_API_KEY',
            model: 'MISTRAL_MODEL',
            parameters: [], // Añade parámetros personalizados (temperature, logprobs, etc)
            strict_response: false, // Salida estructurada estricta
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("¡Hola!"))
    ->getMessage();

echo $message->getContent();
// Hola, ¿en qué puedo ayudarte hoy?
```

### ZAI

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\ZAI\ZAI;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new ZAI(
            key: 'ZAI_API_KEY',
            model: 'glm-5',
            parameters: [], // Añade parámetros personalizados (temperature, logprobs, etc)
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("¡Hola!"))
    ->getMessage();

echo $message->getContent();
// Hola, ¿en qué puedo ayudarte hoy?
```

### HuggingFace

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\HuggingFace\HuggingFace;
use NeuronAI\Providers\HuggingFace\InferenceProvider;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new HuggingFace(
            key: 'HF_ACCESS_TOKEN',
            model: 'mistralai/Mistral-7B-Instruct-v0.3',
            // https://huggingface.co/docs/inference-providers/en/index
            inferenceProvider: InferenceProvider::HF_INFERENCE,
            parameters: [
                'max_tokens' => 500,
                'temperature' => 0.5
            ]
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("¡Hola!"))
    ->getMessage();

echo $message->getContent();
// Hola, ¿en qué puedo ayudarte hoy?
```

### Deepseek

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Deepseek\Deepseek;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Deepseek(
            key: 'DEEPSEEK_API_KEY',
            model: 'DEEPSEEK_MODEL',
            parameters: [], // Añade parámetros personalizados (temperature, logprobs, etc)
            strict_response: false, // Salida estructurada estricta
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("¡Hola!"))
    ->getMessage();

echo $message->getContent();
// Hola, ¿en qué puedo ayudarte hoy?
```

### Grok (X-AI)

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\XAI\Grok;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Grok(
            key: 'GROK_API_KEY',
            model: 'grok-4',
            parameters: [], // Añade parámetros personalizados (temperature, logprobs, etc)
            strict_response: false, // Salida estructurada estricta
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("¡Hola!"))
    ->getMessage();

echo $message->getContent();
// Hola, ¿en qué puedo ayudarte hoy?
```

### AWS Bedrock Runtime

Para usar el `BedrockRuntime` proveedor, necesitas instalar el [`paquete aws/aws-sdk-php`](https://github.com/aws/aws-sdk-php) .

```bash
composer require aws/aws-sdk-php
```

A continuación puedes encontrar la sintaxis para usarlo en tu agente.

```php
namespace App\Neuron;

use Aws\BedrockRuntime\BedrockRuntimeClient;
use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\AWS\BedrockRuntime;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        $client = new BedrockRuntimeClient([
            'version' => 'latest',
            'region' => 'us-east-1',
            'credentials' => [
                'key' => 'AWS_BEDROCK_KEY',
                'secret' => 'AWS_BEDROCK_SECRET',
            ],
        ]);
        
        return new BedrockRuntime(
            client: $client,
            model: 'AWS_BEDROCK_MODEL',
            inferenceConfig: []
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("¡Hola!"))
    ->getMessage();

echo $message->getContent();
// Hola, ¿en qué puedo ayudarte hoy?
```

### Cohere

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Cohere\Cohere;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Cohere(
            key: 'COHERE_API_KEY',
            model: 'command-a-reasoning-08-2025',
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("¡Hola!"))
    ->getMessage();

echo $message->getContent();
// Hola, ¿en qué puedo ayudarte hoy?
```

### Alibaba DashScope

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Alibaba\DashScopeOpenAI;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new DashScopeOpenAI(
            key: 'DS_API_KEY',
            model: 'wan2.6-t2i',
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("¡Hola!"))
    ->getMessage();

echo $message->getContent();
// Hola, ¿en qué puedo ayudarte hoy?
```

## Enrutamiento

Oficial [Neuron Router](https://github.com/neuron-core/router) añade una capa de fiabilidad y gestión entre la sesión del Agente y la API de proveedores, dándote a ti y a tu aplicación varias ventajas clave.

#### Conmutación por error del proveedor para alta disponibilidad <a href="#provider-failover-for-high-availability" id="provider-failover-for-high-availability"></a>

La API de proveedores ocasionalmente experimenta interrupciones o limitación de tasa. Al usar RouterProvider, tus solicitudes conmutan automáticamente entre múltiples proveedores subyacentes. Si un proveedor no está disponible o tiene limitación de tasa, el router dirige sin problemas la solicitud a otro, manteniendo tus sesiones sin interrupciones.

#### Control de la lógica de enrutamiento

Puedes usar lógica de enrutamiento como `RoundRobin` como equilibrador de carga, `ContentRule` para enrutar la solicitud según los bloques de contenido dentro del mensaje (imágenes, archivos, audio, video), o `DifficultyRule` para determinar qué modelo tiene las mejores capacidades para manejar el prompt entrante.&#x20;

Primero instala el paquete:

```shellscript
composer require neuron-core/router
```

Ahora usa el `RouterProvider` como cualquier otro proveedor en la clase de tu agente:

```php
use NeuronAI\Router\RouterProvider;
use NeuronAI\Router\Rules\MethodRule;
use NeuronAI\Providers\Anthropic\Anthropic;
use NeuronAI\Providers\OpenAI\OpenAI;

class MyAgent extens Agent
{
    protected function provider(): AIProviderInterface
    {
        return RouterProvider::make()
            ->addProvider('anthropic', new Anthropic(
                key: 'ANTHROPIC_API_KEY',
                model: 'claude-sonnet-4-20250514',
            ))
            ->addProvider('openai', new OpenAI(
                key: 'OPENAI_API_KEY',
                model: 'gpt-4o',
            ))
            ->setRule(
                new RoundRobinRule(['anthropic', 'openai'])
            );
    }

    protected function instructions(): string
    {...}

    protected function tools(): array
    {...}
}
```

En el ejemplo anterior usamos el `RoundRobinRule` haciendo que el router actúe como un equilibrador de carga entre los proveedores de IA conectados. El paquete incluye varias reglas incorporadas, incluido un clasificador LLM para enrutar llamadas al modelo adecuado según la puntuación de dificultad del prompt: <https://github.com/neuron-core/router#difficultyrule>

## Cliente HTTP personalizado

Los proveedores usan un cliente HTTP para comunicarse con el servicio remoto. Puedes personalizar la configuración del cliente HTTP pasando explícitamente una instancia con parámetros de constructor personalizados, como tiempo de espera, encabezados personalizados, etc.

```php
use NeuronAI\Providers\HttpClientOptions;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Ollama(
            url: 'OLLAMA_URL',
            model: 'OLLAMA_MODEL',
            httpClient: new GuzzleHttpClient(
                customHeaders: [...],
                timeout: 30,
            )
        );
    }
}
```

## Implementar un proveedor personalizado

Si quieres crear un nuevo proveedor, tienes que implementar la `AIProviderInterface` interfaz:

```php
namespace NeuronAI\Providers;

use NeuronAI\Chat\Messages\Message;
use NeuronAI\Tools\ToolInterface;
use NeuronAI\Providers\MessageMapperInterface;

interface AIProviderInterface
{
    /**
     * Enviar una instrucción predefinida al LLM.
     */
    public function systemPrompt(?string $prompt): AIProviderInterface;

    /**
     * Establecer las herramientas que se expondrán al LLM.
     *
     * @param array<ToolInterface> $tools
     */
    public function setTools(array $tools): AIProviderInterface;
    
    /**
     * El componente responsable de mapear el mensaje de NeuronAI al formato del proveedor de IA.
     */
    public function messageMapper(): MessageMapperInterface;

    /**
     * Enviar un prompt al agente de IA.
     */
    public function chat(array $messages): Message;
    
    /**
     * Emitir la respuesta del LLM.
     */
    public function stream(array|string $messages, callable $executeToolsCallback): \Generator;
    
    /**
     * Respuesta validada por esquema.
     */
    public function structured(string $class, Message|array $messages, int $maxRetry = 1): mixed;
}
```

El `chat` el método debe contener la llamada al LLM subyacente. Si el proveedor no admite herramientas y llamadas a funciones, puedes implementarlo como un marcador de posición.

Esta es la plantilla básica para una nueva implementación de proveedor de IA.

```php
namespace App\Neuron\Providers;

use GuzzleHttp\Client;
use GuzzleHttp\RequestOptions;
use NeuronAI\Chat\Messages\AssistantMessage;
use NeuronAI\Chat\Messages\Message;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\HandleWithTools;
use NeuronAI\Providers\MessageMapperInterface;

class MyAIProvider implements AIProviderInterface
{
    use HandleWithTools;
    
    /**
     * El cliente HTTP.
     *
     * @var Client
     */
    protected Client $client;

    /**
     * Instrucciones del sistema.
     *
     * @var string
     */
    protected string $system;

    /**
     * El componente responsable de mapear el mensaje de NeuronAI al formato del proveedor de IA.
     *
     * @var MessageMapperInterface
     */
    protected MessageMapperInterface $messageMapper;
    
    public function __construct(
        protected string $key,
        protected string $model
    ) {
        $this->client = new Client([
            'base_uri' => 'https://api.provider.com/v1',
            'headers' => [
                'Content-Type' => 'application/json',
                'Authorization' => "Bearer {$this->key}",
            ]
        ]);
    }

    /**
     * @inerhitDoc
     */
    public function systemPrompt(string $prompt): AIProviderInterface
    {
        $this->system = $prompt;
        return $this;
    }

    public function messageMapper(): MessageMapperInterface
    {
        return $this->messageMapper ?? $this->messageMapper = new MessageMapper();
    }

    /**
     * @inerhitDoc
     */
    public function chat(array $messages): Message
    {
        $result = $this->client->post('chat', [
            RequestOptions::JSON => [
                'model' => $this->model,
                'messages' => \array_map(function (Message $message) {
                    return $message->jsonSerialize();
                }, $messages)
            ]
        ])->getBody()->getContents();
        
        $result = \json_decode($result, true);

        return new AssistantMessage($result['content']);
    }
}
```

Después de crear tu propia implementación, puedes usarla en el agente:

```php
namespace App\Neuron;

use App\Neuron\Providers\MyAIProvider;
use NeuronAI\Agent;
use NeuronAI\Providers\AIProviderInterface;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new MyAIProvider (
            key: 'PROVIDER_API_KEY',
            model: 'PROVIDER_MODEL',
        );
    }
}
```

{% hint style="warning" %}
Recomendamos encarecidamente que envíes nuevas implementaciones de proveedores mediante PR en el repositorio oficial o usando otros [Inspector.dev](https://inspector.dev/developer-support/) canales de soporte. La nueva implementación puede recibir un impulso importante en su avance por parte de la comunidad.
{% endhint %}