IvyClaw عملی رہنمائی: منصوبہ بندی، کوڈنگ، جانچ اور جائزے کی صلاحیت رکھنے والا کثیر ایجنٹی تحقیق و ترقی کا نظام بنانا

1۔ IvyClaw کیا ہے

IvyClaw سافٹ ویئر ڈویلپمنٹ کے کاموں کے لیے ایک ملٹی ایجنٹ AI Agent انجینئرنگ سسٹم ہے، جو DeepAgents اور LangGraph کی بنیاد پر بنایا گیا ہے۔ یہ صرف ایک مرتبہ بڑے ماڈل کو کال نہیں کرتا، بلکہ ضروریات کو سمجھنے، کام کی منصوبہ بندی، معلومات کی تلاش، کوڈ کے نفاذ، خودکار ٹیسٹنگ، کوڈ ریویو اور نتائج واپس کرنے کے عمل کو ایک مسلسل چلنے والے Agent Workflow میں منظم کرتا ہے۔

یہ پروجیکٹ Python، FastAPI، PostgreSQL، Redis، ARQ، Docker، Prometheus اور Grafana جیسی ٹیکنالوجیز استعمال کرتا ہے، اس لیے AI Agent کی انجینئرنگ پر مبنی عملی تنصیب سیکھنے اور آزمانے کے لیے موزوں ہے۔

یہ بات قابل توجہ ہے کہ ریپوزٹری میں بعض صلاحیتیں اب بھی انجینئرنگ پروٹوٹائپ یا ڈیمو کے طور پر موجود ہیں۔ پروڈکشن ماحول میں استعمال سے پہلے شناخت کی تصدیق، اجازتوں کا کنٹرول، سیکیورٹی آئسولیشن اور بنیادی ڈھانچے کی ترتیب کو مزید مکمل کرنا ضروری ہے۔

پروجیکٹ کا پتہ: IvyClaw GitHub Repository۔

2۔ بنیادی ورک فلو اور سسٹم آرکیٹیکچر

IvyClaw ایک ڈویلپمنٹ درخواست کو واضح ذمہ داریوں رکھنے والے متعدد Agents میں تقسیم کرتا ہے۔ عام ورک فلو یہ ہے:

User Request
      ↓
   Gateway
      ↓
  Dispatcher
      ↓
   Planner
      ↓
Researcher（حسبِ ضرورت）
      ↓
    Coder
      ↓
   Tester
      ↓
  Reviewer
      ↓
Final Response

Planner ضروریات کو سمجھنے، کام کی منصوبہ بندی اور فیصلے کرنے کی ذمہ داری لیتا ہے؛ Researcher ضرورت پڑنے پر معلومات تلاش اور منظم کرتا ہے؛ Coder کوڈ نافذ اور تبدیل کرتا ہے؛ Tester ٹیسٹ چلاتا اور مسائل کی نشاندہی کرتا ہے؛ Reviewer حتمی نتیجے کا کوڈ ریویو کرتا ہے۔

درخواست عام طور پر پہلے API Gateway میں داخل ہوتی ہے، پھر چینل اڈاپٹر اور Dispatcher اسے Agent Runtime کے حوالے کرتے ہیں۔ PostgreSQL سیشن کی حالت، LangGraph Checkpointer اور Store کا ڈیٹا مستقل طور پر محفوظ کرتا ہے، جبکہ Redis کیش، شرح کی حد بندی، رن ٹائم حالت اور ٹاسک قطار کے لیے استعمال ہوتا ہے۔ زیادہ وقت لینے والے کام ARQ Worker کو غیر متزامن طور پر سونپے جاتے ہیں۔

3۔ رن ٹائم ماحول کی تیاری

شروع کرنے سے پہلے Python پروجیکٹ کا رن ٹائم ماحول، قابل استعمال PostgreSQL اور Redis سروسز، اور پروجیکٹ کی ترتیب کے مطابق ماڈل API تیار کریں۔ پروجیکٹ Python کی dependencies منظم کرنے کے لیے uv استعمال کرتا ہے۔

سب سے پہلے ریپوزٹری کلون کریں اور پروجیکٹ ڈائریکٹری میں جائیں:

git clone https://github.com/ivyfan-toowell/IvyClaw.git
cd IvyClaw

اس کے بعد نمونہ فائل سے مقامی ماحول کی ترتیب بنائیں۔ Linux، macOS یا Unix جیسے ماحول میں یہ کمانڈ چلائی جا سکتی ہے:

cp .env.example .env

Windows PowerShell میں یہ کمانڈ چلائیں:

Copy-Item .env.example .env

.env میں مقامی ماحول کے مطابق ضروری ترتیبات درج کریں، مثلاً:

IVC_API_KEY=your_api_key_here
IVC_POSTGRES_URL=postgresql://user:password@localhost:5432/ivyclaw
IVC_DATABASE_URL=postgresql://user:password@localhost:5432/ivyclaw
IVC_REDIS_URL=redis://localhost:6379/0

براہ کرم اصل .env فائل GitHub پر جمع نہ کریں۔ LLM API Key، LangSmith API Key، Feishu App Secret، ڈیٹابیس پاس ورڈ اور اصل Gateway API Key جیسی حساس معلومات مقامی یا محفوظ تعیناتی کے ماحول میں رکھی جانی چاہییں۔

4۔ Dependencies انسٹال کرنا اور سروس شروع کرنا

Python Dependencies انسٹال کرنا

پروجیکٹ کی جڑ والی ڈائریکٹری میں یہ کمانڈ چلائیں:

uv sync

یہ کمانڈ پروجیکٹ کی ترتیب کے مطابق Python ماحول اور dependencies کو ہم آہنگ کرے گی۔

FastAPI API شروع کرنا

ڈویلپمنٹ سرور شروع کرنے کے لیے یہ کمانڈ استعمال کریں:

uv run uvicorn api.app:app --reload --port 8000

شروع ہونے کے بعد http://localhost:8000/docs کھولیں، جہاں FastAPI کی خودکار طور پر تیار کردہ Swagger API دستاویزات دیکھی جا سکتی ہیں۔

ARQ Worker شروع کرنا

اگر زیادہ وقت لینے والے Agent کاموں کو پراسیس کرنا ہو تو دوسرے ٹرمینل میں ARQ Worker بھی شروع کریں:

uv run arq tasks.worker.WorkerSettings

درخواستیں Redis قطار کے ذریعے Worker کو بھیجی جا سکتی ہیں۔ Worker Agent Runtime کو کال کرتا اور کام کے نتائج مستقل طور پر محفوظ کرتا ہے۔ غیر متزامن کام کے ورک فلو میں عام طور پر Job ID، کام کی حالت کی جانچ، پسِ منظر میں نفاذ، idempotent submission اور نتیجہ حاصل کرنا شامل ہوتا ہے۔

Feishu Long Connection شروع کرنا

اگر Feishu WebSocket کنکشن استعمال کرنا ہو تو یہ کمانڈ چلائیں:

uv run python -m channels.feishu_ws

IvyClaw Feishu Webhook، Generic Webhook اور CLI جیسے داخلی راستوں کو بھی سپورٹ کرتا ہے۔ مختلف چینلز کو یکساں طور پر InboundMessage میں تبدیل کیا جاتا ہے، جس کے بعد وہی handle_message() اور Agent پروسیسنگ لاجک دوبارہ استعمال ہوتی ہے۔

5۔ Agent کے Tool Calls کو سمجھنا

IvyClaw مختلف Agents کو ان کی ذمہ داریوں سے مطابقت رکھنے والے کم سے کم Tools فراہم کرتا ہے، تاکہ غیر ضروری کالز اور غلط کارروائی کے خطرے کو کم کیا جا سکے۔ پروجیکٹ میں معاون Tools کی اقسام یہ ہیں:

• Git：کوڈ کے ورژن کو دیکھنا اور اس پر کارروائی کرنا۔
• pytest：خودکار ٹیسٹ چلانا۔
• Python اور Shell：ڈویلپمنٹ کمانڈز چلانا۔
• Web Search：Tavily یا Exa کے ذریعے معلومات تلاش کرنا۔
• MCP：بیرونی Tools اور سروسز سے جڑنا۔
• File Tools：ورک اسپیس فائلیں پڑھنا اور تبدیل کرنا۔
• Sandbox：Agent کے تیار کردہ کوڈ کو الگ تھلگ ماحول میں چلانا۔

پروجیکٹ skills/ کے ذریعے دوبارہ استعمال کے قابل ڈویلپمنٹ ورک فلو بھی محفوظ کرتا ہے، جن میں ضروریات کی وضاحت، منظم ڈیبگنگ، ٹیسٹ ڈرائیون ڈویلپمنٹ، یونٹ ٹیسٹنگ اور تکمیل سے پہلے تصدیق شامل ہیں۔ عام ڈائریکٹریاں یہ ہیں:

