이 블로그엔 에이전트 설계 글이 이미 여럿 있다. 계층으로 쪼개 보기(아키텍처 분해), 다섯 층(에이전트 5계층), 네 축(4차원), OS 관점(OS 로 보는 에이전트 설계), 멀티 에이전트 원칙(13원칙). 전부 무엇이 있는가 를 다룬 글이다.

이번 글은 두 가지만 다룬다.

  1. 결정 순서 — 어떤 질문을 어떤 차례로 던져야 되돌리기 비싼 결정을 먼저 제대로 하는가.
  2. 도구(ACI) 설계 — 실제 성능을 가장 크게 움직이는데 가장 덜 설계되는 부분.

근거는 1차 출처 다섯 편이다. Anthropic 엔지니어링 글 세 편123, OpenAI 의 실무 가이드4, 그리고 ACI 라는 말을 만든 SWE-agent 논문(NeurIPS 2024)5. 필자 의견은 (필자 제안) 으로 따로 표시했다.

한 장 요약 — 7개의 질문

순서 질문 틀리면 치르는 값 주 출처
Q0 이게 에이전트여야 하나? 비용·지연·예측불가를 이유 없이 삼킴 Anthropic1
Q1 워크플로라면 어떤 패턴? 루프가 필요 없는 곳에 루프 Anthropic1
Q2 에이전트는 몇 개? 조율 오버헤드·책임 분산 OpenAI4
Q3 도구는 어떻게 생겼나 (ACI) 성능의 가장 큰 변수 SWE-agent5, Anthropic2
Q4 컨텍스트 예산은? 긴 작업에서 조용한 품질 저하 Anthropic3
Q5 언제 멈추고 언제 사람을 부르나 폭주·되돌릴 수 없는 행동 OpenAI4, Anthropic1
Q6 무엇으로 좋아졌다고 말하나 “느낌상 나아짐” 으로 배포 Anthropic2

순서가 중요한 이유는 뒤 질문의 답이 앞 질문의 답에 묶이기 때문이다. Q0 에서 “워크플로면 된다” 가 나오면 Q2·Q5 의 절반이 사라진다. 반대로 Q3 을 건너뛰고 Q2 로 가서 에이전트를 늘리면, 나쁜 도구를 여러 에이전트가 나눠 쓰는 구조가 된다.

Q0. 에이전트여야 하나

Anthropic 은 두 가지를 구분한다1.

  • 워크플로 — LLM 과 도구가 미리 정해진 코드 경로 로 조율되는 시스템
  • 에이전트 — LLM 이 스스로 과정과 도구 사용을 동적으로 지휘하는 시스템

그리고 첫 권고가 “가능한 가장 단순한 해법을 찾고, 필요할 때만 복잡도를 올려라” 다. 에이전트형 시스템은 더 나은 과제 성능을 얻는 대신 지연과 비용을 치른다는 점을 명시한다. 많은 경우 검색·예시를 붙인 단일 LLM 호출로 충분하다고 한다1.

판단 기준을 한 줄로 줄이면 이렇다 (필자 정리): 단계 수를 미리 적을 수 있으면 워크플로, 못 적으면 에이전트. 버그 수정처럼 몇 개 파일을 건드릴지 사전에 모르는 일이 후자다.

이 질문을 따로 다룬 글: 멀티 에이전트가 손해인 경우.

Q1. 워크플로 패턴 고르기

Anthropic 이 제시한 기본 블록은 증강 LLM(검색·도구·메모리를 붙인 LLM) 하나다. 그 위의 워크플로 패턴 다섯 가지는 다음과 같다1.

패턴 쓸 때 설계 포인트
프롬프트 체이닝 고정된 하위 단계로 깔끔히 나뉨 단계 사이에 프로그램적 게이트 로 검사
라우팅 입력 종류별로 처리가 다름 분류가 정확해야 함
병렬화 독립 하위 작업(섹셔닝) 또는 다수결(보팅) 결과 합치는 규칙
오케스트레이터-워커 하위 작업을 미리 못 정함 병렬화와의 차이는 유연성
평가자-최적화자 평가 기준이 명확하고 반복하면 나아짐 평가자가 판정할 수 있어야 함

(필자 제안) 실무에서 가장 많이 빠지는 건 체이닝의 게이트 다. 1단계 출력이 형식만 맞으면 그대로 2단계로 넘기는 파이프라인이 흔하다. 게이트는 LLM 이 아니라 코드여야 싸고 결정적이다.

Q2. 에이전트 수 — 하나부터

