ステップ 6: エージェントハーネス

ハーネスは、エージェントが長いマルチステップ タスク (計画/実行モード、計画対象の todo リスト、コンテキスト圧縮、ファイル メモリ、ファイル アクセス、および再要求しないツールの承認) を実行するために必要なスキャフォールディングを使用してチャット クライアントをラップします。 これらのパーツを自分で組み立てる代わりに、ハーネス エージェントを作成すれば、すぐに使える状態で利用できます。

IChatClient拡張メソッドを使用して、任意のAsHarnessAgentからハーネス エージェントを作成します。 ハーネスは多くのステップにわたって対話的にタスクを処理するため、通常は会話ループでこれを動かします。つまり、ハーネスの状態（プラン、ToDo、履歴）がターンをまたいで維持されるように 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();
}

ハーネスは、会話全体にわたって計画、Todo 追跡、履歴の永続化を処理します。 ツール承認プロンプト、todo/mode レンダリング、スラッシュ コマンドを備えたフル機能のコンソールについては、 サンプルターミナル UX を参照してください。

Tip

完全に実行可能なアプリケーションについては、.NETハーネスのサンプルを参照してください。

完全なサンプルでは、Microsoft Foundry チャット クライアントを作成し、create_harness_agentでラップし、2 ターンにわたって 1 つのセッションを再利用します。 このハーネスにより、計画、to-do 追跡、圧縮が追加され、サンプルではファイル メモリと Web 検索が無効になり、フォーカスが維持されます。

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 およびモード レンダリング、スラッシュ コマンドを含むフル機能のコンソールについては、 サンプルターミナル UX を参照してください。

Tip

詳細については、完全な入門サンプルを参照してください。 その他のパターンについては、Pythonハーネスのサンプルを参照してください。

Tip

agent-framework-builder-pythonコーディングエージェントスキルは、ハーネスの構成とパッケージの選択を導くことができます。 これはランタイム エージェント スキルとは別であり、これらは引き続きオプトインの Python ハーネス機能です。

Prerequisites

  • Go 1.26 以降。
  • Agent Framework Go リポジトリのローカル チェックアウト。
  • FOUNDRY_PROJECT_ENDPOINTとFOUNDRY_MODELを使用して構成された Foundry プロジェクト エンドポイントとモデルのデプロイ。
  • DefaultAzureCredential でサポートされる Azure 資格情報。たとえば az login での Azure CLI サインインなど。

Go ハーネスを設定する

agent/harness パッケージは、通常のプロバイダーに基づくエージェントを設定します。 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.",
        },
    )

既定値には、todos、計画モードと実行モード、セッションごとに分離されたファイルメモリ、スキル、ホストされた Web 検索、ツール承認ミドルウェア、OpenTelemetry インストルメンテーションが含まれます。 ヘルパーにより、サービスごとの呼び出し履歴の永続化とメッセージの挿入も有効になります。

この Foundry サンプルは DisableStoreOutput: true を設定し、ローカル履歴が会話を管理できるようにします。 選択したプロバイダーまたはデプロイでホストされた Web 検索がサポートされていない場合は、DisableWebSearchでharness.Configを設定します。

Go リポジトリルートから完全なサンプルを実行してください。

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

このサンプルでは、2 ターンにわたってセッションを再利用し、ツール承認要求を処理し、メモリ分離を示す別のセッションを開きます。 ファイルのメモリは、作業ディレクトリの agent-file-memory の下に保持されます。

コンパクションとループは、Go ハーネスの既定値ではなくオプトイン方式です。 構成とコンポーネントの境界については、「 エージェント ハーネス」を参照してください。

Tip

複合ハーネスの完全なサンプルと Go ハーネス構成ガイドを参照してください。

次のステップ

手順 7: エージェントをホストする

より深く進む:

  • 最終更新: