Agent 執行框架

代理架構，有時稱為人工智慧架構，是將語言模型轉化為能執行工作的代理的執行時支架。它能驅動模型與工具呼叫，管理對話狀態與上下文，套用核准政策，並能持續讓代理完成多步驟任務。

Agent Framework 提供一套帶有主觀意見且包含電池的束帶，用於研究、編碼、資料分析及其他長期工作。你提供聊天客戶端，並只自訂應用程式所需的功能。

Architecture

Harness 是由現有的代理框架建構模組組成，而不是定義一個獨立的代理執行階段：

聊天客戶端 — 將經紀人與模特兒連結。
聊天管線 — 新增函式調用、訊息注入、每項服務通話歷史持久化，以及可選的壓縮功能。
Agent 與上下文提供者 — 新增工作階段範圍指令、工具、記憶體、待辦事項狀態、操作模式及選用功能。
中介軟體與裝飾器 — 新增核准處理、可檢視性，以及選用的有界循環。
應用程式使用者體驗 — 串流回應、顯示進度，並收集工具審核等輸入。

最終產生的物件仍是一般的代理框架代理：在 .NET 中源自 AIAgent 的 HarnessAgent、Python 中由 create_harness_agent 傳回的 Agent，或是在 Go 中使用 harness.AgentConfig 設定、由提供者支援的 *agent.Agent。它的工作階段使用與其他代理相同的工作階段和上下文提供者抽象。

線束能力矩陣

Capability	執行框架行為	標準指引
函式叫用	啟用並可設定每個請求的迭代次數限制。 Go 提供者建構函式負責管理工具叫用迴圈。	功能工具
每次服務呼叫的歷程記錄持久化	在工具呼叫執行過程中，每次模型呼叫後都會保存歷史紀錄。	會議
壓縮	當在 .NET 和 Python 中提供代幣限制或自訂策略時，該功能會啟用。 Go 需要明確的提供者組合。	壓縮
待辦事項追蹤	默認為啟用。	規劃與待辦事項
代理模式	預設啟用了規劃與執行模式。	規劃與待辦事項
檔案記憶體與檔案存取	預設會啟用工作階段檔案記憶體；共用檔案存取為主動選擇加入。	上下文提供者
工具核准	預設啟用了常設批准和自動批准規則。	工具核准
OpenTelemetry	代理可觀察性預設為啟用。	可觀察性
網路搜尋	預設新增在所選聊天客戶端支援的地方。	網路搜尋
代理人技能	在 .NET 和 Go 中預設為啟用；在 Python 中則透過提供者或路徑選擇加入。	特工技能
背景代理程式	在 .NET 和 Python 中，可選擇平行委派給具名子代理。沒有封裝的 Go 背景 Agent 提供者。	背景特工
殼層執行	由 shell 套件構成；Python 工廠函式可自動將其串接。	Shell 工具
迴圈	由評估工具或謂詞驅動的選用有界重新叫用。	代理迴圈

背景代理委派與提供者管理的背景回應是分開的。背景 Agent 會執行子Agent 來處理委派的工作；背景回覆會使用接續權杖來輪詢或恢復單一提供者要求。

Tip

若要取得可協助建構 Python 控制框架應用程式的編碼代理程式指引，請安裝 agent-framework-builder-python。這項外部編碼代理技能與矩陣中列出的執行階段 Agent Skills 功能是分開的。

建立一個執行框架 Agent

Microsoft.Agents.AI.Harness 套件會在 Microsoft.Agents.AI 命名空間中公開 HarnessAgent。使用AsHarnessAgent從任何IChatClient建立一個，或直接建構HarnessAgent：

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

AIAgent agent = chatClient.AsHarnessAgent();

AgentResponse response = await agent.RunAsync("Plan a weekend trip to Seattle.");
Console.WriteLine(response.Text);

用 HarnessAgentOptions 以設定線束層級的操作指引、代理專屬指令及功能選項：

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    Name = "research-agent",
    HarnessInstructions = "Use tools deliberately and report verified results.",
    ChatOptions = new ChatOptions
    {
        Instructions = "You are a research assistant focused on academic sources.",
    },
    MaxContextWindowTokens = 128_000,
    MaxOutputTokens = 16_384,
});

HarnessAgent.DefaultInstructions 提供預設的安全帶指引。 HarnessInstructions 出現在 ChatOptions.Instructions之前。

自訂構圖

