> Yapay zeka ajanları için: adım adım kurulum kılavuzu — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), dokümantasyon dizini — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# Yapay zeka ajanları için

Entegrasyonu bir yapay zeka ajanına nasıl devredersiniz: her araç için hazır bir prompt. Aşağıda — dokümantasyonun makine tarafından okunabilir adresleri ve ajanın tek komutla kurduğu bir skill.

## Ajan için prompt

Bu promptu yapay zeka ajanınıza gönderin. Aşağıdaki kılavuza göre aracı yapılandırır ve anahtarı sizden ister.

```text
kendi aracın aracını Gonka ağının OpenAI ve Anthropic uyumlu API'si olan JoinGonka Gateway'e https://gate.joingonka.ai/docs/agents.md adresindeki talimata göre bağla. Anahtarı ben vereceğim: depo dosyalarına kaydetme ve genel ortam değişkenlerini değiştirme. Sonunda kısa bir istekle bağlantıyı doğrula ve sonucu bildir.
```

Aşağıda kılavuzun kendisi var. Ajan bunu [/docs/agents.md](https://gate.joingonka.ai/docs/agents.md) adresinden Markdown olarak alır.

## Kurallar

- API anahtarını bir insan oluşturur — [gate.joingonka.ai](https://gate.joingonka.ai/keys) adresindeki kişisel panelde. Hesap açmayın ve kendiniz anahtar oluşturmayın: kullanıcıdan anahtar isteyin.
- Anahtarı terminal oturumunuzun `JOINGONKA_API_KEY` ortam değişkeninde tutun. Git altındaki dosyalara yazmayın, commit etmeyin ve raporda göstermeyin.
- `OPENAI_*` ve `ANTHROPIC_*` global değişkenlerini değiştirmeyin — ne kabuk profilinde ne de sistemde: kullanıcının diğer araçları bunları okur. Anahtar ve adres aracın kendi yapılandırmasına yazılır — kurulum sihirbazı da böyle yapar.

## Bilgiler

- OpenAI API istemcileri için temel adres: `https://gate.joingonka.ai/v1`
- Anthropic API istemcileri için temel adres, `/v1` olmadan: `https://gate.joingonka.ai`
- Anahtar `Authorization: Bearer jg-…` veya `x-api-key: jg-…` başlığında iletilir
- Model istekleri için anahtar `jg-` ile başlar; yönetim anahtarı `gm-` modellere erişemez.
- Önerilen model: `MiniMaxAI/MiniMax-M2.7`
- Kullanılabilir modellerin listesi: `GET https://gate.joingonka.ai/v1/models`
- Anahtar başına — dakikada 120 isteğe kadar, limit aşılırsa — `Retry-After` başlıklı 429 yanıtı. Limitler ve zaman aşımları — `GET /v1/capabilities` yanıtında, `limits` alanında.

## Yapılandırma

Kullanıcının aracını bölümün sonundaki tabloda bulun. `--tool` değeri varsa — kurulum sihirbazıyla yapılandırın, yoksa — kılavuza göre elle.

### Kurulum sihirbazıyla

Sorular sormayan tek komut: anahtar ortam değişkeninden, model flag ile. Kurulum sihirbazı aracın yapılandırmasını yazar, öncekinin kopyasını saklar ve ağ geçidine bir istekle bağlantıyı test eder.

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

| Flag | Ne yapar |
| --- | --- |
| `--tool <id>` | Hangi aracın yapılandırılacağı — araç tablosundaki değer. |
| `--model <id>` | Model kimliği: önerilen — `MiniMaxAI/MiniMax-M2.7`, tüm mevcut olanlar — `GET /v1/models`. |
| `--non-interactive` | Soru sormadan: anahtar `JOINGONKA_API_KEY` değişkeninden alınır. |
| `--scope local` | Yapılandırma ev dizininde değil, geçerli projede. Yalnızca Claude Code için; yapılandırma dosyası `.gitignore` dosyasına eklenir. |
| `--no-verify` | Yapılandırma yazıldıktan sonra bağlantıyı test etme. |

| Çıkış kodu | Ne anlama gelir |
| --- | --- |
| `0` | Tamam: yapılandırma yazıldı, test isteği başarılı. Test ağ veya bakiye nedeniyle yapılamadıysa kurulum sihirbazı bir uyarı yazdırır ama yine de 0 koduyla çıkar — kullanıcıya bunu bildirin. |
| `1` | Yapılandırma başarısız oldu, nedeni çıktıda: örneğin bilinmeyen bir `--tool` değeri, `JOINGONKA_API_KEY` ayarlanmamış veya anahtar `jg-` ile başlamıyor. |
| `2` | Yapılandırma yazıldı ama test isteği geçmedi: anahtarı ve model kimliğini kontrol edin. |

Araç çalışıyorduysa yeniden başlatın: yapılandırma başlangıçta okunur.

### Elle

Kurulum sihirbazı olmayan bir araç için kılavuzunu açın (bağlantı aşağıdaki tabloda) ve üç değeri ayarlayın:

- temel adres — OpenAI API istemcileri için `https://gate.joingonka.ai/v1` veya Anthropic API istemcileri için `https://gate.joingonka.ai`;
- anahtar — araç ayarlarındaki API anahtarı alanına;
- model — `MiniMaxAI/MiniMax-M2.7` veya `GET /v1/models` içinden başka biri.

### Araçlar ve kılavuzlar

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

## Doğrulama

Anahtar doğrulama — bakiye sorgusu: token harcamaz, anahtar `JOINGONKA_API_KEY` değişkeninden alınır:

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

Adres, anahtar ve model doğrulama — modele kısa bir istek:

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

Model metniyle `200` yanıtı — bağlantı çalışıyor. Kurulum sihirbazı böyle bir testi kendisi yapar: sonrasında 0 çıkış kodu yeterlidir.

## Bir sorun varsa

Hata, yanıt gövdesindeki `error` alanında gelir — türü ve neden metniyle birlikte.

| Yanıt | Ne yapmalı |
| --- | --- |
| `401 authentication_error` | Anahtar kabul edilmedi. Tam kopyalandığından ve `Authorization: Bearer` veya `x-api-key` içinde iletildiğinden emin olun; yeni anahtarı kullanıcı oluşturur. |
| `402 insufficient_funds` | Bakiyede para yok. Kullanıcıya bildirin: bakiye kişisel panelden yüklenir. |
| `402 child_key_limit_exceeded` | Alt anahtarın limiti doldu. Başka bir anahtar ya da daha yüksek limit gerekir — buna anahtar sahibi karar verir. |
| `403 forbidden` | Bu, yönetim anahtarı `gm-`: modellere erişemez. `jg-` anahtarı gerekir. |
| `400 invalid_request_error` | İstekte hata var. Model bulunamadıysa hata metninde mevcut kimliklerin listesi bulunur — oradan ya da `GET /v1/models` içinden birini alın. |
| `404 model_not_found` | Bu model şu anda yok — `GET /v1/models` içinden başka birini seçin. |
| `429` | Çok fazla istek var veya ağ meşgul. `Retry-After` başlığında belirtilen saniye kadar bekleyip yeniden deneyin. |
| `503 model_unavailable` | Ağ şu anda bu modeli sunmuyor. Hata metnindeki modele ya da `GET /v1/models` içinden başka birine geçin. |
| `504 upstream_timeout` | Ağ zamanında yanıt vermeye başlamadı. İsteği yineleyin; uzun yanıtlar için `stream: true` etkinleştirin. |
| `502` | Ağ geçidi veya ağ tarafında arıza — anahtarla ilgisi yok. Daha sonra yeniden deneyin; ağ durumu [Ağ durumu](https://gate.joingonka.ai/tr/status) sayfasında. |

Tüm yanıt kodları ve limitler — [Hatalar ve Limitler](https://gate.joingonka.ai/tr/docs/errors) bölümünde.

## Rapor

Sonunda kullanıcıya şunları bildirin:

- hangi aracın yapılandırıldığı ve hangi yapılandırma dosyasının yazıldığı (yolu kurulum sihirbazı yazdırır, öncekinin kopyası yanındadır);
- temel adres ve model kimliği;
- kontrol sonucu: yanıt kodu ve modelin yanıtı — ya da kontrolün neden yapılamadığı;
- kullanıcının kendisinin yapması gerekenler: örneğin aracı yeniden başlatmak veya bakiye yüklemek.

Anahtarı rapora dahil etmeyin.

## Makine adresleri

| Adres | Ne var orada |
| --- | --- |
| [/llms.txt](https://gate.joingonka.ai/llms.txt) | Dil modelleri için dokümantasyon dizini. |
| [/llms-full.txt](https://gate.joingonka.ai/llms-full.txt) | Tüm dokümantasyon tek dosyada. |
| `/docs/<page>.md` | Dokümantasyon sayfasının Markdown sürümü: sonuna `.md` eklenmiş aynı adres ([/docs/models.md](https://gate.joingonka.ai/docs/models.md)) veya `Accept: text/markdown` başlığıyla yapılan sayfa isteği. |
| `GET /v1/capabilities` | Ağ geçidinin yetenekleri ve limitleri — `limits` alanı. |
| `GET /v1/models` | Şu anda kullanılabilir modeller. |
| `GET /api/pricing` | 1M token başına model bazlı fiyatlar ve komisyonlar. |
| `GET /v1/network-status` | Model durumu ve olaylar. |

## Ajan için beceri

Talimat, ajana bir beceri (skill) olarak kurulabilir — böylece prompt olmadan da her zaman elinin altında olur:

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