서론

2026년 7월 22일, Microsoft Agent Framework의 공식 블로그에 「The Microsoft Agent Framework Harness is now released」가 공개되었으며, 에이전트 하네스(Agent Harness)의 핵심 기능이 정식 출시(GA, General Availability)되었습니다.

지금까지 TodoProvider나 AgentModeProvider 등의 부품을 수동으로 조합하여 구축해야 했던 하네스를, 이제 AsHarnessAgent() 호출 한 번으로 얻을 수 있게 되었습니다. 루프(Loop), 실행 계획(Execution Plan), 메모리(Memory), 컨텍스트 관리(Context Management), 승인(Approval), OpenTelemetry까지 처음부터 배선되어 즉시 이용 가능한 에이전트입니다.

이 기사에서는 공식 블로그, Microsoft Learn, GitHub 리포지토리(소스 코드, CHANGELOG, Pull Request)를 조사한 결과를 바탕으로 정식 출시된 Harness의 전체상을 정리하며, 후반부에서는 검증용 샘플을 작성하여 LM Studio의 로컬 LLM으로 GA 버전의 동작을 확인합니다.

이 기사에서 알 수 있는 것

• 에이전트 하네스란 무엇인가, Agents / Workflows와의 위치 선정
• 이번에 GA가 된 핵심 기능과, 아직 옵트인(Opt-in) 취급인 프리뷰(Preview) 기능의 구분
• .NET 패키지, 최소 코드, 커스터마이징 방법
• HarnessAgent의 내부 파이프라인 구조 - 프리뷰 시절부터 도입된 파괴적 변경(Breaking Changes)과 이행 시 주의점
• GA 버전 Harness를 LM Studio(google/gemma-4-12b)에서 실제로 구동한 결과

에이전트 하네스란 무엇인가

공식 문서에서는 에이전트 하네스를 다음과 같이 정의하고 있습니다.

An agent harness is the scaffolding that turns a language model into an agent that can actually do things. A model on its own can only generate text.

언어 모델(Language Model) 단체는 텍스트를 생성하는 것밖에 할 수 없습니다. 도구를 호출하고, 다단계 태스크를 수행하며, 수행한 내용을 기억하고, 업무가 끝날 때까지 계속 진행하기 위해서는 모델 주변을 감싸는 런타임(Runtime)이 필요합니다. 그 런타임이 바로 하네스입니다.

하네스가 담당하는 역할은 다음과 같습니다.

• 모델 호출과 도구 실행의 루프(Loop)를 돌림
• 대화 이력과 컨텍스트를 관리하여 모델의 제한 범위 내에 유지함
• 액션 실행 전에 승인 및 안전 정책(Safety Policy)을 적용함
• 태스크 완료를 향해 에이전트를 계속 전진시킴

이 관계를 도식화하면 다음과 같습니다. 모델은 '텍스트를 반환할 뿐'인 존재이며, 루프를 돌려 태스크를 앞으로 진행시키는 것은 하네스의 역할입니다.

공식 문서에는 「Coding assistants and autonomous agents are all built on some form of harness — it's the engine wrapped around the model.」라고 명시되어 있으며, 코딩 에이전트 또한 어떤 형태로든 하네스 위에 구축되어 있다는 업계 공통의 개념을 바탕으로 설계되었음을 알 수 있습니다.

에이전트 / 하네스 / 워크플로우의 위치 선정

Microsoft Learn에서는 Agent Framework가 세 가지 주요 카테고리로 구성된다고 설명합니다.

중요한 점은 하네스(Harness)가 워크플로우(Workflow)와는 별개의 레이어라는 점입니다. 내부적으로 하네스는 chat client 기반의 에이전트(ChatClientAgent)에 Agent Framework의 각 기능을 쌓아 올린 것이며, 그 자체로 하나의 AIAgent입니다. 따라서 AIAgent를 받을 수 있는 곳(워크플로우의 노드 등)에는 Harness 에이전트도 포함할 수 있습니다.

하네스와 워크플로우 모두 AIAgent 타입으로 취급할 수 있으므로, 데코레이터(Decorator)처럼 구현할 수도 있습니다.

