에이전트 하네스는 언어 모델을 작업을 수행할 수 있는 에이전트로 바꾸는 런타임 스캐폴딩입니다. 모델 및 도구 호출을 구동하고, 대화 상태 및 컨텍스트를 관리하고, 승인 정책을 적용하며, 에이전트가 다단계 작업을 진행하도록 유지할 수 있습니다.
Agent Framework는 연구, 코딩, 데이터 분석 및 기타 장기 실행 작업을 위해 배터리가 포함된 의견 있는 Harness를 제공합니다. 채팅 클라이언트를 제공하고 애플리케이션에 필요한 기능만 사용자 지정합니다.
Architecture
Harness는 별도의 에이전트 런타임을 정의하는 대신 기존 에이전트 프레임워크 구성 요소를 구성합니다.
- 채팅 클라이언트 - 에이전트를 모델에 연결합니다.
- 채팅 파이프라인 - 함수 호출, 메시지 삽입, 서비스별 호출 기록 지속성 및 선택적 압축을 추가합니다.
- 에이전트 및 컨텍스트 공급자 - 세션 범위 명령, 도구, 메모리, 할 일 상태, 운영 모드 및 선택적 기능을 추가합니다.
- 미들웨어 및 데코레이터 - 승인 처리, 관찰 가능성 및 선택적 경계 루핑을 추가합니다.
- 애플리케이션 UX - 응답을 스트리밍하고, 진행률을 표시하고, 도구 승인과 같은 입력을 수집합니다.
결과 개체는 .NET 파생 HarnessAgent 되거나 Python AIAgent 반환된 Agent 일반 Agent Framework 에이전트 create_harness_agent 로 유지됩니다. 해당 세션은 다른 에이전트와 동일한 세션 및 컨텍스트 공급자 추상화 기능을 사용합니다.
Harness 기능 매트릭스
| Capability | Harness 동작 | 정식 지침 |
|---|---|---|
| 함수 호출 | 구성 가능한 요청당 반복 제한으로 사용하도록 설정됩니다. | 함수 도구 |
| 서비스별 호출 기록 지속성 | 도구 호출 실행에서 각 모델 호출 후 기록을 유지합니다. | 세션 |
| 압축 | 토큰 제한 또는 사용자 지정 전략을 제공할 때 사용하도록 설정됩니다. | 압축 |
| 할 일 추적 | 기본적으로 활성화되어 있습니다. | 계획 및 할 일 |
| 에이전트 모드 | 계획 및 실행 모드는 기본적으로 사용하도록 설정됩니다. | 계획 및 할 일 |
| 파일 메모리 및 파일 액세스 | 세션 파일 메모리는 기본적으로 사용하도록 설정됩니다. 공유 파일 액세스는 옵트인입니다. | 컨텍스트 공급자 |
| 도구 승인 | 대기 승인 및 자동 승인 규칙은 기본적으로 사용하도록 설정됩니다. | 도구 승인 |
| OpenTelemetry | 에이전트 관찰성은 기본적으로 사용하도록 설정됩니다. | 관찰 가능성 |
| 웹 검색 | 선택한 채팅 클라이언트가 지원하는 위치에 기본적으로 추가됩니다. | 웹 검색 |
| 에이전트 기술 | 기본적으로 .NET; Python 공급자 또는 경로를 통해 옵트인합니다. | 에이전트 기술 |
| 백그라운드 에이전트 | 명명된 자식 에이전트에 대한 선택적 병렬 위임입니다. | 백그라운드 에이전트 |
| 셸 실행 | 셸 패키지에서 구성됩니다. Python 팩터리는 자동으로 연결할 수 있습니다. | 셸 도구 |
| 루핑 (반복) | 계산기 또는 조건자에 의해 구동되는 선택적 경계 다시 호출입니다. | 에이전트 루핑 |
백그라운드 에이전트 위임은 공급자 관리 백그라운드 응답과는 별개입니다. 백그라운드 에이전트는 위임된 작업에서 자식 에이전트를 실행합니다. 백그라운드 응답은 연속 토큰을 사용하여 하나의 공급자 요청을 폴링하거나 다시 시작합니다.
하네스 에이전트 만들기
패키지는 Microsoft.Agents.AI.Harness 네임스페이 HarnessAgent 스에 노출됩니다Microsoft.Agents.AI. 다음을 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앞에 나타납니다.
컴퍼지션 사용자 지정
기본 기능에는 ,, ,DisableTodoProviderDisableAgentModeProviderDisableFileMemoryDisableAgentSkillsProviderDisableWebSearch, 및 를 DisableToolAutoApproval비롯한 DisableOpenTelemetry대상 옵션이 있습니다.DisableCompaction
를 사용하여 사용자 지정 컨텍스트 공급자 추가 AIContextProviders 를 사용하여 파일 액세스 FileAccessStore, 백그라운드 위임 및 BackgroundAgents루프를 LoopEvaluators사용하여 옵트인합니다.
하네스 에이전트 만들기
팩터리는 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_tododisable_modedisable_file_memorydisable_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포함됩니다.
Important
이러한 콘솔 프로젝트는 제공된 프레임워크 구성 요소가 아닌 샘플입니다. 실행 가능한 예제로 사용하거나 사용자 고유의 터미널 환경을 위한 시작점으로 사용합니다.
.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 터미널 샘플이 포함되어 있지 않습니다.