skills/
├── fastapi-endpoint/
├── requirements-clarification/
├── systematic-debugging/
├── test-driven-development/
├── unit-test/
└── verification-before-completion/

6۔ Code Sandbox اور محفوظ نفاذ

Agent کا تیار کردہ کوڈ براہِ راست مرکزی سروس پراسیس میں نہیں چلایا جاتا، بلکہ اسے الگ تھلگ ماحول میں چلایا جا سکتا ہے۔ IvyClaw Docker Sandbox اور Daytona Sandbox کو سپورٹ کرتا ہے، اور Python، pytest، Git سمیت مختلف کمانڈز چلانے کی سہولت فراہم کرتا ہے۔

Sandbox کی صلاحیتوں میں الگ ورکنگ ڈائریکٹری، Sandbox کا دوبارہ استعمال اور لائف سائیکل مینجمنٹ، نیز CPU، Memory اور PID جیسی وسائل کی پابندیاں شامل ہیں۔ پروڈکشن ماحول میں بطورِ پیش فرض Docker Sandbox استعمال ہوتا ہے، جبکہ gVisor یا Kata جیسے زیادہ مضبوط آئسولیشن رن ٹائمز کے لیے توسیع کی گنجائش رکھی گئی ہے۔

Sandbox ترتیب دیتے وقت حقیقی خطرے کے جائزے کے مطابق نیٹ ورک کی اجازتوں، فائل تک رسائی کی حدود، وسائل کی زیادہ سے زیادہ حد اور ہم وقت کاموں کے پیمانے کا جائزہ لینا چاہیے۔ README واضح کرتا ہے کہ پروڈکشن ماحول میں سیکیورٹی آئسولیشن کو مزید مضبوط کرنا ضروری ہے، اور موجودہ ڈیمو ترتیب کو مکمل سیکیورٹی حل نہیں سمجھنا چاہیے۔

7۔ حالت کا مستقل ذخیرہ اور غیر متزامن کام

Persistent Components

PostgreSQL بنیادی طور پر LangGraph Checkpointer، Store، سیشن کی حالت اور دیگر مستقل ڈیٹا محفوظ کرتا ہے؛ Redis کیش، شرح کی حد بندی، ٹاسک قطار اور رن ٹائم حالت جیسی ذمہ داریاں سنبھالتا ہے۔ Checkpointer اور Store کی مدد سے Agent کا نفاذی سیاق متعدد درخواستوں کے دوران جاری رہ سکتا ہے۔

غیر متزامن کام کا ورک فلو

زیادہ وقت لینے والے ڈویلپمنٹ کاموں کے لیے FastAPI سے ٹاسک بنوانا، پھر Redis اور ARQ Worker کے ذریعے اسے غیر متزامن طور پر پراسیس کروانا تجویز کیا جاتا ہے:

Client
  ↓
FastAPI
  ↓
Create Job
  ↓
Redis Queue
  ↓
ARQ Worker
  ↓
Agent Runtime
  ↓
Persist Result
  ↓
Query Job Status

یہ طریقہ طویل مدت تک synchronous HTTP درخواست پر قبضہ برقرار رکھنے سے بچاتا ہے، اور کام کی حالت کی جانچ، دوبارہ کوشش اور نتائج کے مستقل ذخیرے کے لیے بنیادی سہولت فراہم کرتا ہے۔

8۔ Human-in-the-Loop: زیادہ خطرے والی کارروائیوں کے لیے منظوری

فائلیں حذف کرنا یا تباہ کن تبدیلیاں نافذ کرنا مکمل طور پر خودکار بنانے کے لیے موزوں نہیں۔ IvyClaw Human-in-the-Loop کو سپورٹ کرتا ہے۔ جب Agent کسی زیادہ خطرے والے Tool Call کی درخواست کرتا ہے تو نفاذ کو روک کر انسانی فیصلے کا انتظار کیا جا سکتا ہے۔

Agent requests risky action
          ↓
       Interrupt
          ↓
    Human Approval
       ↓       ↓
    Approve   Reject
       ↓
 Command(resume)
       ↓
Agent continues

انسانی منظوری کے بعد resume کمانڈ کے ذریعے نفاذ جاری رکھا جاتا ہے؛ اگر درخواست مسترد ہو تو موجودہ ورک فلو کو ختم یا تبدیل کیا جاتا ہے۔ یہ طریقہ خودکاری کی کارکردگی اور آپریشنل سیکیورٹی کے درمیان ایک کنٹرول پوائنٹ قائم کرتا ہے۔