추상적으로 보면 쿼리(Query)를 전달하면 어떠한 처리를 수행하여 답변을 생성하는 동작은 동일합니다.

이미지

사용 구분 지침은 다음과 같습니다.

• 태스크가 오픈 엔드(Open-ended)이며, 자율적인 도구 사용이나 계획이 필요한 경우 → 에이전트(Agent) 또는 하네스(Harness)
• 공정이 명확하게 정의되어 있고 실행 순서를 명시적으로 제어하고 싶은 경우 → 워크플로(Workflow)

패키지 및 버전

GA(General Availability)가 된 핵심 기능

공식 블로그에서 언급하는 이번 출시 핵심 기능은 다음과 같습니다.

조금 전에 GA된 Skills도 포함되어 있어 매우 유용합니다.

옵트인(Opt-in) 4가지 기능

반면, 공식 블로그는 「Coming soon」이라며 다음 4가지 기능은 아직 정식 출시(GA)에 포함하지 않았음을 명시하고 있습니다.

블로그에서는 「더 개선할 수 있다고 생각하며, 정식 출시 전에 고객 피드백을 수집하고 싶다」는 이유를 밝히고 있습니다.

기본적으로 연결되는 것과 옵트인(Opt-in)의 관계를 정리하면 다음과 같습니다. AsHarnessAgent()를 한 번 호출하는 것만으로 왼쪽의 3개 그룹이 자동으로 연결됩니다.

하네스 에이전트(Harness Agent) 생성하기

IChatClient가 있다면, 확장 메서드 하나만으로 Harness 에이전트가 됩니다.

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
// chatClient는 임의의 IChatClient 구현체
...

생성자(Constructor)를 직접 사용할 수도 있습니다.

AIAgent agent = new HarnessAgent(chatClient);

둘 다 매우 간단합니다.

옵션을 통한 커스터마이징

HarnessAgentOptions를 통해 지시 사항/도구 추가, 컨텍스트 압축(Context compaction), 기능 비활성화를 제어합니다.

// 지시 사항과 도구 추가
AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
...

// 토큰 예산을 지정하여 Compaction 활성화
AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
...

// 불필요한 기능 비활성화
AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
...

옵트인 기능을 사용하는 경우는 다음과 같습니다 (사용 시 experimental 경고가 발생합니다).

// Looping: 완료 조건을 충족할 때까지 재호출
AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
...

// Background agents: 서브 태스크의 병렬 위임
AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
...

내부 구조

HarnessAgent는 Agent Framework의 기존 부품들을 정해진 순서로 쌓아 올린 것입니다. NuGet 패키지의 XML 문서와 소스 코드를 확인하면, HarnessAgent는 DelegatingAIAgent를 상속하며, 안쪽에서 바깥쪽으로 다음과 같은 파이프라인(Pipeline)을 구성하고 있습니다.

그리고 TodoProvider, AgentModeProvider, FileMemoryProvider, AgentSkillsProvider는 AIContextProvider로서 삽입됩니다 (각각 Disable* 플래그를 통해 개별적으로 비활성화 가능합니다).

공식 문서에도 "All these features are also available as standalone features in Agent Framework."라고 명시되어 있듯이, 이 구성 요소들은 모두 단독으로 사용할 수 있습니다. 즉, Harness는 "구성 요소의 권장 구성을 패키지화한 것"이며, 세밀하게 제어하고 싶다면 기존 방식대로 구성 요소를 직접 조립할 수도 있습니다.

소스 배치도 두 군데로 나뉘어 있습니다.

dotnet/src/Microsoft.Agents.AI.Harness/

— HarnessAgent
/ HarnessAgentOptions
/ AsHarnessAgent()
(NuGet 패키지 본체)

dotnet/src/Microsoft.Agents.AI/Harness/

— Todo / AgentMode / FileMemory / FileAccess / Loop / ToolApproval / BackgroundAgents 등의 building block (코어 패키지 측)

Plan / Execute 워크플로우

Harness에는 plan / execute 두 가지 모드가 처음부터 내장되어 있습니다.

