> Pour les agents IA : guide de configuration étape par étape — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), index de la documentation — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# Pour les agents IA

Comment confier l'intégration à un agent IA : un prompt prêt à l'emploi pour n'importe quel outil. Ci-dessous — les adresses lisibles par machine de la documentation et une skill que l'agent installe en une seule commande.

## Prompt pour l'agent

Envoyez ce prompt à votre agent IA. Il configurera l'outil selon le mode d'emploi ci-dessous et vous demandera la clé.

```text
Connecte votre outil à JoinGonka Gateway — l'API de la réseau Gonka compatible OpenAI et Anthropic — en suivant les instructions https://gate.joingonka.ai/docs/agents.md. Je te donnerai la clé moi-même : ne l'enregistre pas dans les fichiers du dépôt et ne modifie pas les variables d'environnement globales. À la fin, teste la connexion par une courte requête et indique le résultat.
```

Voici le mode d'emploi. L'agent le reçoit au format Markdown à l'adresse [/docs/agents.md](https://gate.joingonka.ai/docs/agents.md).

## Règles

- La clé API est créée par un humain — dans l'espace personnel sur [gate.joingonka.ai](https://gate.joingonka.ai/keys). Ne créez ni compte ni clé vous-même : demandez la clé à l'utilisateur.
- Gardez la clé dans la variable d'environnement `JOINGONKA_API_KEY` de votre session de terminal. Ne l'écrivez pas dans des fichiers suivis par git, ne la committez pas et ne l'affichez pas dans le rapport.
- Ne modifiez pas les variables globales `OPENAI_*` et `ANTHROPIC_*` — ni dans le profil du shell, ni au niveau système : d'autres outils de l'utilisateur les lisent. La clé et l'adresse s'écrivent dans la config de l'outil lui-même — c'est ce que fait l'installateur.

## Faits

- URL de base pour les clients OpenAI API : `https://gate.joingonka.ai/v1`
- URL de base pour les clients Anthropic API, sans `/v1` : `https://gate.joingonka.ai`
- La clé se transmet dans l'en-tête `Authorization: Bearer jg-…` ou `x-api-key: jg-…`
- La clé pour interroger les modèles commence par `jg-` ; la clé d'administration `gm-` ne donne pas accès aux modèles.
- Modèle recommandé : `MiniMaxAI/MiniMax-M2.7`
- Liste des modèles disponibles : `GET https://gate.joingonka.ai/v1/models`
- Par clé — jusqu'à 120 requêtes par minute ; au-delà de la limite, la réponse est 429 avec l'en-tête `Retry-After`. Limites et délais d'attente — dans la réponse `GET /v1/capabilities`, champ `limits`.

## Configuration

Trouvez l'outil de l'utilisateur dans le tableau en fin de section. Si la valeur `--tool` existe — configurez avec l'installateur, sinon — manuellement selon le guide.

### Via l'installateur

Une seule commande, sans questions : la clé vient de la variable d'environnement, le modèle est passé en flag. L'installateur écrira la config de l'outil, conservera une copie de l'ancienne et vérifiera la connexion par une requête à la passerelle.

```bash
JOINGONKA_API_KEY=<key> npx -y @joingonka/setup --tool <id> --model MiniMaxAI/MiniMax-M2.7 --non-interactive
```

| Flag | Ce qu'il fait |
| --- | --- |
| `--tool <id>` | Quel outil configurer — valeur issue du tableau des outils. |
| `--model <id>` | Identifiant du modèle : recommandé — `MiniMaxAI/MiniMax-M2.7`, tous les disponibles — `GET /v1/models`. |
| `--non-interactive` | Sans questions : la clé est lue depuis `JOINGONKA_API_KEY`. |
| `--scope local` | Config dans le projet courant, pas dans le répertoire personnel. Uniquement pour Claude Code ; le fichier de config est ajouté à `.gitignore`. |
| `--no-verify` | Ne pas vérifier la connexion après l'écriture de la config. |

| Code de sortie | Signification |
| --- | --- |
| `0` | Terminé : config écrite, requête de vérification réussie. Si la vérification a échoué à cause du réseau ou du solde, l'installateur affiche un avertissement mais sort tout de même avec le code 0 — signalez-le à l'utilisateur. |
| `1` | La configuration a échoué, la cause est dans la sortie : par exemple, valeur `--tool` inconnue, `JOINGONKA_API_KEY` non définie ou clé ne commençant pas par `jg-`. |
| `2` | Config écrite, mais la requête de vérification a échoué : vérifiez la clé et l'identifiant du modèle. |

