하네스는 채팅 클라이언트를, 에이전트가 길고 여러 단계로 이루어진 작업을 처리하는 데 필요한 기반 기능들(계획/실행 모드, 계획을 위한 할 일 목록, 컨텍스트 압축, 파일 메모리, 파일 액세스, 다시 묻지 않기 도구 승인)로 감싸는 구성 요소입니다. 이러한 조각을 직접 조립하는 대신, 하네스 에이전트를 만들어서 상자 밖으로 내보낼 수 있습니다.
IChatClient 확장 메서드를 사용하여 임의의 AsHarnessAgent에서 하니스 에이전트를 생성합니다. 하네스는 여러 단계에 걸쳐 작업을 대화형으로 처리하므로, 일반적으로 대화 루프를 통해 이를 구동합니다. 즉, 여러 턴에 걸쳐 하네스 상태(계획, 할 일, 기록)가 유지되도록 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 Harness 샘플을 참조하세요.
전체 샘플은 Microsoft Foundry 채팅 클라이언트를 만들고 create_harness_agent로 래핑하고, 한 세션을 두 번의 턴에 걸쳐 재사용합니다. 이 도구는 계획, to-do 추적 및 압축을 추가하는 반면 샘플은 파일 메모리 및 웹 검색을 비활성화하여 포커스를 유지합니다.
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 Harness 샘플을 참조하세요.
Tip
agent-framework-builder-python 코딩 에이전트 스킬은 하네스 구성 및 패키지 선택을 안내할 수 있습니다. 옵트인 Python 하네스 기능으로 유지되는 런타임 에이전트 스킬과는 별개입니다.
Prerequisites
- Go 1.26 이상.
- 에이전트 프레임워크 Go 리포지토리의 로컬 체크 아웃입니다.
-
FOUNDRY_PROJECT_ENDPOINT및FOUNDRY_MODEL을 통해 구성된 Foundry 프로젝트 엔드포인트 및 모델 배포입니다. -
az login이(가) 있는 Azure CLI 로그인과 같이DefaultAzureCredential에서 지원하는 Azure 자격 증명.
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.",
},
)
기본값으로는 할 일, 계획 및 실행 모드, 세션 격리 파일 메모리, skills, 호스팅된 웹 검색, 도구 승인 미들웨어 및 OpenTelemetry 계측이 포함됩니다. 이 헬퍼는 서비스 호출 기록의 영구 저장 및 메시지 주입 기능도 제공합니다.
이 Foundry 샘플 세트는 지역 기록이 대화의 중심이 되도록 DisableStoreOutput: true을(를) 설정합니다. 선택한 공급업체 또는 배포 환경에서 호스팅 웹 검색을 지원하지 않는 경우 harness.Config에서 DisableWebSearch을(를) 설정하세요.
Go 리포지토리 루트에서 전체 샘플을 실행합니다.
go run .\examples\02-agents\harness\step04_composite_harness
샘플은 두 턴에서 세션을 다시 사용하고, 도구 승인 요청을 처리하고, 메모리 격리를 보여 주는 별도의 세션을 엽니다. 파일 메모리는 작업 디렉터리 아래의 agent-file-memory에 유지됩니다.
압축 및 루핑은 Go harness 기본값이 아닌 옵트인입니다. 구성 및 구성 요소 경계는 에이전트 Harness를 참조하세요.
Tip
전체 복합 하네스 샘플 및 Go harness 구성 가이드를 참조하세요.
다음 단계
더 자세히 살펴보기: