Agent Harness

Harness는 agent가 반복 작업을 안정적으로 수행하도록 context, tool, policy, observability, verification을 제공하는 주변 실행 환경이다. Source에는 두 가지 용례가 섞여 있다 — product agent용 harness(Deep Agents SDK 같은 올인원 프레임워크)와 coding agent용 repository harness engineering(Codex를 위한 리포지터리 설계). 공통점은 scaffolding과 control surface지만, 같은 제품 계층을 가리키지는 않는다.

Framework, Runtime, Harness가 나뉘는 층위

• LangChain은 agent를 만드는 데 도움이 되는 오픈소스 패키지를 framework, runtime, harness 세 갈래로 구분한다: framework는 agent를 쉽게 만들기 위한 추상화(예: LangChain), runtime은 agent를 안정적으로 실행하는 환경(예: LangGraph), harness는 복잡한 agent를 만들기 위한 사전 구성된 도구와 기능(예: Deep Agents SDK)이다.^[1]

Human-steered, Agent-executed 아래의 다섯 원칙

• Human-steered, agent-executed: 사람은 목표와 acceptance를 정하고 agent는 bounded task를 실행한다.
• Agent-centric readability: agent가 찾을 수 없는 규칙과 signal은 운영상 존재하지 않는 것과 같다 — "에이전트 관점에서 실행 중 컨텍스트 안에서 접근할 수 없는 것은 사실상 존재하지 않는다."^[2]
• Executable taste: architecture boundary는 prose와 함께 linter, schema, test로 강제한다.
• Local observability: browser, log, metric, trace, screenshot을 agent가 직접 확인해야 한다.
• Context continuity: AGENTS 문서는 map과 rule에 집중하고, 상세 결정은 spec, plan, design, decision record로 분리한다 — "Codex에는 1,000페이지의 설명서가 아니라 맵을 제공해야 한다."^[2:1]

Runtime persistence가 harness에 들어올 때

• Harness가 runtime을 포함할 때, durable execution은 "재시도 코드"만 뜻하지 않는다. thread state checkpoint, interruption resume, fault tolerance를 함께 제공하는 persistence boundary다.
• LangGraph 모델에서는 checkpointer가 thread-scoped graph state를, store가 cross-thread application data를 담당한다.^[3] harness는 어느 데이터를 어느 범위와 retention으로 보관할지 policy로 정해야 한다.
• Managed server(Agent Server)가 persistence infrastructure를 대신 제공할 수 있어도,^[3:1] user-facing memory의 namespace, visibility, deletion policy까지 자동으로 결정하지는 않는다는 것은 이 페이지의 해석이다.

큰 AGENTS.md가 실패하는 이유

• 컨텍스트는 희소 자원이다. 거대한 지침 파일은 작업·코드·관련 문서를 압박해 agent가 주요 제약 조건을 놓치거나 잘못된 제약에 맞춰 최적화하게 만든다.^[2:2]
• 지침이 너무 많으면 지침이 되지 않는다 — "모든 것이 중요하다면 중요한 것은 아무것도 없다."^[2:3] agent는 의도적으로 탐색하기보다 로컬 패턴 매칭을 하게 된다.
• 단일 거대 매뉴얼은 빠르게 낡아 오래된 규칙의 무덤이 되고, 단일 블롭은 커버리지·신선도·소유권·교차 연결을 기계적으로 검증하기 어려워 드리프트가 불가피하다.^[2:4]
• 그래서 AGENTS.md는 백과사전이 아니라 목차로 취급하고, 리포지터리 지식은 docs/의 구조화된 기록 시스템에 두며, 전용 린터와 CI가 신선도·교차 링크·구성을 기계적으로 검증한다.^[2:5]
• Codex는 표준 개발 도구(gh, 로컬 스크립트, 리포지터리 내장 스킬)를 직접 사용해 application을 실행·검증하도록 browser와 observability를 제공받는다.^[2:6]

개인 workflow 기록은 같은 방향을 다른 규모에서 보여준다. task를 작게 나누고 plan, DESIGN, handoff 문서를 남기는 편이 대화창에만 기억을 맡기는 것보다 안정적이었다는 관찰이다.^[4]

Harness 품질을 판단하는 기준

좋은 harness는 자유도를 없애지 않고 실패 비용이 큰 경계만 강제한다고 보인다. 문서가 많을수록 entrypoint는 짧은 map이어야 하며, 상세 문서는 freshness와 검증 경로를 가져야 한다. Harness quality는 prompt 길이보다 feedback latency로 평가할 수 있다는 것이 이 페이지의 해석이다. Runtime state와 repository record는 보존 대상과 lifecycle이 다르다 — 하나는 실행 재개를 위한 state history이고, 다른 하나는 사람과 다음 agent가 읽을 지식 기록이다.

이 경계가 흐려지는 경우

• 거대한 instruction file, prose-only policy, invisible application, unbounded task, 겹치는 tool, SDK lock-in은 context drift와 검증 지연을 만든다.
• Runtime이 repository architecture rule을 대신하거나, 문서가 checkpoint를 대신한다고 가정하면 책임이 흐려진다.

테스트 질문

• Framework, runtime, harness의 책임은 어떻게 다른가?
• repository record와 runtime checkpoint는 무엇을 보존하는가?

관련

• AI Agent Architecture
• Agent Evaluation Loop
• AI 보조 개발의 인지 부채 — harness의 context·observability가 사람의 system 이해를 지원하는 surface가 될 수 있다.

출처