What Is an Agent Harness? And Why Every AI Agent Needs One

최근 AI 개발에 시간을 보낸 적이 있다면 'agent'라는 단어를 많이 들어보셨을 것입니다. 하지만 거의 다루지 않는 중요한 것은, 실제 AI 에이전트를 만들기 위해서는 반드시 harness가 필요하다는 사실입니다. 이 용어는 낯설거나 추상적으로 들릴 수 있습니다. 처음 접했을 때 저도 같은 반응을 보였습니다. 하지만 한 번 깨달았을 때는 다시 잊을 수 없었고, 저는 이것이 단순 LLM API 호출을 넘어 자율적으로 일을 수행하는 것을 구축하고 싶다면 이해해야 할 가장 중요한 개념 중 하나라고 진심으로 생각합니다. 모든 것을 기초부터 정리해 보겠습니다.

'단순 모델 사용'의 문제점
시나리오를 상상해 보세요: Claude 나 GPT-4 같은 강력한 모델에 API 접근이 있습니다. 프롬프트를 보내면 응답을 받습니다. 이는 챗봇과 한 번 완성 (one-shot completions) 에는 훌륭하지만, 모델을 다음처럼 수행하고 싶다면 어떻게 될까요?

웹을 탐색하고 실시간 데이터를 가져오기?
Python 코드를 실행하여 해당 데이터를 분석하기?
지난 주에 말한 것을 기억하기?
여러 단계로 조정 — 각 단계가 전 단계에 의존하는 경우?
내부 API 나 툴 호출하기?
원래 모델은 이것들을 수행할 수 없습니다. 이 일을 할 수 있다는 것만 이야기할 수는 있지만, 실제로 이를 수행할 방법은 없습니다. 이는 뛰어난 분석가를 고용했지만 노트북이 없고 인터넷도 없으며, 오직 메모를 전달하여만 소통할 수 있는 상황과 같습니다. 지능은 있습니다 — 인프라는 아닙니다.

그 누락된 인프라가 바로 harness 입니다.

Agent Harness 는 정확히 무엇인가?
Agent Harness 는 모델을 텍스트 생성기에서 실제 세계에서 행동하는 에이전트로 변환하기 위해 모델 주변에 구축하는 모든 것입니다. 제가 접한 가장 깔끔한 공식은 다음과 같습니다:

Agent = Model + Harness

에이전트의 모델이 아닌 모든 것은 harness 의 일부입니다.

구체적으로 말하면, harness 는 일반적으로 다음을 포함합니다:

orchestration loop — 사용자 메시지를 받아 에이전트가 무엇을 해야 하는지 물어보고, 해당 동작을 실행한 후 결과를 다시 입력하여 작업을 완료할 때까지 반복하는 논리.
tool connections — 브라우저 호출, 코드 실행, 데이터베이스 쿼리, 외부 API 호출 등을 가능하게 하는 파이프라인.
memory — 세션 내의 단기 컨텍스트와 세션 간에 지속되는 장기 기억.
context management — 각 단계마다 프롬프트에 들어가는 정보를 결정 (무한히 계속 추가할 수 없으며 모델은 토큰 제한이 있음).
compute and sandboxing — 에이전트가 시스템을 폭파하지 않고 안전하게 코드를 실행할 수 있는 곳.
authentication — 에이전트가 외부 API 를 안전하게 호출할 수 있도록 함.

신뢰할 수 있는 API 를 사용하되 자격증명을 누설하지 않습니다. 가시성 — 2 시에 일이 엉망이 될 때 무엇을 일어난지 알 수 있도록 로그, 트래스, 디버깅 도구입니다. 세션 관리 — 사용자가 중단하고 재개하여 마지막 자리에서 바로 다시 시작할 수 있는 기능입니다. 오늘 사용하는 모든 AI 기반 제품을 살펴보세요 — Claude Code, GitHub Copilot, Cursor, Perplexity — 배경에는 이 모든 작업을 수행하는 하네스가 있습니다. 모델은 훨씬 더 큰 기계의 일부일 뿐입니다. 왜 하네스 구축이 이렇게 고통스러운지 여기가 솔직한 현실입니다: 처음부터 하네스를 구축하는 것은 어렵고 시간이 많이 걸립니다. 이전에 해본 적이 있다면 그 과정을 알 것입니다. 프레임워크를 선택합니다 — LangGraph, LlamaIndex, CrewAI, Strands Agents — 그리고 코드를 작성하기 시작합니다. 도구를 연결합니다. 모델이 혼란스러워하지 않도록 프롬프트 구조를 신중하게 관리합니다. 도구 호출 실패에 대한 오류 처리를 추가합니다. 재시도 로직을 구축합니다. 스트리밍 출력을 처리합니다. 로그 설정을 합니다. 모든 것을 컨테이너로 패키징하고, 일부 컴퓨팅 자원을 할당하며 배포합니다. 그리고 세션 지속성을 필요로 함을 깨닫습니다. 그래서 데이터베이스를 추가합니다. 그리고 에이전트가 외부 API 와 인증해야 함을 깨닫습니다. 그래서 자격증명 관리를 설정합니다. 이제 에이전트가 왜 이상한 추론 경로를 선택했는지 이해해야 하므로 트래스를 추가합니다. 단순한 사용 사례라면 몇 일이 걸릴 수 있습니다. 복잡한 경우라면 몇 주 — 그리고 전체 팀이 필요할 수 있습니다. AI 에이전트 구축의 진정한 장벽은 모델이 아닙니다. 하네스입니다. 관리형 하네스 소개: 에이전트 팩토리 모델 도구링은 마침내 이 문제를 따라잡았습니다. 관리형 하네스의 아이디어는 간단합니다: 모든 오케스트레이션과 인프라 코드를 직접 작성하는 대신, 에이전트가 필요로 하는 것을 구성으로 선언하고, 서비스가 하네스를 구축해 줍니다. 자체 서버 설정 (하네스 코드 처음부터 작성) 과 관리형 클라우드 서비스 사용 (구성 선언하고 플랫폼이 나머지를 처리) 의 차이점을 생각해보세요. Amazon Bedrock AgentCore 는 이 접근 방식을 취하는 서비스 중 하나입니다. AgentCore 의 하네스 기능을 사용하면 JSON 구성 파일 — 모델, 시스템 프롬프트, 도구, 메모리 설정 — 에서 에이전트를 정의하고, 플랫폼이 그 아래 인프라를 모두 처리하며 완전히 실행되는 에이전트로 컴파일합니다. 내부적으로, AgentCore 하네스는 Strands Agents (AWS 의 오픈소스 에이전트 SDK) 를 사용하여 오케스트레이션 루프, 도구 실행, 메모리 관리를 조립합니다.

컨텍스트 처리 및 스트리밍을 지원합니다. 그런 다음 단일 서버 프로비저닝 없이 전용 CPU, 메모리, 파일 시스템을 갖춘 독립형 microVM 내부에서 전체 작업을 실행합니다.

Let's Build Something: An AI Trends Analyst in Minutes 를 구체화하기 위해 AgentCore harness 을 사용하여 0 에서 작동하는 AI 에이전트로 가는 과정과 약 5 분 정도 걸린다는 점을 강조합니다.

목표: HackerNews 와 dev.to 를 탐색하고, 오늘의 상위 AI 및 개발자 도구 게시물을 가져와서 주제별로 클러스터링한 다음 차트와 함께 순위 요약본을 생성하는 에이전트를 구축합니다.

1 단계: CLI 설치
npm install -g @aws/agentcore@preview

2 단계: 에이전트 구성 파일 생성
인터랙티브하게 agentcore create 명령어를 실행하면 사용 모델, 활성화 도구, 인증 유형 등을 안내하는 프롬프트 세트를 진행합니다. 마지막에는 다음과 같은 구성 파일을 생성합니다:
{ "name" : "TrendsAgentHarness" , "model" : { "provider" : "bedrock" , "modelId" : "global.anthropic.claude-sonnet-4-6" }, "tools" : [ { "type" : "agentcore_browser" , "name" : "browser" }, { "type" : "agentcore_code_interpreter" , "name" : "code-interpreter" } ], "skills" : [], "authorizerType" : "AWS_IAM" }
브라우저 도구는 에이전트가 실제 웹사이트를 탐색하게 합니다. 코드 인터프리터는 데이터 처리 및 차트 생성을 위한 Python 샌드박스를 제공합니다.

3 단계: 시스템 프롬프트 작성
구성 파일과 함께 생성된 system-prompt.md 파일을 편집합니다:
당신의 임무는 현재 AI 및 개발 커뮤니티가 무엇을 논의하고 있는지 파악하는 것입니다. 세션마다 HackerNews 와 dev.to 로 이동하여 오늘의 가장 인기 있는 게시물을 크롤링한 다음 코드 인터프리터를 사용하여 모든 것을 이해하게 하세요 — 주제를 클러스터링하고 빈도수에 따라 순위를 매기며 상위 5 개를 평문으로 요약하세요. 막대 차트를 추가하세요. 불필요한 것은 없습니다. 시스템 프롬프트는 에이전트의 성격과 운영 지침입니다. 여기서는 무엇을 수행하는지, 어떻게 생각하는지, 그리고 기대하는 출력 결과를 정의합니다.

4 단계: 배포
agentcore deploy 명령어를 실행하면 구성 파일 및 시스템 프롬프트를 사용하여 Strands Agents 프로그램을 조립하고 관리형 microVM 환경에 배포합니다. Dockerfile, Kubernetes, EC2 인스턴스 없이 단일 명령어로 실행됩니다.

5 단계: 호출
agentcore invoke --harness TrendsAgentHarness \ --session-id " $( uuidgen ) " \ "What's trending in IT today?" 이 명령을 실행하면:
에이전트는 브라우저를 열고 HackerNews 로 이동합니다. 상위 게시물을 스크롤하며 읽습니다. dev.to 도 동일한 작업을 수행합니다.

to. 코드 인터프리터에 모든 결과를 가져옵니다. Python 을 실행하여 주제를 군집화하고 빈도를 계산하며 막대 차트를 구축합니다. 포맷된 요약은 터미널로 스트리밍됩니다. 이 모든 것은 세션 동안 시작되고 완료될 때 종료되는 격리된 microVM 에서 실행됩니다. 크로스 세션 데이터 유출 없음, 노이즈 이웃 없음.

What Comes Built In Here 는 AgentCore harness 가 추가 설정 없이 제공하는 내용을 정리합니다:

Capability	What It Actually Means For You
Isolated microVM per session	세션마다 별도의 CPU, 메모리, 파일 시스템을 갖습니다. 세션은 완전히 격리됩니다.
Shell access	모델의 추론 루프를 거치지 않고 직접 shell 명령어를 실행할 수 있습니다. 더 빠르고 저렴합니다.
Persistent filesystem	세션 중 파일을 저장하고, 중단한 후 처음부터 다시 시작할 수 있습니다.
Model-agnostic routing	Bedrock, OpenAI, Google Gemini 간 전환이 가능합니다. 세션 중 제공자를 변경해도 대화 컨텍스트는 유지됩니다.
Built-in browser tool	AgentCore Browser 를 기반으로 합니다. 에이전트는 검색 API 만이 아닌 실제 웹사이트를 탐색할 수 있습니다.
Built-in code interpreter	전체 Python sandbox 를 제공합니다. 에이전트는 코드를 작성하고 실행하며, 차트를 생성하고 파일을 처리할 수 있습니다.
MCP server support	Slack, Notion, GitHub 등 모든 MCP 호환 도구 서버에 연결할 수 있습니다.
AgentCore Gateway	중앙에서 등록한 API 에 연결하여 자격 증명을 에이전트 외부에서 관리합니다.
Custom tool definitions	에이전트가 호출할 사용자 정의 인라인 함수 도구를 정의할 수 있습니다.
Skills	Domain expertise 를 markdown + scripts 로 패키징하고, 에이전트에 필요할 때 전문가 수준의 컨텍스트를 제공합니다.
Full observability	모든 동작은 AgentCore Observability 를 통해 자동으로 추적됩니다. 따라서 발생된 모든 것을 디버깅 및 감사할 수 있습니다.

