代理工具是运行时基架，可将语言模型转换为可执行工作的代理。 它驱动模型和工具调用，管理聊天状态和上下文，应用审批策略，并可以让代理继续执行多步骤任务。
代理框架为研究、编码、数据分析和其他长时间运行的工作提供一个采用预设配置且开箱即用的工具套件。 提供聊天客户端并仅自定义应用程序所需的功能。
Architecture
Harness 由现有的 Agent Framework 构建模块组合而成，而不是定义一个独立的代理运行时：
- 聊天客户端 - 将代理连接到模型。
- 聊天管道 - 添加函数调用、消息注入、按服务调用历史记录持久性和可选压缩。
- 代理和上下文提供程序— 添加会话范围的指令、工具、内存、待办事项状态、操作模式和可选功能。
- 中间件和修饰器 — 添加审批处理、可观测性和可选的有界循环。
- 应用程序用户体验 — 流式传输响应、显示进度，并收集工具批准等输入。
生成的对象仍然是普通的 Agent Framework 代理：HarnessAgent派生自AIAgent.NET中的代理或Agent由Python返回的create_harness_agent代理。 其会话使用与其他代理相同的 会话 和 上下文提供程序 抽象。
Harness 功能矩阵
| Capability | 工具套件行为 | 权威指南 |
|---|---|---|
| 函数调用 | 支持针对每个请求配置迭代次数上限。 | 函数工具 |
| 每次服务调用的历史记录持久化 | 在一次工具调用运行中，每次模型调用后都会持久保存历史记录。 | 会话 |
| 压 实 | 在提供令牌限制或自定义策略时启用。 | 压缩 |
| 待办事项跟踪 | 默认启用。 | 规划和待办事项 |
| 代理模式 | 默认情况下启用计划和执行模式。 | 规划和待办事项 |
| 文件内存和文件访问 | 会话文件记忆功能默认启用；共享文件访问需手动启用。 | 上下文提供程序 |
| 工具审批 | 默认情况下会启用永久审批和自动审批规则。 | 工具审批 |
| OpenTelemetry | 代理可观测性默认处于启用状态。 | 可观察性 |
| Web 搜索 | 在所选聊天客户端支持的情况下默认添加。 | Web 搜索 |
| 智能体技能 | 在 .NET 中默认启用；在 Python 中通过提供程序或路径选择启用。 | 代理技能 |
| 后台代理 | 可以选择向已命名的子代理并行委托任务。 | 后台代理 |
| 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、、DisableAgentModeProviderDisableFileMemory、DisableAgentSkillsProviderDisableWebSearch、DisableToolAutoApproval、和DisableOpenTelemetryDisableCompaction。
使用 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 工具套件。 直接编写相应的 Go 代理、上下文提供程序、压缩和中间件包。 有关当前支持，请参阅 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 Harness 示例。
Python 示例在工具套件示例旁使用基于 Textual 的console包：
from console import run_agent_async
await run_agent_async(agent)
使用观察器、格式化器、命令和用户界面组件来自定义示例。 请参阅 Python Harness 示例。
存储库当前不包括打包的 Go Harness 终端示例。