> 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/agente/async.md).

# HTTP y asíncrono

Ejecuta flujos de trabajo en un contexto asíncrono.

Neuron admite la ejecución asíncrona y el procesamiento paralelo de agentes, lo que te permite manejar eficientemente múltiples operaciones al mismo tiempo. El enfoque de Neuron para la ejecución asíncrona ofrece varias ventajas:

**Independiente del marco**: Puedes hacer que los agentes y RAG sean compatibles con asincronía para los entornos asíncronos más comunes con un simple adaptador; no se requieren cambios en tu implementación.

**Compatibilidad con proveedores**: Nuestra solución funciona independientemente del proveedor que uses. Puedes tener flujos de trabajo o sistemas multiagente que usen diferentes proveedores y modelos funcionando sin problemas en un bucle asíncrono.

**Escalabilidad**: Las aplicaciones que manejan grandes volúmenes de datos (clasificación de productos, moderación de contenido, etiquetado de datos) se benefician significativamente de las capacidades de procesamiento concurrente.

### Concurrencia vs asincronía

La concurrencia es el concepto de alto nivel de gestionar tareas, lo que puede implicar múltiples hilos/núcleos (paralelismo), mientras que la asincronía usa bucles de eventos/callbacks para permitir que las tareas se ejecuten fuera de orden, perfecto para trabajo ligado a E/S sin esperar.

La concurrencia consiste en gestionar muchas cosas en paralelo, mientras que la asincronía es cómo un solo hilo puede gestionar muchas operaciones de E/S de forma eficiente.

Los agentes de IA suelen considerarse software que consume mucha E/S porque la solicitud HTTP para ejecutar la inferencia sobre el modelo normalmente tarda segundos en completarse. En un entorno PHP estándar, durante este tiempo tu aplicación simplemente espera. En esta sección de la documentación te ofrecemos un par de soluciones para ejecutar múltiples agentes de forma eficiente.

## Concurrencia

No necesitas ninguna característica particular de Neuron para ejecutar múltiples agentes en paralelo. Solo necesitas que tu aplicación PHP sea capaz de abrir múltiples procesos para manejar la ejecución de varios agentes al mismo tiempo. Puedes hacerlo con bibliotecas de PHP como [spatie/fork](https://github.com/spatie/fork), o soluciones específicas del marco como [concurrencia en Laravel](https://laravel.com/docs/master/concurrency), o [proceso de Symfony](https://symfony.com/doc/current/components/process.html).

La asincronía es otra historia.

## Asincronía

Las versiones anteriores de Neuron estaban fuertemente acopladas al cliente Guzzle para realizar solicitudes HTTP para la inferencia del modelo en la API de los proveedores. Guzzle es una gran herramienta, pero no es compatible con bucles de eventos verdaderamente asíncronos como los que proporcionan marcos como [Amp](https://github.com/amphp/amp) y [ReactPHP](https://github.com/reactphp/reactphp).

Para ejecutar agentes en ऐसे entornos asíncronos es necesario integrarse con sus implementaciones específicas. Por eso Neuron incluye un sencillo `HttpClientInterface` que puede implementarse para permitir que los proveedores de IA realicen solicitudes HTTP sin problemas en un bucle asíncrono.

De forma predeterminada, el marco usa la implementación de Guzzle, pero puedes inyectar clientes HTTP personalizados según tus necesidades. Ya proporcionamos implementaciones para el marco asíncrono más común.

### AmpHttpClient

Si quieres usar Amp para ejecutar múltiples solicitudes asíncronas de agentes, necesitas instalar `amphp/http-client` .

```bash
composer require amphp/http-client
```

Ahora puedes inyectar el `AmpHttpClient` adaptador integrado en el proveedor:

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\HttpClient\AmpHttpClient;
use NeuronAI\Providers\Anthropic\Anthropic;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        // Es lo mismo para cualquier proveedor (Anthropic, OpenAI, Ollama, Gemini, etc.)
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
            httpClient: new AmpHttpClient(),
        );
    }
}
```

Ahora puedes ejecutar múltiples solicitudes de agentes usando el patrón asíncrono/await de Amp para ejecutar múltiples agentes de forma asíncrona:

```php
use Amp\Future;