9۔ Gateway، Multi-Tenancy اور استحکام کا انتظام

Agent Runtime میں درخواست داخل ہونے سے پہلے Gateway Layer شناخت کی تصدیق اور بنیادی نظم و نسق مکمل کرتی ہے۔ موجودہ ریپوزٹری میں فراہم کردہ صلاحیتیں یہ ہیں:

• API Key Authentication۔
• Tenant کی شناخت اور آئسولیشن۔
• Rate Limit۔
• Idempotency Control۔
• Request Context۔
• Audit Log۔

README خاص طور پر واضح کرتا ہے کہ موجودہ Key اور Tenant بنیادی طور پر ڈیمو ترتیب کے طور پر ہیں۔ پروڈکشن ماحول میں ڈیٹابیس یا مخصوص شناختی نظام سے جڑنا، اور Tenant کی اجازتوں اور ڈیٹا آئسولیشن کو مزید مکمل کرنا چاہیے۔

بنیادی ڈھانچے کی سطح پر Retry، Timeout، Fallback، Concurrency Control، PostgreSQL Connection Pool، Redis Connection Pool اور Sandbox Pool جیسے میکانزم بھی فراہم کیے گئے ہیں، جو زیادہ ہم وقت درخواستوں، ماڈل کی خرابیوں اور بنیادی ڈھانچے کے اتار چڑھاؤ سے نمٹنے کے لیے استعمال ہوتے ہیں۔

10۔ قابلِ مشاہدہ پن، ٹیسٹنگ اور جائزہ

IvyClaw نے متعدد observability components کو مربوط کیا ہے۔ LangSmith Agent اور LLM کال چین کو ٹریک کرنے کے لیے استعمال ہوتا ہے، Prometheus میٹرکس جمع کرتا ہے، Grafana بصری نگرانی کے لیے استعمال ہوتا ہے، جبکہ structured logs اور audit logs بھی فراہم کیے گئے ہیں۔

رن ٹائم میں درج ذیل میٹرکس پر خصوصی توجہ دی جا سکتی ہے:

• درخواست کا تاخیر کا وقت اور خرابی کی شرح۔
• ہم وقت درخواستوں کی تعداد۔
• LLM کالز کی تعداد۔
• Token کا استعمال اور لاگت۔
• ARQ Worker کی حالت۔
• Sandbox کی حالت۔

پروجیکٹ میں tests/، eval/ اور loadtest/ ڈائریکٹریاں بھی شامل ہیں، جن میں pytest خودکار ٹیسٹس، Agent Runtime ٹیسٹس، Code Cases، Execution Scorer، LLM Judge، Baseline Evaluation، Reviewer Flow Test اور Locust لوڈ ٹیسٹنگ شامل ہیں۔

یہ تجویز کیا جاتا ہے کہ “ڈویلپمنٹ، خودکار ٹیسٹنگ، Agent Evaluation، لوڈ ٹیسٹنگ، میٹرکس کی نگرانی، مسائل کی بہتری” کی ترتیب سے تصدیقی چکر قائم کیا جائے، بجائے اس کے کہ Agent کے قابل اعتماد ہونے کا فیصلہ صرف ایک مرتبہ کی انسانی گفتگو سے کیا جائے۔

11۔ Docker پروڈکشن تعیناتی

اگر مکمل سروس اسٹیک شروع کرنا ہو تو ریپوزٹری میں فراہم کردہ پروڈکشن Compose ترتیب استعمال کی جا سکتی ہے:

docker compose -f docker-compose.prod.yml up -d --build

پروڈکشن تعیناتی میں FastAPI ویب سروس، ARQ Worker، Feishu سروس، PostgreSQL، Redis، Prometheus اور Grafana شامل ہیں۔ API اور Worker مشترکہ طور پر Agent Runtime تک رسائی حاصل کر سکتے ہیں، جبکہ Agent Runtime تیار کردہ کوڈ کو Docker Sandbox کے ذریعے چلاتا ہے۔

باضابطہ طور پر آن لائن کرنے سے پہلے ڈیٹابیس اور Redis کنکشن، کلیدوں کا انتظام، API توثیق، کرایہ داروں کی علیحدگی، شرحِ درخواست کی حد بندی کی حکمتِ عملی، سینڈ باکس وسائل کی پابندیاں، لاگ آڈٹ، اور مانیٹرنگ و الرٹ کی ترتیبات کی جانچ کرنی چاہیے۔

