Mwongozo wa vitendo wa IvyClaw: Kujenga mfumo wa ukuzaji wa programu wenye mawakala wengi unaoweza kupanga, kuandika msimbo, kujaribu na kukagua

I. IvyClaw ni nini

IvyClaw ni mfumo wa uhandisi wa mawakala wengi wa AI unaolenga kazi za utafiti na uundaji wa programu, uliojengwa kwa kutumia DeepAgents na LangGraph. Haufanyi tu mwito mmoja wa modeli kubwa ya lugha, bali hupanga uelewa wa mahitaji, upangaji wa kazi, utafutaji wa taarifa, utekelezaji wa msimbo, majaribio ya kiotomatiki, ukaguzi wa msimbo na urejeshaji wa matokeo kuwa Agent Workflow inayoweza kuendelea kufanya kazi.

Mradi huu unatumia teknolojia kama Python, FastAPI, PostgreSQL, Redis, ARQ, Docker, Prometheus na Grafana, na unafaa kwa kujifunza na kutekeleza kwa vitendo uhandisi wa AI Agent.

Ni muhimu kutambua kwamba baadhi ya uwezo kwenye hazina bado ni mifano ya kihandisi au utekelezaji wa maonyesho. Ikiwa utatumika katika mazingira ya uzalishaji, uthibitishaji wa utambulisho, udhibiti wa ruhusa, utenganishaji wa usalama na usanidi wa miundombinu vinahitaji kuboreshwa zaidi.

Anwani ya mradi: IvyClaw GitHub Repository.

II. Mtiririko mkuu wa kazi na usanifu wa mfumo

IvyClaw hugawanya ombi moja la utafiti na uundaji wa programu kuwa mawakala kadhaa wenye majukumu yaliyo wazi. Mtiririko wa kawaida ni huu:

User Request
      ↓
   Gateway
      ↓
  Dispatcher
      ↓
   Planner
      ↓
Researcher（kulingana na hitaji）
      ↓
    Coder
      ↓
   Tester
      ↓
  Reviewer
      ↓
Final Response

Planner huwajibika kuelewa mahitaji, kupanga kazi na kufanya maamuzi; Researcher hutafuta na kupanga taarifa inapohitajika; Coder hutekeleza na kurekebisha msimbo; Tester huendesha majaribio na kutafuta matatizo; Reviewer hukagua msimbo wa matokeo ya mwisho.

Kwa kawaida ombi huingia kwanza kwenye API Gateway, kisha hupewa Agent Runtime na adapta za njia pamoja na Dispatcher. PostgreSQL huhifadhi hali ya vipindi pamoja na data ya LangGraph Checkpointer na Store, Redis hutumika kwa akiba, udhibiti wa kiwango, hali ya wakati wa utekelezaji na foleni ya kazi. Kazi zinazochukua muda mrefu hukabidhiwa ARQ Worker kwa utekelezaji usio wa kusawazisha.

III. Kuandaa mazingira ya uendeshaji

Kabla ya kuanza, andaa mazingira ya kuendesha mradi wa Python, huduma zinazopatikana za PostgreSQL na Redis, pamoja na API ya modeli inayokidhi mahitaji ya usanidi wa mradi. Mradi hutumia uv kusimamia vitegemezi vya Python.

Kwanza kloni hazina na uingie kwenye saraka ya mradi:

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

Kisha unda usanidi wa mazingira ya eneo lako kutoka kwenye faili la mfano. Katika Linux, macOS au mazingira yanayofanana na Unix unaweza kutekeleza:

cp .env.example .env

Katika Windows PowerShell unaweza kutekeleza:

Copy-Item .env.example .env

Kwenye .env, jaza usanidi unaohitajika kulingana na mazingira ya eneo lako, kwa mfano:

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

Tafadhali usiwasilishe faili halisi la .env kwenye GitHub. LLM API Key, LangSmith API Key, Feishu App Secret, nenosiri la hifadhidata na API Key halisi ya gateway vinapaswa kuhifadhiwa kwenye eneo lako au mazingira salama ya uwekaji.

IV. Kusakinisha vitegemezi na kuanzisha huduma

Kusakinisha vitegemezi vya Python

Tekeleza katika saraka kuu ya mradi:

uv sync

Amri hii itasawazisha mazingira ya Python na vitegemezi kulingana na usanidi wa mradi.

Kuanzisha FastAPI API

