하네스 엔지니어링으로 설계하는 AI 에이전트 실행 환경
도구 레지스트리, MCP 서버, 오케스트레이션, 격리 샌드박스를 결합해 AI 에이전트 실행 환경을 설계하는 하네스 엔지니어링 아키텍처를 정리한다.
2026-08-14 · 최초 발행 2026-08-02
프롬프트 이후에는 실행 환경이 남는다
AI 개발의 관심은 모델에 질문을 잘 던지는 방법에서 컨텍스트를 구성하는 방법으로 옮겨 왔고, 2025년 이후에는 에이전트가 실행되는 환경 자체를 설계하는 문제로 확장됐다. 이 흐름에서 하네스 엔지니어링(Harness Engineering)은 에이전트의 안전성·효율성·확장성을 모델 품질만의 문제가 아니라 실행 환경의 설계 품질로 다룬다.
프롬프트 엔지니어링은 2022~2023년에 모델에게 좋은 질문을 만드는 데 초점을 뒀다. Few-shot prompting, Chain-of-thought, Role prompting이 주요 기법이었지만, 컨텍스트가 단절되고 상태를 유지하지 못하며 도구 연동이 어렵다는 한계가 있었다. 개발자는 텍스트 입출력을 다루는 Prompt Wizard에 가까웠다.
2023~2025년의 컨텍스트 엔지니어링은 모델의 컨텍스트 창에 어떤 정보를 넣을지 다뤘다. RAG, Memory injection, Tool use, Structured output이 대표적이다. 다만 단일 에이전트 중심의 구조, 충분히 성숙하지 않은 오케스트레이션, 보안 경계의 부재가 남았다. 이 단계의 개발자 역할은 정보 흐름을 설계하는 컨텍스트 큐레이터였다.
하네스 엔지니어링은 2025~현재의 접근으로, 도구 레지스트리·MCP 서버·오케스트레이션 레이어·격리 샌드박스를 포함한 실행 환경 전체를 대상으로 한다. 멀티에이전트 협업, 수평 확장, 보안 경계를 기본 설계에 넣으며, 개발자는 실행 환경을 설계하는 하네스 아키텍트가 된다.
에이전트 능력을 제어하는 하네스
Harness는 말에 씌우는 마구(馬具)에서 온 말이다. 에너지를 원하는 방향으로 제어하는 구조물이라는 뜻이 AI 에이전트 환경에도 이어진다. 여기서 하네스는 에이전트의 능력을 안전하고 효율적으로 활용하기 위한 실행 환경 전체를 말한다.
도구, MCP 서버, 오케스트레이션 레이어, 격리 샌드박스, 모니터링이 이 환경을 구성한다. 설계의 기준은 최소 권한, 관찰 가능성, 수평 확장성, 장애 격리다.
| 구분 | 전통 엔지니어링 | 하네스 엔지니어링 |
|---|---|---|
| 실행 단위 | 함수/서비스 | 에이전트/서브에이전트 |
| 통신 프로토콜 | REST/gRPC/MQ | MCP/Agent Protocol |
| 상태 관리 | DB/Cache | Agent Memory/Context |
| 보안 경계 | API Gateway/Firewall | 샌드박스/Tool Guard |
| 확장 방식 | 수평적 서비스 복제 | 에이전트 풀 동적 할당 |
| 디버깅 | 로그/트레이싱 | 에이전트 실행 추적/관찰 |
실행 경계를 계층으로 나누는 구조
에이전트 런타임은 인프라부터 오케스트레이션까지의 레이어를 분리해 다룰 수 있다. 하위 레이어는 실행 자원과 보안 경계를 제공하고, 상위 레이어는 작업을 분해하고 에이전트 결과를 조합한다.
L0 인프라 레이어에는 토큰 사용량 추적, 속도 제한, 비용 할당, 폴백 라우팅을 맡는 모델 API 게이트웨이가 놓인다. 메모리는 단기 세션 메모리, 장기 벡터 DB, 에이전트 간 공유 메모리로 나눌 수 있다. 관찰가능성 파이프라인은 OpenTelemetry 기반 실행 추적과 Span 단위 비용 분석을 담당한다.
L1은 에이전트가 실제로 실행되는 격리 경계다. WebAssembly 또는 gVisor 컨테이너에서 코드를 실행하고, 읽기 전용 마운트·임시 writable 영역·비밀 볼트 접근 제어로 파일시스템을 다룬다. 외부 호출은 허용 목록, DNS 필터링, 에그레스(Egress) 제한으로 통제한다.
L2에서는 JSON Schema 기반 도구 메타데이터를 중앙에서 관리하고, MCP 서버의 라이프사이클·헬스체크·버전을 관리한다. Tool Guard는 호출 전에 권한과 파라미터를 검증하고 호출 빈도를 제한한다.
L3의 Primary Agent는 목표를 해석하고 계획을 세우며 서브에이전트 위임을 결정한다. Sub-Agent Pool은 동적으로 생성·소멸하고, Specialist Agent는 코드 실행·검색·데이터 분석처럼 단일 도메인에 집중한다.
L4는 작업 큐, 우선순위, 자원 할당을 관리한다. 작업 분해기는 복잡한 목표를 원자적 태스크로 나누고 DAG를 만들며, 결과 집계기는 병렬 실행 결과의 충돌을 해결해 최종 응답을 만든다.
도구를 중앙에서 등록하고 통제하기
도구 호출은 에이전트가 외부 시스템에 영향을 미치는 지점이다. 따라서 도구 정의, 버전, 권한 정책, 실행 이력을 별도의 레지스트리로 관리할 수 있다.
등록 과정에서는 먼저 JSON Schema로 입출력을 명세하고 Low, Medium, High, Critical 위험 등급을 부여한다. 이어 자동화된 도구 테스트 스위트와 사이드이펙트 분석을 수행한다. High와 Critical 도구는 사람 검토 후 활성화하며, 배포는 카나리 배포 뒤 점진적인 에이전트 풀 확장으로 진행한다. 폐기 단계에서는 Deprecation 태그, 유예 기간, 강제 비활성화 순서를 둔다.
| 카테고리 | 예시 | 위험 등급 | 샌드박스 요구 |
|---|---|---|---|
| 읽기 전용 조회 | DB 조회, 파일 읽기 | Low | 선택적 |
| 외부 API 호출 | 날씨, 검색, 번역 | Medium | 권장 |
| 상태 변경 | DB 쓰기, 이메일 발송 | High | 필수 |
| 시스템 실행 | 코드 실행, 파일 삭제 | Critical | 강제 격리 |
| 에이전트 위임 | 서브에이전트 생성 | High | 부모 상속 |
MCP 서버를 실행 환경에 연결하는 방식
MCP(Model Context Protocol) 서버는 LLM 런타임이 달라도 동일한 인터페이스로 도구를 노출하게 한다. Stateful 연결을 통해 에이전트 컨텍스트를 지속하고, 파일·DB·API 응답을 표준화된 리소스로 제공하며, 재사용 가능한 프롬프트 구조를 서버 수준에서 관리한다.
서버를 등록할 때는 도구 목록, 스키마, 버전을 중앙 레지스트리에 기록한다. 운영 중에는 주기적 ping과 응답 시간 모니터링, 자동 재시작 정책으로 헬스체크를 수행한다. Semantic Versioning과 Breaking Change 감지, 하위 호환성 검증은 버전 관리의 대상이다. 무중단 배포, 점진적 트래픽 전환, 즉시 롤백은 롤링 업데이트에 포함되며, 은퇴하는 서버에는 대체 서버 마이그레이션 가이드를 자동 생성할 수 있다.
보안 측면에서는 mTLS 기반 서버 간 인증과 OAuth 2.0 에이전트 신원 확인을 사용한다. 역할(role)에 따라 MCP 서버 접근 범위를 제한하고, JSON Schema로 호출 파라미터를 검증해 인젝션 공격을 방어한다. 모든 MCP 호출은 불변 로그 저장소(Immutable Log Store)에 기록한다.
작업을 분해하고 결과를 모으는 오케스트레이션
복잡한 목표는 독립적으로 실행 가능한 태스크와 순차 의존 태스크를 구분해야 한다. 예를 들어 웹사이트 성능 분석과 개선 보고서 작성은 성능 메트릭 수집, 병목 원인 분석, 개선안 생성으로 나뉠 수 있으며, 결과 집계기가 산출물을 결합한다.
직렬 체인 패턴은 에이전트 A의 출력을 B의 입력으로, B의 출력을 C의 입력으로 넘긴다. 순차 의존성이나 결과 정제 파이프라인에 맞지만 지연이 누적되고 단일 장애가 전파될 수 있다.
병렬 팬아웃 패턴은 오케스트레이터가 N개 에이전트를 동시에 실행하고 결과를 집계한다. 독립 서브태스크와 빠른 응답 요구에 적합하지만, 집계 복잡도와 부분 실패 처리가 과제다.
계층적 위임은 Primary, Supervisor, Worker 에이전트로 계층을 구성한다. 복잡하고 장기 실행되는 태스크, 품질 검토를 흐름에 넣어야 하는 경우에 맞지만 오버헤드와 레이어 간 컨텍스트 손실이 발생할 수 있다.
반응형 루프 패턴에서는 에이전트가 환경 이벤트에 반응해 자율 실행한다. 지속 모니터링과 이벤트 기반 자동화에 쓸 수 있으나, 루프 탈출 조건의 설계가 복잡하다.
수평 확장을 위해서는 작업 큐 길이에 따른 에이전트 풀 동적 조정, 세션 상태를 외부 스토어에 분리하는 무상태 확장, 카테고리별·우선순위별 작업 큐 파티셔닝(Kafka/RabbitMQ), 동일 입력과 도구 조합의 결과 캐싱을 고려한다. 연속 실패한 에이전트는 서킷 브레이커로 격리하고 헬스가 회복된 뒤 복귀시킨다.
샌드박스가 만드는 보안 경계
에이전트는 허용된 메모리와 임시 파일시스템을 쓸 수 있어도, 데이터베이스·외부 API·영구 파일시스템으로의 접근은 제어된 경로를 거쳐야 한다. Tool Guard, 네트워크 프록시, 시크릿 프록시는 이 경계를 통과시키는 구성 요소다.
프로세스 격리에서는 Linux Namespace의 PID, Network, IPC, Mount, UTS를 분리하고, Cgroup으로 CPU와 메모리 자원을 제한한다. Non-root 실행과 Capability Drop도 이 레이어의 제어 항목이다.
시스템 콜은 Seccomp 프로필의 허용 시스템 콜 화이트리스트로 제한한다. ptrace, mount, kexec_load 같은 위험 시스템 콜은 차단하고, 위반 시 SIGKILL 또는 감사 로그 기록을 수행한다.
커널 에뮬레이션 레이어에서는 gVisor, WASM, Firecracker를 선택지로 둔다. gVisor는 Go로 구현된 사용자 공간 커널이며 호스트 커널과 완전 격리된다. WASM은 웹어셈블리 기반 실행 환경으로 메모리 안전성을 보장하고, Firecracker는 Lambda-like 경량 VM 기반 강력한 격리를 제공한다.
네트워크 정책은 허용된 외부 도메인/IP만 접근하게 하는 에그레스 화이트리스트, 악성·미승인 도메인을 차단하는 DNS 싱크홀, DPI 기반 데이터 유출(Exfiltration) 방어를 포함한다.
에이전트 정체성에는 역할(Role)과 범위(Scope)를 포함한 JWT 기반 토큰을 사용한다. 태스크에 필요한 최소한의 도구와 리소스만 허용하고, 권한을 넘는 행동 시도는 즉시 차단·알림한다. 모든 권한 사용 이력은 불변 로그로 보존한다.
생성부터 종료까지 관리되는 에이전트
에이전트는 생성, 프로비저닝, 실행, 대기, 체크포인트, 완료 또는 실패, 정리의 상태를 거친다. 상태 전이가 명시돼야 재시도와 리소스 정리를 일관되게 처리할 수 있다.
생성 단계에서는 에이전트 템플릿을 기준으로 초기화하고, 의존 MCP 서버의 헬스를 확인한 뒤 시스템 프롬프트와 메모리를 초기 컨텍스트에 주입한다.
실행 중에는 하트비트 기반 Liveness Probe로 생존 여부를 확인하고, 정기 체크포인트로 Resume 가능성을 보장하며, 실행 시간 초과(Timeout) 정책을 강제한다.
종료 시에는 진행 중인 도구 호출을 완료한 뒤 Graceful shutdown을 수행한다. 임시 파일시스템을 완전히 삭제하고 메모리를 초기화하며, 실행 결과·비용·에러 메트릭을 수집해 종료 기록을 남긴다.
재시도는 지수 백오프(Exponential Backoff)를 따를 수 있다. 도구 오류와 모델 오류를 구분해 재시도 대상을 정하고, 영구 실패 태스크는 Dead Letter Queue로 격리한다.
관찰 가능해야 운영할 수 있다
추적(Tracing)에서는 OpenTelemetry Span으로 에이전트 실행을 기록한다. 에이전트에서 도구 호출, MCP 서버, 백엔드까지 전 구간을 분산 추적하며, Span 속성에는 에이전트 ID, 도구명, 입출력 해시, 토큰 수, 비용을 넣는다.
메트릭(Metrics)은 에이전트 처리량(TPS), 평균 완료 시간, 95th 퍼센타일 지연, 도구 호출 성공률, MCP 서버 가용성, 샌드박스 자원 사용률을 다룬다. 토큰 소비량, API 비용, 에이전트별 ROI도 운영 지표가 된다.
로그(Logging)는 에이전트 ID, 세션 ID, 이벤트 타입, 컨텍스트 스냅샷을 담은 구조화 JSON 로그로 남긴다. 민감 정보는 PII 레덕션으로 자동 마스킹하며, 장기 보존은 S3 + Athena 기반 비용 효율적 쿼리를 사용한다.
실패를 분석할 때는 체크포인트를 이용해 특정 시점부터 실행을 재현(Replay)할 수 있다. 실패 시 컨텍스트 창 전체 덤프를 보존하고, 운영 도구를 목(Mock)으로 교체해 안전하게 디버깅한다. 실행 그래프는 Gantt 또는 DAG 형태로 시각화한다.
기존 에이전트 코드를 하네스로 옮기는 과정
기존 코드의 외부 호출 지점(API, DB, 파일)을 모두 식별하고, 각 호출의 위험 등급·부작용·멱등성 여부를 분류하는 것에서 시작한다. 식별된 호출은 JSON Schema 기반 도구 정의로 바꾸고 Tool Guard 미들웨어와 권한 정책을 붙인다.
그다음 도구 그룹을 MCP 서버로 묶어 표준 인터페이스로 노출하고, 기존 비즈니스 로직은 MCP 서버 안에 캡슐화한다. 코드 실행과 파일 조작 도구에는 격리 샌드박스를 적용하며 네트워크 정책과 파일시스템 정책을 정의·테스트한다. 마지막으로 복잡한 멀티스텝 로직을 에이전트 DAG로 재표현하고, 병렬 실행 가능한 태스크와 결과 집계 로직을 분리한다.
프롬프트에 모든 로직을 담는 방식은 다음과 같다.
# 단일 프롬프트에 모든 로직 내포
response = llm.complete(
f"웹사이트 {url}의 성능을 분석하고 개선안을 제시해줘."
f"사용 가능한 도구: requests, beautifulsoup"
)하네스를 통한 구조적 실행은 실행 환경과 태스크를 분리한다.
# 하네스를 통한 구조적 실행
harness = AgentHarness(
tool_registry=tool_registry,
mcp_hub=mcp_hub,
sandbox=IsolatedSandbox(risk_level="medium"),
orchestrator=DAGOrchestrator()
)
result = await harness.run(
goal="웹사이트 성능 분석 및 개선안 도출",
context={"url": url},
agent_pool=["search_agent", "analysis_agent", "writer_agent"],
timeout=300
)프레임워크가 다루는 경계의 차이
| 항목 | 하네스 엔지니어링 | LangChain Agents | AutoGen Multi-Agent |
|---|---|---|---|
| 아키텍처 철학 | 실행 환경 설계 우선 | 체인 조합 중심 | 에이전트 대화 중심 |
| 도구 관리 | 중앙 레지스트리 + Guard | StructuredTool 개별 등록 | Tool 개별 정의 |
| MCP 지원 | 1급 시민(Native) | 플러그인 방식 | 일부 실험적 지원 |
| 격리 샌드박스 | 내장 필수 요소 | 외부 의존 | LocalCommandLineCodeExecutor |
| 오케스트레이션 | DAG 기반 선언형 | LCEL 체인 명령형 | GroupChat/SwarmAgent |
| 수평 확장 | 설계 원칙으로 내재화 | 별도 구현 필요 | 실험적 |
| 관찰가능성 | OTel 기본 통합 | LangSmith 별도 | 제한적 |
| 성숙도(2026) | 표준 수렴 중 | 검증된 생태계 | 마이크로소프트 지원 |
LangChain 방식은 도구를 체인의 일부로 조합하는 명령형 파이프라인이다. 유연하지만 복잡도가 커질수록 관리가 어려워질 수 있다.
AutoGen 방식은 에이전트 간 대화로 문제를 푸는 대화 중심 접근이다. 협업 흐름을 자연스럽게 표현할 수 있지만 결정론적 흐름을 제어하기 어렵다.
하네스 엔지니어링은 실행 환경을 선언적으로 정의하고, 에이전트가 그 안에서 동작하게 한다. 보안·확장성·운영성을 실행 설계에 내재화하는 접근이다.
시스템 아키텍처 원칙이 에이전트 환경으로 옮겨온다
소프트웨어 공학 관점에서 하네스 엔지니어링은 마이크로서비스 아키텍처의 에이전트 버전으로 볼 수 있다. 서비스 메시(Service Mesh)는 하네스 레이어에 해당하고, API Gateway 패턴은 Tool Guard 패턴에 대응한다.
정보 보안에서는 최소 권한 원칙(PoLP)의 에이전트 버전으로 해석할 수 있다. Zero Trust Architecture는 에이전트 신원 모델에 적용되며, SAST/DAST 개념은 에이전트의 정적·동적 행동 분석으로 이어진다.
데이터베이스 관점에서는 에이전트 메모리 시스템이 L1/L2/L3 다계층 캐시 아키텍처에 해당하고, 벡터 DB는 시맨틱 인덱싱 기반 에이전트 장기 기억으로 기능한다. 네트워크에서는 MCP 프로토콜이 OSI 7계층의 응용 레이어에 속하는 에이전트 통신 표준이며, 에그레스 정책은 네트워크 ACL의 에이전트 버전이다.
2026년 이후에는 CNCF 주도의 Harness Specification 초안, 에이전트 실행을 1급 시민으로 지원하는 AI-Native 인프라, EU AI Act와 NIST AI RMF 요구사항의 하네스 설계 기준 반영이 이어질 전망이다. 에이전트가 하네스 설정을 학습 기반으로 최적화하는 자가 치유 하네스와, 다른 조직의 하네스 사이에서 신뢰를 바탕으로 에이전트를 위임하는 크로스 하네스 연합도 방향성으로 제시된다.
하네스 엔지니어링은 도구·MCP·오케스트레이션·샌드박스를 통해 에이전트 능력을 안전하고 확장 가능하게 만드는 AI 에이전트 시대의 시스템 프로그래밍이다. 1970년대 C 언어가 운영체제 커널을 통해 하드웨어를 추상화했듯, 하네스는 에이전트가 실행 환경과 상호작용하는 방식을 구조화한다. 관심사 분리, 최소 권한, 관찰 가능성이라는 전통 소프트웨어 엔지니어링의 원칙이 이 환경에서도 핵심이 된다. 다음 3년은 하네스 설계 역량이 AI 팀의 경쟁력을 가르는 결정적 시기가 될 것이다.
Sources
- Anthropic Claude Code 공식 문서 — Agent Harness 설계 가이드 (2026)
- Model Context Protocol (MCP) 공식 스펙 — modelcontextprotocol.io (2026)
- CNCF Landscape — AI/ML 에이전트 런타임 분류 (2026)
- AWS re:Invent 2025 — "Building Secure Agent Execution Environments"
- Google DeepMind Technical Report — "Multi-Agent Orchestration Patterns" (2025)
- Microsoft AutoGen 프로젝트 공식 문서 — Agent Lifecycle & Sandbox (2025)
- LangChain 공식 블로그 — "From Prompt Engineering to Harness Engineering" (2026)
- NIST AI RMF 1.0 — AI 시스템 보안 및 신뢰성 프레임워크
- EU AI Act 기술 부속서 — 고위험 AI 시스템 실행 환경 요구사항 (2025)
- 한국정보관리기술사 협회 — AI 에이전트 시스템 아키텍처 설계 가이드라인 (2026)