OpenAI 가이드의 권고는 먼저 단일 에이전트의 능력을 최대한 끌어내라 다. 에이전트를 나누는 기준은 둘이다4.

  1. 로직이 복잡할 때 — 조건 분기가 프롬프트 템플릿으로 감당이 안 될 때
  2. 도구가 과부하일 때 — 단, 기준은 개수가 아니라 유사도·겹침 이다. 서로 다른 도구 15개 이상을 잘 다루는 경우도 있고, 겹치는 도구 10개 미만에서 헤매는 경우도 있다고 적었다.

나눈다면 두 가지 모양이 있다4.

  • 매니저 패턴 — 중앙 에이전트가 다른 에이전트를 도구처럼 호출
  • 분산 패턴 — 에이전트끼리 제어권을 넘기는 핸드오프

두 번째 기준이 Q3 으로 이어진다. 에이전트를 쪼개고 싶어지는 원인이 사실은 겹치는 도구라면, 먼저 도구를 고치는 게 순서다.

Q3. 도구 설계 = ACI 설계

ACI 라는 말이 나온 곳

SWE-agent 논문은 사람을 위한 인터페이스(HCI)처럼 에이전트를 위한 컴퓨터 인터페이스(ACI) 를 따로 설계해야 한다고 주장했다5. 핵심은 세 가지다.

  • 단순한 소수의 행동 — 셸 명령을 그대로 주는 대신 에이전트용 명령을 만든다
  • 가드레일 — 편집 명령에 린터를 붙여, 문법 오류를 내는 편집은 버리고 다시 시도하게 한다
  • 간결한 피드백 — 검색 결과는 최대 50건, 파일 뷰어는 100줄 창

결과(논문 수치, 2024년, 주로 GPT-4 Turbo):

  • SWE-bench 전체 테스트셋 12.47% (2,294 중 286), Lite 18.00%
  • 같은 모델에 셸만 준 경우 대비 상대 64% 향상 (절대 +10.7%p, 어블레이션)

같은 모델에서 인터페이스만 바꿔 이만큼 움직였다는 것이 이 논문의 요지다. 대가도 적혀 있다. 비용은 RAG 기반 대비 8~13배이고, 해결률은 6.7배다5.

Anthropic 의 실측 사례

Anthropic 도 같은 결론을 냈다. SWE-bench 에이전트를 만들 때 “전체 프롬프트보다 도구 최적화에 더 많은 시간을 썼다” 고 한다1. 사례는 이렇다. 루트 디렉터리를 벗어나면 모델이 상대경로를 틀렸다. 도구가 항상 절대경로를 요구하도록 바꾸자 모델이 “완벽하게” 썼다. 모델을 고친 게 아니라 틀리기 어렵게 만든 것이다. 이걸 포카요케(실수 방지) 라고 부른다1.

도구 형식에 대한 권고도 있다1.

  • 모델이 쓰기 전에 생각할 토큰 여유를 줄 것
  • 인터넷 텍스트에 자연스럽게 나오는 형식에 가깝게 할 것
  • 형식 오버헤드를 없앨 것 — diff 헤더의 줄 수를 미리 세게 하거나 JSON 안에 코드를 이스케이프하게 하지 말 것
  • HCI 에 쏟는 만큼의 노력을 ACI 에 쏟을 것

도구 설계 원칙 (Anthropic, 2025-09)

“Writing effective tools for agents” 는 도구를 결정적 시스템과 비결정적 에이전트 사이의 계약 으로 정의한다2. 원칙을 정리하면 다음과 같다.

원칙 나쁜 예 → 좋은 예 이유
API 를 감싸지 말고 작업 을 감쌀 것 list_contacts → search_contacts 에이전트 컨텍스트는 유한. 전부 읽게 하지 말 것
여러 호출을 하나로 로그 조회 여러 번 → search_logs 호출 수·중간 토큰 절감
네임스페이스 search → asana_search, jira_search 도구가 많아질수록 혼동 방지. 접두/접미 선택도 성능에 영향
의미 있는 식별자 반환 UUID → 사람이 읽는 이름 환각 감소
응답 상세도 선택 response_format = concise 또는 detailed 예시에서 concise 가 약 ⅓ 토큰(72 대 206)
페이지네이션·필터·절단 전부 반환 → 기본값 있는 페이지 Claude Code 는 도구 응답을 기본 25,000 토큰으로 제한
행동 가능한 에러 에러 코드·트레이스백 → 무엇을 고쳐 다시 부를지 에러도 프롬프트다
파라미터 이름 user → user_id 모호성 제거

