Jinsi ya kufanya routing ya miundo kwa coding agents

Jinsi routing ya miundo mingi inavyoathiri wakala wa uandishi wa msimbo (coding agent)

Routing ya miundo mingi hutuma kila ombi kwenye muundo wa bei nafuu zaidi unaoweza kulishughulikia. Katika trafiki ya gumzo, hii hufanya kazi vizuri. Kwa wakala wa uandishi wa msimbo, kwa kawaida gharama huwa kubwa kuliko akiba inayopatikana, kwa sababu bili ya wakala hutawaliwa na kiambishi awali cha prompt (prompt prefix) ambacho huhifadhiwa kwenye cache kwa kila muundo, na kubadili miundo husababisha cache hiyo kupotea.

Kanuni ambayo chapisho hili inatetea ni: fanya routing kati ya watoa huduma kwa ajili ya upatikanaji, fanya routing kati ya viwango vya gharama (tiers) kwenye mipaka ya kazi pekee, na uweke muundo mmoja kwa kila kipindi (session) kwa shughuli zozote za wakala. Yote yaliyo hapa chini ni hoja za msingi.

Istilahi nne, zilizofafanuliwa mara moja. Router huchagua muundo kwa kila ombi. Gateway ni proxy ambayo ombi hupitia, ambayo inaweza au isifanye routing. Prompt cache ni mtoa huduma anayehifadhi kiambishi awali cha prompt yako kilichochakatwa, ili ombi la baadaye linalorudia kiambishi awali hicho litozwe ada ya sehemu ndogo ya bei ya ingizo. KV cache (key value cache) ni wazo hilohilo ndani ya seva unayojiendeshea mwenyewe.

Kwa nini trafiki ya chat hupita vizuri na trafiki ya agent haipiti

Ombi la chat ni hatua moja. Hufika, huainishwa, hupelekwa kwenye model, kisha hurudi. Hakuna kinachobaki kwa ajili ya ombi linalofuata. Router inaweza kutuma swali hili kwa model ndogo na linalofuata kwa model kubwa, na hakuna ombi kati ya hayo linalojua kuwa lingine limetokea. Huu ndio mzigo wa kazi ambao karibu kila benchmark ya routing hupima, na router nzuri zina uwezo wa kweli katika hili.

Hatua ya agent si ombi moja. Maelekezo moja kama "fix the failing test" hugeuka kuwa wito wa API ishirini hadi sita. Kila wito hutuma tena mazungumzo yote: system prompt, ufafanuzi wa kila tool, kila faili ambayo agent amesoma, na kila matokeo ya command ambayo ameona. Muktadha hukua tu. Kufikia wito wa thelathini, prefix inayojirudia inaweza kuwa na makumi ya maelfu ya tokens, wakati maudhui mapya ya kweli katika kila wito ni mamia machache tu.

Umbo hilo hubadilisha maana ya neno "expensive". Katika chat, gharama ni takriban bei ya model ikizidishwa na ombi. Katika mzunguko wa agent, gharama ni prefix, inayotozwa upya katika kila wito mmoja. Sehemu iliyobaki ya chapisho hili inatokana na ukweli huo mmoja.

Cache ya prompt ni ya kila model, na wakala (agent) anaishi ndani yake

Anthropic inatoa bei ya usomaji wa cache kwa mara 0.1 ya bei ya msingi ya input, na uandishi wa cache wa dakika tano kwa mara 1.25. Hizi ndizo bei rasmi zilizochapishwa, kuanzia Agosti 2026.

[
  {
    "label": "Opus 5",
    "uncached_input_usd": "5.00",
    "cache_read_usd": "0.50"
  },
  {
    "label": "Sonnet 5",
    "uncached_input_usd": "2.00",
    "cache_read_usd": "0.20"
  },
  {
    "label": "Haiku 4.5",
    "uncached_input_usd": "1.00",
    "cache_read_usd": "0.10"
  }
]

