Jenga na Ujiendeshee Wafanyakazi Wenza wa AI kwa useAgent

Onyo la awali: useAgent bado inaendelezwa kikamilifu. API na schema zinaweza kubadilika kati ya matoleo, kwa hivyo weka lebo ya toleo unapohitaji uthabiti.

useAgent ni nini?

useAgent ni jukwaa huria la mfanyakazi mwenza wa AI kwa kuendesha mawakala kama Claude Code, Codex, na OpenCode. Badala ya kutoa majibu ya mazungumzo pekee, mawakala hufanya kazi katika mazingira ya Linux yaliyotengwa na wanaweza kuwasilisha tovuti, mawasilisho, lahajedwali, ripoti za utafiti, na pull request zilizokamilishwa na kufanyiwa majaribio.

Kila thread hupokea kituo cha kazi chenye terminali, hazina za msimbo, kivinjari, na eneo-kazi linaloonekana kupitia noVNC. Uendeshaji huhifadhiwa kama ratiba za matukio katika Postgres, jambo linalozifanya zidumu, ziweze kuchezwa tena, na zikaguliwe baada ya kukamilika.

Vipengele muhimu

• Muingiliano mmoja kwa mawakala wengi: Injini mahususi za watoa huduma huwasiliana kupitia mkataba sanifu wa matukio.
• Utekelezaji unaodumu: Uendeshaji huendelea kuwepo baada ya kuwashwa upya kwa backend, huku urejeshaji ukiweza kuchunguza tena vipindi vinavyoendelea na kupokea kazi iliyokamilika.
• Sanduku za mchanga za Linux zilizotengwa: Kila thread hupokea kituo tofauti cha kazi. Daytona na CubeSandbox hutekeleza mkataba wa pamoja wa sanduku la mchanga.
• Lango la zana linaloaminika: Sifa za kuingia hubaki kwenye safu ya udhibiti badala ya kuingizwa kwenye sanduku la mchanga la wakala.
• Uidhinishaji wa binadamu: Miito hatari ya zana husitishwa ili kuidhinishwa katika kiolesura cha wavuti au Slack kabla ya kuendelea kwa uwezo unaohusishwa na hoja na kutumika mara moja tu.
• Ujuzi unaotegemea GitHub: Timu zinaweza kuleta faili za SKILL.md zenye matoleo, kusawazisha mabadiliko, na kupanga ujuzi unaohusika katika zamu za mawakala.
• Muktadha wa shirika: Urejeshaji wa maarifa hujumuisha marejeo, huku kumbukumbu ya timu ikitumia mkondo wa mafunzo unaopitiwa na binadamu.
• Bidhaa asilia: Jukwaa linaunga mkono faili za DOCX, XLSX, PPTX, na PDF zenye marekebisho pamoja na vitoa‑mwonekano asilia.
• Njia nyingi za kuingizia kazi: Kazi inaweza kuwasili kupitia programu ya wavuti, Slack, API ya REST, au ratiba.

Jinsi usanifu unavyofanya kazi

useAgent hutenganisha safu yake ya udhibiti inayojipangisha yenyewe na mazingira ambamo wakala hufanya kazi. Njia za kuingizia huunda uendeshaji kupitia njia ileile ya uendeshaji. Adapta za injini hutafsiri shughuli mahususi za mtoa huduma kuwa matukio sanifu, huku kila thread ikipewa sanduku la mchanga lililotengwa.

Sifa tatu za usanifu ni muhimu hasa:

1. Injini zinaweza kubadilishwa: Kubadilisha injini hakuhitaji kubadilisha uwakilishi wa pamoja wa threads, bidhaa, au kumbukumbu.
2. Postgres ndiyo chanzo cha ukweli: Kila uendeshaji huhifadhiwa kama kumbukumbu ya matukio, ikiwezesha uchezaji tena sahihi na ukaguzi baada ya kuwashwa upya.
3. Siri hubaki nje ya sanduku za mchanga: Miunganisho hutolewa kama zana zenye aina kupitia lango linaloaminika, huku sifa za kuingia zikihifadhiwa pekee kwenye safu ya udhibiti.

