Prime Agent Ollama 2026 : résoudre les connexions

Le modèle est visible dans Prime Agent, mais une tâche de programmation reste bloquée ou renvoie une erreur.

La solution la plus rapide consiste à ne pas réinstaller immédiatement : isolez successivement le service Ollama, l’adresse réseau, models.json, les paramètres de compatibilité API et les capacités du modèle.

Dernière mise à jour

Dernière mise à jour le 11 août 2026. Les informations ont été vérifiées à partir de la documentation officielle de Prime Agent, de sa page Custom Models et des documentations officielles d’Ollama sur l’API OpenAI-compatible, le dépannage et la FAQ. Les champs de compatibilité peuvent évoluer rapidement avec les versions du projet.

Cet article s’adresse à trois profils :

• les développeurs qui ne voient pas leur modèle Ollama dans Prime Agent et veulent confirmer que la configuration est réellement chargée ;
• les ingénieurs IA qui obtiennent une réponse simple, mais rencontrent ensuite une erreur de rôle, d’outil, de flux ou de paramètre ;
• les équipes qui souhaitent exécuter Prime Agent à distance ou laisser une tâche active après la fermeture du terminal.

Le bon diagnostic commence par cinq couches séparées

Un cas revient souvent : vous sélectionnez un modèle Ollama dans Prime Agent, la conversation courte fonctionne, puis une tâche comme « lire plusieurs fichiers, modifier le code et lancer les tests » s’arrête après quelques échanges. Ce scénario ne prouve ni un bogue de Prime Agent ni une incompatibilité générale d’Ollama. Il peut révéler une faiblesse du modèle, un paramètre refusé, une mémoire insuffisante ou un service qui perd son état.

Le diagnostic doit suivre cette séquence :

1. Service : Ollama fonctionne-t-il et le modèle est-il installé ?
2. Adresse : Prime Agent atteint-il le bon hôte et le bon port ?
3. Configuration : le fichier models.json est-il valide, lu au bon endroit et rechargé ?
4. Interface : l’API accepte-t-elle les rôles, options et flux envoyés par Prime Agent ?
5. Capacité : le modèle sait-il suivre des instructions, utiliser les outils et maintenir une tâche longue ?

Cette séparation évite deux coûts cachés. D’abord, vous pouvez perdre du temps à modifier la configuration alors que le modèle n’a jamais été téléchargé. Ensuite, vous pouvez changer de modèle alors que le vrai problème vient d’un baseUrl inaccessible depuis un conteneur ou une machine distante.

Prime Agent documente l’usage de ~/.prime/agent/models.json pour ajouter des fournisseurs et modèles personnalisés, notamment Ollama, vLLM et d’autres serveurs compatibles. Le dépôt indique également que les sessions et certains processus peuvent continuer après une déconnexion du terminal, mais cela ne garantit pas que le serveur Ollama ou le modèle dispose de ressources suffisantes. (documentation Prime Agent)

Première étape : prouver qu’Ollama fonctionne sans Prime Agent

Commencez par retirer Prime Agent de l’équation. Sur la machine où Ollama est censé tourner, vérifiez la présence du service et du modèle :

ollama list
ollama ps
curl http://localhost:11434/api/tags

La commande ollama list doit afficher l’identifiant exact du modèle, avec sa balise éventuelle. Si votre configuration mentionne qwen2.5-coder:7b alors que la machine possède qwen2.5-coder:latest, ces deux identifiants ne doivent pas être considérés comme interchangeables dans votre diagnostic.

L’API locale d’Ollama utilise par défaut l’adresse http://localhost:11434/api. Le port 11434 n’est donc pas un choix arbitraire à remplacer par celui d’un autre service. Le point de contrôle utile est la réponse réelle de l’API, pas seulement l’icône de l’application ou la présence du processus. (API officielle d’Ollama)

Testez ensuite une requête minimale :

curl http://localhost:11434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<MODELE_OLLAMA>",
    "messages": [
      {"role": "user", "content": "Répondez uniquement par OK."}
    ],
    "stream": false
  }'

Résultat attendu : un objet JSON contenant une réponse du modèle et aucune erreur de connexion. Si vous obtenez connection refused, le service ne répond pas sur cette adresse. Si vous obtenez une erreur indiquant que le modèle est introuvable, le problème se situe avant Prime Agent. Si la réponse arrive, conservez-la comme preuve de référence.

