> Para agentes de IA: guia passo a passo de configuração — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), índice da documentação — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# Para agentes de IA

Como delegar a integração a um agente de IA: prompt pronto para qualquer ferramenta. Abaixo — endereços de documentação legíveis por máquina e uma skill que o agente instala com um único comando.

## Prompt para o agente

Envie este prompt ao seu agente de IA. Ele vai configurar a ferramenta conforme as instruções abaixo e vai pedir a chave para você.

```text
Conecte o sua ferramenta ao JoinGonka Gateway — a API compatível com OpenAI e Anthropic da rede Gonka — seguindo as instruções em https://gate.joingonka.ai/docs/agents.md. A chave eu mesmo vou fornecer: não a salve em arquivos do repositório nem altere variáveis de ambiente globais. No final, teste a conexão com uma requisição curta e informe o resultado.
```

Abaixo estão as instruções. O agente as recebe em Markdown no endereço [/docs/agents.md](https://gate.joingonka.ai/docs/agents.md).

## Regras

- A chave de API é criada por uma pessoa no painel do usuário em [gate.joingonka.ai](https://gate.joingonka.ai/keys). Não cadastre uma conta nem crie chaves por conta própria: peça a chave ao usuário.
- Mantenha a chave na variável de ambiente `JOINGONKA_API_KEY` da sua sessão de terminal. Não a grave em arquivos sob git, não faça commit dela nem a mostre no relatório.
- Não altere as variáveis globais `OPENAI_*` e `ANTHROPIC_*` — nem no perfil do shell nem no sistema: outras ferramentas do usuário as leem. A chave e o endereço são gravados na configuração da própria ferramenta — é o que o instalador faz.

## Fatos

- URL base para clientes da OpenAI API: `https://gate.joingonka.ai/v1`
- URL base para clientes da Anthropic API, sem `/v1`: `https://gate.joingonka.ai`
- A chave é enviada no cabeçalho `Authorization: Bearer jg-…` ou `x-api-key: jg-…`
- A chave para consultar os modelos começa com `jg-`; a chave de gerenciamento `gm-` não dá acesso aos modelos.
- Modelo recomendado: `MiniMaxAI/MiniMax-M2.7`
- Lista de modelos disponíveis: `GET https://gate.joingonka.ai/v1/models`
- Por chave, até 120 requisições por minuto; acima do limite, resposta 429 com o cabeçalho `Retry-After`. Os limites e timeouts estão na resposta `GET /v1/capabilities`, campo `limits`.

## Configuração

Encontre a ferramenta do usuário na tabela no fim da seção. Se houver o valor `--tool`, configure com o instalador; se não houver, faça manualmente seguindo o guia.

### Com o instalador

Um único comando sem perguntas: a chave vem da variável de ambiente e o modelo é passado por flag. O instalador grava a configuração da ferramenta, salva uma cópia da anterior e testa a conexão com uma requisição ao gateway.

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

| Flag | O que faz |
| --- | --- |
| `--tool <id>` | Qual ferramenta configurar — valor da tabela de ferramentas. |
| `--model <id>` | Identificador do modelo: o recomendado é `MiniMaxAI/MiniMax-M2.7`; todos os disponíveis, `GET /v1/models`. |
| `--non-interactive` | Sem perguntas: a chave é obtida de `JOINGONKA_API_KEY`. |
| `--scope local` | Configuração no projeto atual, e não no diretório home. Somente para o Claude Code; o arquivo de configuração é adicionado ao `.gitignore`. |
| `--no-verify` | Não testar a conexão depois de gravar a configuração. |

| Código de saída | O que significa |
| --- | --- |
| `0` | Pronto: configuração gravada e requisição de teste bem-sucedida. Se não foi possível testar por rede ou saldo, o instalador imprime um aviso, mas também sai com código 0 — avise o usuário. |
| `1` | A configuração falhou; o motivo está na saída: por exemplo, um valor desconhecido de `--tool`, `JOINGONKA_API_KEY` não definida ou uma chave que não começa com `jg-`. |
| `2` | A configuração foi gravada, mas a requisição de teste falhou: verifique a chave e o identificador do modelo. |

Se a ferramenta estava aberta, reinicie-a: a configuração é lida na inicialização.

### Manualmente

Para uma ferramenta sem instalador, abra o guia dela (link na tabela abaixo) e defina três valores:

- endereço base — `https://gate.joingonka.ai/v1` para clientes da OpenAI API ou `https://gate.joingonka.ai` para clientes da Anthropic API;
- chave — no campo de chave de API nas configurações da ferramenta;
- modelo — `MiniMaxAI/MiniMax-M2.7` ou outro de `GET /v1/models`.

### Ferramentas e guias

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

## Verificação

Teste da chave — consulta de saldo: não gasta tokens e a chave vem de `JOINGONKA_API_KEY`:

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

Teste do endereço, da chave e do modelo — uma requisição curta ao modelo:

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

Uma resposta `200` com texto do modelo significa que a conexão funciona. O instalador faz esse teste sozinho: depois dele, basta o código de saída 0.

## Se algo der errado

O erro chega no campo `error` do corpo da resposta — com o tipo e o texto do motivo.

| Resposta | O que fazer |
| --- | --- |
| `401 authentication_error` | Chave não aceita. Verifique se ela foi copiada por inteiro e enviada em `Authorization: Bearer` ou `x-api-key`; quem cria uma chave nova é o usuário. |
| `402 insufficient_funds` | Não há saldo. Avise o usuário: o saldo é recarregado no painel do usuário. |
| `402 child_key_limit_exceeded` | O limite da chave secundária foi esgotado. É preciso outra chave ou um limite maior — isso quem decide é o dono da chave. |
| `403 forbidden` | Essa é a chave de gerenciamento `gm-`: ela não dá acesso aos modelos. É preciso uma chave `jg-`. |
| `400 invalid_request_error` | Erro na requisição. Se o modelo não for encontrado, o texto do erro traz a lista de identificadores disponíveis — pegue de lá ou de `GET /v1/models`. |
| `404 model_not_found` | Esse modelo não está disponível agora — escolha outro de `GET /v1/models`. |
| `429` | Requisições demais ou rede ocupada. Espere a quantidade de segundos indicada no cabeçalho `Retry-After` e tente de novo. |
| `503 model_unavailable` | A rede não está atendendo o modelo agora. Troque para o modelo do texto do erro ou para outro de `GET /v1/models`. |
| `504 upstream_timeout` | A rede não começou a responder a tempo. Repita a requisição; para respostas longas, ative `stream: true`. |
| `502` | Falha do lado do gateway ou da rede — a chave não tem nada a ver com isso. Tente de novo mais tarde; o estado da rede está na página [Status da rede](https://gate.joingonka.ai/pt/status). |

Todos os códigos de resposta e limites estão na seção [Erros e limites](https://gate.joingonka.ai/pt/docs/errors).

## Relatório

No fim, informe ao usuário:

- qual ferramenta foi configurada e qual arquivo de configuração foi gravado (o caminho é impresso pelo instalador e uma cópia da anterior fica ao lado);
- o endereço base e o identificador do modelo;
- o resultado da verificação: o código de resposta e a resposta do modelo — ou por que não foi possível verificar;
- o que ainda cabe ao próprio usuário fazer: por exemplo, reiniciar a ferramenta ou adicionar saldo.

Não inclua a chave no relatório.

## Endereços para máquinas

| Endereço | O que tem lá |
| --- | --- |
| [/llms.txt](https://gate.joingonka.ai/llms.txt) | Índice da documentação para modelos de linguagem. |
| [/llms-full.txt](https://gate.joingonka.ai/llms-full.txt) | Toda a documentação em um único arquivo. |
| `/docs/<page>.md` | Versão em Markdown da página de documentação: o mesmo endereço com `.md` no final ([/docs/models.md](https://gate.joingonka.ai/docs/models.md)) ou uma requisição da página com o cabeçalho `Accept: text/markdown`. |
| `GET /v1/capabilities` | Recursos e limites do gateway — o campo `limits`. |
| `GET /v1/models` | Modelos disponíveis no momento. |
| `GET /api/pricing` | Preços por modelo a cada 1M de tokens e taxas. |
| `GET /v1/network-status` | Status dos modelos e incidentes. |

## Habilidade para o agente

As instruções podem ser instaladas como uma habilidade (skill) para o agente — assim ficam sempre à mão, sem precisar de prompt:

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