預設功能包含特定選項，包括 DisableTodoProvider、DisableAgentModeProvider、DisableFileMemory、DisableAgentSkillsProvider、DisableWebSearch、DisableToolAutoApproval、DisableOpenTelemetry，以及 DisableCompaction。

使用 AIContextProviders 新增自訂上下文提供者。選擇使用 FileAccessStore 啟用檔案存取、使用 BackgroundAgents 啟用背景委派，以及使用 LoopEvaluators 啟用循環。

建立一個執行框架 Agent

create_harness_agent 工廠會回傳已完成設定的 Agent：

from agent_framework import create_harness_agent
from agent_framework.openai import OpenAIChatClient

agent = create_harness_agent(
    client=OpenAIChatClient(model="gpt-4o"),
)

session = agent.create_session()
response = await agent.run("Plan a weekend trip to Seattle.", session=session)
print(response.text)

分別設定線束層級與代理專屬指令：

agent = create_harness_agent(
    client=client,
    name="research-agent",
    harness_instructions="Use tools deliberately and report verified results.",
    agent_instructions="You are a research assistant focused on academic sources.",
    max_context_window_tokens=128_000,
    max_output_tokens=16_384,
)

DEFAULT_HARNESS_INSTRUCTIONS 提供預設的安全帶指引。 harness_instructions 出現在 agent_instructions之前。

自訂構圖

以 disable_todo、disable_mode、disable_file_memory、disable_web_search、disable_tool_auto_approval 和 disable_compaction 等選項來停用預設值。

將內建供應商替換為 todo_provider 或 mode_provider，並將供應商 context_providers加入。技能需透過 skills_provider 或 skills_paths 選擇啟用；檔案存取、背景代理程式、Shell 工具和迴圈功能也都需選擇啟用。

檔案存取預設會將所提供的儲存區作為一個共用工作區使用。若要依據活動會話 ID 隔離檔案，請啟用會話範圍檔案存取：

from agent_framework import FileSystemAgentFileStore, create_harness_agent

file_store = FileSystemAgentFileStore("agent-files")
agent = create_harness_agent(
    client=client,
    file_access_store=file_store,
    file_access_session_scoped=True,
)

若要在選定的會話間有意分享，請直接建構 FileAccessProvider(store=file_store, scope="tenant-1") 並透過 context_providers加入。作用域是一個不透明的金鑰，對應到提供者管理的資料夾，而非路徑。當沒有作用中的工作階段 ID，也未明確指定範圍時，限定範圍的存取會拒絕存取，而不會使用共用存放區根目錄。

當一個代理擁有多個檔案存取提供者時使用 tool_name_prefix 。前綴會產生例如 workspace_file_access_read 這樣的名稱，並防止工具名稱的碰撞。對於前綴提供者，請使用提供者專屬的核准規則工廠，使每條規則與該提供者產生的名稱相符：

from agent_framework import FileAccessProvider, create_harness_agent

workspace = FileAccessProvider(
    store=file_store,
    tool_name_prefix="workspace",
)

agent = create_harness_agent(
    client=client,
    context_providers=[workspace],
    auto_approval_rules=[workspace.get_read_only_tools_auto_approval_rule()],
)

get_all_tools_auto_approval_rule() 為讀寫工具建立等效規則。除非儲存邊界和工具輸入是可信的，否則請保持寫入批准開啟。

當已啟用檔案存取時，可使用 file_access_grep 尋找以 1 為起算的行號、使用 file_access_read_lines 檢查含起訖值的範圍，以及使用 file_access_replace_lines 編輯整行。 file_access_read_lines 會在每一行前面加上該行的行號和一個定位字元；將該行文字作為 expected_line 傳遞時，請省略此前綴。預期的文字可防止過時或不匹配的行號編輯錯誤行。

file_access_grep 使用大小寫不區分的正則表達式，接受最多 256 個字元的模式，並對整個搜尋套用 10 秒的預算。無效或過長的模式，以及超出預算的搜尋結果會回傳錯誤。在重試前先縮小目錄或模式範圍。

這很重要

file_access_grep 回傳與行終結符相符的行文字。自訂的 AgentFileStore.search() 實作必須傳回從 1 開始的行號，且在 AgentFileStore.split_lines() 傳回的文字中，這些行號所對應的行必須與 read() 所對應的行相同。

備註

create_harness_agent 已發布。背景代理程式、檔案存取與迴圈仍處於實驗階段，shell 工具則來自預發布 agent-framework-tools 套件。

