Kufungua mchakato wa wakala wa Codex

Codex CLI⁠(fungua katika dirisha jipya) ni wakala wetu wa programu wa ndani unaofanya kazi kwenye majukwaa mbalimbali, ulioundwa kutoa mabadiliko ya programu ya ubora wa juu na ya kuaminika huku ukifanya kazi kwa usalama na kwa ufanisi kwenye mashine yako. Tumejifunza mengi sana kuhusu jinsi ya kuunda wakala wa programu wa kiwango cha kimataifa tangu tulipozindua CLI kwa mara ya kwanza mwezi wa Aprili⁠. Ili kufafanua maarifa hayo, hili ni chapisho la kwanza katika mfululizo unaoendelea ambapo tutachunguza vipengele mbalimbali vya jinsi Codex inavyofanya kazi, pamoja na masomo tuliyojifunza kwa bidii. (Ili kupata mwonekano wa kina zaidi wa jinsi Codex CLI inavyoundwa, angalia uhifadhi wetu wa chanzo huria kwenye https://github.com/openai/codex⁠(fungua katika dirisha jipya). Maelezo mengi ya kina ya maamuzi yetu ya muundo yamehifadhiwa katika masuala ya GitHub na ombi la mabadiliko ya kanuni ikiwa ungependa kujifunza zaidi.)

Kuanza, tutazingatia mchakato wa wakala, ambao ni mantiki kuu katika Codex CLI inayohusika na kuratibu mwingiliano kati ya mtumiaji, muundo, na zana ambazo muundo huziita ili kutekeleza kazi ya maana ya programu. Tunatumai chapisho hili linakupa mtazamo mzuri kuhusu jukumu ambalo wakala wetu (au “muunganisho”) linachukua katika kutumia LLM.

Kabla ya kuanza, dokezo fupi kuhusu istilahi: katika OpenAI, “Codex” inajumuisha mkusanyiko wa matoleo ya wakala wa programu, yakiwemo Codex CLI, Codex Cloud, na kiendelezi cha Codex VS Code. Chapisho hili linaangazia muunganisho wa Codex, ambao hutoa mchakato wa msingi wa wakala na mantiki ya utekelezaji inayosimamia matumizi yote ya Codex na inaonyeshwa kupitia Codex CLI. Kwa urahisi hapa, tutatumia istilahi “Codex” na “Codex CLI” kwa kubadilishana.

Katika msingi wa kila wakala wa AI kuna kitu kinachoitwa “mchakato wa wakala.” Mchoro rahisi wa mchakato wa wakala unaonekana hivi:

Kuanza, wakala huchukua ingizo kutoka kwa mtumiaji ili kujumuisha katika seti ya maagizo ya maandishi anayoiandaa kwa muundo unaojulikana kama dokezo.

Hatua inayofuata ni kuuliza muundo kwa kuutumia maagizo yetu na kuuomba utoe jibu, mchakato unaojulikana kama ufasiri. Wakati wa ufasiri, dokezo la maandishi kwanza hutafsiriwa kuwa mfuatano wa tokeni za ingizo la tokeni⁠(fungua katika dirisha jipya)—nambari kamili zinazoorodhesha katika msamiati wa muundo. Tokeni hizi kisha hutumika kuchukua sampuli ya muundo, na kuzalisha mfuatano mpya wa tokeni za matokeo.

Tokeni za matokeo zinatafsiriwa tena kuwa maandishi, ambayo huwa jibu la muundo. Kwa sababu tokeni hutolewa hatua kwa hatua, tafsiri hii inaweza kutokea wakati muundo unapoendelea kufanya kazi, ndiyo sababu programu nyingi zinazotegemea LLM huonyesha utoaji wa mtiririko. Kwa vitendo, ufasiri kwa kawaida hufichwa nyuma ya API inayofanya kazi kwenye maandishi, ikiondoa maelezo ya ugawaji wa tokeni.

Kama matokeo ya hatua ya ufasiri, muundo (1) hutoa jibu la mwisho kwa ingizo la awali la mtumiaji, au (2) huomba wito wa zana ambao wakala anatarajiwa kutekeleza (mfano, “endesha ls na uripoti matokeo”). Katika hali ya (2), wakala hutekeleza wito wa zana na kuongeza matokeo yake kwenye dokezo la awali. Tokeo hili linatumika kuzalisha ingizo jipya linalotumika kuuliza upya muundo; kisha wakala anaweza kuzingatia taarifa hii mpya na kujaribu tena.

Mchakato huu unajirudia hadi muundo uache kutoa miito ya zana na badala yake utoe ujumbe kwa mtumiaji (unaojulikana kama ujumbe wa msaidizi katika miundo ya OpenAI). Katika hali nyingi, ujumbe huu hujibu moja kwa moja ombi la awali la mtumiaji, lakini pia unaweza kuwa swali la ufuatiliaji kwa mtumiaji.

Kwa sababu wakala anaweza kutekeleza miito ya zana inayorekebisha mazingira ya ndani, "matokeo" yake hayazuiliwi kwa ujumbe wa msaidizi. Katika hali nyingi, matokeo ya msingi ya wakala wa programu ni msimbo anaouandika au kuuhariri kwenye mashine yako. Hata hivyo, kila zamu daima huisha na ujumbe wa msaidizi—kama vile “Niliongeza architecture.md ulioomba”—ambao huashiria hali ya kusitisha katika mchakato wa wakala. Kutoka kwa mtazamo wa wakala, kazi yake imekamilika na udhibiti unarudi kwa mtumiaji.

Safari kutoka ingizo la mtumiaji hadi jibu la wakala iliyoonyeshwa kwenye mchoro inarejelewa kama zamu moja ya mazungumzo ( utungo katika Codex). Ingawa zamu hii ya mazungumzo inaweza kujumuisha marudio mengi kati ya ufasiri wa muundo na miito ya zana. Kila wakati unapowasilisha ujumbe mpya kwenye mazungumzo yaliyopo, historia ya mazungumzo inajumuishwa kama sehemu ya dokezo kwa zamu mpya, ambayo inajumuisha jumbe na miito ya zana kutoka kwa zamu zilizopita:

Hii inamaanisha kwamba mazungumzo yanapokua, ndivyo pia urefu wa dokezo linalotumika kuchukua sampuli ya muundo unavyoongezeka. Urefu huu ni muhimu kwa sababu kila muundo una nafasi ya muktadha, ambayo ni idadi ya juu zaidi ya tokeni inayoweza kutumika kwa mwito mmoja wa ufasiri. Kumbuka nafasi hli inajumuisha tokeni za ingizo na tokeni za kutolewa. Kama unavyoweza kufikiria, wakala anaweza kuamua kufanya mamia ya miito ya zana katika zamu moja, na hivyo huenda akalimaliza nafasi ya muktadha. Kwa sababu hii, usimamizi wa nafasi ya muktadha ni mojawapo ya majukumu mengi ya wakala. Sasa, hebu tuangalie tuone jinsi Codex inavyoendesha mchakato wa wakala.

Codex CLI hutuma maombi ya HTTP kwa Responses API⁠(fungua katika dirisha jipya) ili kuendesha ufasiri wa muundo. Tutachunguza jinsi taarifa zinavyotiririka kupitia Codex, inayotumia Responses API kuendesha mchakato wa wakala.

Sehemu ya mwisho ya Responses API ambayo Codex CLI hutumia ni inayoweza kusanidiwa⁠(fungua katika dirisha jipya), kwa hivyo inaweza kutumiwa na sehemu yoyote ya mwisho inayotekeleza Responses API⁠(fungua katika dirisha jipya):

• Unapotumia kuingia kwa ChatGPT⁠(fungua katika dirisha jipya) kwa kutumia Codex CLI, inatumia https://chatgpt.com/backend-api/codex/responses kama sehemu ya mwisho
• Unapotumia uthibitishaji wa Kitufe cha API⁠(fungua katika dirisha jipya) na miundo inayopangishwa na OpenAI, hutumia https://api.openai.com/v1/responses kama sehemu ya mwisho
• Unapoendesha Codex CLI kwa --oss ili kutumia gpt-oss⁠ na ollama 0.13.4+⁠(fungua katika dirisha jipya) au LM Studio 0.3.39+⁠(fungua katika dirisha jipya), kwa chaguo-msingi inatumia http://localhost:11434/v1/responses inayoendeshwa kwa ndani kwenye kompyuta yako
• Codex CLI inaweza kutumika na Responses API inayohifadhiwa na mtoa huduma wa wingu kama Azure

Hebu tuchunguze jinsi Codex inavyounda dokezo kwa mwito wa kwanza wa ufasiri katika mazungumzo.

Kama mtumiaji wa mwisho, hufafanui dokezo linalotumika kuchukua sampuli ya muundo neno kwa neno unapouliza Responses API. Badala yake, unataja aina mbalimbali za ingizo kama sehemu ya swali lako, na seva ya Responses API huamua jinsi ya kupanga taarifa hii kuwa dokezo ambalo muundo umeundwa kulitumia. Unaweza kufikiria dokezo kama “orodha ya vipengee”; sehemu hii itaeleza jinsi swali lako linavyobadilishwa kuwa orodha hiyo.

Katika dokezo la kwanza, kila kipengee kwenye orodha kinahusishwa na jukumu. Jukumu linaonyesha uzito wa maudhui yanayohusishwa na ni mojawapo ya thamani zifuatazo (kwa mpangilio wa kupungua kwa kipaumbele): mfumo, msanidi programu, mtumiaji, msaidizi.

API ya Responses API⁠(fungua katika dirisha jipya) hupokea kiinidata cha JSON chenye vigezo vingi. Tutazingatia haya matatu:

• maagizo⁠(fungua katika dirisha jipya): ujumbe wa mfumo (au wa msanidi programu) uliowekwa katika muktadha wa muundo
• zana⁠(fungua katika dirisha jipya): orodha ya zana ambazo muundo unaweza kuita wakati wa kuzalisha jibu
• ingizo⁠(fungua katika dirisha jipya): orodha ya viingizo vya maandishi, picha, au faili kwa muundo

Katika Codex, sehemu ya maagizo husomwa kutoka kwenye model_instructions_file⁠(fungua katika dirisha jipya) katika ~/.codex/config.toml, ikiwa imebainishwa; vinginevyo, base_instructions zinazohusishwa na modeli⁠(fungua katika dirisha jipya) hutumika. Maelekezo mahususi ya miundo yanapatikana kwenye hifadhi ya Codex na yamejumuishwa kwenye CLI (mfano, gpt-5.2-codex_prompt.md⁠(fungua katika dirisha jipya)).

Sehemu ya zana ni orodha ya ufafanuzi wa zana zinazolingana na kielezo kilichobainishwa na Responses API. Kwa Codex, hii inajumuisha zana zinazotolewa na Codex CLI, zana zinazotolewa na API ya Majibu ambazo zinapaswa kupatikana kwa Codex, pamoja na zana zinazotolewa na mtumiaji, kwa kawaida kupitia seva za MCP:

Hatimaye, sehemu ya ingizo ya kiinidata cha JSON ni orodha ya vitu. Codex huingiza vipengee vifuatavyo⁠(fungua katika dirisha jipya) kwenye ingizo kabla ya kuongeza ujumbe wa mtumiaji:

1. Ujumbe wenye role=developer unaoelezea sehemu ya majaribio ambayo inatumika tu kwa zana ya sheli iliyotolewa na Codex iliyofafanuliwa katika sehemu ya zana. Hiyo ni kusema, zana nyingine, kama zile zinazotolewa kutoka kwa seva za MCP, hazijawekwa kwenye sehemu ya majaribio na Codex na zinawajibika kutekeleza ulinzi wao wenyewe.

Ujumbe unaundwa kutoka kwa kiolezo ambapo vipande muhimu vya maudhui hutoka kwenye vijisehemu vya Lugha ya muundo vilivyofungashwa ndani ya Codex CLI, kama workspace_write.md⁠(fungua katika dirisha jipya) na on_request.md⁠(fungua katika dirisha jipya):

2. (Hiari) Ujumbe wenye role=developer ambao maudhui yake ni thamani ya developer_instructions iliyosomwa kutoka kwenye faili ya config.toml ya mtumiaji.

3. (Hiari) Ujumbe wenye role=user ambao maudhui yake ni “maelekezo ya mtumiaji,” ambayo hayachukuliwi kutoka kwenye faili moja bali yamekusanywa kutoka vyanzo mbalimbali⁠(fungua katika dirisha jipya). Kwa ujumla, maagizo mahususi zaidi yataonekana baadaye:

• Maudhui ya AGENTS.override.md na AGENTS.md katika $CODEX_HOME
• Kwa kuzingatia kikomo (KiB 32, kwa chaguo-msingi), tafuta katika kila folda kuanzia mzizi wa Git/mradi wa cwd (ikiwa upo) hadi cwd yenyewe: ongeza maudhui ya yoyote kati ya AGENTS.override.md, AGENTS.md, au jina lolote la faili lililobainishwa na project_doc_fallback_filenames katika config.toml
• Ikiwa ujuzi⁠(fungua katika dirisha jipya) wowote umewekwa:
  • utangulizi mfupi kuhusu ujuzi
  • metadata ya ujuzi⁠(fungua katika dirisha jipya) kwa kila ujuzi
  • sehemu kuhusu jinsi ya kutumia ujuzi⁠(fungua katika dirisha jipya)

4. Ujumbe wenye role=user unaoelezea mazingira ya ndani ambamo wakala anaendesha shughuli zake kwa sasa. Hii inaeleza saraka inayotumika ya sasa na sheli ya mtumiaji⁠(fungua katika dirisha jipya):

Mara tu Codex inapomaliza kufanya mahesabu yote yaliyo hapo juu ili kuanzisha ingizo, inaongeza ujumbe wa mtumiaji ili kuanzisha mazungumzo.

Mifano iliyopita ililenga maudhui ya kila ujumbe, lakini kumbuka kwamba kila kipengele cha ingizo ni kitu cha JSON chenye aina, jukumu⁠(fungua katika dirisha jipya), na maudhui kama ifuatavyo:

Mara tu Codex inapounda kiinidata cha JSON cha kutuma kwa Responses API, hufanya ombi la HTTP POST lenye kichwa cha Idhini kulingana na jinsi sehemu ya mwisho ya Responses API ilivyosanidiwa katika ~/.codex/config.toml (vichwa vya ziada vya HTTP na vigezo vya maswali huongezwa ikiwa vimebainishwa).

Wakati seva ya Responses API ya OpenAI inapopokea ombi, hutumia JSON kupata dokezo la muundo kama ifuatavyo (ili kuwa na uhakika, utekelezaji maalum wa Responses API unaweza kuleta chaguo tofauti):

Kama unavyoweza kuona, mpangilio wa vipengee vitatu vya kwanza katika dokezo huamuliwa na seva, si mteja. Hata hivyo, kati ya vipengele hivyo vitatu, ni maudhui ya ujumbe wa mfumo pekee ndiyo yanayodhibitiwa pia na seva, kwa kuwa zana na maagizo huamuliwa na mteja. Hizi hufuatwa na ingizo kutoka kwenye kiinidata cha JSON ili kukamilisha dokezo.

Sasa kwa kuwa tuna dokezo letu, tuko tayari kuchukua sampuli ya muundo.

Ombi hili la HTTP la Responses API linaanzisha “awamu” ya kwanza ya mazungumzo katika Codex. Seva hujibu na mtiririko wa Server-Sent Events (SSE⁠(fungua katika dirisha jipya)). Data ya kila tukio ni kiinidata cha JSON chenye "aina" kinachoanza na "jibu", ambalo linaweza kuwa kitu kama hiki (orodha kamili ya matukio inaweza kupatikana katika nyaraka zetu za API⁠(fungua katika dirisha jipya)):

Codex hutumia mtiririko wa matukio⁠(fungua katika dirisha jipya) na kuyachapisha tena kama vitu vya matukio ya ndani vinavyoweza kutumiwa na mteja. Matukio kama response.output_text.delta hutumiwa kusaidia utiririshaji katika UI, ilhali matukio mengine kama response.output_item.added hubadilishwa kuwa vitu vinavyoongezwa kwenye ingizo kwa miito inayofuata ya Responses API.

Fikiria ombi la kwanza la Responses API linajumuisha matukio mawili ya response.output_item.done: moja lenye type=reasoning na moja lenye type=function_call. Matukio haya lazima yawakilishwe katika sehemu ya ingizo ya JSON tunapouliza tena muundo kwa jibu la wito wa zana: 

Dokezo linalotokana lililotumika kuchukua sampuli ya muundo kama sehemu ya swali linalofuata lingeonekana hivi:

Hasa, zingatia jinsi dokezo la zamani ni kiambishi awali halisi cha dokezo jipya. Hili ni la makusudi, kwani hii hufanya maombi yanayofuata kuwa na ufanisi zaidi kwa sababu inatuwezesha kunufaika na uhifadhi wa dokezo (ambao tutaujadili katika sehemu inayofuata kuhusu utendaji).

Tukiangalia nyuma kwenye mchoro wetu wa kwanza wa mchakato wa wakala, tunaona kwamba kunaweza kuwa na marudio mengi kati ya ufasiri na uendeshaji wa zana. Dokezo linaweza kuendelea kukua hadi hatimaye tupokee ujumbe wa msaidizi, unaoonyesha mwisho wa zamu:

Katika Codex CLI, tunawasilisha ujumbe wa msaidizi kwa mtumiaji na kuzingatia mtungaji ili kumwonyesha mtumiaji kwamba ni “zamu” yake ya kuendelea na mazungumzo. Ikiwa mtumiaji atajibu, ujumbe wa msaidizi kutoka zamu iliyotangulia, pamoja na ujumbe mpya wa mtumiaji, lazima uambatishwe kwenye ingizo katika ombi la Responses API ili kuanzisha zamu mpya:

Kwa mara nyingine tena, kwa sababu tunaendelea na mazungumzo, urefu wa ingizo tunaotuma kwa Responses API unaendelea kuongezeka:

Hebu tuchunguze maana ya dokezo hili linalozidi kukua la utendaji.

Huenda unajiuliza, “Je, si mchakato wa wakala ni mraba kwa kuzingatia kiasi cha JSON kinachotumwa kwa Responses API katika kipindi chote cha mazungumzo?” Na ungekuwa sahihi. Ingawa Responses API inaunga mkono kigezo cha hiari cha previous_response_id⁠(fungua katika dirisha jipya) ili kupunguza tatizo hili, Codex haitumii leo, hasa katika kuweka maombi yakiwa bila hali kikamilifu na kuunga mkono usanidi wa Hakuna Kuhifadhi Data (ZDR).

Kwa ujumla, gharama ya kuchukua sampuli za muundo inazidi gharama ya trafiki ya mtandao, na kufanya uchukuaji sampuli kuwa lengo kuu la juhudi zetu za ufanisi. Hii ndiyo sababu uhifadhi wa dokezo ni muhimu sana, kwani hutuwezesha kutumia tena hesabu kutoka kwa mwito wa awali wa ufasiri. Tunapopata maombi ya akiba, kuchukua sampuli ya muundo ni kwa njia ya mstari badala ya kwa njia ya mraba. Nyaraka zetu za uhifadhi wa dokezo ⁠(fungua katika dirisha jipya)zinaeleza hili kwa kina zaidi:

Maombi ya akiba yanawezekana tu kwa ulinganishaji halisi wa viambishi awali ndani ya dokezo. Ili kupata manufaa ya kuhifadhi kwenye akiba, weka maudhui yasiyobadilika kama maagizo na mifano mwanzoni mwa dokezo lako, na weka maudhui yanayobadilika, kama vile taarifa mahususi za mtumiaji, mwishoni. Hii pia inatumika kwa picha na zana, ambazo lazima ziwe sawa kati ya maombi.

Kwa kuzingatia hili, hebu tuzingatie ni aina gani za shughuli zinazoweza kusababisha “ukosefu wa data” katika Codex:

• Kubadilisha zana zinazopatikana kwa muundo katikati ya mazungumzo.
• Kubadilisha muundo ambayo ni lengwa la ombi la Responses API (kwa vitendo, hii hubadilisha kipengee cha tatu katika dokezo asili, kwa kuwa kina maagizo mahususi ya muundo).
• Kubadilisha usanidi wa sehemu ya majaribio, hali ya uidhinishaji, au saraka inayotumika sasa.

Timu ya Codex lazima iwe makini inapoweka vipengele vipya katika Codex CLI ambavyo vinaweza kuhatarisha uhifadhi wa dokezo kwenye akiba. Kwa mfano, usaidizi wetu wa awali wa zana za MCP ulianzisha hitilafu ambapo tulishindwa kuorodhesha zana kwa mpangilio thabiti⁠(fungua katika dirisha jipya), na kusababisha ukosefu wa data. Kumbuka kwamba zana za MCP zinaweza kuwa na changamoto hasa kwa sababu seva za MCP zinaweza kubadilisha orodha ya zana wanazotoa papo hapo kupitia arifa ya notifications/tools/list_changed⁠(fungua katika dirisha jipya). Kuheshimu arifa hii katikati ya mazungumzo marefu kunaweza kusababisha ukosefu ghali wa data.

Ikiwezekana, tunashughulikia mabadiliko ya usanidi yanayotokea katikati ya mazungumzo kwa kuambatanisha ujumbe mpya kwenye ingizo ili kuakisi mabadiliko badala ya kurekebisha ujumbe wa awali:

• Ikiwa usanidi wa sehemu ya majaribio au hali ya uidhinishaji itabadilika, sisi tutaingiza⁠(fungua katika dirisha jipya) ujumbe mpya wa role=developer wenye umbizo sawa na kipengee cha awali cha <permissions instructions>.
• Ikiwa saraka ya kazi ya sasa itabadilika, tunaingiza⁠(fungua katika dirisha jipya) ujumbe mpya wa role=user wenye muundo sawa na ule wa awali wa <environment_context>.

Tunajitahidi sana kuhakikisha kuwa data inapatikana kwa ajili ya utendaji kazi. Kuna rasilimali nyingine muhimu tunalazimika kusimamia: nafasi ya muktadha.

Mkakati wetu wa jumla wa kuepuka kuishiwa na nafasi ya muktadha ni kupunguza mazungumzo mara tu idadi ya tokeni inapozidi kiwango fulani. Hasa, tunabadilisha ingizo na orodha mpya, ndogo ya vipengee inayowakilisha mazungumzo, na kumwezesha wakala kuendelea na uelewa wa kile ambacho kimetokea hadi sasa. Utekelezaji wa awali wa ubanaji⁠(fungua katika dirisha jipya) ulihitaji mtumiaji kuanzisha mwenyewe amri ya /compact, ambayo ingeuliza Responsens API kwa kutumia mazungumzo yaliyopo pamoja na maagizo maalum ya muhtasari⁠(fungua katika dirisha jipya). Codex ilitumia ujumbe wa msaidizi uliotokana na muhtasari kama ingizo⁠(fungua katika dirisha jipya) jipya kwa zamu zinazofuata za mazungumzo.

Tangu wakati huo, Responses API imeendelea kubadilika ili kuunga mkono sehemu ya mwisho ya /responses/compact ⁠(fungua katika dirisha jipya) inayotekeleza ubanaji kwa ufanisi zaidi. Inarejesha orodha ya vipengee⁠(fungua katika dirisha jipya) ambavyo vinaweza kutumika badala ya ingizo la awali ili kuendelea na mazungumzo huku ikiwezesha nafasi kwenye nafasi ya muktadha. Orodha hii inajumuisha kipengee maalum cha type=compaction chenye kipengee kisicho wazi cha encrypted_content kinachohifadhi uelewa fiche wa muundo wa mazungumzo ya awali. Sasa, Codex hutumia kiotomatiki sehemu hii ya mwisho kubana mazungumzo wakati auto_compact_limit⁠(fungua katika dirisha jipya) inapozidiwa.

Tumeanzisha mchakato wa wakala wa Codex na kuelezea jinsi Codex inavyotengeneza na kusimamia muktadha wake inapouliza muundo. Njiani, tuliangazia mambo ya kivitendo na mbinu bora zinazotumika kwa mtu yeyote anayeunda mchakato wa wakala juu ya Responses API.

Ingawa mchakato wa wakala unatoa msingi wa Codex, huo ni mwanzo tu. Katika machapisho yajayo, tutachunguza usanifu wa CLI, tutaangalia jinsi matumizi ya zana yanavyotekelezwa, na kuchunguza kwa karibu zaidi muundo wa sehemu ya majaribio ya Codex.