Pourquoi Prime Agent ne voit-il pas le modèle Ollama ?
Les causes les plus fréquentes sont distinctes : le service n’est pas lancé, le modèle n’est pas installé, le nom indiqué ne correspond pas à celui retourné par ollama list, ou le fichier de configuration n’est pas celui que Prime Agent lit. Ne corrigez pas ces quatre situations avec la même action.

Pour les modèles utilisant l’interface OpenAI-compatible, vérifiez aussi la liste exposée par Ollama :

curl http://localhost:11434/v1/models

Ollama documente cette route ainsi que /v1/chat/completions. La clé API peut être une valeur factice pour un serveur local, car Ollama l’ignore dans ce mode. (API OpenAI-compatible d’Ollama)

Deuxième étape : vérifier models.json et son rechargement

Le fichier attendu par Prime Agent est :

~/.prime/agent/models.json

Vérifiez le chemin et la syntaxe avant de toucher aux paramètres :

ls -l ~/.prime/agent/models.json
python -m json.tool ~/.prime/agent/models.json

Le second contrôle doit se terminer sans message d’erreur. Une virgule finale, une chaîne non fermée ou un mauvais niveau d’imbrication suffit à empêcher le chargement.

Une configuration minimale documentée par Prime Agent ressemble à ceci :

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        { "id": "<MODELE_OLLAMA>" }
      ]
    }
  }
}

Le point important est la répartition des responsabilités :

• providers.ollama décrit le serveur, son adresse et l’interface API ;
• models déclare les modèles disponibles chez ce fournisseur ;
• id doit correspondre au nom réellement accepté par Ollama ;
• compat ajuste le comportement d’envoi pour un serveur OpenAI-compatible partiel.

Prime Agent indique que la configuration est relue lorsque vous ouvrez le sélecteur /model. La documentation précise qu’un redémarrage complet n’est donc pas nécessaire pour chaque modification, mais il reste préférable de fermer une session confuse après plusieurs essais et de vérifier le résultat dans un nouveau contexte.

Après modification, utilisez :

/model

ou, selon votre installation :

prime-agent model list

Si le fournisseur apparaît mais pas le modèle, contrôlez d’abord models[].id. Si ni le fournisseur ni le modèle ne s’affichent, revenez à la syntaxe JSON et à l’emplacement du fichier. Si le modèle s’affiche mais échoue à la sélection, passez à la couche réseau.

Troisième étape : remplir correctement baseUrl selon l’environnement

Pour une installation locale sur la même machine, utilisez généralement :

http://localhost:11434/v1

Ne mettez pas directement /v1/chat/completions dans baseUrl si Prime Agent construit ensuite la route complète. La configuration doit pointer vers la racine compatible du fournisseur, pas vers une requête finale.

Comment choisir baseUrl lorsque Prime Agent et Ollama ne sont pas sur la même machine ?
Vous devez remplacer localhost par une adresse réellement accessible depuis le processus Prime Agent. localhost désigne la machine ou l’espace réseau du processus qui effectue la requête. Dans un conteneur, il désigne souvent le conteneur lui-même ; sur une machine distante, il désigne cette machine distante, pas votre Mac de développement.

Procédez dans cet ordre :

1. Depuis l’environnement Prime Agent, testez curl <BASE_URL>/models.
2. Vérifiez que le nom DNS ou l’adresse IP se résout correctement.
3. Contrôlez que le port est ouvert uniquement sur le réseau nécessaire.
4. Consultez les journaux d’Ollama au moment exact de la requête.
5. Comparez l’adresse écoutée par Ollama avec l’adresse utilisée par Prime Agent.

Ollama se lie par défaut à 127.0.0.1 sur le port 11434. Pour une exposition réseau, sa documentation indique qu’il faut modifier OLLAMA_HOST. Cette ouverture ne doit pas être faite sans contrôle d’accès ou réseau privé : un serveur Ollama exposé directement peut être utilisé pour lancer des requêtes et consommer les ressources de la machine. (FAQ officielle d’Ollama)

Un test de connectivité ne doit pas seulement répondre « le port est ouvert ». L’endpoint /v1/models doit renvoyer une réponse cohérente et l’endpoint de conversation doit accepter le modèle déclaré. Un code HTTP réussi sur une route de santé ne prouve pas que la route de génération, l’identifiant du modèle ou le streaming fonctionnent.

Quatrième étape : corriger les paramètres de compatibilité un par un

Lorsque le modèle apparaît et que la connexion est établie, l’erreur peut venir du contenu exact de la requête. Prime Agent documente plusieurs options de compatibilité OpenAI, dont :

• supportsDeveloperRole ;
• supportsReasoningEffort ;
• supportsUsageInStreaming ;
• maxTokensField ;
• requiresToolResultName ;
• supportsStrictMode.