Soma mfululizo wa pili dhidi ya wa kwanza, ukivuka safu mlalo badala ya kushuka chini. Usomaji wa cache kwenye Opus 5 ni 0.50 dola kwa kila token milioni. Input isiyo na cache kwenye Haiku 4.5, model ya bei nafuu zaidi iliyoorodheshwa, ni 1.00 dola. Kwa hivyo, kusoma tena prefix iliyopo kwenye cache (warm prefix) kwenye model ya bei ghali zaidi kunagharimu kidogo kwa kila token ya input kuliko kusoma prefix hiyo hiyo bila cache (cold) kwenye model ya bei nafuu zaidi.

Ulinganisho huo mmoja unavunja mipango mingi ya routing. Router inayohamisha kazi "chini" kwenye tier nyingine inalinganisha bei za orodha. Lakini wakala aliye katikati ya session halipi bei ya orodha kwenye model anayotumia tayari. Analipa bei ya usomaji wa cache, ambayo tayari iko chini ya kiwango cha input isiyo na cache ya model ya bei nafuu.

Cache zinatambuliwa kwa hash ya prefix ya prompt, na ni za kila model. Ombi kwa model tofauti hufanya hash dhidi ya hifadhi ambayo haijawahi kuiona, kwa hivyo haipati chochote na inalipa bei kamili. Cache pia ni ya kihierarkia: tools kwanza, kisha system, kisha messages. Mabadiliko katika ngazi yoyote hubatilisha ngazi hiyo na kila kitu kinachofuata, jambo linalomaanisha kuwa kuhariri ufafanuzi wa tool moja hutupa cache ya system prompt iliyo nyuma yake. Mawakala wanaosajili tools wakati wa runtime hukumbwa na hili bila hata kugusa router.

Gharama halisi ya kubadili modeli katikati ya kipindi

Chukua kipindi chenye prefix ya token 40,000, ukubwa wa kawaida baada ya wakala kusoma faili chache. Hapo chini ni gharama ya prefix kwa zamu moja, iliyohesabiwa kutoka bei za orodha hapo juu.

[
  {
    "label": "Opus 5, cache warm",
    "prefix_cost_usd": "0.020"
  },
  {
    "label": "Sonnet 5, turn after switch",
    "prefix_cost_usd": "0.100"
  },
  {
    "label": "Opus 5, cache re-warmed",
    "prefix_cost_usd": "0.250"
  }
]

Kubaki kwenye Opus 5 ukiwa na cache iliyopo hugharimu 0.020 dola kwa prefix ya zamu hiyo. Zamu ya kwanza baada ya kuelekeza kazi kwenye Sonnet 5 hugharimu 0.100 dola, kwa sababu Sonnet haina ingizo la prefix hii na inalazimika kuandika moja. Kurudi kwenye Opus 5 hugharimu 0.250 dola, kwa sababu ingizo la awali liliisha muda wake wakati kipindi hicho kikiwa kimehamishiwa kwingine.

Kwa hivyo, safari ya kwenda na kurudi inagharamia uandishi wa cache mara mbili ili kuepuka usomaji wa cache mara mbili. Kinyume chake, ubadilishaji huo ulinunua zamu moja ya matokeo kwa bei ya matokeo ya Sonnet badala ya ile ya Opus. Kizuizi cha maelezo kinafafanua safari nzima: akiba inapatikana kwa sehemu ndogo ya senti, na adhabu ya cache inafikia makumi ya senti. Adhabu hiyo ni kubwa kwa zaidi ya mara kumi, na inakua kadiri prefix inavyorefuka wakati akiba haikui.

Opus 5, warm read     40,000 x $0.50 / 1e6  = $0.020
Sonnet 5, cache write 40,000 x $2.50 / 1e6  = $0.100   (1.25 x $2 base)
Opus 5, cache write   40,000 x $6.25 / 1e6  = $0.250   (1.25 x $5 base)

800 x ($25 - $10) / 1e6 = $0.012

Miundo ya wito wa zana (tool calls) si sawa katika watoa huduma wote