Tumia amri ifuatayo kuanzisha seva ya maendeleo:

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

Baada ya kuanzisha, fungua http://localhost:8000/docs ili kuona nyaraka za Swagger API zinazozalishwa kiotomatiki na FastAPI.

Kuanzisha ARQ Worker

Ikiwa unahitaji kushughulikia kazi za Agent zinazochukua muda mrefu, pia anzisha ARQ Worker kwenye terminal nyingine:

uv run arq tasks.worker.WorkerSettings

Maombi yanaweza kuwasilishwa kwa Worker kupitia foleni ya Redis. Worker huiita Agent Runtime na huhifadhi matokeo ya kazi. Mtiririko wa kazi usio wa kusawazisha kwa kawaida huwa na Job ID, ufuatiliaji wa hali ya kazi, utekelezaji wa chinichini, uwasilishaji usiojirudia na upatikanaji wa matokeo.

Kuanzisha muunganisho endelevu wa Feishu

Unapotumia muunganisho wa Feishu WebSocket, unaweza kutekeleza:

uv run python -m channels.feishu_ws

IvyClaw pia inaauni Feishu Webhook, Generic Webhook na CLI kama njia za kuingilia. Njia tofauti hubadilishwa kwa pamoja kuwa InboundMessage, kisha hutumia tena handle_message() na mantiki ileile ya kushughulikia Agent.

V. Kuelewa miito ya zana za Agent

IvyClaw huwapa mawakala tofauti seti ndogo za zana zinazolingana na majukumu yao, hivyo kupunguza miito isiyohitajika na hatari ya utendaji usio sahihi. Aina za zana zinazoungwa mkono na mradi ni pamoja na:

• Git: Kuangalia na kuendesha matoleo ya msimbo.
• pytest: Kuendesha majaribio ya kiotomatiki.
• Python na Shell: Kuendesha amri za uundaji.
• Web Search: Kutafuta taarifa kupitia Tavily au Exa.
• MCP: Kuunganisha zana na huduma za nje.
• File Tools: Kusoma na kurekebisha faili za eneo la kazi.
• Sandbox: Kuendesha msimbo uliotengenezwa na Agent katika mazingira yaliyotengwa.

Mradi pia hutumia skills/ kuhifadhi michakato ya utafiti na uundaji wa programu inayoweza kutumiwa tena, ikiwemo kufafanua mahitaji, utatuzi wa kimfumo, uundaji unaoongozwa na majaribio, majaribio ya kitengo na uthibitishaji kabla ya kukamilisha. Saraka za kawaida ni pamoja na:

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

VI. Sandbox ya msimbo na utekelezaji salama

Msimbo unaotengenezwa na Agent hautekelezwi moja kwa moja katika mchakato mkuu wa huduma, bali unaweza kuwekwa na kuendeshwa katika mazingira yaliyotengwa. IvyClaw inaunga mkono Docker Sandbox na Daytona Sandbox, pamoja na utekelezaji wa amri kama Python, pytest na Git.

Uwezo wa sandbox unajumuisha saraka huru ya kazi, matumizi tena ya sandbox na usimamizi wa mzunguko wa maisha, pamoja na vizuizi vya rasilimali kama CPU, Memory na PID. Mazingira ya uzalishaji hutumia Docker Sandbox kwa chaguo-msingi, huku yakiweka nafasi ya upanuzi kwa mazingira yenye utenganishaji thabiti zaidi kama gVisor au Kata.

Unaposanidi sandbox, tathmini ruhusa za mtandao, eneo la ufikiaji wa faili, viwango vya juu vya rasilimali na ukubwa wa uendeshaji kwa kuzingatia hatari halisi. README inaeleza wazi kwamba utenganishaji wa usalama katika mazingira ya uzalishaji bado unahitaji kuimarishwa zaidi; usanidi wa sasa wa maonyesho haupaswi kuchukuliwa kuwa suluhisho kamili la usalama.

VII. Uhifadhi wa hali na kazi zisizo za kusawazisha

Vipengele vya uhifadhi

PostgreSQL huhifadhi hasa LangGraph Checkpointer, Store, hali za vipindi na data nyingine ya kudumu; Redis hubeba majukumu ya akiba, udhibiti wa kiwango, foleni ya kazi na hali ya wakati wa utekelezaji. Kwa kutumia Checkpointer na Store, muktadha wa utekelezaji wa Agent unaweza kuendelea kati ya maombi.