۱۲۔ پروجیکٹ کی ساخت سے کوڈ کا مقام تلاش کرنا

ڈائریکٹری کی ساخت سے واقفیت فیچر کو تیزی سے وسعت دینے میں مدد دیتی ہے:

IvyClaw/
├── agent/          # مرکزی Agent اور ٹاسک شیڈولنگ
├── api/            # FastAPI API
├── channels/       # CLI / Feishu / Webhook انضمام
├── gateway/        # API توثیق، Tenant، شرحِ درخواست کی حد بندی
├── infra/          # PostgreSQL، Redis، LLM Router
├── middleware/     # درخواست کا سیاق، ہم وقتی عمل، آڈٹ، لاگت کے اعداد و شمار
├── obs/            # Metrics اور قابلِ مشاہدہ پن
├── profiles/       # ماڈل اور Agent Profile
├── sandbox/        # Docker / Daytona سینڈ باکس
├── skills/         # Agent Skills
├── subagents/      # Planner / Researcher / Coder / Tester / Reviewer
├── tasks/          # ARQ غیر ہم وقتی ٹاسکس
├── tools/          # Git / pytest / Search / MCP ٹولز
├── eval/           # Agent Evaluation
├── loadtest/       # Locust لوڈ ٹیسٹنگ
├── tests/          # خودکار ٹیسٹس
├── scripts/        # ترقی، ٹیسٹنگ اور ڈیمو اسکرپٹس
├── web/            # Web UI
├── Dockerfile
├── docker-compose.prod.yml
├── pyproject.toml
└── .env.example

۱۳۔ عملی استعمال کی تجاویز

1. پہلے .env، PostgreSQL اور Redis ترتیب دیں، اور تصدیق کریں کہ API کو Swagger دستاویز کے ذریعے رسائی حاصل ہے۔
2. پہلے ہم وقت API یا CLI کے ذریعے بنیادی Agent Workflow کی تصدیق کریں، پھر طویل ٹاسکس سنبھالنے کے لیے ARQ Worker شروع کریں۔
3. C​​oder، Tester اور Reviewer کے لیے ٹول کی اجازتوں کی الگ الگ جانچ کریں، تاکہ کسی ایک Agent کو غیر ضروری زیادہ خطرے والی صلاحیتیں نہ دی جائیں۔
4. تیار کردہ کوڈ کے لیے سینڈ باکس میں عمل درآمد فعال کریں، اور CPU، میموری، پروسیسز کی تعداد اور ورکنگ ڈائریکٹری کے لیے مناسب حدود مقرر کریں۔
5. حذف یا تباہ کن ترمیم شامل ہونے پر Human-in-the-Loop فعال کریں، اور خودکار منظوری کو بطورِ ڈیفالٹ فعال نہ کریں۔
6. درخواست کے سلسلے، لاگت، تاخیر اور خرابیوں کی نگرانی کے لیے LangSmith، Prometheus، Grafana اور ساختہ لاگز استعمال کریں۔
7. آن لائن کرنے سے پہلے pytest، Agent Evaluation اور Locust لوڈ ٹیسٹنگ چلائیں، اور نتائج کی بنیاد پر ماڈل روٹنگ، ہم وقتی عمل اور دوبارہ کوشش کی حکمتِ عملی کو ایڈجسٹ کریں۔

اختتامیہ

IvyClaw کی اہمیت کسی ایک ماڈل کال میں نہیں، بلکہ کثیر ایجنٹ تعاون، ٹول کالز، کوڈ سینڈ باکس، حالت کی پائیدار ذخیرہ کاری، غیر ہم وقتی عمل درآمد، انسانی منظوری، گیٹ وے گورننس اور قابلِ مشاہدہ پن کو ملا کر ایک مکمل سافٹ ویئر ریسرچ و ڈیولپمنٹ Agent انجینئرنگ سسٹم بنانے میں ہے۔

مقامی آغاز مکمل کرنے کے بعد، موجودہ subagents/، tools/ اور skills/ سے شروع کریں، Planner، Researcher، Coder، Tester اور Reviewer کے باہمی تعاون کو بتدریج سمجھیں، پھر کاروباری ضروریات کے مطابق چینلز، ٹولز یا جائزہ لینے کے عمل کو وسعت دیں۔