Mpangilio wa hazina

• frontend/ ina kiolesura cha bidhaa kwa vipindi, ujuzi, vitabu vya utekelezaji, wiki, bidhaa, otomatiki, na mipangilio.
• backend/ ina uthibitishaji, uratibu wa uendeshaji, adapta za injini, sanduku za mchanga, maarifa, kumbukumbu, bidhaa, na viunganishi.
• packages/ ina mikataba ya pamoja ya matukio, vipande vya kazi, miundo ya bidhaa, vitoa‑mwonekano, na vifurushi vinavyohusiana.
• docs-site/ ina tovuti ya nyaraka.
• infra/self-host/ ina zana za upelekaji zisizotegemea mtoa huduma na marejeo ya Terraform ya Hetzner.
• memory/ ina huduma ya hiari ya kumbukumbu ya timu.

Mahitaji ya awali

Usakinishaji wa maendeleo wa ndani unahitaji Bun na Postgres 16 au mpya zaidi yenye kiendelezi cha pgvector. Picha za kawaida za kontena za Postgres hazijumuishi pgvector, kwa hivyo tumia picha inayofaa iliyo na pgvector.

Unapaswa pia kuwa na Docker ikiwa unapanga kuanzisha kontena ya hifadhidata iliyotolewa. Tekeleza hatua zifuatazo kutoka kwenye mzizi wa hazina ya useAgent.

Hatua ya 1: Anzisha Postgres yenye pgvector

Ikiwa bado huna hifadhidata inayooana, anzisha moja kwenye Docker:

docker run -d --name useagent-pg -p 5432:5432 \
  -e POSTGRES_HOST_AUTH_METHOD=trust pgvector/pgvector:pg16
export DATABASE_URL=postgres://postgres@localhost:5432/postgres

Amri ya kwanza hufichua Postgres kwenye porti 5432. Ya pili huweka mfuatano wa muunganisho unaotumiwa na programu. Mipangilio ya trust ni rahisi kwa maendeleo ya ndani; mazingira ya uzalishaji yanapaswa kutumia sifa za kuingia kwenye hifadhidata zilizo salama ipasavyo.

Hatua ya 2: Sakinisha vitegemezi vya workspace

Vitegemezi husakinishwa kwa kujitegemea katika workspaces za vifurushi vya pamoja, backend, na frontend:

for workspace in \
  packages/agent-harness packages/artifact-workspace \
  packages/agent-client packages/artifact-formats packages/conformance \
  backend frontend; do
  (cd "$workspace" && bun install)
done

Hatua ya 3: Anzisha backend na frontend

Fungua vipindi tofauti vya terminali na uanzishe michakato miwili ya maendeleo:

bun run dev:backend

bun run dev:frontend