• Plan 모드 — 대화형. 에이전트는 확인 질문을 하고, TODO 리스트와 계획 초안을 작성하며, 큰 작업에 들어가기 전에 사용자의 승인을 받습니다.
• Execute 모드 — 자율형. 에이전트는 TODO를 스스로 처리하며, 진행 상황을 보고하면서 나아갑니다.

공식 샘플(Harness_Step01_Research)에서는 이 두 모드에 TodoCompletionLoopEvaluator를 조합하여, "execute 모드에서 TODO가 남아 있는 한 재호출한다"는 자율 루프를 구성하고 있습니다.

LoopEvaluators =
[
new TodoCompletionLoopEvaluator(
...

프리뷰 시대부터의 파괴적 변경 (Breaking Changes)

GA(General Availability) 단계로 넘어가면서 여러 파괴적 변경 사항이 포함되었습니다. 프리뷰 버전에서 Harness를 테스트하고 있었다면 특히 주의가 필요합니다.

특히 FileAccess의 변경은 동작에 직결됩니다. 프리뷰 버전에서는 {cwd}/working에 암묵적인 파일 스토어가 생성되었지만, GA 버전에서는 스토어를 전달하지 않는 한 파일 액세스 도구 자체가 활성화되지 않습니다.

동작 확인 — LM Studio에서 Harness 구동하기

이제부터 Harness 에이전트를 실제로 구동하여 확인해 보겠습니다. OpenAI 호환 API를 공개한 LM Studio 상의 로컬 LLM에 HarnessAgent를 연결합니다.

검증용 샘플 HarnessCoreReleaseSample

전체적인 모습은 다음과 같습니다. 직접 작성하는 부분은 OpenAI 호환 클라이언트의 연결과 2개의 커스텀 도구(현재 날짜/시간 취득 및 TinyFish 웹 검색)뿐이며, Provider 그룹은 AsHarnessAgent()가 자동으로 연결합니다.

확인 내용 및 성공 조건

환경

확인 날짜: 2026년 7월 23일

사전 준비: 웹 검색 API 키

웹 검색 확인(시나리오 2)에는 TinyFish Search API 키가 필요합니다. 실행 전에 환경 변수에 설정해 둡니다.

$env:TINYFISH_API_KEY = "your-tinyfish-api-key"
# 선택 사항 (미설정 시 코드 측의 기본값 JP / ja가 사용됩니다)
$env:TINYFISH_LOCATION = "JP"
...

API 키 취득 방법 및 이용 조건은 TinyFish의 문서를 확인해 주세요.

코드

Program.cs

using System.ClientModel;
using System.ComponentModel;
using System.Text;
...

구현 포인트

• 웹 검색은 커스텀 도구로 등록: 내장된 웹 검색(Web search)은 "검색 실행은 추론 서비스 측에서 수행한다"라는 마커이며, 백엔드를 TinyFish 등으로 교체할 수 있는 후크(Hook)는 없습니다. 따라서 hosted 버전은 비활성화한 채로, TinyFish를 호출하는 SearchWeb을 일반 함수 도구로 등록했습니다. Harness 입장에서는 GetCurrentDateTime과 동일한 단순한 도구이므로, TODO 관리나 승인 플로우와 그대로 연동됩니다. TINYFISH_API_KEY가 설정되지 않은 경우에는 도구 자체를 등록하지 않습니다. -
• 로컬 LLM 사용 시: 기본적으로 DisableWebSearch = true를 권장합니다. HostedWebSearchTool이 ChatOptions.Tools에 자동으로 추가됩니다. 활성화된 상태에서도 이번 LM Studio + google/gemma-4-12b 조합에서는 에러 없이 완주했지만, 로컬 환경에는 hosted web search의 백엔드가 존재하지 않으므로 비활성화해 두는 것이 안전할 것으로 보입니다. -
• gemma 계열의 reasoning 모델: 추론(Reasoning) 토큰만으로 출력 상한에 도달하여 본문이 빈 채로 "정상 종료"될 수 있습니다. MaxOutputTokens를 넉넉하게 설정하세요. -
• 세션 API: 1.15.0 버전에서는 CreateSessionAsync()로 AgentSession을 만들고, RunAsync(prompt, session)에 전달합니다. 응답 타입은 AgentResponse입니다.

입니다 -
도구 이름 명시적 지정: 최상위 문(top-level statement) 내의 로컬 함수를 AIFunctionFactory.Create에 전달하면, 자동 생성된 이름(_Main_g_GetCurrentDateTime_0_0과 같은 형태)이 되기 때문에, 두 번째 인자로 이름을 지정하고 있습니다.

실행 결과 1: TODO 및 커스텀 도구

시나리오 1에서는 모델 호출과 도구 실행이 다음과 같은 흐름으로 진행되었습니다. TODO의 등록 및 완료는 모두 모델 측의 판단에 따라 이루어졌으며, 앱 측에서는 일절 지시하지 않았습니다.

콘솔 출력은 다음과 같습니다.

HarnessCoreReleaseSample
package=Microsoft.Agents.AI.Harness 1.15.0 (GA)
endpoint=http://localhost:1234/v1
...

내장 Web search와 커스텀 검색 도구의 차이

시나리오 2에 들어가기 전에, Harness의 「Web search」 기능과 이번 SearchWeb 도구의 관계를 정리해 두겠습니다.

Harness에 포함된 HostedWebSearchTool은 LLM 서비스 측에서 추론 도중에 실행하는 Web 검색입니다. AIFunction과 달리 실행 코드를 갖지 않는 허가 마커(permission marker)이며, 검색 실행부터 결과 응답 반영까지가 추론 서비스의 서버 내에서 완결됩니다. ChatGPT가 답변하는 동안 브라우징을 통해 출처와 함께 답변하는 기능의 API 버전이라고 생각하면 이해하기 쉽습니다.

지원되는 것은 OpenAI Responses API의 web_search 도구(Microsoft Foundry 프로젝트를 경유하는 경우 포함. 공식 Harness 샘플은 이 구성임)나, Chat Completions의 검색 대응 모델용 web_search_options 등입니다. 검색 기능이 없는 서비스에 전달할 경우 단순히 무시됩니다.

LM Studio와 같은 로컬 환경은 전자의 백엔드를 가지고 있지 않기 때문에, 전달하더라도 에러는 발생하지 않지만 검색도 수행되지 않습니다. 로컬 LLM에 Web 검색을 시키고 싶다면, 후자의 형태로 실행 부분을 직접 구현해야 합니다.

실행 결과 2: Web 검색 도구 (TinyFish)

시나리오 2는 TinyFish를 커스텀 도구로 통합하여 Web 검색을 확인하는 과정입니다. SearchWeb 호출(쿼리 결정 포함)은 모두 모델 측의 판단으로 이루어집니다.

==================== Scenario 2: Web 검색 도구 (TinyFish) ====================
prompt-start
Web 검색 도구의 연동을 확인합니다. 다음 작업을 순차적으로 진행해 주세요.
...

실제 검색 결과(공식 블로그 및 Microsoft Learn)의 제목과 URL이 최종 응답에 그대로 인용되는 것을 확인할 수 있습니다.

확인된 사항

• AsHarnessAgent()의 반환값은 Microsoft.Agents.AI.HarnessAgent 타입임
• 아무것도 추가 등록하지 않았음에도, TodoProvider의 내장 도구인 todos_add / todos_complete가 모델로부터 호출되어, TODO 등록 → 순차적 완료가 실행됨
• 커스텀 도구인 GetCurrentDateTime도 동일한 도구 루프 내에서 호출되어 결과가 최종 응답에 반영됨
• TinyFish를 호출하는 SearchWeb

또한 모델의 판단에 따라 호출되었으며, 실제 검색 결과의 제목과 URL이 최종 응답에 인용되었다. 내장된 Web search (웹 검색)를 교체할 수는 없지만, 외부 검색 API를 일반적인 함수 도구 (Function Tool)로 통합하는 방법은 문제없이 작동한다 - 도구 실행 시 승인 요청은 발생하지 않았다. 내장된 todo 도구뿐만 아니라 외부 API를 호출하는 SearchWeb도 자동 승인 범위 내에서 자동 실행되었다 - 실행 후, 작업 디렉토리에 agent-file-memory/ 폴더가 자동으로 생성되었다 (FileMemoryProvider의 기본 스토어. 이번에는 모델이 파일 저장 도구를 사용하지 않았기 때문에 내용은 비어 있음) - 입력 토큰은 시나리오 1에서 약 19,000개가 소비되었다. 이는 Harness의 기본 지시 사항과 각 Provider의 컨텍스트 주입 (Context Injection)에 의한 것이며, 12B 클래스의 로컬 모델로도 1턴의 태스크 진행에는 충분히 기능했다.

4가지 옵트인 (Opt-in) 기능 (Looping / File access / Background agents / Shell tooling) 검증은 내용이 길어지므로 후편으로 나누었습니다.

요약

• 2026년 7월 22일, Microsoft Agent Framework의 Harness 핵심 기능이 정식 출시되었습니다. (.NET 버전은 Microsoft.Agents.AI.Harness 1.14.0 이후)
• Harness는 "모델을 에이전트로 변환하는 발판"이며, 도구 루프 (Tool Loop) · 이력 영속화 (History Persistence) · 컨텍스트 압축 (Context Compression) · TODO/모드 관리 · 파일 메모리 (File Memory) · Skills · 웹 검색 (Web Search) · 도구 승인 (Tool Approval) · OpenTelemetry를 연결해 줍니다.
• Background agents / File access / Looping / Shell tooling의 4가지 기능은 아직 옵트인 프리뷰 (Opt-in Preview) 상태입니다.
• GA (General Availability)와 동시에 파괴적 변경 (Breaking Changes)이 포함되었습니다. 특히 "FileAccess의 옵트인화"와 ".NET에서의 Shell 연동 삭제"는 프리뷰 버전에서 마이그레이션할 때 반드시 확인해야 합니다.
• 검증용 샘플을 통해 확인한 결과, LM Studio 상의 google/gemma-4-12b에서도 내장 TODO 도구와 커스텀 도구가 연동되어 동작했습니다 - 내장 Web search는 백엔드 교체가 불가능한 반면, TinyFish와 같은 외부 검색 API는 일반적인 함수 도구로 등록하면 TODO 관리 및 승인 플로우와 연동되어 문제없이 동작함을 확인했습니다.

내부가 기존 부품들의 조합으로 구성되어 있어, "먼저 AsHarnessAgent()로 구동하고, 필요해지면 부품 구성을 수정한다"는 단계적인 사용이 가능하다는 점이 이번 출시의 실용적인 가치라고 느껴집니다. 전체적으로 오케스트레이션의 Magentic 패턴보다 사용하기 쉽고 효율적인 에이전트를 구축할 수 있을 것 같다는 확신이 들었습니다. 프리뷰 공개 시와 달리 상당히 간단하게 생성할 수 있다는 점이 좋네요.

4가지 옵트인 기능 (Looping / File access / Background agents / Shell tooling)을 동일한 샘플에서 실제로 테스트한 결과는 후편 기사에 정리하겠습니다.

참고

• 공식 블로그 (릴리스 발표)
• Microsoft Learn: Agent Harnesses
• GitHub: microsoft/agent-framework
• .NET 샘플: https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/02-agents/Harness
• .NET 소스: https://github.com/microsoft/agent-framework/tree/main/dotnet/src/Microsoft.Agents.AI.Harness
• PR #7119 (HarnessAgent GA 승격): https://github.com/microsoft/agent-framework/pull/7119
• PR #7093 (FileAccess 옵트인화): https://github.com/microsoft/agent-framework/pull/7093

패키지

• 관련 블로그

• 자신만의 클로(Claw)와 에이전트 하네스 구축하기: https://devblogs.microsoft.com/agent-framework/build-your-own-claw-and-agent-harness-with-microsoft-agent-framework

• 당신의 에이전트 하네스와 클로 만나보기: https://devblogs.microsoft.com/agent-framework/meet-your-agent-harness-and-claw/

• 에이전트 하네스: 데이터를 안전하게 다루기: https://devblogs.microsoft.com/agent-framework/agent-harness-working-with-your-data-safely/

• 에이전트 하네스: 클로 또는 하네스 기능 확장하기: https://devblogs.microsoft.com/agent-framework/agent-harness-scaling-the-claw-or-harness-capabilities/

• 참조일: 2026년 7월 23일

토론 (Discussion)