Wakala (agent) ni kitanzi cha wito wa zana, kwa hivyo muundo wa wito wa zana ni muhimu kwa namna ambayo haijawahi kuwa muhimu kwa gumzo (chat). API ya Messages ya Anthropic inarejesha tool_use content block na inatarajia tool_result block kurudishwa. API zinazoendana na OpenAI zinarejesha tool_calls array ambapo function.arguments ni string iliyosimbwa kwa JSON badala ya kitu kilichowekwa ndani ya kingine (nested object). Lango (gateway) hutafsiri kati ya miwili hiyo, na kwa wito wa kawaida, tafsiri hiyo ni safi.

Matatizo hujitokeza pembezoni. Wito wa zana sambamba (parallel tool calls), ambapo modeli hutoa wito kadhaa katika jibu moja, huwakilishwa kwa njia tofauti na hayatumiki kwa usawa kila mahali. Utekelezaji mkali wa schema (strict schema enforcement) ni kipengele cha kila mtoa huduma, kwa hivyo modeli inayohakikisha hoja (arguments) halali za schema kwenye endpoint moja huwa na mwelekeo wa kutoa hoja halali kwenye nyingine. Wakala huona tofauti hiyo kama matokeo ya zana yenye hitilafu ya uchanganuzi (parse error), ambayo kisha hujaribu kuirekebisha kwa kutumia zamu nyingine. Zamu hizo za urekebishaji hutoza gharama kamili ya bei ya prefix, kwa hivyo kutolingana kwa muundo huonekana kwenye ankara na pia kwenye nakala ya mazungumzo.

Endpoints zinazojiendesha zenyewe (self-hosted) zinahitaji hili kusanidiwa waziwazi. Seva ya vLLM inayoendana na OpenAI inahitaji --enable-auto-tool-choice pamoja na --tool-call-parser iliyolinganishwa na familia ya modeli (hermes, mistral, llama3_json na nyinginezo), pamoja na kiolezo cha gumzo (chat template) kinachoshughulikia ujumbe wa jukumu la zana (tool-role messages). Nyaraka za vLLM ziko wazi kuhusu mipaka ya njia hii: kwa tool_choice="auto" na bila kizuizi kikali cha schema, vLLM huchota wito wa zana kutoka kwa maandishi ghafi, kwa hivyo hoja zinaweza wakati mwingine kuwa na makosa au kukiuka schema ya kigezo cha utendaji. Kuchagua kichanganuzi (parser) kibaya kwa modeli yako ni hitilafu ya usanidi inayojitokeza kama wakala asiyeweza kupiga wito wa zana, jambo ambalo ni vyema kujua kabla ya kuelekeza trafiki kwake. Tofauti kati ya Ollama na vLLM kwa ajili ya kuhudumia modeli wewe mwenyewe ni muhimu hapa, kwa sababu vyote viwili hufichua wito wa zana kwa masharti tofauti.

Mabadiliko ya fallback katikati ya kazi hayatoi hitilafu

Uelekezaji wa fallback ndiyo kipengele kinachoweza kuwashwa kwa bahati mbaya zaidi. Gateway husanidiwa ili kujaribu tena kwenye model nyingine wakati ya kwanza ikirejesha kikomo cha kasi (rate limit) au hitilafu ya 5xx, kisha huiweka model iliyoshindwa kwenye hali ya kupoa (cooldown) kwa sekunde kadhaa. Kwenye trafiki ya chat, hii ni sahihi kabisa. Ndani ya kazi ndefu ya wakala (agent task), inamaanisha kuwa nusu ya pili ya kazi yako iliendeshwa kwenye model ambayo hukuchagua.

Hakuna kinachoripoti hili. Kazi haishindwi, wakala haitoi onyo, na hali ya kutoka (exit status) ni ya mafanikio. Unachopata ni kazi ambapo mpango uliandikwa na model moja na marekebisho yakafanywa na nyingine, ikiwa na sauti na mazoea yanayobadilika katikati. Ishara pekee ya kuaminika ni uwanja wa model katika logi ya ombi la gateway au metadata ya majibu, kwa hivyo ikiwa unatumia fallback, logi uwanja huo kwa kila ombi na uisome wakati matokeo yanapokushangaza. Kutatua tabia bila kujua ni model ipi iliyoizalisha hupoteza muda mwingi kuliko ule uliookolewa na fallback.

