Proveedor de IA

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

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

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é.

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:

composer require google/auth

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

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:

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:

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.

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.

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

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

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:

composer require google/auth

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

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

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

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

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

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)

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 .

composer require aws/aws-sdk-php

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

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

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

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

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.

Primero instala el paquete:

composer require neuron-core/router

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

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.

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:

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.

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:

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

Recomendamos encarecidamente que envíes nuevas implementaciones de proveedores mediante PR en el repositorio oficial o usando otros Inspector.dev canales de soporte. La nueva implementación puede recibir un impulso importante en su avance por parte de la comunidad.