Backend hutoa API na huduma ya uratibu kwenye porti 3201. Frontend huendeshwa kwenye porti 3400 na hupeleka maombi yaliyo chini ya /api/* kwa backend.

Fungua http://localhost:3400 kwenye kivinjari ili kufikia kiolesura. Usanidi wa mtoa huduma na sandbox unaweza kutofautiana, kwa hiyo fuata nyaraka za useAgent za sasa unapounganisha injini ya wakala au kuandaa mazingira yake ya utekelezaji.

Hatua ya 4: Thibitisha msimbo

Endesha kikagua aina katika hazina nzima baada ya usakinishaji au kabla ya kuwasilisha mabadiliko:

bun run typecheck

Amri hii inahusisha kila kifurushi katika hazina na husaidia kugundua mabadiliko yasiyooana katika mikataba inayoshirikiwa, backend, na frontend.

Matumizi ya msingi

Unda utekelezaji wa wakala

1. Fungua kiolesura cha wavuti kwenye porti 3400.
2. Tumia mtunzi wa wakala kueleza matokeo yaliyokamilika unayohitaji.
3. Anzisha utekelezaji na ufuate ratiba yake ya matukio ya moja kwa moja.
4. Kagua shughuli za terminali, kivinjari, kompyuta ya mezani, au nafasi ya kazi wakala anapoendelea.
5. Kagua kadi yoyote ya idhini kabla ya kuruhusu utendakazi wa zana unaoweza kuharibu data.
6. Kusanya kifaa kilichokamilika au kazi ya hazina iliyorejeshwa na kipindi.

Kazi inaweza kuandaliwa kwa kuzingatia tokeo maalum, kwa mfano:

Chunguza mada, taja vyanzo vinavyohusiana, na urejeshe matokeo kama ripoti iliyopangwa.

Kwa kazi ya programu, fafanua utekelezaji na uthibitishaji unaotarajiwa:

Tekeleza mabadiliko yaliyoombwa katika hazina, endesha majaribio husika, na andaa kazi iliyokamilika kwa ukaguzi.

Hii ni mifano ya kazi za lugha ya kawaida, si sintaksia maalum ya amri. Zana halisi zinazopatikana kwa utekelezaji hutegemea injini, sandbox, vyanzo vya maarifa, ujuzi, na miunganisho iliyosanidiwa.

Fanya kazi kupitia Slack

Muunganisho asilia wa Slack unapokuwa umesanidiwa, watumiaji wanaweza kumtaja wakala ili kuanza kazi. Majibu, viambatisho, vizalia, na maombi ya idhini hubaki katika mazungumzo ya Slack. Hii hutoa njia ileile ya utekelezaji kama kiolesura cha wavuti huku ushirikiano ukiendelea katika kituo kilichoanzisha kazi.

Tumia maarifa na ujuzi wa shirika

Maarifa, maudhui ya wiki, na kumbukumbu ya timu vinaweza kutoa muktadha wa shirika wenye manukuu. Maagizo yanayoweza kutumika tena yanaweza pia kuagizwa kutoka GitHub kama ujuzi wenye matoleo wa SKILL.md. useAgent inaweza kusawazisha ujuzi huu upya kiotomatiki na kupanga unaohusiana zaidi katika kila zamu.

Kujihifadhi useAgent

useAgent inaweza kuendeshwa kwenye mwenyeji yeyote wa Linux, ikijumuisha AWS, Google Cloud, Azure, Hetzner, au vifaa halisi. Hazina inajumuisha hati za utumiaji zisizotegemea mtoa huduma pamoja na mwenyeji wa marejeo wa Hetzner wa amri moja uliojengwa kwa Terraform.

Baada ya kuandaa mwenyeji wa Linux na thamani zinazohitajika, ita hati ya uwekaji kutoka kwenye hazina:

SERVER_IP=<host-ip> PG_PASSWORD=... OPENROUTER_API_KEY=... \
  infra/self-host/deploy-app.sh /path/to/this/repo

Mchakato wa uandaaji huwasiliana na mashine lengwa kupitia SSH. Angalia infra/self-host/README.md kwa mwongozo kamili wa uzalishaji na maelezo yanayohitajika ya mazingira, badala ya kuchukulia mfano huu uliofupishwa kuwa usanidi kamili wa usalama.

Chagua mazingira ya sandbox

• Daytona: Huduma ya sandbox inayosimamiwa ambayo inaweza kuunganishwa na mwenyeji wa control plane kwenye wingu lolote. README inaieleza kama chaguo rahisi zaidi la kuanzia.
• CubeSandbox: Mazingira ya utekelezaji yanayojihifadhiwa kwa mashirika yanayotaka sandbox kwenye vifaa vyao wenyewe na yanayohitaji data ibaki kikamilifu katika eneo lao.

Mazingira yote mawili yanafuata mkataba uleule wa sandbox, hivyo kuruhusu control plane kuratibu kazi ya wakala bila kufanya muundo wake mkuu wa utekelezaji utegemee mtoa huduma mmoja wa sandbox.

Vidokezo vya juu vya uendeshaji

• Funga lebo ya toleo: Kwa kuwa mradi uko katika hatua ya alpha, kufunga lebo inayojulikana hupunguza hitilafu zisizotarajiwa kutokana na API au schema zinazobadilika.
• Linda Postgres: Kumbukumbu ya matukio ndiyo chanzo cha ukweli cha utekelezaji. Hifadhi nakala na endesha hifadhidata ipasavyo.
• Weka vitambulisho katika gateway: Usikiuke usanifu kwa kunakili siri za muda mrefu za miunganisho kwenye sandbox.
• Tumia idhini kwa makusudi: Weka vidhibiti vya mtu-katika-mchakato vikiwashwa kwa vitendo vinavyoweza kuharibu data, hasa utekelezaji unapoanza kupitia Slack au ratiba.
• Chagua sandbox kulingana na uendeshaji: Daytona hutoa njia inayosimamiwa, huku CubeSandbox ikiwezesha utekelezaji unaojihifadhiwa na data kubaki katika eneo lako.
• Endesha ukaguzi wa aina kwa uthabiti: Mikataba inayoshirikiwa inaenea katika nafasi kadhaa za kazi, kwa hiyo tumia bun run typecheck baada ya mabadiliko yanayovuka vifurushi.
• Kagua njia za uzalishaji: Mwongozo kamili wa uwekaji unapatikana chini ya infra/self-host/, na njia ya toleo la kontena zisizobadilika na za nyongeza imeandikwa katika docs/operations/immutable-releases.md.
• Chunguza mtiririko wa ombi: Hazina inajumuisha mchoro shirikishi katika docs/architecture/request-flow.html kwa uchunguzi wa kina wa usanifu.

Miunganisho na sehemu za uwasilishaji

Mbali na usaidizi asilia wa Slack na GitHub, jukwaa linaorodhesha Gmail, Linear, Notion, na HubSpot kupitia viunganishi. OAuth inashughulikiwa na broker, na tokeni hufungwa upande wa seva. Sehemu za nafasi ya kazi zinajumuisha msingi wa maarifa, kumbukumbu ya timu, ujuzi, vitabu vya utekelezaji, na otomatiki zilizopangwa.

Muunganisho wa GitHub unaauni uthibitishaji wa App, kloni ya hazina, na mtiririko wa maombi ya kuvuta. Bila kujali muunganisho, miito ya zana hupitia gateway inayoaminika badala ya kufichua vitambulisho moja kwa moja kwenye kituo cha kazi cha wakala.

Mazingatio ya leseni

useAgent inasambazwa chini ya leseni ya GNU AGPL v3.0-only. Inaweza kutumiwa, kurekebishwa na kujiendeshea mwenyewe kwa kuzingatia masharti hayo. Leseni ya kibiashara inapatikana kwa kuipachika katika bidhaa za umiliki, bidhaa za OEM au zenye chapa yako, usambazaji bila masharti ya AGPL, au mahitaji mengine ya leseni.

Hitimisho

useAgent inachanganya injini nyingi za mawakala, uendeshaji unaodumu unaotumia Postgres, sandbox za Linux zilizotengwa, muktadha wa shirika, miunganisho salama, uidhinishaji na vielelezo vinavyoweza kuhaririwa katika jukwaa moja linaloweza kujiendeshea mwenyewe. Anza ndani ya mazingira yako kwa kutumia Bun na pgvector, thibitisha monorepo kwa kikagua aina zake, kisha tumia njia iliyoandikwa ya kujiendeshea mwenyewe unapohamia kwenye seva pangishi ya Linux ya uzalishaji.