Mtego huohuo huathiri ufinyazaji wa muktadha (context compression). Mawakala wengi hufupisha historia ndefu kwa kuita model ndogo. Ikiwa mwito huo utabeba model tofauti au system prompt tofauti, huandika ingizo lake la cache na haiburudishi ile ya kikao kikuu, kwa hivyo zamu inayofuata kamili hulipia prefix baridi. Ufinyazaji uliokoa tokeni lakini ukapoteza cache.

Gharama ya uelekezaji (routing overhead) ni ya kweli, lakini latency si mahali ambapo huleta madhara

Router huongeza kazi kwa kila ombi, na ni vyema kuwa sahihi kuhusu kiasi hicho. DigitalOcean inaripoti kuwa mtindo wao wa Arch-Router hutatua nia ya uelekezaji (routing intent) katika takriban milisekunde 51, kwa usahihi wa 93.17% katika tathmini yao wenyewe. Hizo ni takwimu zao, kutoka kwa vipimo na benchmark yao, si zetu na si matokeo ya jumla. Zichukulie kama zilivyo na hitimisho ni la kutia moyo: milisekunde 51 katika wito wa wakala (agent calls) arobaini ni takriban sekunde mbili zilizoongezwa kwenye kazi inayochukua dakika kadhaa.

Sekunde mbili si ndizo zinazofanya uelekezaji kuwa ghali hapa. Gharama inayoumiza ni router inayofanya uainishaji kwa kutumia wito kamili wa model, kwa sababu hiyo ni inference ya pili kwa kila ombi, inayotozwa na kupangwa kwenye foleni kama nyingine yoyote. Chini ya yote hayo kuna hesabu za cache zilizotajwa hapo juu, ambazo si gharama ya ziada hata kidogo. Ni gharama ya kitu ambacho uelekezaji ulikusudiwa kukiboresha.

Kwenye seva unayojiendeshea mwenyewe, kanuni hiyo hiyo inatumika huku kukiwa na nafasi ndogo ya kubadilika. Kilinganifu cha ndani cha prompt cache ni prefix caching katika KV cache, inayokaa kwenye kumbukumbu ya GPU. Kupangisha model mbili kwenye GPU moja hugawa kumbukumbu hiyo kati yao, hivyo kila moja huhifadhi KV cache ndogo na kufuta prefix mapema zaidi. Uelekezaji kati ya model mbili za ndani unaweza hivyo kupunguza kiwango cha cache hit kwa zote mbili kwa wakati mmoja. Ikiwa unapanga ukubwa wa maunzi kwa ajili ya hili, kumbukumbu na CPU ambazo wakala wa usimbaji anahitaji kwa kweli kwenye VPS ndiyo sehemu muhimu zaidi ya kuanzia kuliko router.

Kanuni ya maamuzi

