CodeAct 讓代理程式透過撰寫程式碼並透過 execute_code 工具執行任務來解決。 CodeAct 不再要求模型一次只呼叫一個工具，而是提供一個沙盒空間，將控制流程、資料轉換與工具協調整合整合於單一執行步驟中。
在 Agent Framework 中，CodeAct 是透過後端專屬套件公開，而非單一內建的核心型別。 連接器可以新增工具 execute_code 、注入執行時指引，並可選擇性地暴露可從沙盒內部呼叫的提供者自有工具。
為什麼選擇 CodeAct
現代 AI 代理程式的瓶頸往往不在模型品質，而在編排開銷。 當代理串連多個小型工具呼叫時，每一步通常需要另一個模型回合，這會增加延遲與令牌使用量。
CodeAct 會把模型 - > 工具 -> 模型的循環壓縮。 Agent Framework 不再要求模型一次選擇一個工具，而是可以只暴露一個 execute_code 工具，讓模型以短程式形式表達完整計畫。 工具不變，模型不變，主要的改變是計畫只在沙盒內執行一次，而不是分散在多個工具呼叫回合中。
對於工具密集的工作負載，這項變更能大幅降低端到端延遲與令牌使用，同時保持計畫精簡且可檢視於單一程式碼區塊中。 請參閱 Hyperlight CodeAct 整合以取得並排配線比較。
當 CodeAct 適合你時
當任務受益於以下條件時，請使用 CodeAct：
- 結合多個工具呼叫，透過迴圈、分支、過濾或聚合進行操作
- 在返回最終答案之前轉換工具的結果
- 在執行過程中產生較大的結構化輸出或產物
- 保留部分工具僅在受控執行環境中使用。
- 將許多小型、可串接的查詢或輕量級運算整合到一個執行步驟中
在以下情況時持續使用直接工具呼叫：
- 這個工作只需要一到兩次工具呼叫，移除時所產生的協調流程額外負荷微乎其微
- 每次通話都有副作用，應該對模特兒和使用者都一目了然
- 您需要每次呼叫的核准提示，而不是整個
execute_code執行中只有一個核准決策
CodeAct 在 Agent Framework 中的定位
CodeAct 連接器通常在一次運行中執行四件事：
- 新增一個
execute_code工具到模型面向工具介面。 - 提供已配置沙盒運行環境的指令。
- 可選擇性地透過
call_tool(...)暴露提供者自有的工具。 - 套用功能限制，例如檔案系統存取或外發網路允許清單。
因為連接器擁有執行時的設定，具體設定細節取決於你選擇的後端。
目前的限制
CodeAct 很適合工具密集的工作流程，但請記得以下幾點限制：
- 文件中所記載的 Agent Framework 連接器是 Hyperlight CodeAct，支援 Python 和 .NET（預覽版）。
- 目前核准作為一個整體適用於
execute_code呼叫。 如果你需要逐一核准個別操作，請將這些操作作為直接代理工具，而非依賴call_tool(...)。 - 透過
call_tool(...)觸達的工具仍可在主機處理序中執行。 使用受限且經過審查的主機工具來處理敏感的輸入/輸出，而不是不必要地擴大沙盒存取。 - 當流程協調額外負荷主導時，CodeAct 表現最佳。 對於只有一兩個工具呼叫的小任務，額外的抽象可能不值得。
- 工具名稱、參數元資料和回傳形狀在這裡更為重要，因為模型是根據該合約來撰寫程式碼，而不是逐個選擇單一工具呼叫。
開始
對於 .NET，目前文件記載的連接器是 Hyperlight CodeAct，並以 Microsoft.Agents.AI.Hyperlight 套件形式提供。
該套件包含：
-
HyperlightCodeActProvider— 一個會在每次執行時注入execute_code和 CodeAct 指引的AIContextProvider -
HyperlightExecuteCodeFunction— 當沙箱組態為固定時，用於靜態/手動配線的獨立AIFunction - 提供者管理的工具仍可在沙箱內透過
call_tool(...)取得 -
CodeActApprovalMode以及ApprovalRequiredAIFunction整合以進行核准 - 沙盒執行時的選用檔案系統（
FileMounts、HostInputDirectory）與對外網路（AllowedDomains）設定
Important
.NET套件目前還在預覽階段，依賴Hyperlight.HyperlightSandbox.Api尚未在 nuget.org 上發布的 NuGet。 請參閱 Hyperlight CodeAct 以了解目前的安裝注意事項與平台要求。
請參閱 Hyperlight CodeAct 以了解安裝、範例及執行時專用指引。
開始
目前 Python 的官方文件連接器是 Hyperlight CodeAct。
Hyperlight 套件提供：
-
HyperlightCodeActProvider適用於基於上下文提供者的執行 -
HyperlightExecuteCodeTool當你想直接接線execute_code時 - 提供者管理的工具仍可在沙箱內透過
call_tool(...)取得 - 沙盒執行時可選用的檔案系統與外撥網路設定
請參閱 Hyperlight CodeAct 以了解安裝、範例、執行時專用指引（如何時使用 print(...) 和 /output/），以及目前 Hyperlight 專屬限制。
Note
Go 對此功能的支援即將推出。 最新狀態請參閱 Agent Framework Go 倉庫 。