Go agent/harness 套件組裝了中介軟體、情境提供者，以及一般的、由提供者支援的代理程式的歷史預設值。呼叫 harness.AgentConfig(harness.Config{}, agent.Config{...})，處理其錯誤，並將回傳的配置傳給提供者建構器。它不會引入獨立的代理類型或工具執行迴圈。

建立一個執行框架 Agent

複合範例會設定 Foundry 支援的控制框架 Agent：

import (
    "context"
    "fmt"
    "os"
    "path/filepath"

    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/agent/harness"
    "github.com/microsoft/agent-framework-go/examples/internal/demo"
    "github.com/microsoft/agent-framework-go/message"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"
)
    workingDirectory, err := os.Getwd()
    if err != nil {
        return fmt.Errorf("get working directory: %w", err)
    }
    cfg, err := harness.AgentConfig(harness.Config{WorkingDirectory: workingDirectory}, agent.Config{
        Name:        "HarnessAssistant",
        Middlewares: []agent.Middleware{logger},
    })
    if err != nil {
        return err
    }
    a := foundryprovider.NewAgent(
        demo.FoundryProjectEndpoint,
        demo.FoundryTokenCredential(),
        foundryprovider.ModelDeployment(demo.FoundryModel),
        foundryprovider.AgentConfig{
            Config:             cfg,
            DisableStoreOutput: true,
            Instructions:       "Help with software engineering tasks. Use memory and todos to track the current session's work.",
        },
    )

自訂構圖

該協助程式會使用以下預設值：

Component	Go 控制框架預設值
Planning	工作階段支援的待辦事項工具與規劃/執行模式 (從規劃模式開始)
檔案記憶體	`agent-file-memory` 下的持續性檔案，每個工作階段皆有隔離的工作資料夾
Skills	從工作目錄進行檔案支援的探索 (排除記憶體子樹狀結構)
網路搜尋	裝載的網頁搜尋宣告 (除非呼叫端已提供該宣告)
Approval	針對需要核准的工具提供常設核准與自動核准中介軟體
History	具備按服務呼叫持續性的記憶體內部歷程記錄
訊息注入	按 Agent 的 `agent.MessageInjector`
追蹤	Agent、工具與支援的模型呼叫檢測

用 harness.Config 來停用元件或覆寫其設定。當所選服務或部署不支援託管網頁搜尋時，停用託管網頁搜尋。檔案支援的技能指令碼需要明確設定的指令碼執行器。

輔助程式保留呼叫端工具、中介軟體、上下文提供者及明確設定的歷史提供者。在 Foundry 模型部署中，當本機歷程記錄主導對話時，請使用 DisableStoreOutput: true。

Go 協助程式不會新增壓縮、迴圈及殼層工具。需要時明確設定它們。其他 SDK 中描述的打包式背景代理委派提供者在 Go 中無法使用。

請參考「建立 Go harness 代理程式」來進行設定，以及Go harness 設定指南中的預設值與覆寫。

範例終端用戶體驗

Harness 並未預先規定應用程式介面。該儲存庫包含範例終端機應用程式，可串流輸出、顯示待辦事項與當前模式、表面工具核准提示，並提供如 /todos、 /mode、 /exit等指令。

這很重要

這些主控台專案只是範例，並非正式交付的框架元件。把它們當作可執行的範例，或是你自己終端機體驗的起點。

.NET 範例入口為HarnessConsole.RunAgentAsync：

using Harness.Shared.Console;

await HarnessConsole.RunAgentAsync(
    agent,
    userPrompt: "Ask me anything to get started.");

使用觀察器、工具格式化器、指令處理程式和 HarnessConsoleOptions 來自訂範例。請參閱 .NET 線束範例。

Python 範例使用基於console文本的套件，與 Harness 範例並列：

from console import run_agent_async

await run_agent_async(agent)

透過觀察器、格式化器、指令和使用者介面元件來自訂範例。請參閱 Python Harness 範例。

Go 存放庫包含具有核准處理機制的複合控制框架範例，以及獨立的互動式聊天 CLI 示範。聊天 CLI 使用普通代理;它並非 C# 或 Python Harness 主控台的等價物。

下一步

規劃工作並追蹤待辦事項

深入了解

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-11-01

Agent 執行框架

Architecture

線束能力矩陣

建立一個執行框架 Agent

自訂構圖

建立一個執行框架 Agent

自訂構圖

建立一個執行框架 Agent

自訂構圖

範例終端用戶體驗

下一步

深入了解

意見反應

其他資源