Ne désactivez pas tous les paramètres en même temps. Vous perdriez l’information qui permet d’identifier le champ rejeté.

Commencez par la configuration la plus conservatrice :

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [
        {
          "id": "<MODELE_OLLAMA>",
          "reasoning": false
        }
      ]
    }
  }
}

Si la requête fonctionne, réactivez ensuite un seul comportement à la fois. Cette méthode est importante, car un modèle peut accepter le format de conversation tout en refusant un paramètre de raisonnement ou un champ associé au streaming.

La documentation actuelle de Prime Agent distingue bien la compatibilité au niveau du fournisseur et celle au niveau du modèle. Placez une règle au niveau du fournisseur lorsqu’elle s’applique à tous les modèles Ollama ; utilisez une surcharge au niveau du modèle lorsqu’un seul identifiant se comporte différemment. Les champs et leur comportement doivent être vérifiés dans la version de la documentation utilisée au moment du diagnostic.

Ollama annonce la prise en charge de plusieurs fonctions dans son interface OpenAI-compatible, notamment les conversations, le streaming, les outils et le contrôle du raisonnement. Cette liste décrit ce que l’API sait traiter ; elle ne signifie pas que chaque modèle local suivra correctement un protocole d’agent complexe ou produira des appels d’outils fiables.

Cinquième étape : séparer conversation, outils et capacité de programmation

Ollama répond aux questions, mais Prime Agent ne termine pas le travail de programmation : que faire ?
Ne concluez pas immédiatement à un problème de connexion. Utilisez une progression en trois jalons :

1. demandez à Prime Agent de lire un fichier court sans le modifier ;
2. demandez une modification limitée et vérifiable sur un fichier de test ;
3. demandez l’exécution d’une commande de test sans enchaîner plusieurs sous-tâches.

À chaque jalon, contrôlez quatre éléments :

• le fichier réellement lu ;
• le contenu précis de la modification ;
• la commande effectivement exécutée ;
• le résultat retourné par le système, et non celui simplement annoncé par le modèle.

Un modèle peut produire une réponse fluide mais inventer l’exécution d’une commande, oublier un outil ou perdre le fil après plusieurs étapes. Ce n’est pas nécessairement un défaut de Prime Agent ou d’Ollama. Cela peut venir du réglage du modèle, de son entraînement au code, de sa capacité à suivre les appels d’outils ou de la taille du contexte disponible.

La documentation de Prime Agent indique que l’agent peut exécuter du code Python et des commandes avec les permissions de l’utilisateur. Utilisez donc un dépôt de test, un clone jetable ou un espace de travail restaurable avant d’autoriser des essais automatisés.

Le choix du modèle doit correspondre à la tâche :

• conversation, résumé et génération de texte : un modèle généraliste peut suffire ;
• correction de code et modifications ciblées : privilégiez un modèle connu pour le suivi d’instructions et la programmation ;
• appels d’outils répétés et travail long : validez d’abord la stabilité du modèle sur une séquence courte ;
• audio, vidéo ou design assisté par script : vérifiez également que l’environnement local possède les bibliothèques, codecs, fichiers et permissions nécessaires ; le modèle seul ne fournit pas ces dépendances.

Ne simulez jamais une réussite en demandant au modèle d’écrire « commande exécutée avec succès » sans vérifier la sortie du terminal. Une fausse validation rend le diagnostic plus difficile et peut endommager le dépôt.

Sixième étape : traiter les blocages, coupures et épuisements de ressources

Pourquoi Prime Agent se bloque-t-il ou coupe-t-il le flux avec un modèle local ?
Examinez séparément le chargement du modèle, la croissance du contexte, les tâches parallèles et la mémoire disponible.

Commencez par surveiller Ollama :

ollama ps

La commande permet de voir si le modèle est chargé sur le processeur, le processeur graphique ou un mélange des deux. Ollama indique aussi que les modèles sont conservés en mémoire pendant environ cinq minutes par défaut avant déchargement, sauf réglage différent. Une première requête lente peut donc correspondre au chargement du modèle plutôt qu’à une panne réseau.

Vérifiez ensuite les causes suivantes :

