IvyClaw amaliyoti: rejalashtirish, kodlash, testlash va ko‘rib chiqish qobiliyatiga ega ko‘p agentli dasturiy ta’minot ishlab chiqish tizimini yaratish

I. IvyClaw nima

IvyClaw dasturiy ta’minot ishlab chiqish vazifalariga mo‘ljallangan, ko‘p agentli AI Agent muhandislik tizimi bo‘lib, DeepAgents va LangGraph asosida qurilgan. U faqat bitta katta til modeli chaqiruvini bajarib qolmaydi, balki talablarni tushunish, vazifalarni rejalashtirish, materiallarni izlash, kod yozish, avtomatik testdan o‘tkazish, kodni ko‘rib chiqish va natijani qaytarish jarayonlarini uzluksiz ishlaydigan Agent Workflow ko‘rinishida tashkil qiladi.

Loyiha Python, FastAPI, PostgreSQL, Redis, ARQ, Docker, Prometheus va Grafana kabi texnologiyalardan foydalanadi. U AI Agent’larni muhandislik jihatidan amaliyotga joriy etishni o‘rganish va sinab ko‘rish uchun mos keladi.

Shuni hisobga olish kerakki, repozitoriydagi ayrim imkoniyatlar hali ham muhandislik prototipi yoki namoyish ko‘rinishidadir. Ishlab chiqarish muhitida foydalanish uchun autentifikatsiya, ruxsatlarni boshqarish, xavfsiz izolyatsiya va infratuzilma konfiguratsiyasini yanada takomillashtirish kerak.

Loyiha manzili: IvyClaw GitHub Repository.

II. Asosiy ish jarayoni va tizim arxitekturasi

IvyClaw bitta ishlab chiqish so‘rovini vazifalari aniq ajratilgan bir nechta Agent’ga bo‘ladi. Odatdagi jarayon quyidagicha:

User Request
      ↓
   Gateway
      ↓
  Dispatcher
      ↓
   Planner
      ↓
Researcher（按需）
      ↓
    Coder
      ↓
   Tester
      ↓
  Reviewer
      ↓
Final Response

Planner talabni tushunish, vazifalarni rejalashtirish va qaror qabul qilish uchun javob beradi; Researcher zarur bo‘lganda materiallarni izlaydi va tartiblaydi; Coder kodni yozadi va o‘zgartiradi; Tester testlarni bajaradi va muammolarni aniqlaydi; Reviewer yakuniy natijani kod jihatidan ko‘rib chiqadi.

So‘rov odatda avval API Gateway’ga kiradi, keyin kanal adapterlari va Dispatcher orqali Agent Runtime’ga uzatiladi. PostgreSQL sessiya holati, LangGraph Checkpointer va Store ma’lumotlarini doimiy saqlash uchun ishlatiladi; Redis keshlash, tezlikni cheklash, ish vaqti holati va vazifalar navbati uchun xizmat qiladi. Uzoq davom etadigan vazifalar esa ARQ Worker’ga asinxron bajarish uchun topshiriladi.

III. Ishlash muhitini tayyorlash

Boshlashdan oldin Python loyihasini ishga tushirish muhiti, ishlaydigan PostgreSQL va Redis xizmatlari hamda loyiha konfiguratsiyasi talablariga mos model API’sini tayyorlang. Loyiha Python bog‘liqliklarini boshqarish uchun uv dan foydalanadi.

Avval repozitoriyni klon qilib, loyiha katalogiga kiring:

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

Keyin namuna faylidan mahalliy muhit konfiguratsiyasini yarating. Linux, macOS yoki Unix-ga o‘xshash muhitda quyidagini bajarish mumkin:

cp .env.example .env

Windows PowerShell’da esa quyidagini bajaring:

Copy-Item .env.example .env

.env faylida mahalliy muhitga mos zarur konfiguratsiyalarni kiriting, masalan:

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

Haqiqiy .env faylini GitHub’ga yubormang. LLM API Key, LangSmith API Key, Feishu App Secret, ma’lumotlar bazasi paroli va haqiqiy gateway API Key kabi maxfiy ma’lumotlar mahalliy muhitda yoki xavfsiz joylashtirish muhitida saqlanishi kerak.

IV. Bog‘liqliklarni o‘rnatish va xizmatlarni ishga tushirish

Python bog‘liqliklarini o‘rnatish

Loyiha ildiz katalogida quyidagini bajaring:

uv sync

Bu buyruq loyiha konfiguratsiyasiga muvofiq Python muhiti va bog‘liqliklarini sinxronlaydi.

