代理架構是運行時的支架，將語言模型轉化為能執行工作的代理。 它能驅動模型與工具呼叫，管理對話狀態與上下文，套用核准政策，並能讓代理持續完成多步驟任務。
Agent Framework 提供一套帶有主觀意見且包含電池的束帶，用於研究、編碼、資料分析及其他長期工作。 你提供聊天客戶端，並只自訂應用程式所需的功能。
Architecture
Harness 是由現有的代理框架建構模組組成，而不是定義一個獨立的代理執行階段：
- 聊天客戶端 — 將經紀人與模特兒連結。
- 聊天管線 — 新增函式調用、訊息注入、每項服務通話歷史持久化，以及可選的壓縮功能。
- 代理與情境提供者 — 新增會話範圍指令、工具、記憶體、待辦事項狀態、操作模式及選用功能。
- 中介軟體與裝飾器——新增核准處理、可觀察性，以及可選的有界迴圈。
- 應用程式使用者體驗 — 串流回應、顯示進度，並收集工具審核等輸入。
最終產生的物件仍是一般的 Agent Framework 代理：在 .NET 中衍生自 AIAgent 的 HarnessAgent，或在 Python 中由 create_harness_agent 傳回的 Agent。 它的工作階段使用與其他代理相同的工作階段和上下文提供者抽象。
線束能力矩陣
| Capability | 背帶行為 | 標準指引 |
|---|---|---|
| 函式呼叫 | 啟用並可設定每個請求的迭代次數限制。 | 功能工具 |
| 每次服務呼叫的歷程記錄持久化 | 在工具呼叫執行過程中，每次模型呼叫後都會保存歷史紀錄。 | 會議 |
| 壓縮 | 當提供代幣限制或自訂策略時啟用。 | 壓縮 |
| 待辦事項追蹤 | 默認為啟用。 | 規劃與待辦事項 |
| 代理模式 | 預設啟用了規劃與執行模式。 | 規劃與待辦事項 |
| 檔案記憶體與檔案存取 | 預設啟用會話檔案記憶體;共享檔案存取為選擇加入方式。 | 上下文提供者 |
| 工具核准 | 預設啟用了常設批准和自動批准規則。 | 工具核准 |
| OpenTelemetry | 代理可觀察性預設為啟用。 | 可觀察性 |
| 網路搜尋 | 預設新增在所選聊天客戶端支援的地方。 | 網路搜尋 |
| 代理人技能 | 在 .NET 中預設啟用；在 Python 中則需透過提供者或路徑選擇啟用。 | 特工技能 |
| 背景代理程式 | 可選擇性地將平行委派給指定子代理。 | 背景特工 |
| Shell 執行 | 由 shell 套件構成；Python 工廠函式可自動將其串接。 | Shell 工具 |
| 迴圈 | 由評估器或謂詞驅動的可選受限重新調用。 | 代理迴圈 |
背景代理委派與提供者管理的 背景回應是分開的。 背景代理會執行子代理來處理委派的任務；背景回應會使用接續權杖來輪詢或恢復單一提供者請求。
建立一個安全帶代理
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 啟用循環。
建立一個安全帶代理
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 工具和迴圈功能也都需選擇啟用。
備註
create_harness_agent 已發布。 背景代理程式、檔案存取與迴圈仍處於實驗階段，shell 工具則來自預發布 agent-framework-tools 套件。
備註
目前沒有可用的打包版 Go Harness。 直接建立對應的 Go agent、context-provider、compaction 和 middleware 套件。 請參閱 Agent Framework Go 倉庫 以獲取目前的支援。
範例終端用戶體驗
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 Harness 終端機範例。