코딩 에이전트의 내부를 하나의 함수로 만든 Microsoft의 Agent Harness

Claude Code나 Codex와 같은 코딩 에이전트(Coding Agent)를 사용하면서, "이 내부 구조, 나도 직접 만들 수 있지 않을까"라고 한 번쯤 생각해 본 사람은 많을 것이다. 모델에 도구(Tool)를 전달하고 루프(Loop)를 돌리고 있을 뿐이라는 것을 머리로는 알고 있다. 하지만 막상 직접 만들려고 하면, 대화 이력이 길어져 문맥(Context)이 넘치는 문제, 셸(Shell)을 실행하기 전에 인간의 승인을 거치는 메커니즘, 계획 모드(Planning Mode)와 실행 모드(Execution Mode)의 전환, 작업 메모의 영속화(Persistence)…… 등, 사소하고 번거로운 부품들이 줄줄이 필요해진다. 모델 그 자체보다 그 "외부의 발판(Footwork)"을 만드는 것이 훨씬 더 고된 일이다.

Microsoft는 이 발판을 오픈 소스인 Microsoft Agent Framework에 create_harness_agent()라는 하나의 함수로서 통째로 넣어두었다. BUILD 2026에서 정식으로 공개된 기능으로, Python과 C#/.NET 양쪽 모두에서 동일한 사상으로 사용할 수 있다(라이선스는 MIT). 이것은 "모델"이 아니라 "하네스(Harness)", 즉 코딩 에이전트의 골격 그 자체를 부품화했다는 점에서 다른 모델 발표와는 결이 다르다.

익숙하지 않은 용어지만, Microsoft의 정의는 허탈할 정도로 솔직하다. 공식 블로그 'Agent Harness in Agent Framework'는 다음과 같이 단언하고 있다.

Agent harness is the layer where model reasoning connects to real execution: shell and filesystem access, approval flows, and context management across long-running sessions.

여기서 언급된 세 가지, 즉 셸 및 파일 시스템 액세스, 승인 흐름(Approval Flows), 장시간 세션에 걸친 문맥 관리(Context Management)가 바로 하네스의 구성 요소 그 자체다. 요컨대 하네스란 "모델의 두뇌"와 "현실의 조작"을 연결하는 배선반이며, 코딩 에이전트를 자처한다면 피할 수 없는 진흙탕 같은 부분들을 이곳에 한데 모아둔 것이다. 튜토리얼 기사 'Build your own claw'에서는 "코딩 에이전트란 모델과 하네스의 결합이다(a coding agent is a model plus a harness)"라고까지 말하고 있어, 그 사상이 명확하다.

Agent Harness가 묶어주는 부품들은 지금까지 각자가 스크래치(Scratch)로 작성해 왔던 것들뿐이다. 직접 만들었을 때와 비교하면 무엇을 대신 처리해 주는지 알 수 있다.

필요한 기능	직접 만들 경우	Agent Harness
도구 호출 루프	직접 구현	function invocation 내장
...

실제 코드는 놀라울 정도로 짧다. Python 튜토리얼 'Meet your agent harness and claw'에 나오는 예시는 다음과 같다.

pip install agent-framework

