Para agentes de IA: guia passo a passo de configuração — /docs/agents.md, índice da documentação — /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.

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ê.

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.

• A chave de API é criada por uma pessoa no painel do usuário em gate.joingonka.ai. 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.

• URL base para clientes da OpenAI API: https://gate.joingonka.ai/v1Copiar
• URL base para clientes da Anthropic API, sem /v1: https://gate.joingonka.aiCopiar
• 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.7Copiar
• 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.

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.

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

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#

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

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:

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.

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

Todos os códigos de resposta e limites estão na seção Erros e limites.

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.

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

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