IvyClaw হাতে-কলমে: পরিকল্পনা, কোডিং, পরীক্ষা ও পর্যালোচনার সক্ষমতাসম্পন্ন মাল্টি-এজেন্ট গবেষণা ও উন্নয়ন ব্যবস্থা তৈরি

১. IvyClaw কী

IvyClaw হলো সফটওয়্যার研发 কাজের জন্য তৈরি একটি মাল্টি-এজেন্ট AI Agent ইঞ্জিনিয়ারিং সিস্টেম, যা DeepAgents এবং LangGraph-এর ওপর নির্মিত। এটি শুধু একবার বড় ভাষা মডেল কল করে না; বরং প্রয়োজন বোঝা, কাজের পরিকল্পনা, তথ্য অনুসন্ধান, কোড বাস্তবায়ন, স্বয়ংক্রিয় পরীক্ষা, কোড পর্যালোচনা এবং ফলাফল ফেরত দেওয়াকে একটি ধারাবাহিকভাবে চলমান Agent Workflow হিসেবে সংগঠিত করে।

প্রকল্পটি Python, FastAPI, PostgreSQL, Redis, ARQ, Docker, Prometheus এবং Grafana-এর মতো প্রযুক্তি ব্যবহার করে। AI Agent-এর ইঞ্জিনিয়ারিং বাস্তবায়ন শেখা ও অনুশীলনের জন্য এটি উপযোগী।

মনে রাখতে হবে, রিপোজিটরির কিছু সক্ষমতা এখনও ইঞ্জিনিয়ারিং প্রোটোটাইপ বা প্রদর্শনী বাস্তবায়ন হিসেবে রয়েছে। প্রোডাকশন পরিবেশে ব্যবহার করতে হলে পরিচয় যাচাই, অনুমতি নিয়ন্ত্রণ, নিরাপত্তা বিচ্ছিন্নতা এবং অবকাঠামো কনফিগারেশন আরও উন্নত করতে হবে।

প্রকল্পের ঠিকানা: IvyClaw GitHub Repository।

২. মূল ওয়ার্কফ্লো ও সিস্টেম আর্কিটেকচার

IvyClaw একটি ডেভেলপমেন্ট অনুরোধকে একাধিক সুস্পষ্ট দায়িত্বসম্পন্ন Agent-এ ভাগ করে। সাধারণ প্রবাহটি হলো:

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-এর কাছে অ্যাসিঙ্ক্রোনাসভাবে পাঠানো হয়।

৩. রানটাইম পরিবেশ প্রস্তুত করা

শুরু করার আগে Python প্রকল্প চালানোর পরিবেশ, ব্যবহারযোগ্য PostgreSQL ও Redis পরিষেবা এবং প্রকল্পের কনফিগারেশন অনুযায়ী মডেল API প্রস্তুত করুন। প্রকল্পটি Python নির্ভরতা পরিচালনার জন্য 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, ডেটাবেস পাসওয়ার্ড এবং আসল গেটওয়ে API Key-এর মতো সংবেদনশীল তথ্য স্থানীয় পরিবেশে বা নিরাপদ ডিপ্লয়মেন্ট পরিবেশে সংরক্ষণ করা উচিত।

৪. নির্ভরতা ইনস্টল ও পরিষেবা চালু করা

Python নির্ভরতা ইনস্টল

প্রকল্পের মূল ডিরেক্টরিতে চালান:

uv sync

এই কমান্ডটি প্রকল্পের কনফিগারেশন অনুযায়ী Python পরিবেশ ও নির্ভরতাগুলো সিঙ্ক্রোনাইজ করবে।

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, কাজের অবস্থা অনুসন্ধান, ব্যাকগ্রাউন্ডে সম্পাদন, ইডেমপোটেন্ট সাবমিশন এবং ফলাফল সংগ্রহ অন্তর্ভুক্ত থাকে।

Feishu দীর্ঘ সংযোগ চালু করা

Feishu WebSocket সংযোগ ব্যবহার করতে হলে চালান:

uv run python -m channels.feishu_ws

IvyClaw Feishu Webhook, Generic Webhook এবং CLI-এর মতো প্রবেশপথও সমর্থন করে। বিভিন্ন চ্যানেলকে统一ভাবে InboundMessage-এ রূপান্তর করা হয় এবং এরপর একই handle_message() ও Agent প্রক্রিয়াকরণ যুক্তি পুনর্ব্যবহার করা হয়।

৫. Agent-এর টুল কল বোঝা

IvyClaw প্রতিটি Agent-কে তার দায়িত্বের সঙ্গে সামঞ্জস্যপূর্ণ ন্যূনতম টুলসেট দেয়, যাতে অপ্রয়োজনীয় কল ও ভুল操作ের ঝুঁকি কমে। প্রকল্পে সমর্থিত টুলের ধরনগুলো হলো:

• Git: কোডের সংস্করণ দেখা ও পরিচালনা করা।
• pytest: স্বয়ংক্রিয় পরীক্ষা চালানো।
• Python ও Shell: ডেভেলপমেন্ট কমান্ড চালানো।
• Web Search: Tavily বা Exa-এর মাধ্যমে তথ্য অনুসন্ধান করা।
• MCP: বাহ্যিক টুল ও পরিষেবায় সংযোগ করা।
• File Tools: ওয়ার্কস্পেসের ফাইল পড়া ও পরিবর্তন করা।
• Sandbox: Agent-নির্মিত কোড বিচ্ছিন্ন পরিবেশে চালানো।

প্রকল্পটি skills/-এর মাধ্যমে পুনর্ব্যবহারযোগ্য ডেভেলপমেন্ট প্রক্রিয়াও সংরক্ষণ করে। এর মধ্যে রয়েছে প্রয়োজন স্পষ্টীকরণ, পদ্ধতিগত ডিবাগিং, টেস্ট-ড্রিভেন ডেভেলপমেন্ট, ইউনিট টেস্ট এবং সম্পন্ন করার আগে যাচাই। সাধারণ ডিরেক্টরিগুলো হলো:

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

৬. কোড স্যান্ডবক্স ও নিরাপদ সম্পাদন

Agent-এর তৈরি কোড সরাসরি মূল পরিষেবা প্রক্রিয়ায় চালানো হয় না; বরং বিচ্ছিন্ন পরিবেশে চালানো যায়। IvyClaw Docker Sandbox ও Daytona Sandbox সমর্থন করে এবং Python, pytest, Git-এর মতো কমান্ড চালাতে পারে।

স্যান্ডবক্সের সক্ষমতার মধ্যে রয়েছে পৃথক ওয়ার্কিং ডিরেক্টরি, স্যান্ডবক্স পুনর্ব্যবহার ও জীবনচক্র ব্যবস্থাপনা এবং CPU, Memory ও PID-এর মতো সম্পদ সীমা। প্রোডাকশন পরিবেশে ডিফল্টভাবে Docker Sandbox ব্যবহৃত হয়। একই সঙ্গে gVisor বা Kata-এর মতো আরও শক্তিশালী বিচ্ছিন্ন রানটাইমের জন্য সম্প্রসারণের সুযোগ রাখা হয়েছে।

স্যান্ডবক্স কনফিগার করার সময় বাস্তব ঝুঁকি মূল্যায়নের ভিত্তিতে নেটওয়ার্ক অনুমতি, ফাইল অ্যাক্সেসের পরিসর, সম্পদের সীমা এবং সমসাময়িক কাজের পরিমাণ নির্ধারণ করা উচিত। README-তে স্পষ্টভাবে বলা হয়েছে, প্রোডাকশন পরিবেশে নিরাপত্তা বিচ্ছিন্নতা আরও জোরদার করতে হবে। বর্তমান প্রদর্শনী কনফিগারেশনকে সম্পূর্ণ নিরাপত্তা সমাধান হিসেবে সরাসরি বিবেচনা করা উচিত নয়।

৭. অবস্থা স্থায়ীকরণ ও অ্যাসিঙ্ক্রোনাস কাজ

স্থায়ীকরণ উপাদান

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

এই পদ্ধতিতে দীর্ঘ সময়ের জন্য সিঙ্ক্রোনাস HTTP অনুরোধ আটকে রাখা এড়ানো যায় এবং কাজের অবস্থা অনুসন্ধান, পুনরায় চেষ্টা ও ফলাফল স্থায়ীকরণের ভিত্তি তৈরি হয়।

৮. Human-in-the-Loop: উচ্চ-ঝুঁকির কাজে অনুমোদন যোগ করা

ফাইল মুছে ফেলা বা ধ্বংসাত্মক পরিবর্তন সম্পাদনের মতো কাজ পুরোপুরি স্বয়ংক্রিয় করা উপযুক্ত নয়। IvyClaw Human-in-the-Loop সমর্থন করে। Agent উচ্চ-ঝুঁকির টুল কলের অনুরোধ করলে সম্পাদন থামিয়ে মানব সিদ্ধান্তের জন্য অপেক্ষা করা যায়।

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

মানব অনুমোদনের পর পুনরারম্ভ কমান্ডের মাধ্যমে কাজ চালিয়ে যাওয়া যায়। প্রত্যাখ্যান করা হলে বর্তমান প্রবাহ বন্ধ বা পরিবর্তন করা হয়। এই ব্যবস্থা স্বয়ংক্রিয়তার দক্ষতা ও কার্যক্রমের নিরাপত্তার মধ্যে একটি নিয়ন্ত্রণ বিন্দু তৈরি করে।

