Modo TCP

Explica cómo conectar Laravel Copilot SDK a un servidor Copilot CLI ya arrancado, con menor overhead y uso compartido.

​

Modo TCP

Normalmente el SDK arranca un nuevo proceso de Copilot CLI por cada petición (modo stdio). Con el modo TCP puedes conectar a un servidor Copilot CLI arrancado previamente.

​

Ventajas del modo TCP

• Mejor rendimiento: no hay overhead de arranque de proceso
• Recursos compartidos: varios procesos Laravel pueden compartir el mismo servidor CLI
• Gestión de procesos: puedes gestionarlo como proceso en segundo plano con Laravel Forge / Laravel Cloud
• Compatible con despliegues: soporta el reinicio automático en cada despliegue

​

Uso

​

1. Arranca el servidor Copilot CLI

copilot --headless --port 12345

​

2. Configura la variable de entorno

COPILOT_URL=tcp://127.0.0.1:12345
# COPILOT_URL=http://127.0.0.1:12345
# COPILOT_URL=127.0.0.1:12345
# COPILOT_URL=12345
# COPILOT_URL=127.0.0.1
# COPILOT_URL=localhost

Con solo esto, el SDK pasa automáticamente de stdio a TCP.

• tcp:// es opcional. Funciona también con http:// o sin esquema.
• Puedes indicar solo el puerto; en ese caso el host es 127.0.0.1 de forma automática.
• Si indicas solo el host, únicamente son válidos 127.0.0.1 y localhost; en ese caso el puerto por defecto es 12345.

​

Fichero de configuración

Puedes configurar la conexión TCP en config/copilot.php.

return [
    // URL de destino de la conexión TCP (si se configura, se usa el modo TCP)
    'url' => env('COPILOT_URL'),

    // Lo siguiente solo se usa en modo stdio
    'cli_path' => env('COPILOT_CLI_PATH', 'copilot'),
    'cli_args' => [],
    'cwd' => null,
    'log_level' => env('COPILOT_LOG_LEVEL', 'info'),

    // Común a ambos modos
    'timeout' => env('COPILOT_TIMEOUT', 60),
    'model' => env('COPILOT_MODEL'),
];

Si defines tanto COPILOT_URL (cli_url) como COPILOT_CLI_PATH, tiene prioridad el modo TCP.

​

Cambio de modo en tiempo de ejecución

Normalmente se elige automáticamente TCP o stdio según el fichero de configuración. También puedes cambiarlo explícitamente en el código.

use Revolution\Copilot\Facades\Copilot;

// Cambia a modo TCP
$response = Copilot::useTcp(url: 'tcp://127.0.0.1:12345')->run(prompt: 'Hello, TCP mode!');
// Si lo omites, usa el valor del fichero de configuración
$response = Copilot::useTcp()->run(prompt: 'Hello, TCP mode!');

// Cambia a modo stdio
$stdioConfig = [
    'cli_path' => 'copilot',
    'cli_args' => [],
    'cwd' => base_path(),
    'log_level' => 'info',
];
$response = Copilot::useStdio($stdioConfig)->run(prompt: 'Hello, stdio mode!');

// Si lo omites, usa el valor del fichero de configuración
// Si tienes ambos modos configurados, como TCP tiene prioridad, sirve para hacer una sobreescritura temporal
$response = Copilot::useStdio()->run(prompt: 'Hello, stdio mode!');

Según el servidor, es posible que el modo TCP no funcione correctamente. También puedes usarlo de forma mixta: modo TCP para procesos en cola y modo stdio para procesos dentro de peticiones HTTP.

​

Operar en Laravel Forge / Laravel Cloud

​

Laravel Forge

1. Crea un Daemon: crea un Daemon en el panel de Forge.

   Command: copilot --headless --port 12345
   User: forge
   Directory: /home/forge/your-app
   

2. Configura la variable de entorno: añade COPILOT_URL en .env.

3. Reinicia en el despliegue: reinicia el Daemon en el script de despliegue.

Puede no ser necesario en las versiones actuales de Forge.

sudo supervisorctl restart daemon-123456:*

​

Laravel Cloud

Puedes ejecutarlo como proceso en segundo plano con la funcionalidad de workers de Laravel Cloud.

Consulta Uso en Laravel Cloud para más detalles.

​

Consideraciones

​

Seguridad

Siempre que sea posible, haz que el servidor TCP escuche localmente (127.0.0.1). Si vas a exponerlo al exterior, configura el firewall adecuadamente.

​

Reconexión

La versión actual no tiene reconexión automática. Si se pierde la conexión, se lanza una excepción.

​

Comprobar el modo actual

Puedes comprobar en qué modo está el cliente desde el programa.

use Revolution\Copilot\Facades\Copilot;

$client = Copilot::client();

if ($client->isTcpMode()) {
    // Modo TCP
} else {
    // Modo stdio
}

​

Solución de problemas

​

No se puede conectar

1. Comprueba que el servidor Copilot CLI está arrancado

ps aux | grep copilot

2. Comprueba que el puerto es correcto

netstat -an | grep 12345

3. Revisa la configuración del firewall

​

Error de timeout

Aumenta el valor de timeout en config/copilot.php.

'timeout' => 120, // 2 minutos

Consulta la información más reciente en el repositorio de GitHub.