Mtiririko wa kazi usio wa kusawazisha

Kwa kazi za utafiti na uundaji wa programu zinazochukua muda mrefu, inashauriwa FastAPI iunde kazi, kisha Redis na ARQ Worker zishughulikie kazi hiyo bila kusawazisha:

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

Njia hii huepusha kushikilia ombi la HTTP linalosawazisha kwa muda mrefu, na hutoa msingi wa kufuatilia hali ya kazi, kujaribu tena na kuhifadhi matokeo.

VIII. Human-in-the-Loop: Kuongeza idhini kwa shughuli zenye hatari kubwa

Ufutaji wa faili na marekebisho yanayoweza kuharibu mfumo hayafai kujiendesha kikamilifu. IvyClaw inaunga mkono Human-in-the-Loop. Agent inapoomba mwito wa zana yenye hatari kubwa, utekelezaji unaweza kusitishwa na kusubiri uamuzi wa binadamu.

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

Baada ya idhini ya binadamu, utekelezaji unaendelea kupitia amri ya kurejesha; ombi likikataliwa, mtiririko wa sasa hukomeshwa au kubadilishwa. Utaratibu huu huweka kituo cha udhibiti kati ya ufanisi wa uwekaji kiotomatiki na usalama wa uendeshaji.

IX. Gateway, wapangaji wengi na usimamizi wa uthabiti

Kabla ya ombi kuingia kwenye Agent Runtime, hupitia safu ya gateway inayotekeleza utambuzi wa utambulisho na usimamizi wa msingi. Uwezo unaotolewa na hazina ya sasa unajumuisha:

• Uthibitishaji wa API Key.
• Utambuzi na utenganishaji wa Tenant.
• Udhibiti wa Rate Limit.
• Udhibiti wa Idempotency.
• Muktadha wa ombi kupitia Request Context.
• Ukaguzi wa shughuli kupitia Audit Log.

README inaeleza hasa kwamba Key na Tenant za sasa hutumika zaidi kama usanidi wa maonyesho. Mazingira ya uzalishaji yanapaswa kuunganisha hifadhidata au mfumo maalumu wa uthibitishaji wa utambulisho, na kuboresha zaidi ruhusa za wapangaji pamoja na utenganishaji wa data.

Safu ya miundombinu pia hutoa mbinu kama Retry, Timeout, Fallback, Concurrency Control, PostgreSQL Connection Pool, Redis Connection Pool na Sandbox Pool ili kukabiliana na uendeshaji wa wakati mmoja kwa kiwango kikubwa, hitilafu za modeli na kuyumba kwa miundombinu.

X. Ufuatiliaji, majaribio na tathmini

IvyClaw imeunganisha vipengele mbalimbali vya ufuatiliaji. LangSmith hutumika kufuatilia mnyororo wa miito ya Agent na LLM, Prometheus hukusanya vipimo, Grafana hutumika kuonyesha ufuatiliaji kwa njia ya michoro, na pia kuna kumbukumbu zilizopangwa pamoja na kumbukumbu za ukaguzi.

Wakati wa utekelezaji, zingatia hasa vipimo vifuatavyo:

• Muda wa majibu na kiwango cha hitilafu.
• Kiasi cha uendeshaji wa wakati mmoja.
• Idadi ya miito ya LLM.
• Kiasi cha matumizi ya Token na gharama.
• Hali ya ARQ Worker.
• Hali ya Sandbox.

Mradi pia una saraka za tests/, eval/ na loadtest/, zinazojumuisha majaribio ya kiotomatiki ya pytest, majaribio ya Agent Runtime, Code Cases, Execution Scorer, LLM Judge, Baseline Evaluation, Reviewer Flow Test na majaribio ya mzigo ya Locust.

Inashauriwa kujenga mzunguko kamili wa uthibitishaji kwa kufuata mpangilio wa “uundaji, majaribio ya kiotomatiki, Agent Evaluation, majaribio ya mzigo, ufuatiliaji wa vipimo na uboreshaji wa matatizo”, badala ya kuamua kutegemeka kwa Agent kupitia mazungumzo moja tu ya kibinadamu.

XI. Uwekaji wa Docker katika uzalishaji

Ikiwa unahitaji kuanzisha safu kamili ya huduma, unaweza kutumia usanidi wa uzalishaji wa Compose uliotolewa na hazina:

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

Utekelezaji wa uzalishaji unahusisha huduma ya wavuti ya FastAPI, ARQ Worker, huduma ya Feishu, PostgreSQL, Redis, Prometheus na Grafana. API na Worker zinaweza kufikia Agent Runtime kwa pamoja, huku Agent Runtime ikitekeleza msimbo uliotengenezwa kupitia Docker Sandbox.

Kabla ya kuanza rasmi, unapaswa kukagua miunganisho ya hifadhidata na Redis, usimamizi wa funguo, uthibitishaji wa API, utenganishaji wa wapangaji, mikakati ya kuweka kikomo cha kasi, vizuizi vya rasilimali za sandbox, ukaguzi wa kumbukumbu pamoja na usanidi wa ufuatiliaji na tahadhari.

Kumi na mbili: Kutafuta msimbo kupitia muundo wa mradi

Kuifahamu muundo wa saraka husaidia kupanua vipengele kwa haraka:

IvyClaw/
├── agent/          # Agent mkuu na upangaji wa kazi
├── api/            # API ya FastAPI
├── channels/       # Miunganisho ya CLI / Feishu / Webhook
├── gateway/        # Uthibitishaji wa API, Tenant, kikomo cha kasi
├── infra/          # PostgreSQL, Redis, LLM Router
├── middleware/     # Muktadha wa ombi, concurrency, ukaguzi, takwimu za gharama
├── obs/            # Metrics na uonekano wa mfumo
├── profiles/       # Modeli na Agent Profile
├── sandbox/        # Sandbox ya Docker / Daytona
├── skills/         # Ujuzi wa Agent
├── subagents/      # Planner / Researcher / Coder / Tester / Reviewer
├── tasks/          # Kazi za asincronasi za ARQ
├── tools/          # Zana za Git / pytest / Search / MCP
├── eval/           # Tathmini ya Agent
├── loadtest/       # Majaribio ya mzigo kwa Locust
├── tests/          # Majaribio ya kiotomatiki
├── scripts/        # Hati za uundaji, majaribio na maonyesho
├── web/            # Kiolesura cha wavuti
├── Dockerfile
├── docker-compose.prod.yml
├── pyproject.toml
└── .env.example

Kumi na tatu: Mapendekezo ya matumizi ya vitendo

1. Kwanza sanidi .env, PostgreSQL na Redis, kisha thibitisha kuwa API inaweza kufikiwa kupitia hati za Swagger.
2. Kwanza tumia API ya kusawazisha au CLI kuthibitisha Agent Workflow ya msingi, kisha uanzishe ARQ Worker kushughulikia kazi ndefu.
3. Kagua tofauti za ruhusa za zana za Coder, Tester na Reviewer, ili kuepuka kumpa Agent mmoja uwezo hatarishi usio wa lazima.
4. Washa utekelezaji wa msimbo uliotengenezwa ndani ya sandbox, na uweke vikomo vinavyofaa vya CPU, kumbukumbu, idadi ya michakato na saraka ya kazi.
5. Kwa shughuli zinazohusisha ufutaji au marekebisho ya kuharibu, washa Human-in-the-Loop; usikubali kiotomatiki kwa chaguo-msingi.
6. Tumia LangSmith, Prometheus, Grafana na kumbukumbu zenye muundo kufuatilia mnyororo wa maombi, gharama, ucheleweshaji na makosa.
7. Kabla ya uzinduzi, endesha pytest, Agent Evaluation na majaribio ya mzigo kwa Locust, kisha urekebishe uelekezaji wa modeli, concurrency na mikakati ya kujaribu tena kulingana na matokeo.

Hitimisho

Lengo kuu la IvyClaw si kuita modeli moja pekee, bali ni kuunganisha ushirikiano wa mawakala wengi, matumizi ya zana, sandbox ya msimbo, uhifadhi endelevu wa hali, utekelezaji wa asincronasi, idhini ya binadamu, usimamizi wa gateway na uonekano wa mfumo kuwa mfumo kamili wa uhandisi wa Agent kwa ajili ya uundaji wa programu.

Baada ya kukamilisha uanzishaji wa ndani, unaweza kuanzia kwenye subagents/, tools/ na skills/ zilizopo, kuelewa hatua kwa hatua jinsi Planner, Researcher, Coder, Tester na Reviewer wanavyoshirikiana, kisha kupanua njia za mawasiliano, zana au michakato ya tathmini kulingana na mahitaji ya biashara.