하네스 설계와 구현

1. ReAct, AI가 스스로 일하는 가장 기본적인 루프

자율적인 AI 에이전트의 작동 방식을 가장 자주 인용되는 한 줄로 요약하면 "생각하고, 행동하고, 관찰하고, 다시 생각한다"가 됩니다. 이 패턴에 이름을 붙인 논문이 2022년 10월 Princeton과 Google Brain 공동 연구진이 발표한 ReAct: Synergizing Reasoning and Acting in Language Models (arxiv 2210.03629)입니다. ChatGPT보다 약 한 달 먼저 나온 이 논문이, 지금 우리가 쓰는 거의 모든 에이전트형 도구의 뼈대가 되었습니다.

1.1 동작 루프

루프가 도는 동안 모델은 자기 생각을 글로 남깁니다. Claude Code 같은 도구를 써본 사람이라면 익숙한 풍경입니다.

Thought: 사용자가 로그인 API를 만들어달라고 했다.
         먼저 기존 인증 코드를 확인해야 한다.
Action: 파일 검색, auth 관련 파일 찾기
Observation: src/auth/middleware.ts 파일을 발견했다.
Thought: 기존 미들웨어를 확인하고, 같은 패턴으로 새 라우트를 추가해야겠다.
Action: 파일 읽기, src/auth/middleware.ts
Observation: JWT 기반 인증을 사용 중이다.
Thought: JWT 패턴에 맞춰 로그인 API를 작성하겠다.
Action: 파일 생성, src/auth/login.ts

이 풍경이 익숙해야 하는 이유는 하네스 설계에서 우리가 통제하는 거의 모든 변수가 이 루프 안에서 일어나기 때문입니다. 어떤 Action(도구)을 허용할지, Observation을 어떤 형식으로 모델에 다시 보여줄지, 루프를 몇 번까지 돌게 둘지, 한 번 돌 때마다 사람이 개입할 자리가 있는지. 이 결정들이 곧 하네스입니다.

2. Anthropic의 다섯 가지 워크플로우 패턴

2024년 12월 Anthropic은 Building Effective Agents라는 가이드를 발표합니다. 이 문서는 지금도 자율 에이전트 설계의 표준 참고서로 인용되는데, 거기서 정리한 다섯 가지 워크플로우 패턴이 가장 자주 인용됩니다. 하나씩 보면 자기가 만들고 있는 게 어떤 모양인지 빠르게 짚어볼 수 있습니다.

가이드의 핵심 조언 한 줄은 이렇습니다. "성공한 구현은 대부분 복잡한 프레임워크가 아니라 단순한 패턴의 조합이다. 가장 단순한 것부터 시도하고, 그게 안 될 때만 복잡한 패턴으로 올라가라."

2.1 Prompt Chaining (체이닝)

큰 작업을 작은 단계로 쪼개서 차례차례 처리합니다. 3장에서 "한 번에 다 시키지 말고 새 대화로 끊자"고 한 그 발상을, 작업 단계 분리 형태로 정형화한 것입니다.

사용 예: 문서 초안 → 번역 → 톤 수정. 모델이 한 번에 너무 많은 걸 처리하지 않도록 작업을 분리해서 정확도를 올리는 패턴.

2.2 Routing (라우팅)

들어온 요청의 종류를 먼저 분류해서, 그에 맞는 모델·프롬프트로 전달합니다.

사용 예: 고객 응대에서 간단한 질문은 빠르고 싼 모델로, 까다로운 환불 분쟁은 강한 모델로 보냄. 비용 절감 효과가 가장 큰 패턴 중 하나.

2.3 Parallelization (병렬화)

독립적인 작업을 동시에 돌립니다. 두 가지 변형이 있습니다.

Sectioning. 작업을 부분으로 쪼개 동시에 처리 (예: 한 문서를 영어·일본어·중국어로 동시 번역).
Voting. 같은 질문을 여러 번 돌려 합의된 답만 채택 (예: 코드 보안 검사에서 한 모델만 잡으면 노이즈가 큰데, 3개가 잡으면 진짜 취약점).

2.4 Orchestrator-Workers (오케스트레이터-워커)

한 명의 "관리자 LLM"이 작업을 작은 단위로 쪼개 여러 "워커 LLM"에게 나눠주고, 결과를 모아 정리합니다.

병렬화와 비슷하지만 작업 분배 자체를 모델이 동적으로 한다는 점이 다릅니다. 사용 예: 복잡한 리팩토링에서 관리자 LLM이 "이 파일 5개를 동시에 고쳐야 한다"고 판단해서 각 파일을 워커에게 맡김. Claude Code의 서브 에이전트(Explore, Plan 같은 것들)도 이 패턴에 가깝습니다.

2.5 Evaluator-Optimizer (평가자-최적화기)

한 모델이 결과를 만들고, 다른 모델이 그 결과를 평가해서 점수와 피드백을 줍니다. 피드백을 기준점으로 첫 번째 모델이 다시 시도합니다. 일정 기준을 통과할 때까지 루프가 돕니다.

사용 예: 카피라이팅의 초안을 또 다른 모델이 "타깃 독자에게 정말 와닿는가" 기준으로 평가, 통과될 때까지 개선. 3장에서 본 자기 검증과 비슷하지만 평가자를 분리한 형태.