FastAPI API’ni ishga tushirish

Ishlab chiqish serverini quyidagi buyruq bilan ishga tushiring:

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

Ishga tushgach, FastAPI avtomatik yaratgan Swagger API hujjatlarini ko‘rish uchun http://localhost:8000/docs manzilini oching.

ARQ Worker’ni ishga tushirish

Uzoq davom etadigan Agent vazifalarini qayta ishlash kerak bo‘lsa, boshqa terminalda ARQ Worker’ni ham ishga tushiring:

uv run arq tasks.worker.WorkerSettings

So‘rovlar Redis navbati orqali Worker’ga yuboriladi. Worker Agent Runtime’ni chaqiradi va vazifa natijalarini saqlaydi. Asinxron vazifa jarayoni odatda Job ID, vazifa holatini tekshirish, fonda bajarish, idempotent yuborish va natijani olish bosqichlarini o‘z ichiga oladi.

Feishu doimiy ulanishini ishga tushirish

Feishu WebSocket orqali ulanish kerak bo‘lsa, quyidagini bajarish mumkin:

uv run python -m channels.feishu_ws

IvyClaw Feishu Webhook, Generic Webhook va CLI kabi kirish nuqtalarini ham qo‘llab-quvvatlaydi. Turli kanallar yagona InboundMessage formatiga o‘giriladi, keyin bir xil handle_message() va Agent qayta ishlash mantiqidan foydalaniladi.

V. Agent vositalari chaqiruvini tushunish

IvyClaw har bir Agent’ga uning vazifasiga mos minimal vositalar to‘plamini biriktiradi, shu orqali keraksiz chaqiruvlar va noto‘g‘ri amallar xavfi kamayadi. Loyiha qo‘llab-quvvatlaydigan vosita turlari:

• Git: kod versiyalarini ko‘rish va boshqarish.
• pytest: avtomatlashtirilgan testlarni bajarish.
• Python va Shell: ishlab chiqish buyruqlarini ishga tushirish.
• Web Search: Tavily yoki Exa orqali ma’lumot izlash.
• MCP: tashqi vositalar va xizmatlarni ulash.
• File Tools: ish sohasi fayllarini o‘qish va o‘zgartirish.
• Sandbox: Agent yaratgan kodni izolyatsiyada bajarish.

Loyiha, shuningdek, skills/ orqali qayta foydalanish mumkin bo‘lgan ishlab chiqish jarayonlarini jamlaydi. Ular talablarni aniqlashtirish, tizimli nosozliklarni tuzatish, test asosida ishlab chiqish, birlik testlari va yakunlashdan oldingi tekshiruvni o‘z ichiga oladi. Odatdagi kataloglar:

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

VI. Kod sandbox’i va xavfsiz bajarish

Agent yaratgan kod to‘g‘ridan-to‘g‘ri asosiy xizmat jarayonida bajarilmaydi, balki izolyatsiya qilingan muhitga joylashtirilib, shu yerda ishlatilishi mumkin. IvyClaw Docker Sandbox va Daytona Sandbox’ni qo‘llab-quvvatlaydi hamda Python, pytest, Git kabi buyruqlarni bajarish imkonini beradi.

Sandbox imkoniyatlariga alohida ish katalogi, sandbox’dan qayta foydalanish va uning hayotiy siklini boshqarish, shuningdek CPU, Memory va PID kabi resurslarni cheklash kiradi. Ishlab chiqarish muhitida odatda Docker Sandbox ishlatiladi, gVisor yoki Kata kabi kuchliroq izolyatsiya runtime’lari uchun esa kengaytirish imkoniyati qoldirilgan.

Sandbox’ni sozlashda haqiqiy xavf bahosiga asoslanib, tarmoq ruxsatlari, fayllarga kirish doirasi, resurs chegaralari va bir vaqtdagi vazifalar ko‘lamini belgilang. README’da ishlab chiqarish muhiti uchun xavfsizlik izolyatsiyasini yanada kuchaytirish zarurligi aniq ko‘rsatilgan. Joriy namoyish konfiguratsiyasini to‘liq xavfsizlik yechimi deb qabul qilmaslik kerak.

VII. Holatni doimiy saqlash va asinxron vazifalar

Doimiy saqlash komponentlari

PostgreSQL asosan LangGraph Checkpointer, Store, sessiya holati va boshqa doimiy ma’lumotlarni saqlaydi; Redis esa keshlash, tezlikni cheklash, vazifalar navbati va ish vaqti holati kabi vazifalarni bajaradi. Checkpointer va Store yordamida Agent bajarilish konteksti bir nechta so‘rov davomida saqlanib qolishi mumkin.

