> 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` | কনফিগ লেখা হয়েছে, কিন্তু যাচাই অনুরোধ সফল হয়নি: কী এবং মডেল আইডি পরীক্ষা করুন। |

টুলটি চালু থাকলে আবার চালু করুন: কনফিগ শুরুতে পড়া হয়।

### ম্যানুয়ালি

ইনস্টলার-বিহীন টুলের জন্য তার গাইড খুলুন (লিংক নিচের টেবিলে) এবং তিনটি মান সেট করুন:

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

সব রেসপন্স কোড এবং সীমা — [ত্রুটি ও সীমা](https://gate.joingonka.ai/bn/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
```