Agenvoy v1.0.27 Release Notes
v1.0.26 -> v1.0.27
Summary
Every tool now ships with its full parameter schema in the initial tool list. On-demand schema loading is still the goal; this release is the interim step taken while the core tool set is small enough to afford it.
翻譯
所有工具現在都在初始工具清單中帶完整參數 schema。依需載入仍是目標，本版是在核心工具數量還夠少的時候採取的過渡做法。
Why the interim step
Deferred tool loading has shipped since v0.17.3: unloaded tools went out as a name and a description with an empty parameter object, and find_tools(mode=search) swapped the real schema in on first use. With cache reuse now the priority, that swap is the bottleneck, so the tool list goes out complete instead.
- Swapping the schema into the tool list rewrote a block that is serialized ahead of the messages, so every lookup invalidated the whole prompt cache — four breaks in one 27-turn session, each re-ingesting 24K–57K tokens at full price.
- Delivering the schema as tool output instead kept the cache intact but broke the calls.
codex@honours only what the tool list declares: an empty parameter object makes it send{}for every argument, and a tool absent from the list is never called at all. Both arms were measured againstgpt-6-luna.
Sending everything up front costs a larger constant prefix. With the core tool set alone, the cold first send goes from roughly 16K tokens to 21K, measured on codex@gpt-6-luna; any tools registered beyond the core add to that, and token counts are not comparable across models because each tokenizes the same text differently. Whatever its size, that prefix is served from cache on every later send — one measured session: 11 sends, 87.2% cache hit, no breaks.
Two further findings tip the balance. In a long loop, reaching a tool for the first time re-cached everything the loop had already accumulated, so the later a tool is first touched, the more the swap costs. And since v1.0.0 the tool descriptions and prompts have been condensed, bringing the default payload down on its own. Against a prefix that is already small, withholding schema now costs more than it saves — deferred loading has become a drag rather than a saving.
Deferred loading is still the right end state for a registry much larger than today's. Reaching it needs a mechanism that a provider will honour without a declaration in the tool list; until then the tool list stays complete and immutable.
翻譯
依需載入自 v0.17.3 起實裝：未載入的工具只送名稱與描述並帶空參數物件，真正的 schema 在首次使用時由 find_tools(mode=search) 換進工具清單。現階段以最大化快取為優先，這個抽換動作成為瓶頸，因此改為工具清單一次送完整。
- 把 schema 換進工具清單等於改寫一個序列化在 messages 之前的區塊，每次查詢都讓整份 prompt 快取失效——一個 27 輪的 session 斷了四次，每次全價重吃 24K–57K token。
- 改以工具回傳交付 schema 雖然保住快取，卻讓呼叫失效。
codex@只認工具清單裡的宣告：空參數物件會讓它每個參數都送{}，而不在清單裡的工具則完全不會被呼叫。兩個方向都以gpt-6-luna實測。
全量送出的代價是固定前綴變大。以核心工具集、codex@gpt-6-luna 實測，冷啟首次送出由約 16K token 增為 21K；核心以外另行註冊的工具會再往上加，且跨模型不可比較——同一份文字各家 tokenizer 切出的 token 數不同。無論多大，這段前綴在後續每次送出都由快取提供：一次實測 session，11 次送出、87.2% 命中、零斷點。
另有兩項實測結果讓天平更偏。長回圈中首次碰到一個工具時，先前回圈累積的結果會被整批重新快取，所以工具越晚被碰到，抽換的代價越大。加上自 v1.0.0 起工具描述與 prompt 大幅濃縮精簡，預設 payload 本身已明顯縮減。在前綴已經夠小的前提下，延後交付 schema 省下的比付出的少——依需載入已經是拖累，不再是節省。
工具規模遠大於現在時，依需載入仍是正確的終點，但需要一個不必在工具清單宣告、provider 也會認的機制；在那之前，工具清單維持完整且不可變。
Changes
UPDATE
- Load every tool with its full parameter schema as an interim step (@pardnchiu) [f8e93113]
翻譯
- 所有工具改為在初始工具清單帶完整參數 schema，此為過渡處理，依需載入仍在測試中
REFACTOR
- Return searched tool schemas in conversation content while keeping the executor tool list unchanged, preserving prompt-cache stability (@pardnchiu) [c19f1c4c]
- Simplify tool-call handling and make tool discovery accept search-result schema context (@pardnchiu) [c19f1c4c]
翻譯
- 在對話內容中回傳搜尋到的工具結構，同時維持 executor 工具清單不變，以穩定提示快取
- 簡化工具呼叫處理，並讓工具探索流程接收搜尋結果中的結構資訊
Scope
internal/tools/— UPDATE, REFACTOR (executor.go,searcher/)internal/agents/exec/— REFACTOR (toolCall.go)doc/— DOC
Generated by version-generate