AI 에이전트 시대의 '하네스',
도대체 무엇인가
용어가 중요한 건 아니지만, 커뮤니케이션의 원활함을 위해 요즘 떠돌고 있는 키워드를 정리합니다. Microsoft · Anthropic · OpenAI 공식 문서를 나란히 놓고 확인한 하네스의 실제 경계 — 그리고 헷갈리지 않기 위한 5층 분류.
최근 Claude Code, Codex, OpenCode, Agent SDK, 플러그인, MCP, 심지어 여러 에이전트를 관리하는 오케스트레이터까지 '하네스'라는 말로 묶여 설명되는 경우가 많습니다. 그런데 공식 문서들을 나란히 보면, 실제로 업계의 경계가 완전히 통일되어 있지는 않습니다. 용어가 중요한 건 아니지만 커뮤니케이션의 원활함을 위해, 요즘 떠돌고 있는 이 키워드를 출처와 함께 정리합니다.
이 글의 목표는 "누가 맞고 누가 틀리다"를 가르는 것이 아닙니다. Model, Harness, Tool/Extension, Environment, Orchestrator가 어떤 관계에 있는지를 이해하고, 서로 다른 문서를 읽을 때 혼란을 줄이는 데 목적이 있습니다.
핵심 질문은 "하네스라는 단어의 정답"이 아니라, 모델 바깥의 무엇이 에이전트의 행동을 결정하는가입니다.
01 · 가장 명확한 공식 정의Microsoft: "모델을 실제로 일하는 에이전트로 바꾸는 스캐폴딩"
2026년 Microsoft Agent Framework 문서는 Agent Harness를 매우 직접적으로 정의합니다. 모델 자체는 텍스트를 생성할 뿐이며, 실제 도구 호출과 다단계 작업, 기억, 완료까지의 진행을 위해서는 모델을 둘러싼 런타임이 필요하다고 설명합니다.[1]
Microsoft 문서에서는 하네스가 모델 호출 루프, 도구 실행, 대화 기록과 컨텍스트 관리, 승인과 안전 정책을 맡는다고 설명합니다.[1][2]
이 정의를 기준으로 보면 Claude Code나 Codex CLI처럼 파일을 읽고, 코드를 바꾸고, 명령을 실행하고, 결과를 확인하며 작업을 계속하는 코딩 에이전트는 넓은 의미에서 '하네스형 런타임'으로 이해하기 쉽습니다. OpenAI는 Codex CLI를 로컬에서 코드를 읽고 수정하고 실행하는 "coding agent"로 공식 설명합니다.[3]
정리하면: LLM + 실행 루프 + 도구 + 상태/컨텍스트 관리가 결합되면서 '에이전트'가 된다.
02 · 그런데 Anthropic은 조금 다르게 말한다같은 회사 문서 안에서도 '하네스'의 경계가 문맥에 따라 달라진다
Anthropic의 평가(Evals) 글은 agent harness 또는 scaffold를 "모델이 에이전트처럼 행동하도록 해주는 시스템"이라고 설명하며, 입력 처리와 tool call orchestration을 포함합니다. 그리고 Claude Code를 "flexible agent harness"의 사례로 직접 언급합니다.[4]
반면 Anthropic의 2026년 연구 글 Trustworthy agents in practice는 에이전트 시스템을 model / harness / tools / environment 네 층으로 나눕니다. 이 글에서는 harness를 주로 모델이 따르는 instructions와 guardrails로 설명하고, tools와 environment는 별도 구성요소로 분리합니다.[5]
| 출처 | Harness의 범위 |
|---|---|
| Microsoft Agent Framework | 루프, context, tool 실행, 승인, 안전정책 등을 포함하는 runtime |
| Anthropic Evals | 모델이 agent처럼 행동하도록 하는 system/scaffold, tool orchestration 포함 |
| Anthropic Trustworthy Agents | instructions + guardrails 중심, tools/environment는 별도 층 |
03 · 어디서 갑자기 나온 말인가'Harness' 자체는 AI가 만든 신조어가 아니다
소프트웨어 분야에서는 오래전부터 test harness라는 표현을 사용해 왔습니다. NIST가 공개한 오래된 테스트 문서에서도 test harness를 여러 테스트를 실행할 수 있게 하는 소프트웨어로 설명하고 있으며, Python 공식 문서에서도 end-user test harness라는 표현이 여전히 사용됩니다.[6][7] 즉 '어떤 대상의 주변을 감싸 입력을 주고, 실행시키고, 결과를 관찰하는 구조'라는 비유는 AI보다 훨씬 오래되었습니다.
다만 "Agent Harness라는 말을 누가 최초로 만들었다"는 단일 창시자를 확인할 만한 공인된 출처는 찾기 어렵습니다. 현재 확인 가능한 자료만 놓고 보면, 기존 소프트웨어의 harness/scaffold 개념이 LLM evaluation과 agent runtime 문맥으로 자연스럽게 확장됐다고 보는 편이 안전합니다.
최근 연구도 harness를 독립적인 연구 대상으로 다룹니다. 예를 들어 2026년 MemoHarness는 agent harness를 "base LLM을 executable agent로 바꾸는 external control layer"로 정의하고 context, tools, orchestration, memory, decoding, output handling을 관리하는 층으로 설명합니다.[8]
04 · 2025~2026, 왜 갑자기 중요해졌나모델 성능만으로 에이전트 성능을 설명하기 어려워졌기 때문이다
Anthropic은 2025년 장기 실행 에이전트를 다룬 글에서 Claude Agent SDK를 "general-purpose agent harness"라고 부르며, 긴 작업에서 context compaction만으로는 충분하지 않고 세션 간 진행상태를 이어주는 구조가 필요하다고 설명했습니다.[9] 2026년에는 더 직접적인 표현이 등장합니다. Anthropic은 Harness design for long-running application development에서 frontier agentic coding의 성능에 harness design이 중요하다고 강조합니다.[10]
OpenAI 역시 2026년 2월 공식 엔지니어링 글의 제목을 아예 "Harness engineering"이라고 붙였습니다. 여기서 핵심은 에이전트에게 단순히 더 좋은 프롬프트를 주는 것이 아니라, 저장소 구조·문서·테스트·관측성·가드레일·피드백 루프처럼 에이전트가 안정적으로 일할 수 있는 환경 자체를 설계하는 일입니다.[11]
모델이 좋아지는 것과 별개로, 모델이 일하는 환경을 얼마나 잘 설계했는가가 성능을 크게 좌우합니다.
Martin Fowler 사이트에서도 2026년 들어 "Harness engineering"을 별도의 엔지니어링 관점으로 다루기 시작했고, OpenAI 사례를 바탕으로 테스트·구조적 검증·피드백 장치의 중요성을 논의하고 있습니다.[12]
05 · 실무에서 헷갈리지 않는 분류커뮤니케이션을 위한 5층 구분
| 층 | 예시 | 역할 |
|---|---|---|
| 1. Model | GPT · Claude · Gemini · Qwen | 언어를 읽고 생성하며 추론하는 기반 모델 |
| 2. Agent Harness / Runtime | Claude Code · Codex CLI · Agent SDK 기반 런타임 | 모델을 반복 실행하고 행동시키는 실행 골격 |
| 3. Extensions / Components | Skill · Plugin · Hook · Rules · MCP client/server 연결 | 하네스의 능력·지침·연결 범위를 확장하는 구성요소 |
| 4. Environment | 파일시스템 · Git · Shell · 브라우저 · 사내망 | 에이전트가 실제로 접근하고 영향을 미치는 작업 공간 |
| 5. Orchestrator | 다수 agent/session/workflow 관리 | 여러 에이전트와 작업을 라우팅하고 관리하는 상위 제어층 |
이것은 업계 표준을 선언하는 분류가 아니라 대화를 명확하게 하기 위한 실무적 분류입니다. 특히 Anthropic이 harness/tools/environment를 분리해서 설명하는 사례가 있기 때문에, "MCP나 plugin은 무조건 harness가 아니다"라고 단정하기보다는 "이 글에서는 extension/component라고 부르겠다"고 먼저 범위를 정하는 편이 좋습니다.[5]
06 · Claude Code와 Plugin을 둘 다 Harness라고 부르는 이유'제품'과 '행동을 규정하는 주변 구조'를 같은 단어로 부르기 시작했기 때문이다
Claude Code는 Anthropic 공식 문서에서 터미널에서 작동하며 파일을 직접 편집하고 명령을 실행하고 MCP를 통해 외부 데이터에 접근할 수 있는 agentic coding tool로 설명됩니다.[13] Anthropic의 Evals 글은 더 직접적으로 Claude Code를 flexible agent harness라고 부릅니다.[4]
하지만 최근 연구에서는 harness의 범위를 prompts, tools, skills, middleware, memory 같은 주변 제어 요소까지 넓게 잡기도 합니다. Co-Harness는 runtime harness가 prompts, tools, skills, middleware, memory를 포함한다고 명시합니다.[14] 그래서 강력한 플러그인 하나가 지침·툴·스킬·워크플로·메모리를 함께 가져오면, 누군가는 그것을 "작은 하네스" 또는 "하네스 레이어"라고 표현할 수 있습니다.
용어의 경계보다 중요한 것은 누가 모델의 행동 루프와 컨텍스트, 도구, 검증을 통제하느냐다.
07 · 자주 생기는 오해하네스를 '설정'하는 것과 '개발'하는 것은 다른 작업이다
이 지점에서 실무 커뮤니케이션의 오해가 하나 생깁니다. 플러그인·스킬·훅·MCP 설정을 정성껏 구성해 놓고 "하네스를 개발했다"고 말하는 경우입니다.
구분은 간단한 사실에서 출발합니다. 플러그인만 가지고는 LLM이 돌지 않습니다. 스킬 파일, 훅 스크립트, MCP 설정, 규칙 문서는 전부 텍스트와 코드 조각일 뿐이고, 그것을 읽어 들여 모델 호출 루프를 실제로 돌리는 CLI나 런타임 — Claude Code, Codex CLI, Agent SDK로 만든 앱 — 이 있어야 비로소 작동합니다. 확장(Extension)은 정의상 숙주가 되는 런타임을 전제합니다. 앞의 5층 분류에서 2층(Harness/Runtime)과 3층(Extensions)을 나눈 이유가 바로 이것입니다.
그래서 '하네스'가 들어가는 작업은 실제로 세 가지로 갈라집니다.
| 작업 | 실제로 하는 일 | 결과물 |
|---|---|---|
| 하네스 개발 (runtime development) | 모델 호출 루프, 도구 실행기, 컨텍스트 관리, 승인·안전 정책을 직접 구현. Agent SDK로 자체 런타임을 만들거나 오픈소스 하네스 코드를 수정 | 새로운 실행 런타임 |
| 하네스 설정·확장 (configuration) | 기존 런타임 위에 스킬·플러그인·훅·MCP·규칙을 조합하고 튜닝 | 더 유능해진 기존 하네스 |
| 하네스 엔지니어링 (harness engineering) | 저장소 구조·테스트·문서·관측성·가드레일 등 에이전트가 일하는 환경을 설계[11] | 에이전트 친화적 작업 환경 |
판별 질문은 하나면 충분합니다. "모델 호출 루프가 누구의 코드에서 돌고 있는가?" 루프가 Claude Code나 Codex 같은 남의 제품 안에서 돌고 있다면, 내가 한 일은 설정·확장이거나 하네스 엔지니어링입니다. 루프를 내 코드가 직접 돌리고 있어야 하네스를 개발한 것입니다.
08 · 그리고 Harness 위에 Orchestration이 올라온다한 에이전트를 잘 돌리는 문제와 여러 에이전트를 관리하는 문제는 다르다
OpenAI는 2026년 4월 Symphony를 공개하며 이를 명시적으로 agent orchestrator라고 표현했습니다. 프로젝트 관리 보드를 coding agent의 control plane으로 사용해 여러 작업을 관리하는 구조입니다.[15]
이 구분은 중요합니다. 하네스가 보통 한 모델/에이전트가 어떻게 행동하는가를 책임진다면, 오케스트레이터는 여러 에이전트에게 어떤 일을 언제 배분하고 어떻게 상태를 관리할 것인가에 더 가깝습니다.
따라서 여러 코딩 에이전트를 한곳에서 실행하고 세션이나 작업을 관리하는 제품을 설명할 때는 Harness Orchestrator 또는 Agent Orchestrator라고 부르는 편이 기능적 역할을 더 명확히 전달할 수 있습니다. 특정 제품이 스스로 어떤 용어를 쓰는지는 별도로 확인해야 합니다.
09 · 결론모델을 고르는 시대에서, 모델이 일하는 구조를 설계하는 시대로
몇 년 전까지 생성형 AI를 비교하는 핵심 질문은 "어떤 모델이 더 좋은가?"였습니다. 하지만 에이전트 시대에는 같은 모델이라도 context, tools, runtime loop, permissions, tests, memory, environment가 어떻게 설계되어 있느냐에 따라 결과가 크게 달라집니다. Microsoft, Anthropic, OpenAI의 최근 공식 글들이 공통적으로 강조하는 지점도 바로 이 주변 실행 구조입니다.[1][9][11]
Agent 성능 = Model만의 성능이 아니다. Model × Harness × Tools × Context × Environment × Feedback의 결과에 가깝다.
그래서 'Harness'라는 단어의 완벽한 사전적 경계를 외우는 것보다, 대화할 때 "여기서 하네스라고 부르는 범위가 어디까지인가?"를 확인하는 것이 더 중요합니다. 제가 기술 커뮤니케이션에서 사용할 기준은 위 5층 분류입니다 — Model(기반 모델), Harness(실행 런타임/스캐폴딩), Extension(Skill·Plugin·Hook·MCP), Environment(파일·Shell·Git·브라우저), Orchestrator(다수 에이전트의 작업·세션 관리). 이 분류는 표준화 문서가 아니라 현재 공식 문서들의 서로 다른 용례를 바탕으로 한 실무적 커뮤니케이션 프레임입니다.
References주요 출처
- [1] Microsoft Learn, "Agent Harnesses", Agent Framework, updated 2026-07-08. learn.microsoft.com/en-us/agent-framework/agents/harness
- [2] Microsoft Learn, "Step 6: Agent Harness", updated 2026-07-10. learn.microsoft.com/en-us/agent-framework/get-started/harness
- [3] OpenAI Help Center, "OpenAI Codex CLI – Getting Started". help.openai.com/en/articles/11096431
- [4] Anthropic Engineering, "Demystifying evals for AI agents". anthropic.com/engineering/demystifying-evals-for-ai-agents
- [5] Anthropic Research, "Trustworthy agents in practice", 2026. anthropic.com/research/trustworthy-agents
- [6] NIST-hosted Best Practice Guide, "Testing Spreadsheet Applications", test harness definition. nist.gov (PDF)
- [7] Python Documentation, unittest — Unit testing framework. docs.python.org/3/library/unittest.html
- [8] Huang et al., "MemoHarness: Agent Harnesses That Learn from Experience", arXiv:2607.14159, 2026. arxiv.org/abs/2607.14159
- [9] Anthropic Engineering, "Effective harnesses for long-running agents", 2025-11-26. anthropic.com/engineering/effective-harnesses-for-long-running-agents
- [10] Anthropic Engineering, "Harness design for long-running application development", 2026-03-24. anthropic.com/engineering/harness-design-long-running-apps
- [11] OpenAI Engineering, Ryan Lopopolo, "Harness engineering: leveraging Codex in an agent-first world", 2026-02-11. openai.com/index/harness-engineering
- [12] Martin Fowler, "Harness Engineering - first thoughts", 2026. martinfowler.com/articles/exploring-gen-ai/harness-engineering-memo.html
- [13] Anthropic Docs, "Claude Code overview". docs.anthropic.com/en/docs/claude-code/overview
- [14] Chen et al., "Co-Harness: Co-Evolving Harnesses and Model Weights for LLM Agents", arXiv:2607.22688, 2026. arxiv.org/abs/2607.22688
- [15] OpenAI Engineering, "An open-source spec for Codex orchestration: Symphony", 2026-04-27. openai.com/index/open-source-codex-orchestration-symphony