Mode TCP

Connectez Laravel Copilot SDK à un serveur Copilot CLI démarré au préalable et partagez-le en production avec un faible overhead.

​

Mode TCP

Par défaut, le SDK démarre un nouveau processus Copilot CLI à chaque requête (mode stdio). Avec le mode TCP, vous vous connectez à un serveur Copilot CLI démarré au préalable.

​

Avantages du mode TCP

• Meilleures performances : pas d’overhead de démarrage de processus
• Partage de ressources : un même serveur CLI peut être partagé par plusieurs processus Laravel
• Gestion de processus : peut être géré comme un processus d’arrière-plan par Laravel Forge / Laravel Cloud
• Compatible déploiement : gère le redémarrage automatique lors des déploiements

​

Utilisation

​

1. Démarrer le serveur Copilot CLI

copilot --headless --port 12345

​

2. Définir la variable d’environnement

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

Cela suffit : le SDK bascule automatiquement du mode stdio au mode TCP.

• tcp:// est optionnel. http:// ou l’absence de schéma fonctionnent aussi.
• Vous pouvez ne préciser que le port. Dans ce cas, l’hôte est automatiquement 127.0.0.1.
• N’indiquer que l’hôte n’est possible que pour 127.0.0.1 et localhost. Le port par défaut est alors 12345.

​

Fichier de configuration

Vous pouvez configurer la connexion TCP dans config/copilot.php.

return [
    // URL cible pour la connexion TCP (si définie, le mode TCP est utilisé)
    'url' => env('COPILOT_URL'),

    // Ce qui suit ne s'applique qu'en mode stdio
    'cli_path' => env('COPILOT_CLI_PATH', 'copilot'),
    'cli_args' => [],
    'cwd' => null,
    'log_level' => env('COPILOT_LOG_LEVEL', 'info'),

    // Commun aux deux modes
    'timeout' => env('COPILOT_TIMEOUT', 60),
    'model' => env('COPILOT_MODEL'),
];

Si COPILOT_URL (cli_url) et COPILOT_CLI_PATH sont définis, le mode TCP est prioritaire.

​

Basculer de mode à l’exécution

Normalement, le fichier de configuration détermine automatiquement mode TCP ou stdio. Vous pouvez aussi basculer explicitement dans le code.

use Revolution\Copilot\Facades\Copilot;

// Basculer en mode TCP
$response = Copilot::useTcp(url: 'tcp://127.0.0.1:12345')->run(prompt: 'Hello, TCP mode!');
// Sans argument, la valeur de la config est utilisée
$response = Copilot::useTcp()->run(prompt: 'Hello, TCP mode!');

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

// Sans argument, la valeur de la config est utilisée
// Si les deux modes sont configurés, TCP est prioritaire : utile pour surcharge temporaire
$response = Copilot::useStdio()->run(prompt: 'Hello, stdio mode!');

Certains serveurs peuvent ne pas fonctionner correctement en mode TCP. Vous pouvez alors alterner : mode TCP pour la file d’attente, mode stdio pendant les requêtes HTTP.

​

Exploitation avec Laravel Forge / Laravel Cloud

​

Laravel Forge

1. Créer un Daemon : dans l’interface Forge, créez un Daemon.

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

2. Configurer les variables d’environnement : ajoutez COPILOT_URL à .env.

3. Redémarrer lors du déploiement : redémarrez le Daemon dans le script de déploiement.

Peut ne pas être nécessaire sur les environnements Forge actuels.

sudo supervisorctl restart daemon-123456:*

​

Laravel Cloud

Utilisez la fonctionnalité de worker de Laravel Cloud pour l’exécuter en arrière-plan.

Voir Utilisation avec Laravel Cloud pour plus de détails.

​

Points d’attention

​

Sécurité

Utilisez autant que possible une liaison locale (127.0.0.1) pour le serveur TCP. Si vous l’exposez, configurez un pare-feu adapté.

​

Reconnexion

La version actuelle n’a pas de mécanisme de reconnexion automatique. En cas de coupure, une exception est levée.

​

Vérifier le mode actuel

Vous pouvez inspecter dans le code le mode utilisé par le client.

use Revolution\Copilot\Facades\Copilot;

$client = Copilot::client();

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

​

Dépannage

​

Impossible de se connecter

1. Vérifiez que le serveur Copilot CLI est démarré

ps aux | grep copilot

2. Vérifiez le bon port

netstat -an | grep 12345

3. Vérifiez le pare-feu

​

Erreurs de timeout

Augmentez la valeur timeout dans config/copilot.php.

'timeout' => 120, // 2 minutes

Pour les dernières informations, consultez le dépôt GitHub.