Agent Skills: Teaching Your Agent Domain Expertise 는 특히 언급할 가치가 있는 기능입니다. 에이전트 스킬은 특정 도메인 또는 워크플로우에 대한 깊은 지식을 제공하는 markdown 지침과 (선택적으로) 스크립트의 묶음입니다. 이를 이렇게 생각해보세요: 일반 모델을 특정 컨텍스트로 훈련할 수 있습니다.
예를 들어:

• 내부 데이터 형식과 함께 에이전트를 가르치는 스킬
• 회사 API 관례를 가이드하는 스킬
• Excel 리포트를 처리하는 방법을 단계별로 알려주는 스킬
  스킬은 에이전트 환경에 패키징하고, harness 를 지시하며, 에이전트가 이를 가져와 자동으로 사용합니다.

적절할 때만 적용합니다. Fine-tuning(파인튜닝) 없음. Custom model training(커스텀 모델 학습) 없음. 에이전트가 참조할 수 있는 구조화된 지식 만입니다. The Escape Hatch(탈출구): Config 한계를 넘어설 때

질문: "내 사용 사례가 config 파일만으로는 부족할 정도로 복잡해질 때, 어떤 일이 발생하나요?"
그건 공정하고 중요한 질문입니다.
아마 다음이 필요할 수 있습니다:

• 에이전트가 작업을 서로 전달하는 커스텀 멀티 에이전트 오케스트레이션
• 메시지 내용에 기반한 특수 라우팅 로직
• 자체 벡터 데이터베이스를 가진 완전 커스텀 메모리 레이어
• 표준 패턴에 맞지 않는 내부 인프라와 통합

AgentCore harness(해니스)는 이에 대한 답을 가지고 있습니다: export to code(코드 내보내기)

완전 통제를 필요할 때, harness 구성을 Strands Agents 코드로 내보낼 수 있습니다.
당신은 AgentCore 가 대신 실행해 준 완전 읽기 가능하고 편집 가능한 Python 프로그램을 얻습니다.
그리고 필요에 따라 확장할 수 있습니다.
동일한 플랫폼에 남지만 더 많은 통제를 가집니다.
이건 똑똑한 설계입니다.
빠른 경로 (config) 로 시작하고, 실제로 필요할 때만 커스텀 경로 (code) 로 진급합니다.
하나로 묶이지 않습니다.

Common Questions Answered(자주 묻는 질문)

Claude.ai 나 ChatGPT 를 사용 중이라면 harness 를 구축해야 하나요?
아니요. 그건 다른 사람이 이미 harness 를 구축해 준 소비자 제품입니다.
커스텀 에이전트를 만들 때만 스스로 구축해야 합니다:

• 특정 도구를 호출하는 에이전트
• 내부 시스템과 연결하는 에이전트
• 상태를 유지하는 에이전트
• 여러 단계에 걸쳐 자율적으로 실행하는 에이전트

Harness 가 Agent framework(에이전트 프레임워크) 와 같은가요?
아니요.
프레임워크 (Strands Agents, LangGraph, CrewAI 등) 는 구성 요소 블록을 제공합니다:

• 도구 인터페이스
• 루프 패턴
• 모델 커넥터

해니스는 완전히 조립되고 실행 중인 시스템입니다:

• 프레임워크 코드
• 컴퓨팅
• 샌드박싱
• 메모리
• 인증
• 관측 가능성

프레임워크를 사용하여 해니스를 만들거나, 관리 서비스를 사용하여 하나를 만들어 줍니다.

Framework 없이 harness 를 구축할 수 있나요?
기술적으로는 가능하지만, 오케스트레이션 루프, 도구 디스패치, 오류 복구, 컨텍스트 관리를 모두从零부터 작성해야 합니다.
프레임워크는 바로 그 일을 하지 않으려는 존재입니다.
Express.js 대신 raw socket code(소켓 코드) 를 쓰는 것과 비슷합니다. 가능하지만 거의 항상 옳지 않은 선택입니다.

브라우저 도구가 토큰에 비쌉니까?
네, 더 많은 토큰을 소비합니다. 전체 웹 페이지를 처리하기 때문입니다.
트렌드 분석가 사용 사례에는 절대 가치가 있습니다.
데이터 조회가 가벼운 에이전트에게는... (문단未完)