৯. গেটওয়ে, মাল্টি-টেন্যান্ট ও স্থিতিশীলতা পরিচালনা

Agent Runtime-এ প্রবেশের আগে অনুরোধ গেটওয়ে স্তরের মধ্য দিয়ে যায়, যেখানে পরিচয় শনাক্তকরণ ও মৌলিক পরিচালনা সম্পন্ন হয়। বর্তমান রিপোজিটরিতে থাকা সক্ষমতাগুলো হলো:

• API Key প্রমাণীকরণ।
• Tenant শনাক্তকরণ ও বিচ্ছিন্নতা।
• Rate Limit নিয়ন্ত্রণ।
• Idempotency নিয়ন্ত্রণ।
• Request Context অনুরোধ প্রসঙ্গ।
• Audit Log কার্যক্রমের অডিট।

README-তে বিশেষভাবে উল্লেখ করা হয়েছে যে বর্তমান Key ও Tenant মূলত প্রদর্শনী কনফিগারেশন হিসেবে রয়েছে। প্রোডাকশন পরিবেশে ডেটাবেস বা বিশেষায়িত পরিচয় যাচাই ব্যবস্থা যুক্ত করা এবং টেন্যান্টের অনুমতি ও ডেটা বিচ্ছিন্নতা আরও উন্নত করা উচিত।

অবকাঠামো স্তরে Retry, Timeout, Fallback, Concurrency Control, PostgreSQL Connection Pool, Redis Connection Pool এবং Sandbox Pool-এর মতো ব্যবস্থাও রয়েছে। এগুলো উচ্চ সমসাময়িকতা, মডেল ত্রুটি ও অবকাঠামোগত অস্থিরতা মোকাবিলায় ব্যবহৃত হয়।

১০. পর্যবেক্ষণযোগ্যতা, পরীক্ষা ও মূল্যায়ন

IvyClaw একাধিক পর্যবেক্ষণযোগ্যতা উপাদান সংযুক্ত করেছে। LangSmith Agent ও LLM কল চেইন অনুসরণে ব্যবহৃত হয়, Prometheus মেট্রিক সংগ্রহ করে, Grafana ভিজ্যুয়াল মনিটরিংয়ের জন্য ব্যবহৃত হয়। এ ছাড়াও কাঠামোবদ্ধ লগ ও অডিট লগ সরবরাহ করা হয়েছে।

রানটাইমে নিচের মেট্রিকগুলোতে বিশেষ নজর দেওয়া যেতে পারে:

• অনুরোধের বিলম্ব ও ত্রুটির হার।
• সমসাময়িক অনুরোধের পরিমাণ।
• LLM কলের সংখ্যা।
• Token ব্যবহার ও খরচ।
• ARQ Worker-এর অবস্থা।
• Sandbox-এর অবস্থা।

প্রকল্পে tests/, eval/ এবং loadtest/ ডিরেক্টরিও রয়েছে। এগুলোতে pytest স্বয়ংক্রিয় পরীক্ষা, Agent Runtime পরীক্ষা, Code Cases, Execution Scorer, LLM Judge, Baseline Evaluation, Reviewer Flow Test এবং Locust লোড টেস্ট অন্তর্ভুক্ত রয়েছে।

Agent নির্ভরযোগ্য কি না তা শুধু একবারের মানবিক কথোপকথনের ভিত্তিতে নির্ধারণ না করে “ডেভেলপমেন্ট, স্বয়ংক্রিয় পরীক্ষা, Agent Evaluation, চাপ পরীক্ষা, মেট্রিক পর্যবেক্ষণ, সমস্যা উন্নয়ন”—এই ক্রমে যাচাইয়ের একটি বন্ধ চক্র তৈরি করা সুপারিশ করা হয়।

১১. Docker দিয়ে প্রোডাকশন ডিপ্লয়মেন্ট

সম্পূর্ণ পরিষেবা স্ট্যাক চালু করতে হলে রিপোজিটরিতে থাকা প্রোডাকশন Compose কনফিগারেশন ব্যবহার করতে পারেন:

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

প্রোডাকশন ডিপ্লয়মেন্টে FastAPI Web পরিষেবা, 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. দীর্ঘ কাজ পরিচালনার জন্য ARQ Worker চালু করার আগে সিঙ্ক্রোনাস API বা CLI ব্যবহার করে মৌলিক Agent Workflow যাচাই করুন।
3. Coder, 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-এর সহযোগিতার পদ্ধতি বুঝতে পারেন। এরপর ব্যবসায়িক প্রয়োজন অনুযায়ী চ্যানেল, টুল বা মূল্যায়ন প্রক্রিয়া সম্প্রসারণ করুন।