에이전트 하네스

하네스 에이전트 만들기

하네스는 HarnessAgent 네임스페이스(Microsoft.Agents.AI 패키지)의 Microsoft.Agents.AI.Harness 클래스로 노출됩니다. 가장 간단한 방법은 어떤 IChatClient에서든 AsHarnessAgent 확장 메서드를 사용하여 이를 만드는 것입니다:

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

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

AgentResponse response = await agent.RunAsync("Plan a weekend trip to Seattle.");
Console.WriteLine(response.Text);

에이전트를 직접 생성할 수도 있습니다.

AIAgent agent = new HarnessAgent(chatClient);

지침과 도구를 제공할 수 있도록 HarnessAgentOptions을(를) 제공합니다. 하네스 수준의 지침(HarnessAgentOptions.HarnessInstructions)은 일반적인 운영 지침을 설명하며, 반면 작업별 지침은 ChatOptions.Instructions에 제공됩니다. HarnessAgent에는 기본 하네스 수준 지침(HarnessAgent.DefaultInstructions)이 함께 제공되지만, HarnessAgentOptions.HarnessInstructions를 통해 사용자 지정 지침으로 재정의할 수 있습니다.

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    Name = "research-agent",
    ChatOptions = new ChatOptions
    {
        Instructions = "You are a research assistant focused on academic sources.",
        Tools = [AIFunctionFactory.Create(GetStockPrice)],
    },
});

컴팩션 활성화

압축은 긴 도구 호출 루프가 컨텍스트 창을 오버플로하는 것을 방지합니다. 유추 서비스 저장 채팅 기록을 사용하지 않는 경우 세션 저장된 채팅 기록도 압축되도록 기본값 InMemoryChatHistoryProvider 도 동일한 압축 공급자로 제공됩니다. 기본 토큰-예산 인식 전략을 사용하도록 설정하려면 최대 컨텍스트 창 크기와 최대 출력 크기를 모두 제공합니다.

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    MaxContextWindowTokens = 128_000,
    MaxOutputTokens = 16_384,
});

사용자 지정 전략을 사용하려면 HarnessAgentOptions.CompactionStrategy로 설정하고, 컴팩션을 끄려면 DisableCompaction = true로 설정합니다.

기능 사용자 지정 및 사용 안 림

모든 기본 기능에는 해당하는 비활성화 플래그 HarnessAgentOptions가 있으므로 원하는 파이프라인을 유지하고 나머지는 삭제할 수 있습니다.

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    HarnessInstructions = "Custom operating guidelines here.",
    DisableTodoProvider = true,      // No todo list
    DisableAgentModeProvider = true, // No plan/execute modes
    DisableWebSearch = true,         // No hosted web search tool
    DisableFileMemory = true,        // No file-based session memory
});

다른 플래그에는 DisableFileAccess, DisableAgentSkillsProvider및 DisableToolAutoApprovalDisableOpenTelemetry. 을 통해 사용자 고유의 컨텍스트 공급자를 추가하고 을 통해 AIContextProvidersAgentSkillsSource사용자 지정 위치에서 기술 공급자를 가리킬 수도 있습니다.

완료될 때까지 반복

기본적으로 하네스는 호출당 한 번 실행됩니다. 평가자가 완료를 결정할 때까지 에이전트를 자동으로 다시 호출하는 하나 이상의 LoopEvaluator 인스턴스를 제공합니다(예: 완료 표식이 나타나면 조건자가 충족되거나 AI 판사가 승인함).

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    LoopEvaluators = [new CompletionMarkerLoopEvaluator("DONE")],
});

루프는 가장 바깥쪽 에이전트 데코레이터로 적용되므로 각 반복은 독립적으로 도구 승인 및 추적된 완전 에이전트 실행입니다.

셸 및 백그라운드 에이전트

에이전트가 셸 명령을 실행할 수 있도록 하려면 ShellExecutor를 전달하세요. 그러면 승인 제어 셸 실행 도구와 OS, 셸 및 작업 디렉터리 정보를 컨텍스트에 삽입하는 공급자가 추가됩니다.

using Microsoft.Agents.AI.Tools.Shell;

// A shell confined to a working directory. Commands require approval by default;
// the deny-list is a UX pre-filter, not a security boundary.
await using var shell = new LocalShellExecutor(new LocalShellExecutorOptions
{
    WorkingDirectory = workingDir,
    ConfineWorkingDirectory = true,
    Policy = new ShellPolicy(denyList: [@"\brm\s+-rf\b", @"\bsudo\b"]),
});

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    ShellExecutor = shell,
});

병렬 위임을 사용하도록 설정하려면 백그라운드 에이전트 집합을 전달합니다. 에이전트는 동시 실행을 위해 하위 작업을 수행할 수 있습니다.

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    BackgroundAgents = [webSearchAgent, codeAgent],
});

하네스 에이전트 만들기

하네스는 채팅 클라이언트로부터 완전히 구성된 create_harness_agent를 조립하는 Agent 팩터리 함수로 노출됩니다. 가장 간단한 양식에는 클라이언트만 필요합니다.

from agent_framework import create_harness_agent
from agent_framework.openai import OpenAIChatClient

agent = create_harness_agent(
    OpenAIChatClient(model="gpt-4o"),
)

session = agent.create_session()
response = await agent.run("Plan a weekend trip to Seattle.", session=session)
print(response.text)

하네스 수준 지침은 일반적인 운영 지침을 설명하고, 작업별 지침은 agent_instructions에 들어갑니다. 하네스는 기본 하네스 수준의 지침(DEFAULT_HARNESS_INSTRUCTIONS)을 함께 제공하며, 이 지침은 harness_instructions을 통해 재정의할 수 있습니다. 추가 도구를 전달할 수도 있습니다.

agent = create_harness_agent(
    client=client,
    name="research-agent",
    agent_instructions="You are a research assistant focused on academic sources.",
    tools=get_stock_price,
)

컴팩션 활성화

압축은 긴 도구 호출 루프가 컨텍스트 창을 오버플로하는 것을 방지합니다. 모델의 최대 컨텍스트 창 크기와 최대 출력 크기를 모두 제공하여 기본 토큰-예산 인식 전략을 사용하도록 설정합니다.

agent = create_harness_agent(
    client=client,
    max_context_window_tokens=128_000,
    max_output_tokens=16_384,
)

토큰 매개 변수나 사용자 지정 전략이 제공되지 않으면 압축이 자동으로 비활성화됩니다. 사용자 고유의 전략을 사용하려면 before_compaction_strategy 및/또는 after_compaction_strategy을 전달하세요. 압축을 명시적으로 비활성화하려면 disable_compaction=True로 설정하세요.

기능 사용자 지정 및 사용 안 림

모든 기본 기능에는 해당하는 disable_* 키워드 인수가 있으므로 원하는 부분을 유지하고 나머지는 삭제할 수 있습니다.

agent = create_harness_agent(
    client=client,
    harness_instructions="Custom operating guidelines here.",
    disable_todo=True,         # No todo list
    disable_mode=True,         # No plan/execute modes
    disable_web_search=True,   # No hosted web search tool
    disable_file_memory=True,  # No file-based session memory
)

다른 플래그에는 disable_file_access, disable_tool_auto_approval및 disable_compaction. skills_paths을 사용하여 기술 검색이 사용자 지정 위치를 가리키도록 설정하고 context_providers을 사용하여 자체 공급자를 추가할 수 있습니다.

완료될 때까지 반복

기본적으로 하네스는 호출당 한 번 실행됩니다. loop_should_continue 조건자를 전달하여 조건자가 완료되었다고 판단할 때까지 에이전트를 자동으로 다시 호출하도록 합니다. 각 후속 반복에 대한 프롬프트를 제어하고 loop_next_message 패스 수를 제한하는 데 사용합니다loop_max_iterations.

from agent_framework import create_harness_agent, todos_remaining

agent = create_harness_agent(
    client=client,
    loop_should_continue=todos_remaining(),
    loop_max_iterations=10,
)

조건자는 키워드 인수(iteration, last_result, session, agent 등)로 호출되며, todos_remaining는 할 일 목록에 미해결 항목이 남아 있는 동안 에이전트를 다시 실행합니다. 직접 작성하려면 예를 들어 lambda *, last_result, **kwargs: "DONE" not in last_result.text와 같은 해당 키워드 인수를 받도록 하세요.

셸 및 백그라운드 에이전트

에이전트가 셸 명령을 실행할 수 있도록 하려면 shell_executor를 전달하세요(예: LocalShellTool의 agent-framework-tools). 이렇게 하면 승인 제어 셸 실행 도구와 OS 및 셸 환경을 검색하는 공급자가 추가됩니다. 호출자는 실행자의 수명 주기를 소유합니다.

from agent_framework_tools.shell import LocalShellTool, ShellPolicy

# A shell confined to a working directory. Commands require approval by default;
# the deny-list is a UX pre-filter, not a security boundary.
async with LocalShellTool(
    workdir="./working",
    confine_workdir=True,
    policy=ShellPolicy(denylist=[r"\brm\s+-rf\b", r"\bsudo\b"]),
) as shell:
    agent = create_harness_agent(
        client=client,
        shell_executor=shell,
    )

병렬 위임을 사용하도록 설정하려면 백그라운드 에이전트 시퀀스를 전달합니다. 에이전트는 동시 실행을 위해 하위 작업을 수행할 수 있습니다.

agent = create_harness_agent(
    client=client,
    background_agents=[web_search_agent, code_agent],
)

.NET 샘플 콘솔은 Harness.Shared.Console 프로젝트입니다. 진입점은 HarnessConsole.RunAgentAsync이며, 에이전트, 플레이스홀더 프롬프트, 그리고 선택적 HarnessConsoleOptions(관찰자, 슬래시 명령 핸들러, 모드 색상)를 받습니다:

using Harness.Shared.Console;

await HarnessConsole.RunAgentAsync(agent, userPrompt: "Ask me anything to get started.");

자신만의 옵저버, 도구 포매터, 명령 처리기로 이를 사용자 지정하거나, 자신만의 터미널 환경을 위한 기반으로 포크하여 활용할 수 있습니다. .NET 하네스 샘플을 참조하세요.

Python 샘플 콘솔은 하네스 샘플 옆에 있는 패키지입니다console. 해당 진입점은 run_agent_async이며, Textual 기반의 앱을 실행합니다.

from console import run_agent_async

await run_agent_async(agent)

관찰자, UI 구성 요소, 슬래시 명령을 중심으로 구성되어 있으며, 모두 ConsoleObserver, ToolCallFormatter, CommandHandler 기본 클래스를 통해 확장할 수 있습니다(textual 및 rich에 따라 다름). 있는 그대로 실행하거나, 나만의 터미널 환경을 위한 기본 바탕으로 복사해 사용하세요. Python 하네스 샘플을 참조하세요.