use function Amp\async;

$handler1 = MyAgent::make()->setThreadId('chat_id_x')->chat(new UserMessage('¡Hola!'));
$handler2 = MyAgent::make()->setThreadId('chat_id_xx')->chat(new UserMessage('¡Hola!'));
$handler3 = MyAgent::make()->setThreadId('chat_id_xxx')->chat(new UserMessage('¡Hola!'));

// Ejecuta tres solicitudes en paralelo
[$response1, $response2, $response3] = Future\await([
    async(fn() => $handler1->getMessage()), 
    async(fn() => $handler2->getMessage()),
    async(fn() => $handler3->getMessage()),
]);

// Imprime el contenido
echo $response1->getContent();
echo $response2->getContent();
echo $response3->getContent();
```

### RAG asíncrono

La abstracción del cliente HTTP también es aceptada por todos los demás componentes del marco, como los proveedores de embeddings y los almacenes vectoriales. Puedes proporcionar un cliente asíncrono a todos estos componentes y también ejecutar el pipeline de carga de datos de forma asíncrona.

```php
class MyChatBot extends RAG
{
    protected function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
            httpClient: new AmpHttpClient(),
        );
    }
    
    protected function embeddings(): EmbeddingsProviderInterface
    {
        return new VoyageEmbeddingsProvider(
            key: 'OPENAI_API_KEY',
            model: 'OPENAI_MODEL'
            httpClient: new AmpHttpClient(),
        );
    }
    
    protected function vectorStore(): VectorStoreInterface
    {
        return new PineconeVectorStore(
            key: 'PINECONE_API_KEY',
            indexUrl: 'PINECONE_INDEX_URL',
            httpClient: new AmpHttpClient(),
        );
    }
}
```

### Guardrails

La capacidad de ejecutar agentes de forma asíncrona abre la posibilidad de ejecutar una guardia de entrada al mismo tiempo que la solicitud principal. Normalmente puedes crear un agente especializado para ejecutar comprobaciones de seguridad sobre la entrada del usuario y usar la respuesta estructurada para recuperar el resultado.

Puedes ejecutar ambas solicitudes en paralelo y comprobar el resultado de la guardia antes de devolver la respuesta al usuario. Ejecutar ambas solicitudes en paralelo te permite aplicar seguridad sin afectar la experiencia del usuario.

```php
use Amp\Future;
use function Amp\async;

$input = new UserMessage('¡Hola!');

// Ejecuta tres solicitudes en paralelo
[$response, $guardrail] = Future\await([
    async(fn() => MyAgent::make()
        ->setThreadId('chat_id')
        ->chat($input)
        ->getMessage()),
        
    async(fn() => GuardrailAgent::make()
        ->setThreadId('guardrails')
        ->structured($input, Guardrail::class)),
]);

if (! $guardrail->valid) {
    throw \Exception('Violación de la política de contenido.');
}

// Imprime el contenido
echo $response->getContent();
```

## StoppableHttpClient

Detén una respuesta transmitida en mitad del proceso, para un botón de "dejar de generar". El proveedor mantiene el texto transmitido hasta ese momento como contenido parcial y lo guarda en el historial del chat.

Envuelve el cliente en `StoppableHttpClient` con un predicado que el proveedor consulta antes de cada evento que lee; el endpoint de "stop" solo activa una bandera que lee el predicado, en cualquier almacén que compartan ambos procesos:

```php
use NeuronAI\HttpClient\Curl\CurlHttpClient;
use NeuronAI\HttpClient\StoppableHttpClient;

protected function provider(): AIProviderInterface
{
    return new Anthropic(
        key: $this->apiKey,
        model: 'claude-sonnet-4-6',
        // La caché o cualquier almacén compartido funciona (Laravel o Symfony Cache, Redis, una fila de base de datos)
        httpClient: new StoppableHttpClient(
            new CurlHttpClient(), 
            fn (): bool => Cache::pull("stop:{$this->getThreadId()}", false)
        ),
    );
}
```
