> 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

Interactúa con proveedores de LLM o extiende el marco para implementar nuevos.

Con Neuron puedes cambiar entre proveedores de LLM con solo una 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: [], // Agrega parámetros personalizados (temperatura, logprobs, etc.)
        );
    }
}

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

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

#### Caché de prompts de Anthropic

Para aprovechar la caché de prompts de Anthropic debes proporcionar las instrucciones del agente como un array de `SystemContent`:

```php
use NeuronAI\Chat\Messages\ContentBlocks\SystemContent;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
        );
    }

    protected function instructions(): string|array
    {
        return [
            new SystemContent('parte fija')->cache(),
            new SystemContent('parte dinámica'),
        ];
    }
}
```

### Anthropic en Google Vertex AI

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

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

Abajo tienes 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: [], // Agrega parámetros personalizados (temperatura, logprobs, etc.)
        );
    }
}
```

### OpenAIResponses

Este componente usa la API de respuestas más reciente 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: [], // Agrega parámetros personalizados (temperatura, 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 usa 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: [], // Agrega parámetros personalizados (temperatura, 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 de 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: [], // Agrega parámetros personalizados (temperatura, 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: [], // Agrega parámetros personalizados (temperatura, 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: [], // Agrega parámetros personalizados (temperatura, 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
```

Abajo tienes 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: [], // Agrega parámetros personalizados (temperatura, 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: [], // Agrega parámetros personalizados (temperatura, 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: [], // Agrega parámetros personalizados (temperatura, 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: [], // Agrega parámetros personalizados (temperatura, 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: [], // Agrega parámetros personalizados (temperatura, 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 [`aws/aws-sdk-php`](https://github.com/aws/aws-sdk-php) paquete.

```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

No todos los prompts necesitan tu modelo más caro. Con nuestro paquete oficial [neuron-core/router](https://github.com/neuron-core/router) puedes enrutar las llamadas de inferencia a diferentes proveedores o modelos, de forma transparente para el propio agente. El router también te ofrece una estrategia de respaldo a un segundo proveedor en caso de que el principal falle por una caída del servicio o por exceder los límites de uso.

Primero instala el paquete:

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

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

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

class MyAgent extiende 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 la `RoundRobinRule` haciendo que el router actúe como un balanceador de carga entre los proveedores de IA conectados. El paquete incluye varias reglas integradas, incluido un clasificador LLM para enrutar las llamadas al modelo adecuado según el puntaje 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,
            )
        );
    }
}
```

## Implementa 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
{
    /**
     * Envía una instrucción predefinida al LLM.
     */
    public function systemPrompt(?string $prompt): AIProviderInterface;

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

    /**
     * Envía un prompt al agente de IA.
     */
    public function chat(array $messages): Message;
    
    /**
     * Devuelve 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 ni llamadas a funciones, puedes implementarlo con 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 Message 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}",
            ]
        ]);
    }

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

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

    /**
     * @inheritDoc
     */
    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" %}
Te 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 gracias a la comunidad.
{% endhint %}
