步驟六：特工安全帶

執行框架 (harness) 將聊天用戶端與代理程式處理漫長、多步驟工作所需的基礎結構結合在一起 — 包含規劃/執行模式、用來擬定計劃的待辦事項清單、內容壓縮、檔案記憶、檔案存取，以及「不再詢問」的工具核准機制。 與其自己組裝這些元件，不如建立一個 Harness Agent，即可直接使用這些現成功能。

使用 AsHarnessAgent 擴充功能方法從任何 IChatClient 建立 Harness Agent。 因為執行框架會透過多個步驟以互動方式執行工作，所以通常會透過交談迴圈來驅動它：保留一個 AgentSession，讓執行框架的狀態 (計劃、待辦事項和歷程記錄) 能在多回合交談間持續保存，讀取使用者的下一個指令，並在代理程式產生輸出時以串流方式傳送。

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

// chatClient is any IChatClient implementation (Foundry, Azure OpenAI, OpenAI, Anthropic, ...).
AIAgent agent = chatClient.AsHarnessAgent();

// A session carries the harness state (plan, todos, history) across turns.
AgentSession session = await agent.CreateSessionAsync();

Console.WriteLine("Harness agent ready. Type 'exit' to quit.");
while (true)
{
    Console.Write("> ");
    string? input = Console.ReadLine();
    if (string.IsNullOrWhiteSpace(input) || input.Equals("exit", StringComparison.OrdinalIgnoreCase))
    {
        break;
    }

    // Stream this turn's output as the harness plans and works through the request.
    await foreach (var update in agent.RunStreamingAsync(input, session))
    {
        Console.Write(update);
    }

    Console.WriteLine();
}

這個執行框架負責整個交談的規劃、待辦事項追蹤和歷程記錄的保存。 如需功能完整的主控台——包含工具核准提示訊息、待辦事項／模式顯示，以及斜線指令——請參閱 終端機 UX 範例。

Tip

完整可執行應用請參閱 .NET 線束範例。

完整範例建立 Microsoft Foundry 聊天客戶端，並以 create_harness_agent 包裝，並在兩個互動回合中重複使用同一個工作階段。 此測試框架會新增規劃、待辦事項追蹤和壓縮功能，而範例則會停用檔案記憶體和網頁搜尋，以保持聚焦。

import asyncio

from agent_framework import create_harness_agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential


async def main() -> None:
    agent = create_harness_agent(
        client=FoundryChatClient(
            project_endpoint="https://your-account.services.ai.azure.com/api/projects/your-project",
            model="gpt-6-luna",
            credential=AzureCliCredential(),
        ),
        agent_instructions="Help users plan and complete multi-step tasks.",
        disable_file_memory=True,
        disable_web_search=True,
    )
    session = agent.create_session()

    print(await agent.run("Plan a weekend trip to Seattle.", session=session))
    print(await agent.run("Turn that plan into a checklist.", session=session))


if __name__ == "__main__":
    asyncio.run(main())

共用工作階段會在兩個呼叫之間保留測試框架狀態。 若想看功能完整的主控台——包含工具核准提示、to-do 與模式渲染，以及斜線指令——請參考 範例終端機使用者體驗。

Tip

請參閱 完整的入門範例。 如需更多模式，請參考 Python harness 範例。

Tip

agent-framework-builder-python 編碼代理程式技能可引導執行環境組合與套件選擇。 它與執行時的代理技能（Agent Skills）是分開的，後者仍是需選擇啟用的 Python harness 功能。

Prerequisites

  • Go 1.26 或更高版本。
  • Agent Framework Go 倉庫的本地檢出。
  • 一個 Foundry 專案端點與模型部署，透過FOUNDRY_PROJECT_ENDPOINT和FOUNDRY_MODEL進行設定。
  • DefaultAzureCredential 所支援的 Azure 認證，例如使用 az login 進行的 Azure CLI 登入。

設定 Go 控制框架

agent/harness 套件會設定由提供者支援的一般 Agent。 將 harness.AgentConfig 的結果傳給提供者建構子：

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.",
        },
    )

預設值包含待辦事項、規劃與執行模式、工作階段隔離的檔案記憶體、技能、託管網頁搜尋、工具核准中介軟體，以及 OpenTelemetry 檢測。 該輔助工具同時啟用每項服務呼叫歷史的持久性與訊息注入功能。

此 Foundry 範例會設定 DisableStoreOutput: true，讓本機歷程記錄掌控交談內容。 如果你選擇的供應商或部署不支援託管網頁搜尋，請在harness.Config中設定DisableWebSearch。

從 Go 倉庫根執行完整範例：

go run .\examples\02-agents\harness\step04_composite_harness

範例在兩回合重複使用一個會話，處理工具核准請求，並開啟獨立會話以展示記憶體隔離。 檔案記憶體會持續儲存在工作目錄下的 agent-file-memory 中。

壓縮和迴圈需自行啟用，而非 Go harness 的預設值。 關於配置與元件邊界，請參見 Agent Harness。

Tip

請參閱 完整的複合 harness 範例 與 Go harness 設定指南。

下一步

步驟 7：託管您的代理程式

深入探討：

  • 上次更新時間：