Per gli agenti AI: guida passo passo alla configurazione — /docs/agents.md, indice della documentazione — /llms.txt.

Per gli agenti AI

Come affidare l'integrazione a un agente AI: prompt pronto per qualsiasi strumento. Di seguito — indirizzi della documentazione leggibili dalle macchine e una skill che l'agente installa con un solo comando.

Invia questo prompt al tuo agente AI. Configurerà lo strumento seguendo le istruzioni qui sotto e ti chiederà la chiave.

Collega il tuo strumento a JoinGonka Gateway, l'API compatibile con OpenAI e Anthropic della rete Gonka, seguendo le istruzioni su https://gate.joingonka.ai/docs/agents.md. La chiave te la fornisco io: non salvarla nei file del repository e non modificare le variabili d'ambiente globali. Alla fine verifica la connessione con una breve richiesta e riporta il risultato.

Qui sotto ci sono le istruzioni. L'agente le riceve in formato Markdown all'indirizzo /docs/agents.md.

• La chiave API è creata da una persona — nella dashboard su gate.joingonka.ai. Non registrare account e non creare chiavi da solo: chiedi la chiave all'utente.
• Tieni la chiave nella variabile d'ambiente JOINGONKA_API_KEY della tua sessione terminale. Non scriverla in file sotto git, non fare commit e non mostrarla nel report.
• Non modificare le variabili globali OPENAI_* e ANTHROPIC_* — né nel profilo della shell né a livello di sistema: vengono lette da altri strumenti dell'utente. La chiave e l'indirizzo vengono scritti nella configurazione dello strumento stesso — è ciò che fa l'installer.

• Base URL per i client OpenAI API: https://gate.joingonka.ai/v1Copia
• Base URL per i client Anthropic API, senza /v1: https://gate.joingonka.aiCopia
• La chiave si passa nell'header Authorization: Bearer jg-… oppure x-api-key: jg-…
• La chiave per le richieste ai modelli inizia con jg-; la chiave di gestione gm- non dà accesso ai modelli.
• Modello consigliato: MiniMaxAI/MiniMax-M2.7Copia
• Elenco dei modelli disponibili: GET https://gate.joingonka.ai/v1/models
• Per chiave — fino a 120 richieste al minuto, oltre il limite risposta 429 con header Retry-After. Limiti e timeout sono nella risposta GET /v1/capabilities, campo limits.

Trova lo strumento dell'utente nella tabella in fondo alla sezione. Se esiste il valore --tool — configura con l'installer, altrimenti — manualmente seguendo la guida.

Con l'installer#

Un solo comando, senza domande: la chiave dalla variabile d'ambiente, il modello tramite flag. L'installer scrive la configurazione dello strumento, conserva una copia della precedente e verifica la connessione con una richiesta al gateway.

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

Se lo strumento era in esecuzione, riavvialo: la configurazione viene letta all'avvio.

Manualmente#

Per uno strumento senza installer, apri la sua guida (link nella tabella qui sotto) e imposta tre valori:

• indirizzo base — https://gate.joingonka.ai/v1 per i client OpenAI API o https://gate.joingonka.ai per i client Anthropic API;
• chiave — nel campo della chiave API nelle impostazioni dello strumento;
• modello — MiniMaxAI/MiniMax-M2.7 o un altro tra GET /v1/models.

Strumenti e guide#

Verifica della chiave — richiesta del saldo: non consuma token, la chiave viene presa da JOINGONKA_API_KEY:

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

Verifica di indirizzo, chiave e modello — una breve richiesta al modello:

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}'

Risposta 200 con il testo del modello — la connessione funziona. L'installer esegue questa verifica da solo: dopo di lui basta un codice di uscita 0.

L'errore arriva nel campo error del corpo della risposta — con tipo e testo del motivo.

Tutti i codici di risposta e i limiti sono nella sezione Errori e limiti.

Alla fine comunica all'utente:

• quale strumento è stato configurato e quale file di configurazione è stato scritto (il percorso lo stampa l'installer, la copia del precedente è accanto);
• indirizzo di base e identificatore del modello;
• esito della verifica: codice di risposta e risposta del modello — oppure perché non è stato possibile verificare;
• cosa resta da fare all'utente: ad esempio riavviare lo strumento o ricaricare il saldo.

Non includere la chiave nel report.

Le istruzioni possono essere installate nell'agente come skill — così restano sempre a portata di mano, anche senza prompt:

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