에이전트 하네스는 언어 모델을 작업을 수행할 수 있는 에이전트로 바꾸는 런타임 스캐폴딩입니다. 모델 및 도구 호출을 구동하고, 대화 상태 및 컨텍스트를 관리하고, 승인 정책을 적용하며, 에이전트가 다단계 작업을 진행하도록 유지할 수 있습니다.
Agent Framework는 연구, 코딩, 데이터 분석 및 기타 장기 작업에 필요한 모든 기능을 갖춘 체계적인 도구를 제공합니다. 채팅 클라이언트를 제공하고 애플리케이션에 필요한 기능만 사용자 지정합니다.
Architecture
Harness는 별도의 에이전트 런타임을 정의하는 대신 기존 에이전트 프레임워크 구성 요소를 구성합니다.
- 채팅 클라이언트 - 에이전트를 모델에 연결합니다.
- 채팅 파이프라인 - 함수 호출, 메시지 삽입, 서비스별 호출 기록 지속성 및 선택적 압축을 추가합니다.
- 에이전트 및 컨텍스트 공급자 - 세션 범위 명령, 도구, 메모리, 할 일 상태, 운영 모드 및 선택적 기능을 추가합니다.
- 미들웨어 및 데코레이터 - 승인 처리, 관찰 가능성 및 선택적 경계 루핑을 추가합니다.
- 애플리케이션 UX - 응답을 스트리밍하고, 진행률을 표시하고, 도구 승인과 같은 입력을 수집합니다.
결과 개체는 여전히 일반적인 Agent Framework 에이전트입니다. 즉, .NET에서는 AIAgent에서 파생된 HarnessAgent이고, Python에서는 create_harness_agent에서 반환되는 Agent입니다. 해당 세션은 다른 에이전트와 동일한 세션 및 컨텍스트 공급자 추상화 기능을 사용합니다.
Harness 기능 매트릭스
| Capability | 하네스 행동 | 정식 지침 |
|---|---|---|
| 함수 호출 | 구성 가능한 요청당 반복 제한으로 사용하도록 설정됩니다. | 함수 도구 |
| 서비스별 호출 기록 지속성 | 도구 호출 실행에서 각 모델 호출 후 기록을 유지합니다. | 세션 |
| 압축 | 토큰 제한 또는 사용자 지정 전략을 제공할 때 사용하도록 설정됩니다. | 압축 |
| 할 일 추적 | 기본적으로 활성화되어 있습니다. | 계획 및 할 일 |
| 에이전트 모드 | 계획 및 실행 모드는 기본적으로 사용하도록 설정됩니다. | 계획 및 할 일 |
| 파일 메모리 및 파일 액세스 | 세션 파일 메모리는 기본적으로 사용하도록 설정됩니다. 공유 파일 액세스는 옵트인입니다. | 컨텍스트 공급자 |
| 도구 승인 | 대기 승인 및 자동 승인 규칙은 기본적으로 사용하도록 설정됩니다. | 도구 승인 |
| OpenTelemetry | 에이전트 관찰성은 기본적으로 사용하도록 설정됩니다. | 관찰 가능성 |
| 웹 검색 | 선택한 채팅 클라이언트가 지원하는 위치에 기본적으로 추가됩니다. | 웹 검색 |
| 에이전트 기술 | .NET에서는 기본적으로 활성화되며, Python에서는 공급자 또는 경로를 통해 옵트인합니다. | 에이전트 기술 |
| 백그라운드 에이전트 | 이름이 지정된 자식 에이전트로의 선택적 병렬 위임 | 백그라운드 에이전트 |
| 셸 실행 | 셸 패키지에서 구성됩니다. Python 팩터리는 자동으로 연결할 수 있습니다. | 셸 도구 |
| 반복 | 평가자 또는 조건자에 의해 수행되는 선택적 제한 재호출. | 에이전트 반복 실행 |
백그라운드 에이전트 위임은 공급자 관리 백그라운드 응답과는 별개입니다. 백그라운드 에이전트는 위임된 작업에서 자식 에이전트를 실행합니다. 백그라운드 응답은 연속 토큰을 사용하여 하나의 공급자 요청을 폴링하거나 다시 시작합니다.
하네스 에이전트 생성
Microsoft.Agents.AI.Harness 패키지는 Microsoft.Agents.AI 네임스페이스에서 HarnessAgent을(를) 노출합니다. 임의의 IChatClient에서 AsHarnessAgent을 사용해 하나를 만들거나, 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, DisableAgentModeProvider, DisableFileMemory, DisableAgentSkillsProvider, DisableWebSearch, DisableToolAutoApproval, DisableOpenTelemetry 및 DisableCompaction를 포함한 특정 옵션이 있습니다.
를 사용하여 사용자 지정 컨텍스트 공급자 추가 AIContextProviders
FileAccessStore을 사용해 파일 액세스, BackgroundAgents을 사용해 백그라운드 위임, LoopEvaluators를 사용해 루핑을 선택할 수 있습니다.
Harness 에이전트 생성
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와 같은 옵션을 사용하여 기본값을 비활성화합니다.
기본 제공 공급자를 또는 로 바꾸고, 로 공급자를 추가합니다. 스킬은 skills_provider 또는 skills_paths을 통해 선택적으로 활성화되며, 파일 액세스, 백그라운드 에이전트, 셸 도구 기능, 반복 실행도 선택적으로 활성화됩니다.
비고
create_harness_agent 가 릴리스되었습니다. 백그라운드 에이전트, 파일 액세스 및 루핑은 실험적인 상태로 유지되며 셸 도구는 시험판 agent-framework-tools 패키지에서 제공됩니다.
비고
패키지된 Go Harness는 현재 사용할 수 없습니다. 해당 Go 에이전트, 컨텍스트 공급자, 압축 및 미들웨어 패키지를 직접 작성합니다. 현재 지원은 에이전트 프레임워크 Go 리포지토리 를 참조하세요.
예제 터미널 UX
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 샘플은 Harness 샘플 옆에 있는 텍스트 기반 console 패키지를 사용합니다.
from console import run_agent_async
await run_agent_async(agent)
관찰자, 포맷터, 명령 및 UI 구성 요소를 사용하여 샘플을 사용자 지정합니다. Python Harness 샘플을 참조하세요.
리포지토리에는 현재 패키지된 Go Harness 터미널 샘플이 포함되어 있지 않습니다.