Asinxron vazifa jarayoni

Bajarilishi uzoq davom etadigan ishlab chiqish vazifalari uchun FastAPI’da vazifa yaratib, keyin uni Redis va ARQ Worker orqali asinxron qayta ishlash tavsiya etiladi:

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

Bu usul sinxron HTTP so‘rovini uzoq vaqt band qilib qo‘yishning oldini oladi hamda vazifa holatini tekshirish, qayta urinish va natijani doimiy saqlash uchun asos yaratadi.

VIII. Human-in-the-Loop: xavfi yuqori amallar uchun tasdiqlash

Fayllarni o‘chirish yoki buzuvchi o‘zgartirishlarni bajarish kabi amallarni to‘liq avtomatlashtirish maqsadga muvofiq emas. IvyClaw Human-in-the-Loop’ni qo‘llab-quvvatlaydi: Agent xavfi yuqori bo‘lgan vosita chaqiruvini so‘raganda, bajarishni to‘xtatib, inson qarorini kutishi mumkin.

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

Inson tasdiqlaganidan so‘ng, tiklash buyrug‘i orqali bajarishni davom ettirish mumkin; rad etilgan taqdirda esa joriy jarayon to‘xtatiladi yoki o‘zgartiriladi. Ushbu mexanizm avtomatlashtirish samaradorligi va amallar xavfsizligi o‘rtasida nazorat nuqtasini yaratadi.

IX. Gateway, ko‘p ijarachilik va barqarorlikni boshqarish

So‘rov Agent Runtime’ga kirishidan oldin gateway qatlami orqali o‘tadi. Bu qatlam identifikatsiya va asosiy boshqaruvni amalga oshiradi. Joriy repozitoriy taqdim etadigan imkoniyatlar:

• API Key orqali autentifikatsiya.
• Tenant’ni aniqlash va izolyatsiya qilish.
• Rate Limit orqali tezlikni cheklash.
• Idempotency orqali takroriy amallardan himoyalash.
• Request Context so‘rov konteksti.
• Audit Log amallar auditi.

README’da joriy Key va Tenant asosan namoyish konfiguratsiyasi sifatida ishlatilishi alohida ta’kidlangan. Ishlab chiqarish muhitida ma’lumotlar bazasi yoki maxsus identifikatsiya tizimiga ulanish, shuningdek tenant ruxsatlari va ma’lumotlar izolyatsiyasini yanada takomillashtirish kerak.

Infratuzilma qatlamida yuqori parallellik, modeldagi xatolar va infratuzilma beqarorligiga qarshi Retry, Timeout, Fallback, Concurrency Control, PostgreSQL Connection Pool, Redis Connection Pool va Sandbox Pool kabi mexanizmlar ham mavjud.

X. Kuzatuvchanlik, testlash va baholash

IvyClaw bir nechta kuzatuvchanlik komponentlarini birlashtiradi. LangSmith Agent va LLM chaqiruvlari zanjirini kuzatish uchun, Prometheus ko‘rsatkichlarni yig‘ish uchun, Grafana esa monitoringni vizuallashtirish uchun ishlatiladi. Bundan tashqari, tizim strukturaviy loglar va audit loglarini ham taqdim etadi.

Ishlash vaqtida quyidagi ko‘rsatkichlarga alohida e’tibor qaratish mumkin:

• So‘rov kechikishi va xatolar darajasi.
• Parallellik darajasi.
• LLM chaqiruvlari soni.
• Token sarfi va xarajatlar.
• ARQ Worker holati.
• Sandbox holati.

Loyihada pytest avtomatlashtirilgan testlari, Agent Runtime testlari, Code Cases, Execution Scorer, LLM Judge, Baseline Evaluation, Reviewer Flow Test va Locust yuklama testlarini qamrab oluvchi tests/, eval/ va loadtest/ kataloglari ham mavjud.

Agent ishonchliligini faqat bir marta o‘tkazilgan qo‘lda suhbat orqali baholash o‘rniga, “ishlab chiqish, avtomatlashtirilgan test, Agent Evaluation, yuklama testi, ko‘rsatkichlarni kuzatish, muammolarni optimallashtirish” tartibida tekshiruvning yopiq siklini yaratish tavsiya etiladi.

XI. Docker orqali ishlab chiqarish muhitiga joylashtirish

To‘liq xizmatlar stekini ishga tushirish kerak bo‘lsa, repozitoriy taqdim etgan ishlab chiqarish Compose konfiguratsiyasidan foydalanish mumkin:

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

Ishlab chiqarish muhitiga joylashtirish FastAPI Web xizmati, ARQ Worker, Feishu xizmati, PostgreSQL, Redis, Prometheus va Grafana'ni o‘z ichiga oladi. API va Worker Agent Runtime'ga birgalikda kira oladi, Agent Runtime esa yaratilgan kodni Docker Sandbox orqali bajaradi.

Rasmiy ishga tushirishdan oldin ma'lumotlar bazasi va Redis ulanishlari, maxfiy kalitlarni boshqarish, API autentifikatsiyasi, tenantlarni izolyatsiya qilish, tezlikni cheklash siyosati, sandbox resurslari cheklovlari, jurnallar auditi hamda monitoring va ogohlantirish sozlamalarini tekshirish kerak.

O‘n ikki. Loyiha tuzilmasi orqali kodni topish

Direktoriyalar tuzilmasini bilish funksiyalarni tez kengaytirishga yordam beradi:

IvyClaw/
├── agent/          # Asosiy Agent va vazifalarni rejalashtirish
├── api/            # FastAPI API
├── channels/       # CLI / Feishu / Webhook integratsiyalari
├── gateway/        # API autentifikatsiyasi, Tenant, tezlikni cheklash
├── infra/          # PostgreSQL, Redis, LLM Router
├── middleware/     # So‘rov konteksti, parallellik, audit, xarajatlar statistikasi
├── obs/            # Metrics va kuzatuvchanlik
├── profiles/       # Model va Agent Profile
├── sandbox/        # Docker / Daytona sandboxlari
├── skills/         # Agent Skills
├── subagents/      # Planner / Researcher / Coder / Tester / Reviewer
├── tasks/          # ARQ asinxron vazifalari
├── tools/          # Git / pytest / Search / MCP vositalari
├── eval/           # Agent Evaluation
├── loadtest/       # Locust yuklama testi
├── tests/          # Avtomatlashtirilgan testlar
├── scripts/        # Ishlab chiqish, test va namoyish skriptlari
├── web/            # Web UI
├── Dockerfile
├── docker-compose.prod.yml
├── pyproject.toml
└── .env.example

O‘n uch. Amaliy foydalanish bo‘yicha tavsiyalar

1. Avval .env fayli, PostgreSQL va Redis'ni sozlang hamda API'ga Swagger hujjatlari orqali kirish mumkinligini tasdiqlang.
2. Dastlab asosiy Agent Workflow'ni sinxron API yoki CLI orqali tekshiring, so‘ng uzoq davom etadigan vazifalarni bajarish uchun ARQ Worker'ni ishga tushiring.
3. Coder, Tester va Reviewer uchun vositalar ruxsatlarini alohida tekshiring; bitta Agent'ga keraksiz yuqori xavfli imkoniyatlarni bermang.
4. Yaratilgan kodni sandboxda bajarishni yoqing va CPU, xotira, jarayonlar soni hamda ishchi direktoriyaga oqilona cheklovlar belgilang.
5. O‘chirish yoki buzuvchi o‘zgartirishlar bilan bog‘liq holatlarda Human-in-the-Loop'ni yoqing, avtomatik tasdiqlashni standart holat sifatida qo‘llamang.
6. So‘rovlar zanjiri, xarajatlar, kechikish va xatolarni LangSmith, Prometheus, Grafana hamda strukturaviy jurnallar orqali kuzating.
7. Ishga tushirishdan oldin pytest, Agent Evaluation va Locust yuklama testlarini bajaring hamda natijalarga ko‘ra model marshrutlash, parallellik va qayta urinish siyosatini sozlang.

Xulosa

IvyClaw'ning asosiy maqsadi bitta modelni chaqirish emas, balki ko‘p agentli hamkorlik, vositalardan foydalanish, kod sandboxi, holatni saqlash, asinxron bajarish, inson tasdig‘i, gateway boshqaruvi va kuzatuvchanlikni yagona dasturiy ta'minot ishlab chiqish Agent tizimiga birlashtirishdir.

Mahalliy ishga tushirishni tugatgach, mavjud subagents/, tools/ va skills/ kataloglaridan boshlang. Planner, Researcher, Coder, Tester va Reviewer'ning hamkorlik usulini bosqichma-bosqich tushunib, keyin biznes ehtiyojlariga ko‘ra kanallar, vositalar yoki baholash jarayonlarini kengaytiring.