설명문 한 줄이 행동을 바꾼 사례가 둘 있다2.

  • 웹 검색 도구에서 Claude 가 쿼리 끝에 불필요하게 “2025” 를 붙이던 문제는 도구 설명을 고쳐서 해결됐다.
  • Claude 3.5 Sonnet 의 SWE-bench Verified 최고 성능은 도구 설명을 정밀하게 다듬은 뒤 나왔다.

MCP 명세도 같은 방향이다. 도구 정의에 inputSchema 외에 선택적 outputSchema 와 행동 annotations 를 두고, 실행 오류는 프로토콜 오류와 구분해 결과 안에 isError: true 로 돌려주게 한다. 그래야 모델이 그 오류를 읽고 다시 시도할 수 있다6. 단, 명세는 신뢰할 수 없는 서버의 annotations 를 믿지 말라 고 못박는다6. “읽기 전용” 표시는 서버의 자기 신고일 뿐이다. (MCP 사용법 자체는 이 글의 범위가 아니다.)

체크리스트로 줄이면

(필자 제안) 도구 하나를 새로 만들 때 이 다섯 가지를 묻는다.

  1. 이 도구는 API 엔드포인트인가, 작업인가? 엔드포인트면 한 층 올린다.
  2. 가장 흔한 실수 가 무엇이고, 그걸 불가능 하게 만들 수 있나? (절대경로 사례)
  3. 기본 응답이 몇 토큰 인가? 상한과 페이지가 있나?
  4. 실패하면 모델이 다음에 무엇을 할지 에러가 말해 주나?
  5. 비슷한 이름의 다른 도구와 헷갈릴 여지가 있나?

Q4. 컨텍스트 예산

Anthropic 은 컨텍스트를 유한한 주의(attention) 예산 으로 본다. 목표는 원하는 결과가 나올 가능성을 최대화하는 가장 작은, 신호 밀도 높은 토큰 집합 이다3. 긴 작업을 위한 기법은 다음과 같다3.

  • 적시(just-in-time) 로딩 — 데이터를 미리 다 넣지 말고 가벼운 식별자(경로·쿼리·링크)만 들고 있다가 도구로 필요할 때 읽는다. Claude Code 가 파일 전체 대신 head/tail 로 보는 것이 예다.
  • 압축(compaction) — 창이 차면 요약해 새 창에서 이어간다.
  • 구조화된 노트 — 컨텍스트 밖(예: NOTES.md)에 진행 상황을 적고 필요할 때 다시 읽는다.
  • 서브에이전트 — 깨끗한 컨텍스트에서 깊게 탐색한 뒤 1,000~2,000 토큰 정도로 압축한 요약만 돌려준다.

Q3 과 Q4 는 같은 문제의 양면이다. 도구 응답을 25k 토큰으로 자르고 concise 모드를 주는 것(Q3)이 곧 컨텍스트 예산 관리(Q4)다. (필자 제안) 그래서 Q3 을 먼저 두었다. 도구가 토큰을 쏟아내는데 압축으로 막는 건 순서가 거꾸로다.

Q5. 멈춤 조건과 사람 호출

에이전트는 루프이므로 끝나는 조건 이 설계의 일부다.

  • Anthropic: 에이전트는 매 단계 환경에서 실제 결과(ground truth) 를 받아 진척을 판단해야 한다. 최대 반복 횟수 같은 멈춤 조건을 두고, 오류가 누적(compounding) 되므로 샌드박스에서 충분히 시험하고 가드레일을 둔다1.
  • OpenAI: 실행은 종료 조건(최종 출력 도구 호출, 도구 호출 없는 응답 등)까지 도는 루프다. 가드레일은 겹겹의 방어 로 설계한다4.

OpenAI 가이드에서 가장 실용적인 부분은 도구 위험도 등급 이다. 도구마다 저·중·고 위험을 매기고, 기준으로 다음 네 가지를 든다4.

  • 읽기 전용인가, 쓰기인가
  • 되돌릴 수 있는가
  • 필요한 권한
  • 금전적 영향

사람 개입을 부르는 트리거는 두 가지다4.

  1. 실패 임계치 초과 — 재시도 횟수·행동 횟수 한도를 넘을 때
  2. 고위험 행동 — 민감하거나 되돌릴 수 없거나 큰 금액이 걸린 행동

MCP 명세도 도구 호출을 거부할 수 있는 사람 이 항상 루프에 있어야 한다(SHOULD)고 적었다6.

되돌리기 경로를 먼저 만들어 두는 이야기는 행동 전에 돌아갈 길부터 에 따로 썼다.

Q6. 평가를 먼저

