> Para sa mga AI agent: step-by-step na gabay sa setup — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), index ng dokumentasyon — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# Para sa mga AI agent

Paano ipagkatiwala ang integrasyon sa isang AI agent: handa nang prompt para sa anumang tool. Sa ibaba — mga machine-readable na address ng dokumentasyon at skill na ini-install ng agent sa isang command lang.

## Prompt para sa agent

Ipadala ang prompt na ito sa iyong AI agent. Ise-set up nito ang tool ayon sa instruksyon sa ibaba, at hihingin sa iyo ang key.

```text
Ikonekta ang sariling tool sa JoinGonka Gateway — ang API ng Gonka network na compatible sa OpenAI at Anthropic — ayon sa instruksyon sa https://gate.joingonka.ai/docs/agents.md. Ibibigay ko mismo ang key: huwag itong i-save sa mga file ng repository at huwag baguhin ang global environment variables. Sa dulo, iche-check ang koneksyon gamit ang maikling request at ipaalam ang resulta.
```

Nasa ibaba ang instruksyon mismo. Natatanggap ito ng agent bilang Markdown sa address na [/docs/agents.md](https://gate.joingonka.ai/docs/agents.md).

## Mga panuntunan

- Ang API key ay ginagawa ng tao — sa personal na cabinet sa [gate.joingonka.ai](https://gate.joingonka.ai/keys). Huwag magrehistro ng account at huwag gumawa ng mga key nang mag-isa: hingin ang key sa user.
- Itago ang key sa environment variable na `JOINGONKA_API_KEY` ng iyong terminal session. Huwag itong isulat sa mga file na nasa ilalim ng git, huwag i-commit at huwag ilabas sa report.
- Huwag baguhin ang mga global variable na `OPENAI_*` at `ANTHROPIC_*` — kahit sa profile ng shell, kahit sa system: binabasa ito ng ibang mga tool ng user. Ang key at address ay isinusulat sa config ng tool mismo — ganoon ang ginagawa ng installer.

## Mga katotohanan

- Base URL para sa mga OpenAI API client: `https://gate.joingonka.ai/v1`
- Base URL para sa mga Anthropic API client, walang `/v1`: `https://gate.joingonka.ai`
- Ipinapasa ang key sa header na `Authorization: Bearer jg-…` o `x-api-key: jg-…`
- Ang key para sa mga request sa mga modelo ay nagsisimula sa `jg-`; ang management key na `gm-` ay hindi nagpapapasok sa mga modelo.
- Inirerekomendang modelo: `MiniMaxAI/MiniMax-M2.7`
- Listahan ng available na modelo: `GET https://gate.joingonka.ai/v1/models`
- Kada key — hanggang 120 request kada minuto, lampas sa limit — sagot na 429 na may header na `Retry-After`. Mga limit at timeout — sa sagot na `GET /v1/capabilities`, field na `limits`.

## Pag-set up

Hanapin ang tool ng user sa talahanayan sa dulo ng seksyon. Kung may value na `--tool` — i-set up gamit ang installer, kung wala — manu-manong ayon sa guide.

### Sa pamamagitan ng installer

Isang command na walang tanong: key — mula sa environment variable, modelo — sa pamamagitan ng flag. Isusulat ng installer ang config ng tool, magse-save ng kopya ng dati at susuriin ang koneksyon gamit ang request sa gateway.

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

| Flag | Ano ang ginagawa |
| --- | --- |
| `--tool <id>` | Aling tool ang i-set up — value mula sa talahanayan ng mga tool. |
| `--model <id>` | Model identifier: inirerekomenda — `MiniMaxAI/MiniMax-M2.7`, lahat ng available — `GET /v1/models`. |
| `--non-interactive` | Walang tanong: ang key ay kinukuha mula sa `JOINGONKA_API_KEY`. |
| `--scope local` | Config sa kasalukuyang proyekto, hindi sa home directory. Para sa Claude Code lamang; ang config file ay idinadagdag sa `.gitignore`. |
| `--no-verify` | Huwag suriin ang koneksyon pagkatapos isulat ang config. |

| Exit code | Ano ang ibig sabihin |
| --- | --- |
| `0` | Tapos: naisulat ang config, pumasa ang verification request. Kung hindi nagawang suriin dahil sa network o balanse, nagpi-print ang installer ng babala, ngunit lumalabas din na may code na 0 — ipaalam ito sa user. |
| `1` | Nabigo ang pag-set up, ang dahilan ay nasa output: halimbawa, hindi kilalang value na `--tool`, hindi nakatakda ang `JOINGONKA_API_KEY` o ang key ay hindi nagsisimula sa `jg-`. |
| `2` | Naisulat ang config, ngunit hindi pumasa ang verification request: suriin ang key at model identifier. |

Kung ang tool ay tumatakbo, i-restart ito: binabasa ang config sa pagsisimula.

### Manu-mano

Para sa tool na walang installer, buksan ang guide nito (link sa talahanayan sa ibaba) at itakda ang tatlong value:

- base address — `https://gate.joingonka.ai/v1` para sa mga OpenAI API client o `https://gate.joingonka.ai` para sa mga Anthropic API client;
- key — sa field ng API key sa settings ng tool;
- modelo — `MiniMaxAI/MiniMax-M2.7` o iba pa mula sa `GET /v1/models`.

### Mga tool at guide

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

## Verification

Pag-verify ng key — request sa balanse: hindi ito gumagastos ng token, ang key ay kinukuha mula sa `JOINGONKA_API_KEY`:

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

Pag-verify ng address, key at modelo — maikling request sa 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}'
```

Sagot na `200` na may teksto ng modelo — gumagana ang koneksyon. Ginagawa ng installer ang ganitong verification mismo: pagkatapos nito, sapat na ang exit code na 0.

## Kung may hindi tama

Dumarating ang error sa field na `error` ng katawan ng sagot — may uri at teksto ng dahilan.

| Sagot | Ano ang gawin |
| --- | --- |
| `401 authentication_error` | Hindi tinanggap ang key. Suriin na ito ay kopya nang buo at ipinasa sa `Authorization: Bearer` o `x-api-key`; ang bagong key ay ginagawa ng user. |
| `402 insufficient_funds` | Walang pondo sa balanse. Ipaalam sa user: ang balanse ay dinadagdagan sa personal na cabinet. |
| `402 child_key_limit_exceeded` | Naubos ang limit ng child key. Kailangan ng ibang key o mas malaking limit — ito ang desisyon ng may-ari ng key. |
| `403 forbidden` | Ito ang management key na `gm-`: hindi ito nagpapapasok sa mga modelo. Kailangan ang key na `jg-`. |
| `400 invalid_request_error` | May error sa request. Kung hindi natagpuan ang modelo, nasa teksto ng error ang listahan ng mga available na identifier — kunin mula doon o sa `GET /v1/models`. |
| `404 model_not_found` | Wala ang modelong iyon sa ngayon — pumili ng iba mula sa `GET /v1/models`. |
| `429` | Masyadong maraming request o abala ang network. Maghintay ng ilang segundo ayon sa nakasaad sa header na `Retry-After`, at ulitin. |
| `503 model_unavailable` | Hindi naglilingkod ang network sa modelo sa ngayon. Lumipat sa modelong nasa teksto ng error o sa iba pa mula sa `GET /v1/models`. |
| `504 upstream_timeout` | Hindi nagsimulang tumugon ang network nang nasa oras. Ulitin ang request; para sa mahahabang sagot, i-on ang `stream: true`. |
| `502` | May pagkabigo sa panig ng gateway o network — walang kinalaman ang key. Ulitin mamaya; estado ng network — sa pahinang [Status ng network](https://gate.joingonka.ai/tl/status). |

Lahat ng response code at limit — sa seksyong [Mga Error at Limit](https://gate.joingonka.ai/tl/docs/errors).

## Ulat

Sa dulo, ipaalam sa user:

- aling tool ang na-set up at aling config file ang naisulat (ang path ay ipi-print ng installer, ang kopya ng dati ay katabi);
- base address at model ID;
- resulta ng pagsusuri: response code at sagot ng modelo — o bakit hindi ito masusuri;
- ano pa ang dapat gawin ng user mismo: halimbawa, i-restart ang tool o mag-load ng balanse.

Huwag isama ang key sa report.

## Mga machine address

| Address | Ano ang nasa loob |
| --- | --- |
| [/llms.txt](https://gate.joingonka.ai/llms.txt) | Index ng dokumentasyon para sa mga language model. |
| [/llms-full.txt](https://gate.joingonka.ai/llms-full.txt) | Buong dokumentasyon sa isang file. |
| `/docs/<page>.md` | Markdown na bersyon ng page ng dokumentasyon: parehong address na may `.md` sa dulo ([/docs/models.md](https://gate.joingonka.ai/docs/models.md)) o request ng page na may header na `Accept: text/markdown`. |
| `GET /v1/capabilities` | Mga kakayahan ng gateway at mga limit nito — field na `limits`. |
| `GET /v1/models` | Mga modelong available ngayon. |
| `GET /api/pricing` | Presyo kada modelo bawat 1M token at mga komisyon. |
| `GET /v1/network-status` | Status ng mga modelo at mga insidente. |

## Skill para sa agent

Maaaring i-install ang instruksyon sa agent bilang skill — sa gayon, lagi itong nasa kamay nito kahit walang prompt:

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