IvyClaw ngokusebenza: Ukwakha uhlelo lokuthuthukisa olunezihlakaniphile eziningi olukwazi ukuhlela, ukubhala ikhodi, ukuhlola nokubuyekeza

1. Iyini i-IvyClaw

IvyClaw iwuhlelo lobunjiniyela lwe-multi-agent AI Agent oluqondiswe emisebenzini yokuthuthukisa isoftware, olwakhiwe kusetshenziswa i-DeepAgents ne-LangGraph. Ayigcini ngokwenza ucingo olulodwa lwemodeli enkulu; ihlela ukuqonda izidingo, ukuhlela imisebenzi, ukucwaninga ulwazi, ukusebenzisa ikhodi, ukuhlola okuzenzakalelayo, ukubuyekeza ikhodi nokubuyisela imiphumela ibe yi-Agent Workflow eqhubeka nokusebenza.

Le phrojekthi isebenzisa ubuchwepheshe obufana ne-Python, FastAPI, PostgreSQL, Redis, ARQ, Docker, Prometheus ne-Grafana, futhi ilungele ukufunda nokusebenzisa i-AI Agent ngendlela ehlelekile kwezobunjiniyela.

Kubalulekile ukuqaphela ukuthi amanye amakhono akule nqolobane asesezingeni le-prototype yobunjiniyela noma lokubonisa. Uma isetshenziswa endaweni yokukhiqiza, kusadingeka kuthuthukiswe ukuqinisekiswa kobuwena, ukulawulwa kwezimvume, ukuhlukaniswa kokuphepha kanye nokucushwa kwengqalasizinda.

Ikheli lephrojekthi: IvyClaw GitHub Repository.

2. Ukuhamba komsebenzi okuyinhloko nokwakheka kwesistimu

IvyClaw ihlukanisa isicelo esisodwa sokuthuthukisa sibe ama-Agent amaningi anemisebenzi ecacile. Ukuhamba okujwayelekile kungokulandelayo:

User Request
      ↓
   Gateway
      ↓
  Dispatcher
      ↓
   Planner
      ↓
Researcher（uma kudingeka）
      ↓
    Coder
      ↓
   Tester
      ↓
  Reviewer
      ↓
Final Response

Planner unesibopho sokuqonda izidingo, ukuhlela imisebenzi nokwenza izinqumo; Researcher ucinga futhi ahlele ulwazi lapho kudingeka; Coder unesibopho sokusebenzisa nokuguqula ikhodi; Tester wenza izivivinyo futhi athole izinkinga; Reviewer ubuyekeza ikhodi yomphumela wokugcina.

Isicelo ngokuvamile siqala singene ku-API Gateway, bese i-channel adapter ne-Dispatcher basidlulisele ku-Agent Runtime. I-PostgreSQL igcina isimo seseshini kanye nedatha ye-LangGraph Checkpointer ne-Store, kanti i-Redis isetshenziselwa i-cache, ukunciphisa izinga lezicelo, isimo sesikhathi sokusebenza kanye nomugqa wemisebenzi. Imisebenzi ethatha isikhathi idluliselwa ku-ARQ Worker ukuze yenziwe ngokungavumelani.

3. Ukulungisa indawo yokusebenza

Ngaphambi kokuqala, lungisa indawo yokusebenza yephrojekthi ye-Python, izinsizakalo ezitholakalayo ze-PostgreSQL ne-Redis, kanye ne-Model API ehambisana nezidingo zokucushwa kwephrojekthi. Iphrojekthi isebenzisa i-uv ukuphatha iz依依 ze-Python.

Qala ngokukhipha i-clone yenqolobane bese ungena enkombeni yephrojekthi:

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

Bese udala ukucushwa kwendawo ngokusebenzisa ifayela lesibonelo. Ezindaweni ze-Linux, macOS noma ezifana ne-Unix, sebenzisa:

cp .env.example .env

Ku-Windows PowerShell, sebenzisa:

Copy-Item .env.example .env

Ku-.env, gcwalisa ukucushwa okudingekayo ngokwendawo yakho, isibonelo:

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

Ungalokothi uthumele ifayela langempela le-.env ku-GitHub. I-LLM API Key, i-LangSmith API Key, i-Feishu App Secret, iphasiwedi yesizindalwazi kanye ne-Gateway API Key yangempela kufanele kugcinwe endaweni yangakini noma endaweni ephephile yokuphakela.

4. Ukufaka iz依依 nokuqala izinsizakalo

Faka iz依依 ze-Python

Enkombeni eyinhloko yephrojekthi, sebenzisa:

uv sync

Lo myalo uzovumelanisa indawo ye-Python nez依依 ngokokucushwa kwephrojekthi.

Qalisa i-FastAPI API

Sebenzisa lo myalo ukuqala iseva yokuthuthukisa:

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

Ngemva kokuqala, vula http://localhost:8000/docs ukuze ubuke imibhalo ye-Swagger API ekhiqizwa ngokuzenzakalelayo yi-FastAPI.

Qalisa i-ARQ Worker

Uma kudingeka kucutshungulwe imisebenzi ye-Agent ethatha isikhathi, qala ne-ARQ Worker kwenye i-terminal:

uv run arq tasks.worker.WorkerSettings

Izicelo zingathunyelwa ku-Worker ngomugqa we-Redis, bese i-Worker ibiza i-Agent Runtime futhi igcine imiphumela yemisebenzi. Ukuhamba komsebenzi ovumelanayo ngokuvamile kuhlanganisa i-Job ID, ukuhlolwa kwesimo somsebenzi, ukusetshenziswa kwangemuva, ukuthunyelwa kwe-idempotent kanye nokutholwa komphumela.

Qalisa uxhumano olude lwe-Feishu

Uma kudingeka ukuxhuma ku-Feishu WebSocket, sebenzisa:

uv run python -m channels.feishu_ws

IvyClaw iphinde isekele i-Feishu Webhook, i-Generic Webhook ne-CLI njengeminyango yokungena. Iziteshi ezahlukene ziguqulelwa ngendlela efanayo zibe yi-InboundMessage, bese ziphinde zisebenzise i-handle_message() kanye nomqondo ofanayo wokucubungula we-Agent.

5. Ukuqonda ukusetshenziswa kwamathuluzi yi-Agent

IvyClaw inikeza i-Agent ngayinye iqoqo elincane lamathuluzi elihambisana nomsebenzi wayo, ukuze kuncishiswe izingcingo ezingadingekile nobungozi bokusebenza ngokungalungile. Izinhlobo zamathuluzi ezisekelwayo zihlanganisa:

• Git: ukubuka nokuphatha izinguqulo zekhodi.
• pytest: ukwenza izivivinyo ezizenzakalelayo.
• Python ne-Shell: ukusebenzisa imiyalo yokuthuthukisa.
• Web Search: ukucinga ulwazi nge-Tavily noma i-Exa.
• MCP: ukuxhuma amathuluzi nezinsizakalo zangaphandle.
• File Tools: ukufunda nokuguqula amafayela endawo yokusebenza.
• Sandbox: ukwenza ikhodi ekhiqizwe yi-Agent endaweni ehlukanisiwe.

Iphrojekthi iphinde igcine izinqubo zokuthuthukisa ezingasetshenziswa kabusha ngaphansi kwe-skills/, ezihlanganisa ukucacisa izidingo, ukulungisa amaphutha ngendlela ehlelekile, ukuthuthukisa okuqhutshwa izivivinyo, izivivinyo zamayunithi kanye nokuqinisekisa ngaphambi kokuqeda. Izinkomba ezijwayelekile zihlanganisa:

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

6. I-code sandbox nokusebenza okuphephile

Ikhodi ekhiqizwa yi-Agent ayenziwa ngokuqondile enqubweni eyinhloko yesevisi; ingafakwa endaweni ehlukanisiwe ukuze isebenze. IvyClaw isekela i-Docker Sandbox ne-Daytona Sandbox, futhi isekela ukusebenzisa imiyalo efana ne-Python, pytest ne-Git.

Amakhono e-sandbox ahlanganisa inkomba yomsebenzi ezimele, ukusetshenziswa kabusha kwe-sandbox nokuphathwa komjikelezo wayo wokuphila, kanye nemikhawulo yezinsiza ezifana ne-CPU, Memory ne-PID. Endaweni yokukhiqiza, kusetshenziswa i-Docker Sandbox ngokuzenzakalelayo, kanti kugcinwe indawo yokwandisa ukuze kusetshenziswe izikhathi zokuhlukanisa eziqinile njenge-gVisor noma i-Kata.

Lapho ulungisa i-sandbox, hlola izimvume zenethiwekhi, ububanzi bokufinyelela kumafayela, imikhawulo yezinsiza kanye nezinga lokusebenza ngasikhathi sinye ngokusekelwe ekuhlolweni kobungozi bangempela. I-README iveza ngokucacile ukuthi indawo yokukhiqiza isadinga ukuqinisa ukuhlukaniswa kokuphepha, futhi ukucushwa kokubonisa kwamanje akufanele kuthathwe njengohlelo oluphelele lokuphepha.

7. Ukuphikelela kwesimo nemisebenzi engavumelani

Izingxenye zokuphikelela

I-PostgreSQL igcina ikakhulukazi i-LangGraph Checkpointer, i-Store, isimo seseshini kanye nenye idatha ephikelela; i-Redis yona iphatha i-cache, ukunciphisa izinga lezicelo, umugqa wemisebenzi kanye nesimo sesikhathi sokusebenza. Ngenxa ye-Checkpointer ne-Store, umongo wokusebenza we-Agent ungaqhubeka phakathi kwezicelo.

Ukuhamba komsebenzi ovumelanayo

Emisebenzini yokuthuthukisa ethatha isikhathi eside, kunconywa ukuthi i-FastAPI idale umsebenzi, bese i-Redis ne-ARQ Worker bewucubungula ngokungavumelani:

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

Le ndlela igwema ukubamba isicelo se-HTTP esivumelanayo isikhathi eside, futhi inikeza isisekelo sokuhlola isimo somsebenzi, ukuphinda uzame kanye nokugcina umphumela.

8. Human-in-the-Loop: ukwengeza ukuvunywa emisebenzini enobungozi obukhulu

Ukususa amafayela noma ukwenza izinguquko ezibhubhisayo akufanele kube okuzenzakalelayo ngokuphelele. IvyClaw isekela i-Human-in-the-Loop: lapho i-Agent icela ukusebenzisa ithuluzi elinobungozi obukhulu, ukusebenza kungamiswa kulindwe isinqumo somuntu.

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

Ngemva kokuvunywa ngumuntu, ukusebenza kuyaqhubeka ngomyalo wokubuyisela; uma kwenqatshiwe, inqubo yamanje iyamiswa noma ishintshwe. Le ndlela idala indawo yokulawula phakathi kokusebenza kahle okuzenzakalelayo nokuphepha kokusebenza.

9. I-gateway, ama-tenant amaningi nokuphathwa kokuzinza

Ngaphambi kokuba izicelo zingene ku-Agent Runtime, zidlula kungqimba lwe-gateway oluqedela ukuhlonza ubuwena nokuphathwa okuyisisekelo. Amakhono anikezwa yinqolobane yamanje ahlanganisa:

• Ukuqinisekisa nge-API Key.
• Ukuhlonza nokuhlukanisa ama-Tenant.
• Ukunciphisa izinga lezicelo nge-Rate Limit.
• Ukulawula i-Idempotency.
• Umongo wesicelo nge-Request Context.
• Ukucwaninga kokusebenza nge-Audit Log.

I-README igcizelela ukuthi ama-Key nama-Tenant amanje asetshenziswa kakhulu ekucushweni kokubonisa. Endaweni yokukhiqiza, kufanele kuxhunywe isizindalwazi noma uhlelo olukhethekile lokuqinisekisa ubuwena, kuphinde kuthuthukiswe izimvume zama-tenant nokuhlukaniswa kwedatha.

Ungqimba lwengqalasizinda lunikeza futhi izindlela ezifana ne-Retry, Timeout, Fallback, Concurrency Control, PostgreSQL Connection Pool, Redis Connection Pool ne-Sandbox Pool ukuze kubhekwane nokusebenza okuphezulu ngasikhathi sinye, amaphutha emodeli kanye nokungazinzi kwengqalasizinda.

10. Ukubonakala kokusebenza, izivivinyo nokuhlola

IvyClaw ihlanganisa izingxenye eziningi zokubonakala kokusebenza. I-LangSmith isetshenziselwa ukulandelela uchungechunge lwezingcingo ze-Agent ne-LLM, i-Prometheus iqoqa amamethrikhi, i-Grafana isetshenziselwa ukubheka ukusebenza ngendlela ebonakalayo, futhi kunikezwa namalogi ahlelekile kanye namalogi ocwaningo.

Ngesikhathi sokusebenza, naka ikakhulukazi la mamethrikhi:

• Ukubambezeleka kwezicelo nezinga lamaphutha.
• Inani lemisebenzi esebenza ngasikhathi sinye.
• Inani lezingcingo ze-LLM.
• Ukusetshenziswa kwama-Token nezindleko.
• Isimo se-ARQ Worker.
• Isimo se-Sandbox.

Iphrojekthi iphinde ibe nezinkomba ze-tests/, eval/ ne-loadtest/, ezihlanganisa izivivinyo ezizenzakalelayo ze-pytest, izivivinyo ze-Agent Runtime, i-Code Cases, i-Execution Scorer, i-LLM Judge, i-Baseline Evaluation, i-Reviewer Flow Test kanye nokuhlolwa komthwalo nge-Locust.

Kunconywa ukwakha umjikelezo wokuqinisekisa ngokulandelana kokuthi “ukuthuthukisa, izivivinyo ezizenzakalelayo, i-Agent Evaluation, ukuhlolwa kwengcindezi, ukubheka amamethrikhi, nokuthuthukisa izinkinga”, kunokwahlulela ukwethembeka kwe-Agent ngengxoxo eyodwa yomuntu.

11. Ukuphakela ukukhiqiza nge-Docker

Uma kudingeka kuqalwe lonke iqoqo lezinsizakalo, sebenzisa ukucushwa kwe-Compose yokukhiqiza okunikezwe yinqolobane:

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

Ukufakwa emsebenzini kudinga isevisi yewebhu ye-FastAPI, i-ARQ Worker, isevisi ye-Feishu, i-PostgreSQL, i-Redis, i-Prometheus kanye ne-Grafana. I-API ne-Worker zingafinyelela ndawonye ku-Agent Runtime, wona osebenzisa ikhodi ekhiqiziwe nge-Docker Sandbox.

Ngaphambi kokwethulwa ngokusemthethweni, hlola ukuxhumeka kwe-database ne-Redis, ukuphathwa kwezimfihlo, ukuqinisekiswa kwe-API, ukuhlukaniswa kwabaqashi, amasu okukhawulela izicelo, imikhawulo yezinsiza ze-sandbox, ukuhlolwa kwamalogi, kanye nokucushwa kwezaziso zokuqapha.

12. Ukuthola Ikhodi Ngokusebenzisa Isakhiwo Sephrojekthi

Ukujwayelana nesakhiwo samafolda kusiza ekwandiseni imisebenzi ngokushesha:

IvyClaw/
├── agent/          # I-Agent eyinhloko nokuhlelwa kwemisebenzi
├── api/            # I-FastAPI API
├── channels/       # Ukuxhumana kwe-CLI / Feishu / Webhook
├── gateway/        # Ukuqinisekiswa kwe-API, i-Tenant, nokukhawulela izicelo
├── infra/          # I-PostgreSQL, i-Redis, ne-LLM Router
├── middleware/     # Umongo wezicelo, ukuvumelanisa, ukuhlolwa, nezibalo zezindleko
├── obs/            # Ama-Metrics nokubonakala kohlelo
├── profiles/       # Amaphrofayela emodeli ne-Agent
├── sandbox/        # Ama-sandbox e-Docker / Daytona
├── skills/         # Amakhono e-Agent
├── subagents/      # I-Planner / Researcher / Coder / Tester / Reviewer
├── tasks/          # Imisebenzi ye-ARQ engavumelanisi
├── tools/          # Amathuluzi e-Git / pytest / Search / MCP
├── eval/           # Ukuhlolwa kwe-Agent
├── loadtest/       # Ukuhlolwa komthwalo nge-Locust
├── tests/          # Ukuhlolwa okuzenzakalelayo
├── scripts/        # Imibhalo yokuthuthukisa, ukuhlola nedemo
├── web/            # I-Web UI
├── Dockerfile
├── docker-compose.prod.yml
├── pyproject.toml
└── .env.example

13. Izincomo Zokusebenzisa Ngokoqobo

1. Qala ngokumisa i-.env, i-PostgreSQL ne-Redis, bese uqinisekisa ukuthi i-API ingafinyelelwa nge-Swagger documentation.
2. Qala ngokusebenzisa i-synchronous API noma i-CLI ukuze uqinisekise i-Agent Workflow eyisisekelo, bese uqala i-ARQ Worker ukuze icubungule imisebenzi emide.
3. Hlola ngokwehlukana izimvume zamathuluzi e-Coder, Tester ne-Reviewer, ukuze ugweme ukwabela i-Agent eyodwa amakhono ayingozi angadingekile.
4. Yenza ikhodi ekhiqiziwe isebenze ngaphakathi kwe-sandbox, futhi ubeke imikhawulo efanele ye-CPU, inkumbulo, inani lezinqubo kanye nefolda yokusebenza.
5. Uma kuhileleka ukususa noma ukulungisa okulimazayo, vula i-Human-in-the-Loop; ungavumeli ngokuzenzakalelayo njengokuzenzakalelayo.
6. Sebenzisa i-LangSmith, i-Prometheus, i-Grafana namalogi ahlelekile ukuze ubheke uchungechunge lwezicelo, izindleko, ukubambezeleka namaphutha.
7. Ngaphambi kokwethulwa, sebenzisa i-pytest, i-Agent Evaluation kanye nokuhlolwa komthwalo nge-Locust, bese ulungisa umzila wamamodeli, ukuvumelanisa nokuzama futhi ngokwemiphumela.

Isiphetho

Okubalulekile ku-IvyClaw akukhona ukubiza imodeli eyodwa kuphela, kodwa ukuhlanganisa ukubambisana kwama-agent amaningi, ukubizwa kwamathuluzi, i-code sandbox, ukugcinwa kwesimo, ukwenziwa kwemisebenzi ngokungavumelanisi, ukugunyazwa ngabantu, ukuphathwa kwe-gateway kanye nokubonakala kohlelo kube uhlelo lobunjiniyela lwama-Agent lokuthuthukisa isoftware.

Ngemva kokuqeda ukuqalisa kwasendaweni, ungaqala kuma-subagents/, tools/ kanye skills/ akhona, uqonde kancane kancane indlela i-Planner, i-Researcher, i-Coder, i-Tester ne-Reviewer ezisebenzisana ngayo, bese wandisa iziteshi, amathuluzi noma izinqubo zokuhlola ngokwezidingo zebhizinisi.