agent = create_harness_agent(
client=client,
agent_instructions=FINANCE_INSTRUCTIONS,
...

client에 모델 클라이언트를 전달하고, agent_instructions로 역할을 작성하며, 자체 도구를 tools로 추가하기만 하면 된다. 나머지는 이력 유지, 승인, 압축 등을 하네스가 알아서 처리한다. 필요 없는 부품은 disable_todo나 disable_web_search와 같은 플래그로 개별적으로 끌 수 있다(계획 모드를 해제하는 disable_mode, 메모를 해제하는 disable_memory 등도 있다). 처음부터 모든 기능이 포함되어 있으며, 뺄셈을 통해 깎아 나가는 설계다. .NET 측은 chatClient.AsHarnessAgent()라는 확장 메서드를 사용하며, NuGet 패키지는 Microsoft.Agents.AI이다. API의 형태는 달라도 발상은 일치한다.

개인적으로 이 하네스에서 가장 감탄한 점은 context compaction(문맥 압축)을 제대로 부품화했다는 점이다. 오래 작동하는 에이전트의 최대 적은 대화 이력이 컨텍스트 윈도우(Context Window)를 잠식하는 것이다. 이 부분을 소홀히 하면 에이전트는 수십 턴 만에 "방금 무엇을 하고 있었는지"를 놓치게 된다.

Agent Harness는 이를 루프 중간에 토큰 사용량을 모니터링하고 이력을 자동으로 압축함으로써 방지한다. Python에서는 직전의 몇 턴만 남기는 SlidingWindowStrategy(keep_last_groups=3)와 같은 전략을 삽입할 수 있으며, .NET 측은 한 발 더 나아가 여러 전략을 연쇄시키는 파이프라인(Pipeline)을 구성할 수 있다.

new PipelineCompactionStrategy(
new ToolResultCompactionStrategy(CompactionTriggers.MessagesExceed(7)),
new SlidingWindowCompactionStrategy(CompactionTriggers.TurnsExceed(4)),
...

"도구 결과가 7개 메시지를 초과하면 우선 그 부분을 압축한다", "턴이 4를 초과하면 오래된 대화를 윈도우(Window) 밖으로 밀어낸다", "그룹이 12를 초과하면 잘라낸다"와 같은 방식으로 무엇을, 언제, 어떻게 버릴지를 단계적으로 지정할 수 있다. 도구의 거대한 출력 로그부터 먼저 압축한다는 발상은 실제로 코딩 에이전트를 장시간 돌려본 사람일수록 깊이 공감할 것이다. 직접 작성하려면 지옥처럼 세밀해야 할 이 부분이 설정의 조합만으로 해결된다.

셸(Shell) 실행 승인 역시 동일한 수준으로 준비되어 있다. Python이라면 @tool(approval_mode="always_require")를 붙인 도구가 호출될 때마다 user_input_requests가 발생하며, 사람이 y/n으로 허가할 때까지 멈춘다. 공식 문서에서도 "로컬에서 셸을 실행한다면 격리된 환경에서 구동하고, 명시적인 승인을 반드시 거칠 것"이라고 주의를 주고 있다. 에이전트에게 rm -rf 권한을 맡기는 공포를 프레임워크 측에서 전제로 깔고 설계한 셈이다.

Harness로 구성한 에이전트를 프로덕션에 올리는 경로도 동시에 공개되었다. Foundry Hosted Agents를 사용하면, 만든 에이전트를 컨테이너화된 서비스로서 Microsoft Foundry의 매니지드(Managed) 기반에 배포할 수 있다(BUILD 2026 요약 기사). 유휴 시에는 제로(Zero)까지 스케일 다운(Scale-down)되며, 재개 시에는 파일 시스템을 그대로 복원한다. 세션마다 VM이 분리되며, Harness가 내뱉는 OpenTelemetry 트레이스(Trace)는 추가 배선 없이 Application Insights로 흐른다. .NET에서는 .AddFoundryResponses()와 .MapFoundryResponses()가, Python에서는 ResponsesHostServer가 입구가 된다.

참고로 Microsoft는 이 Harness로 구성하는 대화형 에이전트를 사내에서 "claw"라고 부른다. 튜토리얼의 정의에 따르면 "계획하고, 도구를 사용하며, 사물을 기억하고, 안전하게 대리 수행하는 CLI 스타일의 에이전트"이다. 요컨대 Claude Code나 Codex 같은 존재를 자신의 도메인에 맞춰 직접 만들자는 가정이다.

실무적인 관점에서 말하자면, 이는 "코딩 에이전트를 만드는 방법이 공개되었다"기보다 "에이전트의 기반 기술(Infrastructure)이 범용화(Commodity)되기 시작했다"는 신호로 받아들인다. 지금까지 각 기업이 비법 소스처럼 안고 있던 압축 전략, 승인 흐름, 모드 관리 등이 벤더 프레임워크의 인자(Argument)가 되었다. 차별화의 레이어가 기반 기술의 구현에서 그 상위 단계인 업무 지식이나 도구 설계로 한 단계 격상되는 것이다.

반대로 주의해야 할 점은 모든 기능이 포함되어 있기에 발생하는 블랙박스화(Black-box)다. 압축이나 승인을 Harness에 맡겨버리면 "왜 이 이력이 사라졌는지", "왜 이 도구가 멈췄는지"가 프레임워크 내부의 동작에 의존하게 된다. 그렇기에 처음부터 OpenTelemetry 트레이스가 내장되어 있다는 점은 매우 중요하다. 자체 사내 에이전트를 구상 중이라면, 처음부터 배선반을 만들기 전에 먼저 pip install agent-framework로 create_harness_agent()를 한 번 실행해보고, 자신이 정말로 직접 제어하고 싶은 부품이 무엇인지 파악하는 것이 현재 가장 저렴한 학습 비용이 될 것이다.