> AI ایجنٹس کے لیے: سیٹ اپ کی مرحلہ وار ہدایات — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md)، دستاویزات کا انڈیکس — [`/llms.txt`](https://gate.joingonka.ai/llms.txt)۔

# AI ایجنٹس کے لیے

انٹیگریشن کسی AI ایجنٹ کے سپرد کیسے کریں: کسی بھی ٹول کے لیے تیار پرامپٹ۔ ذیل میں — دستاویزات کے مشین کے لیے پڑھنے کے قابل پتے اور ایک اسکل جو ایجنٹ ایک ہی کمانڈ سے انسٹال کرتا ہے۔

## ایجنٹ کے لیے پرامپٹ

یہ پرامپٹ اپنے AI ایجنٹ کو بھیجیں۔ یہ نیچے دی گئی ہدایات کے مطابق ٹول سیٹ اپ کرے گا اور کی آپ ہی سے مانگے گا۔

```text
https://gate.joingonka.ai/docs/agents.md کی ہدایات کے مطابق اپنا ٹول کو JoinGonka Gateway سے جوڑیں — یہ Gonka نیٹ ورک کا OpenAI اور Anthropic کے ساتھ مطابقت رکھنے والا API ہے۔ کلید میں خود دوں گا: اسے ریپوزٹری کی فائلوں میں محفوظ نہ کریں اور گلوبل ماحول کے متغیرات تبدیل نہ کریں۔ آخر میں ایک مختصر درخواست سے کنکشن کی تصدیق کریں اور نتیجہ بتائیں۔
```

نیچے ہدایات خود موجود ہیں۔ ایجنٹ انہیں [/docs/agents.md](https://gate.joingonka.ai/docs/agents.md) سے Markdown کی شکل میں وصول کرتا ہے۔

## اصول

- API کی ایک انسان بناتا ہے — [gate.joingonka.ai](https://gate.joingonka.ai/keys) کے ڈیش بورڈ میں۔ خود اکاؤنٹ رجسٹر نہ کریں اور نہ کی بنائیں: کی صارف ہی سے مانگیں۔
- کی کو اپنے ٹرمینل سیشن کے `JOINGONKA_API_KEY` انوائرنمنٹ ویری ایبل میں رکھیں۔ اسے git میں ٹریک ہونے والی فائلوں میں نہ لکھیں، نہ کمیٹ کریں اور نہ رپورٹ میں دکھائیں۔
- گلوبل `OPENAI_*` اور `ANTHROPIC_*` ویری ایبلز نہ بدلیں — نہ شیل پروفائل میں اور نہ سسٹم میں: صارف کے دیگر ٹولز انہیں پڑھتے ہیں۔ کی اور ایڈریس خود ٹول کی کانفگ میں لکھے جاتے ہیں — انسٹالر یہی کرتا ہے۔

## حقائق

- OpenAI API کلائنٹس کے لیے بیس URL: `https://gate.joingonka.ai/v1`
- Anthropic API کلائنٹس کے لیے بیس URL، `/v1` کے بغیر: `https://gate.joingonka.ai`
- کلید `Authorization: Bearer jg-…` یا `x-api-key: jg-…` ہیڈر میں بھیجی جاتی ہے
- ماڈلز کو درخواستوں کی کی `jg-` سے شروع ہوتی ہے؛ مینجمنٹ کی `gm-` ماڈلز تک نہیں جانے دیتی۔
- تجویز کردہ ماڈل: `MiniMaxAI/MiniMax-M2.7`
- دستیاب ماڈلز کی فہرست: `GET https://gate.joingonka.ai/v1/models`
- فی کی 120 درخواستیں فی منٹ تک، حد سے زیادہ پر `Retry-After` ہیڈر کے ساتھ 429 جواب۔ حدود اور ٹائم آؤٹ — `GET /v1/capabilities` کے جواب میں، `limits` فیلڈ میں۔

## سیٹ اپ

سیکشن کے آخر میں جدول میں صارف کا ٹول تلاش کریں۔ `--tool` ویلیو موجود ہو — انسٹالر سے سیٹ کریں، نہ ہو — گائیڈ دیکھ کر دستی طور پر۔

### انسٹالر کے ذریعے

بغیر سوال ایک کمانڈ: کی — انوائرنمنٹ ویری ایبل سے، ماڈل — فلیگ سے۔ انسٹالر ٹول کی کانفگ لکھے گا، پچھلی کی کاپی رکھے گا اور گیٹ وے پر ایک درخواست سے کنکشن جانچے گا۔

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

| فلیگ | کیا کرتا ہے |
| --- | --- |
| `--tool <id>` | کون سا ٹول سیٹ کرنا ہے — ٹولز کے جدول سے ویلیو۔ |
| `--model <id>` | ماڈل آئی ڈی: تجویز کردہ — `MiniMaxAI/MiniMax-M2.7`، تمام دستیاب — `GET /v1/models`۔ |
| `--non-interactive` | بغیر سوال: کی `JOINGONKA_API_KEY` سے لی جاتی ہے۔ |
| `--scope local` | کانفگ موجودہ پروجیکٹ میں، ہوم ڈائریکٹری میں نہیں۔ صرف Claude Code کے لیے؛ کانفگ فائل `.gitignore` میں شامل کی جاتی ہے۔ |
| `--no-verify` | کانفگ لکھنے کے بعد کنکشن نہ جانچیں۔ |

| ایگزٹ کوڈ | کیا مطلب ہے |
| --- | --- |
| `0` | مکمل: کانفگ لکھی گئی، جانچ کی درخواست کامیاب۔ نیٹ ورک یا بیلنس کی وجہ سے جانچ نہ ہو سکے تو انسٹالر انتباہ چھاپتا ہے، مگر کوڈ 0 کے ساتھ ہی باہر آتا ہے — صارف کو اس بارے میں بتائیں۔ |
| `1` | سیٹ اپ ناکام، وجہ آؤٹ پُٹ میں: مثلاً `--tool` کی نامعلوم ویلیو، `JOINGONKA_API_KEY` سیٹ نہیں یا کی `jg-` سے شروع نہیں ہوتی۔ |
| `2` | کانفگ لکھی گئی، مگر جانچ کی درخواست ناکام رہی: کی اور ماڈل آئی ڈی چیک کریں۔ |

ٹول چل رہا تھا تو دوبارہ چلائیں: کانفگ آغاز پر پڑھی جاتی ہے۔

### دستی طور پر

انسٹالر کے بغیر ٹول کے لیے اس کی گائیڈ کھولیں (لنک نیچے جدول میں) اور تین ویلیوز سیٹ کریں:

- بیس ایڈریس — OpenAI API کلائنٹس کے لیے `https://gate.joingonka.ai/v1` یا Anthropic API کلائنٹس کے لیے `https://gate.joingonka.ai`;
- کی — ٹول کی سیٹنگز میں API کی فیلڈ میں;
- ماڈل — `MiniMaxAI/MiniMax-M2.7` یا `GET /v1/models` میں سے کوئی اور۔

### ٹولز اور گائیڈز

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

## جانچ

کی کی جانچ — بیلنس کی درخواست: یہ ٹوکن خرچ نہیں کرتی، کی `JOINGONKA_API_KEY` سے لی جاتی ہے:

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

ایڈریس، کی اور ماڈل کی جانچ — ماڈل کو ایک مختصر درخواست:

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

ماڈل کے متن کے ساتھ `200` جواب یعنی کنکشن کام کر رہا ہے۔ انسٹالر خود یہی جانچ کرتا ہے: اس کے بعد ایگزٹ کوڈ 0 کافی ہے۔

## کچھ ٹھیک نہ ہو تو

خرابی جواب کی باڈی کے `error` فیلڈ میں آتی ہے — وجہ کی قسم اور متن کے ساتھ۔

| جواب | کیا کریں |
| --- | --- |
| `401 authentication_error` | کی قبول نہیں ہوئی۔ دیکھیں کہ وہ پوری کاپی ہوئی اور `Authorization: Bearer` یا `x-api-key` میں بھیجی گئی؛ نئی کی صارف بناتا ہے۔ |
| `402 insufficient_funds` | بیلنس میں رقم نہیں۔ صارف کو بتائیں: بیلنس ڈیش بورڈ میں بھرا جاتا ہے۔ |
| `402 child_key_limit_exceeded` | چائلڈ کی کی حد ختم ہو گئی۔ کوئی اور کی یا بڑی حد درکار ہے — یہ کی کے مالک کا فیصلہ ہے۔ |
| `403 forbidden` | یہ مینجمنٹ کی `gm-` ہے: ماڈلز تک نہیں جانے دیتی۔ `jg-` کی درکار ہے۔ |
| `400 invalid_request_error` | درخواست میں خرابی۔ ماڈل نہ ملے تو خرابی کے متن میں دستیاب آئی ڈیز کی فہرست ہوتی ہے — وہاں سے یا `GET /v1/models` سے لیں۔ |
| `404 model_not_found` | ایسا ماڈل اس وقت موجود نہیں — `GET /v1/models` میں سے کوئی اور چنیں۔ |
| `429` | بہت زیادہ درخواستیں یا نیٹ ورک مصروف۔ `Retry-After` ہیڈر میں جتنے سیکنڈ لکھے ہیں اتنے انتظار کریں اور دوبارہ کوشش کریں۔ |
| `503 model_unavailable` | نیٹ ورک اس وقت یہ ماڈل پیش نہیں کر رہا۔ خرابی کے متن میں دیے گئے ماڈل پر یا `GET /v1/models` میں سے کسی اور پر جائیں۔ |
| `504 upstream_timeout` | نیٹ ورک نے وقت پر جواب دینا شروع نہیں کیا۔ درخواست دہرائیں; لمبے جوابات کے لیے `stream: true` آن کریں۔ |
| `502` | گیٹ وے یا نیٹ ورک کی طرف خرابی — کی کا اس میں کوئی قصور نہیں۔ بعد میں دوبارہ کوشش کریں; نیٹ ورک کی حالت — [نیٹ ورک کی حیثیت](https://gate.joingonka.ai/ur/status) صفحے پر۔ |

تمام جوابی کوڈز اور حدود — [خرابیاں اور حدود](https://gate.joingonka.ai/ur/docs/errors) سیکشن میں۔

## رپورٹ

آخر میں صارف کو بتائیں:

- کون سا ٹول سیٹ ہوا اور کون سی کانفگ فائل لکھی گئی (پاتھ انسٹالر چھاپتا ہے، پچھلی کی کاپی ساتھ ہی);
- بنیادی ایڈریس اور ماڈل آئی ڈی؛
- جانچ کا نتیجہ: رسپانس کوڈ اور ماڈل کا جواب — یا جانچ کیوں ممکن نہ ہوئی؛
- صارف کو خود کیا کرنا باقی ہے: مثلاً ٹول دوبارہ شروع کرنا یا بیلنس بھرنا۔

رپورٹ میں کلید شامل نہ کریں۔

## مشین ایڈریسز

| ایڈریس | وہاں کیا ہے |
| --- | --- |
| [/llms.txt](https://gate.joingonka.ai/llms.txt) | لینگویج ماڈلز کے لیے دستاویزات کا انڈیکس۔ |
| [/llms-full.txt](https://gate.joingonka.ai/llms-full.txt) | تمام دستاویزات ایک ہی فائل میں۔ |
| `/docs/<page>.md` | دستاویزات کے صفحے کا Markdown ورژن: وہی ایڈریس جس کے آخر میں `.md` ہو ([/docs/models.md](https://gate.joingonka.ai/docs/models.md)) یا `Accept: text/markdown` ہیڈر کے ساتھ صفحے کی درخواست۔ |
| `GET /v1/capabilities` | گیٹ وے کی صلاحیتیں اور اس کی حدود — `limits` فیلڈ۔ |
| `GET /v1/models` | ابھی دستیاب ماڈلز۔ |
| `GET /api/pricing` | 1M ٹوکن پر فی ماڈل قیمتیں اور کمیشن۔ |
| `GET /v1/network-status` | ماڈلز کی اسٹیٹس اور واقعات۔ |

## ایجنٹ کے لیے اسکل

ہدایات کو ایجنٹ میں اسکل (skill) کے طور پر انسٹال کیا جا سکتا ہے — پھر یہ بغیر پرامپٹ کے بھی اس کے پاس دستیاب رہے گی:

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