Si l'outil était lancé, redémarrez-le : la config est lue au démarrage.

### Manuellement

Pour un outil sans installateur, ouvrez son guide (lien dans le tableau ci-dessous) et renseignez trois valeurs :

- adresse de base — `https://gate.joingonka.ai/v1` pour les clients OpenAI API ou `https://gate.joingonka.ai` pour les clients Anthropic API ;
- clé — dans le champ de clé API des réglages de l'outil ;
- modèle — `MiniMaxAI/MiniMax-M2.7` ou un autre parmi `GET /v1/models`.

### Outils et guides

| Outil | `--tool` |
| --- | --- |
| [Cursor](https://joingonka.ai/fr/knowledge/cursor/) | `cursor` |
| [Claude Code](https://joingonka.ai/fr/knowledge/claude-code/) | `claude-code` |
| [OpenClaw](https://joingonka.ai/fr/knowledge/openclaw/) | `openclaw` |
| [OpenCode](https://joingonka.ai/fr/knowledge/opencode/) | `opencode` |
| [Continue](https://joingonka.ai/fr/knowledge/continue-dev/) | `continue` |
| [Cline](https://joingonka.ai/fr/knowledge/cline/) | `cline` |
| [Aider](https://joingonka.ai/fr/knowledge/aider/) | `aider` |
| [LangChain](https://joingonka.ai/fr/knowledge/langchain/) | — |
| [n8n](https://joingonka.ai/fr/knowledge/n8n/) | — |
| [Open WebUI](https://joingonka.ai/fr/knowledge/open-webui/) | — |
| [LibreChat](https://joingonka.ai/fr/knowledge/librechat/) | — |
| [Hermes](https://joingonka.ai/fr/knowledge/hermes/) | `hermes` |
| [Kilo Code](https://joingonka.ai/fr/knowledge/kilo-code/) | `kilo` |
| [Roo Code](https://joingonka.ai/fr/knowledge/roo-code/) | `roo` |
| [LlamaIndex](https://joingonka.ai/fr/knowledge/llamaindex/) | — |
| [PydanticAI](https://joingonka.ai/fr/knowledge/pydantic-ai/) | — |
| [Vercel AI SDK](https://joingonka.ai/fr/knowledge/vercel-ai-sdk/) | — |
| [TanStack AI](https://joingonka.ai/fr/knowledge/tanstack-ai/) | — |
| [ZCode](https://joingonka.ai/fr/knowledge/zcode/) | `zcode` |
| [JetBrains](https://joingonka.ai/fr/knowledge/jetbrains/) | `jetbrains` |
| [Copilot BYOK](https://joingonka.ai/fr/knowledge/copilot-byok/) | `copilot-byok` |
| [Zed](https://joingonka.ai/fr/knowledge/zed/) | `zed` |
| [Pi](https://joingonka.ai/fr/knowledge/pi/) | `pi` |
| [Codex CLI](https://joingonka.ai/fr/knowledge/codex/) | `codex` |
| [DeepSeek Harness](https://joingonka.ai/fr/knowledge/deepseek-harness/) | — |
| [MiniMax Code](https://joingonka.ai/fr/knowledge/minimax-code/) | `minimax-code` |
| [Warp](https://joingonka.ai/fr/knowledge/warp/) | — |
| [Trae](https://joingonka.ai/fr/knowledge/trae/) | — |
| [Cherry Studio](https://joingonka.ai/fr/knowledge/cherry-studio/) | — |
| [omp (Oh My Pi)](https://joingonka.ai/fr/knowledge/omp/) | `omp` |
| [OpenHands](https://joingonka.ai/fr/knowledge/openhands/) | — |
| [Qwen Code](https://joingonka.ai/fr/knowledge/qwen-code/) | `qwen-code` |
| [Goose](https://joingonka.ai/fr/knowledge/goose/) | `goose` |
| [Crush](https://joingonka.ai/fr/knowledge/crush/) | `crush` |
| [Zoo Code](https://joingonka.ai/fr/knowledge/zoo-code/) | `zoo` |
| [Kimi Code](https://joingonka.ai/fr/knowledge/kimi-code/) | `kimi-code` |
| [Factory Droid](https://joingonka.ai/fr/knowledge/factory-droid/) | `droid` |
| [MiMo Code](https://joingonka.ai/fr/knowledge/mimo-code/) | `mimo-code` |

## Vérification

Vérification de la clé — requête de solde : elle ne consomme pas de tokens, la clé est lue depuis `JOINGONKA_API_KEY` :

```bash
curl -s https://gate.joingonka.ai/api/balance \
  -H "Authorization: Bearer $JOINGONKA_API_KEY"
```

Vérification de l'adresse, de la clé et du modèle — une courte requête au modèle :

```bash
curl -s https://gate.joingonka.ai/v1/chat/completions \
  -H "Authorization: Bearer $JOINGONKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MiniMaxAI/MiniMax-M2.7", "messages": [{"role": "user", "content": "Say OK"}], "max_tokens": 32}'
```

Une réponse `200` avec du texte du modèle — la connexion fonctionne. L'installateur fait lui-même cette vérification : après lui, un code de sortie 0 suffit.

## En cas de problème

L'erreur arrive dans le champ `error` du corps de la réponse — avec le type et le texte de la cause.

| Réponse | Que faire |
| --- | --- |
| `401 authentication_error` | Clé refusée. Vérifiez qu'elle est copiée en entier et transmise dans `Authorization: Bearer` ou `x-api-key` ; une nouvelle clé est créée par l'utilisateur. |
| `402 insufficient_funds` | Solde insuffisant. Signalez-le à l'utilisateur : le solde se recharge dans l'espace personnel. |
| `402 child_key_limit_exceeded` | La limite de la clé enfant est atteinte. Il faut une autre clé ou une limite plus élevée — c'est au propriétaire de la clé de décider. |
| `403 forbidden` | C'est une clé d'administration `gm-` : elle ne donne pas accès aux modèles. Il faut une clé `jg-`. |
| `400 invalid_request_error` | Erreur dans la requête. Si le modèle est introuvable, le texte de l'erreur contient la liste des identifiants disponibles — reprenez-en un ou consultez `GET /v1/models`. |
| `404 model_not_found` | Ce modèle n'est pas disponible actuellement — choisissez-en un autre dans `GET /v1/models`. |
| `429` | Trop de requêtes ou réseau occupé. Attendez le nombre de secondes indiqué dans l'en-tête `Retry-After`, puis réessayez. |
| `503 model_unavailable` | Le réseau ne dessert pas ce modèle pour l'instant. Passez au modèle indiqué dans le texte de l'erreur ou à un autre de `GET /v1/models`. |
| `504 upstream_timeout` | Le réseau n'a pas commencé à répondre à temps. Relancez la requête ; pour les réponses longues, activez `stream: true`. |
| `502` | Défaillance côté passerelle ou réseau — la clé n'y est pour rien. Réessayez plus tard ; l'état du réseau est sur la page [État du réseau](https://gate.joingonka.ai/fr/status). |

Tous les codes de réponse et limites — dans la section [Erreurs et limites](https://gate.joingonka.ai/fr/docs/errors).

## Rapport

À la fin, signalez à l'utilisateur :

- quel outil a été configuré et quel fichier de config a été écrit (le chemin est affiché par l'installateur, la copie de l'ancien est à côté) ;
- l'adresse de base et l'identifiant du modèle ;
- le résultat de la vérification : le code de réponse et la réponse du modèle — ou pourquoi la vérification n'a pas pu être effectuée ;
- ce qu'il reste à faire à l'utilisateur lui-même : par exemple, redémarrer l'outil ou recharger son solde.

N'incluez pas la clé dans le rapport.

## Adresses pour les machines

| Adresse | Contenu |
| --- | --- |
| [/llms.txt](https://gate.joingonka.ai/llms.txt) | Index de la documentation pour les modèles de langage. |
| [/llms-full.txt](https://gate.joingonka.ai/llms-full.txt) | Toute la documentation en un seul fichier. |
| `/docs/<page>.md` | Version Markdown d'une page de documentation : la même adresse avec `.md` à la fin ([/docs/models.md](https://gate.joingonka.ai/docs/models.md)), ou une requête de la page avec l'en-tête `Accept: text/markdown`. |
| `GET /v1/capabilities` | Capacités et limites de la passerelle — le champ `limits`. |
| `GET /v1/models` | Modèles actuellement disponibles. |
| `GET /api/pricing` | Tarifs par modèle pour 1M de tokens et commissions. |
| `GET /v1/network-status` | État des modèles et incidents. |

## Compétence pour l'agent

Les instructions peuvent être installées comme compétence (skill) pour votre agent — elles seront alors toujours à portée de main, sans prompt :

```bash
npx skills add https://gate.joingonka.ai
```