Anthropic 의 도구 개발 절차는 프로토타입 → 평가 → 전사(transcript) 분석 → 개선 을 반복하는 것이다2.

  • 평가 과제는 현실적이고 여러 번의 도구 호출 이 필요해야 한다. 한 번 호출로 끝나는 과제는 약하다.
  • 결과는 검증 가능 해야 한다. 단, 너무 엄격한 검증기(서식 차이로 정답을 오답 처리)는 피한다.
  • 정확도뿐 아니라 총 실행 시간, 도구 호출 수, 토큰 소비, 도구 오류 를 같이 본다.
  • 개선에 과적합되지 않도록 홀드아웃 테스트셋 으로 확인한다.

평가기 종류는 평가 하네스 채점기 유형 에 정리해 뒀다.

(필자 제안) Q6 을 마지막에 적었지만 실행 은 Q3 과 같이 시작해야 한다. 도구 설명 한 줄을 바꿨을 때 좋아졌는지는 평가 없이는 알 수 없고, 앞에 든 “2025” 사례처럼 변화는 대개 전사를 읽어야 보인다.

우리 환경에서 관측한 것

필자가 운영하는 봇·에이전트 구성에서 본 것 중 위 원칙과 맞닿는 두 가지다. 일반화 근거가 아니라 사례 다.

  • 작업 결과 보고를 정해진 형식으로 강제 한다 (run_id, 한 일, 증거, PASS/WARN/FAIL/UNVERIFIED). 워커의 주장은 검증 전까지 가설로 다룬다. 이건 Q3 의 “도구 응답 형식” 을 에이전트 사이 계약에 적용한 것이다. 형식이 없던 때는 “완료” 라는 한 단어가 실제 완료인지 알 수 없었다. 구성 전체는 협업 시나리오 글 참고.
  • 쓰기 도구는 기본 거부 이고, 읽기 전용이 기본값이다. Q5 의 위험도 등급을 가장 단순하게 구현한 형태다.

한계

  • 중립 헤드투헤드 부재. “도구 최적화가 프롬프트 최적화보다 효과가 크다” 를 같은 조건에서 비교한 제3자 연구는 찾지 못했다. Anthropic 의 서술은 자사 경험담이다.
  • SWE-agent 수치는 2024년, GPT-4 Turbo 기준 이다. 현재 모델에서 ACI 효과의 크기는 다를 수 있다. 방향(인터페이스가 성능을 바꾼다)은 여러 출처가 일치한다.
  • 도구 개수 기준(겹치는 10개 미만에서도 헤맴, 서로 다른 15개 이상도 가능)은 OpenAI 가 관찰로 제시한 것 이고 벤치마크가 아니다.
  • 서브에이전트 요약 1,000~2,000 토큰은 Anthropic 이 제시한 대략의 범위 이지 최적값이 아니다.
  • 7단계 순서 자체는 필자의 정리 다. 출처들이 이 순서를 제시한 것은 아니다.

References

  1. Erik Schluntz, Barry Zhang (Anthropic), “Building effective agents”, 2024-12-19. https://www.anthropic.com/engineering/building-effective-agents — 워크플로/에이전트 구분, 5개 패턴, 3원칙, Appendix 2 도구 프롬프트 엔지니어링(절대경로·포카요케). ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9 ↩10 ↩11

  2. Ken Aizawa 외 (Anthropic), “Writing effective tools for agents — with agents”, 2025-09-11. https://www.anthropic.com/engineering/writing-tools-for-agents — 평가 절차, 도구 설계 원칙, concise/detailed 72 대 206 토큰, 25,000 토큰 기본 상한. ↩ ↩2 ↩3 ↩4 ↩5 ↩6

  3. Anthropic, “Effective context engineering for AI agents”, 2025. https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents — 주의 예산, 적시 로딩, 압축·노트·서브에이전트. ↩ ↩2 ↩3 ↩4

  4. OpenAI, “A practical guide to building agents” (PDF). https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf — 단일 에이전트 우선, 분할 기준, 매니저/분산 패턴, 가드레일, 도구 위험도, 사람 개입 트리거. ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8

  5. John Yang, Carlos E. Jimenez 외, “SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering”, NeurIPS 2024. arXiv:2405.15793. https://arxiv.org/abs/2405.15793 — ACI 개념, 50건 검색·100줄 뷰어·린터 가드레일, 12.47%/18.00%, 셸 대비 상대 64%. ↩ ↩2 ↩3 ↩4

  6. Model Context Protocol, Specification 2025-06-18, “Tools”. https://modelcontextprotocol.io/specification/2025-06-18/server/tools — inputSchema/outputSchema/annotations, isError, annotations 불신 원칙, human-in-the-loop. ↩ ↩2 ↩3