• Modèle trop lourd : le système commence à utiliser la mémoire générale ou le stockage, ce qui allonge les délais et peut provoquer une instabilité ;
• Contexte en croissance : l’historique, les fichiers lus et les sorties d’outils augmentent la requête jusqu’à dépasser les limites pratiques du modèle ;
• Concurrence : plusieurs sous-agents ou requêtes simultanées saturent le serveur local ;
• Streaming : le flux s’interrompt alors que la génération continue, ou bien le serveur ne gère pas le champ d’utilisation envoyé ;
• Session distante : le terminal est fermé, le processus d’agent n’est pas relancé, ou Ollama s’arrête avec la session utilisateur.

Ollama documente une taille de contexte par défaut de 4 096 jetons dans sa FAQ, avec la possibilité de la modifier par configuration. Ne comparez pas cette valeur à celle déclarée dans models.json sans vérifier le comportement réel du modèle et du serveur. Une valeur déclarée dans Prime Agent décrit les capacités annoncées au client ; elle ne force pas nécessairement Ollama à allouer la même fenêtre.

Pour une tâche longue, notez l’ordre des événements :

1. heure de lancement ;
2. moment où le modèle est chargé ;
3. dernière sortie reçue ;
4. évolution de la mémoire et du processeur ;
5. présence ou absence d’une requête dans les journaux Ollama ;
6. état de la session Prime Agent après la coupure.

Prime Agent fournit des commandes de diagnostic et de gestion d’état, notamment prime-agent status, prime-agent doctor, prime-agent agents et prime-agent attach. Servez-vous-en pour déterminer si l’agent est arrêté, actif en arrière-plan ou simplement détaché du terminal.

Outil de décision : conserver le modèle ou changer d’environnement

Utilisez ce tableau après les tests précédents. Il ne remplace pas les journaux, mais évite de prendre une décision coûteuse sur la base d’un seul symptôme.

Cette grille vous permet de distinguer trois décisions : poursuivre la correction de configuration, changer de modèle ou déplacer l’exécution. Un modèle local reste intéressant pour la confidentialité, les essais rapides et les flux créatifs contrôlés, mais il n’est pas automatiquement le meilleur choix pour une tâche de programmation qui doit continuer sans surveillance.

Validation finale avant un usage réel

Considérez l’intégration comme acceptée uniquement si les jalons suivants sont validés dans l’ordre :

1. le modèle est visible dans /model ;
2. ollama list et l’identifiant de models.json correspondent ;
3. /v1/models répond depuis l’environnement où tourne Prime Agent ;
4. une conversation minimale renvoie une réponse complète ;
5. un fichier de test est lu correctement ;
6. une modification limitée est réellement écrite ;
7. une commande de test renvoie une sortie vérifiable ;
8. une tâche plus longue peut être interrompue puis reprise ;
9. la fermeture du terminal ne détruit pas la session attendue ;
10. les journaux permettent de reconstruire l’échec.

Conservez avec chaque résultat la date, la version de Prime Agent, la version d’Ollama, le nom exact du modèle, le contenu utile de models.json, l’environnement d’exécution, le type de connexion et les journaux associés. Masquez les clés et les informations sensibles avec des valeurs comme <CLE_API> ou <ADRESSE_INTERNE>.

Si le problème persiste seulement avec un modèle précis, formulez-le comme une limite à reproduire, pas comme un bogue confirmé. Si plusieurs modèles échouent de la même manière après validation du service et de l’API, l’investigation doit remonter vers la configuration Prime Agent, le protocole ou l’environnement réseau.

Après cette procédure, votre solution actuelle peut rester pertinente pour des essais locaux, des prototypes confidentiels ou des workflows audio, vidéo et design nécessitant un contrôle direct des fichiers. En revanche, un poste personnel présente souvent trois limites pour les longues exécutions : ressources variables, terminal interrompu et accès distant difficile à maintenir. Un serveur improvisé ajoute parfois une quatrième difficulté avec l’exposition réseau d’Ollama et l’absence de séparation claire entre utilisateurs.

Si vos tests montrent que le blocage vient surtout de la mémoire, de la continuité de session ou d’un environnement difficile à maintenir, comparez alors votre installation actuelle avec une machine indépendante et persistante. Pour un besoin temporaire, une solution de location de Mac à distance proposée par Kvmkit peut éviter de modifier votre poste principal et fournir un espace séparé pour Prime Agent, Ollama et vos dépôts de test. Ce n’est pas le meilleur choix pour une charge lourde permanente nécessitant des interfaces physiques ou un contrôle matériel direct, mais c’est une option plus cohérente lorsque vous cherchez surtout une session stable, accessible à distance et limitée dans le temps.

Pour replacer cette décision dans votre architecture, vous pouvez également consulter la présentation de Kvmkit et de son fonctionnement avant de choisir entre poste local, serveur indépendant et Mac loué.