3. 단일 에이전트 vs 멀티 에이전트

위 패턴 중 Orchestrator-Workers와 Evaluator-Optimizer는 본질적으로 멀티 에이전트입니다. 둘 사이의 트레이드오프를 한 번에 정리해 둡니다.

단일 에이전트. 한 모델이 모든 도구를 들고 일을 풀어갑니다.

장점: 디버깅이 쉽다, 비용이 예측 가능하다.
단점: 컨텍스트가 한 군데 모이니까 길어지면 품질이 떨어진다 (3장의 "긴 대화 문제").

멀티 에이전트. 전문화된 에이전트 여러 명이 협업합니다.

장점: 각 에이전트의 컨텍스트가 짧게 유지된다, 전문화로 정확도가 올라간다.
단점: 비용이 곱셈으로 늘어난다, 디버깅이 어렵다, 에이전트 간 통신이 또 다른 실패 지점이 된다.

Anthropic 가이드의 권고는 분명합니다. "단일 에이전트가 안 될 때까지는 단일로 가라." 멀티가 매력적이지만 그만큼 복잡성과 비용을 부르고, 그게 정당화될 만큼의 가치를 주는 경우는 생각보다 드물다는 입장입니다.

4. 도구 설계, AI가 잘 쓰는 도구의 모양

도구는 사람이 보기에 멀쩡해도 모델 입장에서 못 쓰는 경우가 흔합니다. 이름이 모호하거나, 파라미터가 너무 많거나, 실패 메시지가 의미 없거나 하면 모델이 호출 자체를 안 합니다.

4.1 도구 정의 예시

{
  "name": "search_products",
  "description": "상품을 검색합니다. 상품명·카테고리·가격 범위로 필터링할 수 있습니다.",
  "parameters": {
    "query": {
      "type": "string",
      "description": "검색할 상품명 또는 키워드"
    },
    "category": {
      "type": "string",
      "enum": ["전자기기", "의류", "식품", "도서"],
      "description": "상품 카테고리"
    },
    "min_price": {
      "type": "number",
      "description": "최소 가격 (원)"
    },
    "max_price": {
      "type": "number",
      "description": "최대 가격 (원)"
    }
  },
  "required": ["query"]
}

4.2 잘 작동하는 도구의 다섯 가지 특징

한 도구는 한 일. manage_user처럼 여러 동작이 섞인 도구보다 create_user, update_user, delete_user처럼 쪼개진 도구가 호출 정확도가 높습니다.
이름이 동사로 시작. userInfo가 아니라 get_user_info. 모델이 "지금 무엇을 하려는 행동인가"로 도구를 고르기 때문입니다.
설명이 "언제 쓰는 도구인지" 명시. 기능만 적지 말고 "이런 상황에 쓴다, 이런 상황에는 쓰지 마라"까지 적으면 호출 빈도가 정확해집니다.
파라미터는 enum과 description을 같이. 모델이 잘못된 값을 넣을 확률을 줄입니다.
실패 메시지가 의미 있게. "Error: 500"이 아니라 "Error: query 파라미터가 비어 있습니다. 키워드를 한 개 이상 넣어주세요." 모델이 다음 시도에서 무엇을 고쳐야 할지 알 수 있어야 합니다.

5. 가드레일, 무엇을 못 하게 막을 것인가

AI가 도구를 들기 시작하는 순간, 잘못된 호출의 비용이 글자에서 행동으로 바뀝니다. 가드레일은 이 비용을 통제하는 장치입니다.

5.1 세 단계의 가드레일

입력 단
- 프롬프트 인젝션 패턴 차단 ("이전 지시 무시" 같은 문구 검출)
- 입력 길이 상한 (예: 10,000 토큰)
- 민감 정보 자동 마스킹 (주민번호, 카드번호)

출력 단
- JSON 스키마 검증, 필수 필드 확인
- 유해 콘텐츠 필터
- 컨텍스트와 모순되는 답 차단 (3장의 자기 검증 패턴 응용)

실행 단
- 위험 명령은 사용자에게 확인 (rm -rf, DROP TABLE 같은 패턴)
- API 호출 횟수 상한 (요청당 최대 10회)
- 비용 상한 (일일·세션당 토큰 한도)
- 타임아웃

실행 단 가드레일이 가장 중요합니다. "사람이 확인할 자리"를 어디에 둘지 가 자율성과 안전성을 동시에 결정합니다. Claude Code가 파일 수정 시 사용자에게 확인을 받는 패턴, Plan 모드와 Auto-Accept 모드를 분리한 디자인이 정확히 이 자리의 트레이드오프를 다루고 있습니다.

5.2 비용 가드레일

AI 도구가 자유롭게 도구를 호출하면 비용이 무한정 늘 수 있습니다. 다음 셋은 거의 필수입니다.

세션 토큰 상한. 한 작업이 토큰 1M을 넘기면 자동 중단.
모델 등급 분리. 간단한 분류·라우팅은 경량 모델(예: Haiku), 어려운 추론만 고급 모델(예: Opus).
재시도 상한. 도구가 실패할 때마다 무한 재시도가 일어나지 않도록 보통 3~5회로 제한.