• Elekeza trafiki kupitia watoa huduma mbalimbali kwa ajili ya upatikanaji. Wakati mbadala wake ni ombi lililofeli, gharama yoyote ni sahihi. Funga (pin) mbadala kwenye modeli yenye muundo uleule wa tool call ili mzunguko wa wakala (agent's loop) uendelee kufanya kazi, na uweke kumbukumbu ya modeli iliyohudumia kila ombi.
• Elekeza trafiki kupitia viwango (tiers) tofauti kwa ajili ya gharama kwenye mipaka ya kazi pekee. Kuchagua Haiku kwa ajili ya kubadili jina na Opus kwa ajili ya refactor ni uamuzi mzuri unaofanywa mara moja, kabla ya kipindi (session) kuanza. Ni uamuzi mbaya ukifanywa katika zamu ya thelathini ya kipindi hicho.
• Funga modeli moja kwa kila kipindi kwa chochote kinachohusu wakala. Thamani ya kipindi ni cache yake iliyopo tayari. Ichukulie kubadili modeli kama unavyochukulia kufuta cache hiyo, kwa sababu ndicho kinachotokea.
• Elekeza mawakala wadogo (subagents) kwa uhuru. Wakala mdogo anayeanza na muktadha mpya na mdogo hana cache ya kupoteza, hivyo anaweza kufanya kazi kwenye modeli yoyote inayofaa kazi yake. Hii ndiyo sehemu pekee ndani ya wakala ambapo uelekezaji haugharimu chochote.

Kuhusu jinsi ya kujenga mfumo huu, gateway ndiyo inayofanya kazi hiyo: kwa kutumia model aliases na orodha za mbadala (fallback lists) zilizo wazi. Usanidi mdogo wa LiteLLM proxy unaonekana hivi.

model_list:
  - model_name: agent-primary
    litellm_params:
      model: anthropic/claude-opus-5
      api_key: os.environ/ANTHROPIC_API_KEY
  - model_name: agent-standby
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY

router_settings:
  fallbacks: [{"agent-primary": ["agent-standby"]}]
  num_retries: 2
  cooldown_time: 30

Elekeza wakala kwenye agent-primary na atabaki kwenye modeli moja hadi modeli hiyo isipopatikana. Ingizo zote mbili zipo kwa mtoa huduma yuleyule, hivyo muundo wa tool call haubadiliki wakati mbadala unapoanza kufanya kazi. Bado unakubali mabadiliko ya kiwango (tier) wakati huo, jambo ambalo ni biashara inayofaa kufanywa kwa sababu mbadala wake ni ombi lililofeli. Hiyo ni routing ya upatikanaji bila kuambatana na routing ya gharama, ambayo ndiyo mchanganyiko ambao mawakala wengi wa uandishi wa code wanautaka. Ujenzi kamili, ikijumuisha funguo (keys) na bajeti, umeelezwa katika kuendesha LiteLLM gateway iliyojihost kwenye VPS yako mwenyewe, na chapisho hili kwa makusudi halirudii maelezo hayo.

Wakati modeli moja iliyochaguliwa vyema inaposhinda router yoyote

Routing ni suluhisho la tofauti katika ugumu wa maombi. Wakala wa uandishi wa msimbo (coding agent) ana tofauti ndogo ya aina hiyo kuliko inavyoonekana, kwa sababu sehemu ya gharama kubwa ya kila wito ni prefix ileile, bila kujali ombi la wito huo. Mara tu prefix inapotawala, tofauti kati ya tier yako ya bei nafuu na tier yako ya gharama kubwa hupungua kuelekea tofauti ya bei zao za pato, na pato ni sehemu ndogo ya token za wakala.

Kwa hivyo, chaguo-msingi la uaminifu ni modeli moja, iliyochaguliwa mara moja, ikiwa na caching imewashwa na TTL (time to live) ndefu ya kutosha kufunika mapengo wakati unapoacha kusoma diff. Anthropic inatoa cache write ya saa moja kwa mara 2 ya input ya msingi, ambayo hujilipia yenyewe baada ya usomaji miwili, na hiyo mara nyingi ni lever bora kuliko router yoyote. Chagua tier kwa makusudi ukitumia ulinganisho wa moja kwa moja wa Opus, Sonnet na Haiku, na ikiwa bili bado ni tatizo, ipunguze kwa kutumia bajeti na muktadha mdogo kama ilivyo katika kudhibiti gharama za wakala wa AI kwenye VPS badala ya kubadilisha modeli katikati ya kikao.

Fanya routing wakati maombi yanajitegemea na ni mafupi, au wakati mawakala wadogo (subagents) wanaanza na muktadha mpya. Funga (pin) modeli wakati una kikao kimoja kirefu kinachofanya kazi moja. Kazi nyingi za wakala wa uandishi wa msimbo ni za aina ya pili, ndiyo sababu router inayookoa pesa kwenye bidhaa yako ya chat itakugharimu pesa kimyakimya hapa. Ikiwa bado hujachagua wakala mwenyewe, ulinganisho wa Claude Code dhidi ya Cursor, Codex na Copilot unaelezea jinsi kila mmoja anavyoshughulikia uteuzi wa modeli, na baadhi yao hufanya uamuzi huu kwa ajili yako.

FAQ

Je, kubadili modeli katikati ya kipindi cha kazi kunafuta prompt cache?

Ndiyo. Prompt caches hutegemea hash ya prefix ya prompt na huhifadhiwa kwa kila modeli, kwa hivyo ombi linalotumwa kwa modeli tofauti hulinganishwa na hifadhi ambayo haijawahi kuona prefix hiyo. Haipati chochote na inatoza gharama kamili ya input isiyo na cache, kisha inatoza gharama ya kuandika cache juu yake ikiwa caching imewezeshwa. Kubadili na kurudi kwenye modeli ya awali hakurejeshi data hiyo pia, kwa sababu muda wa kawaida wa dakika tano wa kuhifadhi data kwa kawaida huwa umekwisha. Angalia sehemu za cache_read_input_tokens na cache_creation_input_tokens katika object ya matumizi ya majibu: zamu inayosoma sifuri ya cached tokens kwenye kipindi kirefu cha kazi ni dalili ya hili.

Je, kuelekeza kazi kwenye modeli ya bei nafuu ni nafuu zaidi kwa wakala?

Ni pale tu ambapo hakuna cache iliyopo ya kupoteza. Kusoma cache kwenye Anthropic kunagharimu mara 0.1 ya input ya msingi, jambo linalofanya usomaji wa Opus 5 kuwa chini ya gharama ya input isiyo na cache kwenye Haiku 4.5. Kipindi cha kazi kinapokuwa na prefix kubwa iliyohifadhiwa, modeli inayotumika tayari ndiyo chaguo la bei nafuu kwa input. Uelekezaji wa kazi hulipa pale ambapo muktadha ni mpya na mdogo: mwanzoni mwa kazi, au katika wakala mdogo (subagent) unaobeba muktadha unaohitaji tu.

Kwa nini wakala wangu alifanya kazi tofauti katikati ya kazi?

Angalia kama gateway fallback imefanya kazi. Kikomo cha kasi (rate limit) au hitilafu ya 5xx kwenye modeli kuu huifanya gateway kujaribu tena kwenye modeli ya akiba na kuiweka modeli kuu katika hali ya kupoa (cooldown) kwa sekunde kadhaa, kwa hivyo sehemu iliyobaki ya kazi inaendelea mahali pengine. Hii haitoi hitilafu wala onyo, na kazi bado inaripoti kufanikiwa. Sehemu ya model katika logi ya ombi la gateway au metadata ya majibu ndiyo rekodi pekee ya kuaminika, kwa hivyo iweke kwenye logi kwa kila ombi ikiwa unatumia fallbacks.

Je, tool calls hufanya kazi sawa kwa kila mtoa huduma?

Si hasa. Messages API ya Anthropic hutumia content blocks za tool_use na tool_result, wakati API zinazoendana na OpenAI hutumia array ya tool_calls ambayo function.arguments yake ni string iliyosimbwa kwa JSON. Gateway hutafsiri visa vya kawaida vizuri, lakini tool calls sambamba na utekelezaji mkali wa schema hutofautiana kwa kila mtoa huduma. Kwenye vLLM inayojiendesha mwenyewe lazima uweke --enable-auto-tool-choice na --tool-call-parser inayolingana na familia ya modeli yako, na nyaraka za vLLM zinaeleza kuwa bila kizuizi kikali cha schema, seva huchota tool calls kutoka kwa maandishi ghafi, kwa hivyo hoja zinaweza kuwa na hitilafu mara kwa mara.

Ninapaswa kuweka cache TTL kwa muda gani kwa kipindi cha uandishi wa programu?

Tumia muda wa kawaida wa dakika tano kwa kazi inayoendelea, na chaguo la saa moja wakati binadamu anasoma tofauti (diffs) kati ya zamu. Anthropic hutoza gharama ya kuandika ya dakika tano kwa mara 1.25 ya input ya msingi na kuandika kwa saa moja kwa mara 2, dhidi ya usomaji wa mara 0.1. Gharama ya kuandika ya dakika tano hulipwa na usomaji mmoja, na ile ya saa moja hulipwa na usomaji miwili, kwa hivyo katika kipindi chochote cha kazi ambapo unatarajia kurudi na kuendelea, muda mrefu wa kuhifadhi data kwa kawaida hugharimu kidogo kuliko kulipia prefix baridi.