콘텐츠로 이동

0. 에이전트 지도

“0. 에이전트 지도” 챕터 컨셉 일러스트

한 줄 정의. 에이전트는 모델이 스스로 도구 사용과 다음 행동을 정하며 과업을 끝낼 때까지 도는 시스템이고, 하네스는 그 루프를 모델 바깥에서 감싸 구동하는 실행 장치다.

계획·행동·관찰로 도는 에이전트 실행 루프와 정지 조건을 보여주는 다이어그램

스킬, 도구, 메모리, 서브에이전트… 용어를 따로따로 외우면 서로 어떻게 맞물리는지 놓치기 쉽습니다. 이 장은 앞으로 나올 모든 개념의 좌표축을 먼저 깔아 둡니다. 각 용어가 “모델이 하는 일”인지 “모델을 감싸는 장치가 하는 일”인지만 구분해도 나머지 장이 훨씬 선명해집니다.

그 좌표축의 맨 위에는 에이전트형 시스템(agentic system)이라는 우산 용어가 있습니다. Anthropic은 이 우산 아래에 두 갈래를 두는데, 하나는 워크플로이고 다른 하나는 에이전트입니다1. 둘 다 “LLM과 도구로 무언가를 자동화하는 시스템”이라는 점은 같지만, 경로를 누가 정하는가(control directionality)에서 갈라집니다.

이 한 축이 이 장의 뼈대입니다.

에이전트 vs 워크플로 — 경계는 “경로를 누가 정하나”

섹션 제목: “에이전트 vs 워크플로 — 경계는 “경로를 누가 정하나””

Anthropic의 “Building effective agents”는 두 용어를 영문으로 못 박아 둡니다. 워크플로는 “systems where LLMs and tools are orchestrated through predefined code paths” — LLM과 도구가 미리 정해진 코드 경로로 오케스트레이션되는 시스템입니다.

에이전트는 “systems where LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks” — LLM이 자기 프로세스와 도구 사용을 동적으로 스스로 지휘하며 과업을 어떻게 달성할지 통제하는 시스템입니다1.

구분 기준은 한 문장으로 압축됩니다. 개발자가 코드로 경로를 고정해 두면 워크플로, 모델이 환경 피드백을 받아 다음 경로와 도구를 스스로 고르면 에이전트입니다. “에이전트가 더 똑똑하다”가 아니라 결정권이 코드에 있느냐 모델에 있느냐의 문제라는 점이 핵심입니다.

자율성에는 대가가 따릅니다. Anthropic은 에이전트가 higher costs, and the potential for compounding errors — 더 높은 비용과 오류가 누적될 가능성을 가진다고 명시하고, agentic systems often trade latency and cost for better task performance — 에이전트형 시스템은 흔히 지연시간과 비용을 더 나은 성능과 맞바꾼다고 경고합니다1. 그래서 권장 순서가 분명합니다.

먼저 단순한 단일 프롬프트로 시작하고, 평가(eval)로 측정하며 최적화하고, 그래도 부족할 때만 다단계 에이전트 구조를 추가하라는 것입니다. 가장 정교한 시스템이 아니라 과업에 맞는 가장 단순한 시스템을 찾는 것이 목표입니다.

증강된 LLM — 모든 에이전트형 시스템의 기초 빌딩블록

섹션 제목: “증강된 LLM — 모든 에이전트형 시스템의 기초 빌딩블록”

에이전트든 워크플로든, 그 아래에는 공통의 기초 빌딩블록이 깔립니다. Anthropic은 이를 an LLM enhanced with augmentations such as retrieval, tools, and memory — 검색·도구·메모리로 증강된 LLM으로 정의합니다1. 평범한 한 번의 호출이 아니라, 외부 능력을 끌어다 쓸 수 있도록 보강된 모델이 모든 것의 시작점이라는 뜻입니다.

여기서 중요한 건 이 증강을 모델이 능동적으로 쓴다는 점입니다. 최신 모델은 스스로 검색 쿼리를 만들고, 상황에 맞는 도구를 고르고, 무엇을 메모리에 보존할지 판단합니다1. 즉 “검색·도구·메모리”는 개발자가 매번 손으로 끼워 넣는 부품이 아니라, 모델이 필요할 때 능동적으로 호출하는 능력입니다.

이 빌딩블록이 한 번 도는 모습이 곧 뒤에 나올 계획→행동→관찰 루프의 한 단위가 됩니다.

Anthropic은 이 증강을 Model Context Protocol(MCP)로 구현해 도구·데이터 생태계와 통합하기를 권장합니다1. 그래서 이 장의 빌딩블록은 자연스럽게 이 문서 뒤편의 MCP 좌표로 이어집니다.

하네스(harness) — 루프를 바깥에서 구동하는 장치

섹션 제목: “하네스(harness) — 루프를 바깥에서 구동하는 장치”

흥미롭게도 “harness”를 한 단어로 못 박은 1차 공식 정의 문서는 없습니다(이 위키는 그 사실까지 출처로 둡니다). 실무에서 하네스는 위 그림의 계획→행동→관찰 루프, 정지 조건, 도구 연결, 컨텍스트·메모리 주입을 모델 바깥에서 책임지는 실행 장치를 가리킵니다. 모델은 토큰을 생성할 뿐, 그 출력을 도구 호출로 바꾸고 결과를 다시 먹여 주는 일은 하네스가 합니다.

가장 구체적으로 이 루프를 문서화한 1차 소스는 OpenAI Agents SDK입니다. Runner.run이 도는 한 바퀴는 네 단계로 정의됩니다2.

  1. 현재 에이전트로 LLM을 호출한다.
  2. LLM이 final output을 내면 루프를 종료한다.
  3. LLM이 handoff를 하면 현재 에이전트와 입력을 교체한 뒤 루프를 다시 실행한다.
  4. LLM이 도구 호출을 하면 그 도구를 실행하고, 결과를 대화에 append한 뒤 루프를 다시 실행한다.

정지(final output) 규칙은 추상적인 “완료 선언”이 아니라 명확한 조건으로 정의됩니다. 원하는 타입의 텍스트 출력을 내고, 도구 호출이 하나도 없을 때 루프가 끝납니다.

output_type이 지정돼 있으면 그 타입을 충족하는 출력이 나올 때 종료됩니다2. 이 “도구 호출이 없을 때”라는 조건이 중요합니다. 모델이 텍스트와 함께 도구를 또 호출하면, 아직 일이 안 끝난 것으로 보고 루프가 계속 돕니다.

루프가 매 단계 진행을 판단하는 근거는 Anthropic의 표현으로 ground truth from the environment — 도구 결과, 코드 실행 결과 같은 환경의 실측값입니다1. 모델은 자기 생각만으로 진척을 평가하지 않고, 도구가 돌려준 실제 결과를 보고 다음 수를 정합니다. 그리고 블로커나 체크포인트에서는 사람의 피드백을 받기 위해 멈출 수 있습니다(human-in-the-loop)1. 스트리밍이 필요하면 Runner.run_streamedRunResultStreaming을 반환하고, 이벤트를 수신하는 대로 흘려보냅니다2. 이 루프가 실제로 어떻게 도는지는 4. 하네스 실행 루프에서 단계별로 더 풀어 봅니다.

도구(tool) — 스키마·에러 처리·ACI

섹션 제목: “도구(tool) — 스키마·에러 처리·ACI”

도구는 함수나 외부 서버를 모델이 호출할 수 있는 능력으로 바꾼 것입니다. OpenAI Agents SDK는 여러 종류의 도구를 두는데, 0장 수준에서는 크게 세 갈래만 잡아 두면 충분합니다3.

  • 함수 도구(function tool): 파이썬 함수를 그대로 도구로 노출합니다.
  • 호스티드 도구(hosted tool): OpenAI 서버에서 모델과 함께 실행됩니다. WebSearchTool, FileSearchTool(OpenAI Vector Stores 검색), CodeInterpreterTool, HostedMCPTool, ImageGenerationTool 등이 있습니다.
  • 에이전트를 도구로(agents-as-tools): agent.as_tool()로 다른 에이전트를 도구처럼 호출합니다.

함수 도구의 스키마가 어떻게 만들어지는지가 “자동 스키마 생성·검증”의 실체입니다. @function_tool 데코레이터는 함수 이름을 도구 name으로 기본 도출하고(name_override로 변경 가능), docstring에서 description을 추출하며, 함수 시그니처로부터 Pydantic 모델을 동적으로 생성해 입력을 검증합니다3. 즉 타입 힌트와 docstring을 제대로 쓰면 별도 JSON 스키마를 손으로 짤 필요가 없습니다.

from agents import function_tool
@function_tool
def read_file(path: str) -> str:
"""파일을 읽어 내용을 문자열로 돌려준다.
Args:
path: 읽을 파일의 절대 경로.
"""
with open(path) as f:
return f.read()

도구가 실패하면 어떻게 될까요. failure_error_function을 지정하지 않으면 default_tool_error_function이 동작해, 에러가 났다는 사실을 모델에게 알립니다3. 모델은 그 에러를 관찰값으로 받아 재시도하거나 다른 경로를 택할 수 있습니다.

메모리는 여러 루프 턴과 재개 가능한 실행에 걸쳐 작업 상태를 잇는 영속 계층입니다. OpenAI Agents SDK의 Session은 이를 agent loop 내 작업 컨텍스트를 유지하는 영속 메모리 계층으로 정의합니다.

Session은 턴 사이의 대화 이력을 자동으로 추적하고 실행 간 상태를 보존하므로, 개발자가 매번 손으로 상태를 모으고 다시 넣는 수동 상태관리를 하지 않아도 됩니다4.

구현체는 여러 종류가 있습니다. 기본은 SQLiteSession이고, 그밖에 SQLAlchemySession, AdvancedSQLiteSession, 그리고 Redis·MongoDB·암호화 변형 등이 제공됩니다4. 세션 동작은 RunConfigsession_settings 같은 옵션으로 제어합니다4. 즉 같은 “메모리”라도 로컬 파일 기반(SQLite)으로 빠르게 쓸지, 외부 스토어(Redis 등)로 분산할지, 암호화할지를 구현체 교체로 고를 수 있습니다.

오케스트레이션 — handoff · guardrail · tracing

섹션 제목: “오케스트레이션 — handoff · guardrail · tracing”

오케스트레이션은 여러 에이전트와 검증·관측을 조율하는 메커니즘을 묶어 부르는 말입니다. 세 축으로 나눠 보면 명확합니다.

Handoff(위임). 한 에이전트가 다른 에이전트에게 일을 넘깁니다. 앞의 루프에서 본 대로, handoff가 발생하면 SDK는 current agent와 input을 교체하고 루프를 다시 실행합니다2. agents-as-tools가 “다른 에이전트를 도구처럼 불러 결과만 받는” 방식이라면, handoff는 아예 주도권 자체를 넘기는 방식입니다.

이 둘이 다중 에이전트 조율의 두 기본 패턴입니다.

Guardrail(가드레일). 입력 가드레일과 출력 가드레일이 에이전트 실행과 병렬로 검증을 돌립니다. 위반이 감지되면 빠르게 실패(fail fast)하는데, 구체적으로는 tripwire가 발동하면서 InputGuardrailTripwireTriggered 또는 OutputGuardrailTripwireTriggered 예외가 던져집니다4. “검증해 빠르게 멈춘다”는 말의 실체가 바로 이 병렬 검증 + tripwire + 예외입니다.

병렬로 돌기 때문에 본 작업의 지연을 크게 늘리지 않으면서도, 잘못된 입력·출력을 조기에 끊을 수 있습니다.

Tracing(추적). 내장 추적이 에이전트 호출·도구 실행·모델 호출·가드레일 체크·handoff 전이를 각각 span으로 기록합니다. 이렇게 모인 트레이스는 OpenAI의 평가·파인튜닝·distillation 파이프라인과 연동됩니다4. 즉 추적은 단순 로그가 아니라 이후 개선 루프의 입력 데이터가 됩니다.

이런 능력들이 모델·하네스·외부 서버 사이에서 어떤 규약으로 오가는지는 9. 프로토콜 계층에서 정리합니다.

워크플로 패턴 5종 — 워크플로는 추상어가 아니다

섹션 제목: “워크플로 패턴 5종 — 워크플로는 추상어가 아니다”

워크플로가 “미리 정해진 코드 경로”라고 했을 때, 그 경로의 실제 모양은 다섯 가지 정형 패턴으로 정리됩니다1. 이 패턴들을 알아 두면 “워크플로”가 막연한 말이 아니라 구체적인 코드 구조임을 알 수 있습니다.

  • 프롬프트 체이닝(prompt chaining): 과업을 순차 단계로 분해해, 각 LLM 호출이 이전 출력을 처리합니다. 중간중간 프로그래밍적 게이트(checkpoint)를 두어 조건을 만족해야 다음으로 넘깁니다.
  • 라우팅(routing): 입력을 먼저 분류해 특화된 후속 과업으로 보냅니다. 관심사를 분리해 각 분기를 따로 최적화할 수 있습니다.
  • 병렬화(parallelization): 두 변형이 있습니다. sectioning은 독립 하위과업을 동시에 실행하고, voting은 같은 과업을 여러 번 시도해 신뢰도를 확보합니다.
  • 오케스트레이터-워커(orchestrator-workers): 중앙 LLM이 과업을 동적으로 쪼개 워커 LLM들에 위임하고 결과를 종합합니다. 병렬화와 달리 하위과업이 사전에 고정돼 있지 않다는 점이 결정적 차이입니다.
  • 평가자-최적화자(evaluator-optimizer): 한 LLM이 응답을 생성하고, 다른 LLM이 평가·피드백을 주는 과정을 루프로 돕니다.

여기서 에이전트와의 경계가 다시 드러납니다. 오케스트레이터-워커는 하위과업을 동적으로 쪼갠다는 점에서 에이전트에 가까워 보이지만, 전체 흐름(중앙이 쪼개고 워커가 처리하고 종합)은 여전히 개발자가 코드로 고정한 경로입니다.

반면 진짜 에이전트는 그 큰 흐름 자체를 모델이 정합니다. 이 다섯 패턴은 이 장의 “워크플로” 칸이 비유가 아니라 실제 코드 구조임을 보여 줍니다.

스킬(skill) — 구조·점진적 공개·필드 제약

섹션 제목: “스킬(skill) — 구조·점진적 공개·필드 제약”

스킬은 지침·스크립트·리소스를 담은 폴더로, 에이전트가 특정 과업 성능을 높이려고 필요할 때 동적으로 불러오는 단위입니다. 구조의 핵심은 폴더 루트의 SKILL.md인데, 이는 YAML frontmatter와 마크다운 본문으로 이뤄집니다.

필수 필드는 namedescription 둘뿐입니다56. 자세한 구조는 1. 스킬 기본형에서 다룹니다.

스킬의 작동을 떠받치는 메커니즘이 점진적 공개(progressive disclosure)입니다. 컨텍스트를 한꺼번에 다 채우지 않고 3레벨로 나눠 필요한 만큼만 로드합니다5.

  1. L1 메타데이터(name + description): 시작 시 항상 시스템 프롬프트에 로드됩니다. 스킬당 약 100토큰이라, 다수를 설치해도 컨텍스트 부담이 적습니다.
  2. L2 SKILL.md 본문: 스킬이 트리거될 때 bash로 읽어 로드합니다. 5k 토큰 미만을 권장합니다.
  3. L3+ 번들 리소스: 추가 .md, 스크립트, 참조자료 등은 필요할 때만 접근하므로 사실상 무제한으로 둘 수 있습니다.

핵심은 스킬이 파일시스템 기반이고, Claude가 bash로 SKILL.md를 읽어 컨텍스트로 가져온다는 점입니다. 더 중요한 건 번들 스크립트(예: validate_form.py)는 bash로 실행되며, 코드 자체는 컨텍스트에 들어가지 않고 출력만 토큰을 소비한다는 사실입니다5. 덕분에 결정적(deterministic) 동작을 컨텍스트 비용 없이 제공할 수 있습니다.

100줄짜리 검증 스크립트를 통째로 읽지 않고 “통과/실패” 한 줄만 받는 셈입니다.

스킬은 사용자 요청이 description과 매치될 때 모델이 자동으로 호출(model-invoked)합니다. 항상 켜져 있는 게 아니라 트리거될 때만 깨어나므로, description을 정확히 쓰는 일이 곧 스킬이 제때 발동하느냐를 좌우합니다5.

MCP — 도구·데이터의 프로토콜 좌표

섹션 제목: “MCP — 도구·데이터의 프로토콜 좌표”

도구와 데이터를 모델 바깥의 생태계와 잇는 표준이 Model Context Protocol(MCP)입니다. MCP는 AI 앱을 외부 시스템에 연결하는 오픈 표준으로, USB-C port for AI applications에 비유됩니다. 다만 프로토콜 자체는 LLM을 어떻게 쓸지, 컨텍스트를 어떻게 관리할지는 지시하지 않습니다7.

구조의 좌표는 참여자 3종과 그 연결 규칙에서 선명해집니다8.

  • MCP Host: 여러 client를 조율하는 AI 앱.
  • MCP Client: 서버 1개와 전용 연결을 유지.
  • MCP Server: 컨텍스트를 제공하는 프로그램.

규칙이 핵심입니다. host는 서버마다 client를 1개씩 만들어 1:1 전용 연결을 유지합니다. 즉 서버 N개를 붙이면 client도 N개가 생깁니다.

구조는 2계층으로 나뉩니다. 데이터 계층은 JSON-RPC 2.0 기반으로 라이프사이클·primitive·notification을 정의하고, 전송 계층은 로컬용 stdio(로컬 프로세스 표준입출력)와 원격용 Streamable HTTP(HTTP POST + 선택적 SSE, OAuth 권장)를 둡니다8. 연결은 initialize 핸드셰이크로 시작해 protocolVersion(예: 2025-06-18)과 capabilities를 협상하고, 이후 notifications/initialized로 마무리합니다8.

서버가 제공하는 primitive 3종은 제어 주체가 다르다는 점이 좌표의 핵심입니다8.

primitive제어 주체무엇발견 / 실행
tools모델 제어실행 함수tools/list / tools/call
resources앱 제어컨텍스트 데이터resources/list / resources/read
prompts사용자 제어상호작용 템플릿prompts/list / prompts/get

반대로 client도 primitive를 제공합니다. sampling(sampling/createMessage, 서버가 호스트 LLM에 완성을 요청), elicitation(elicitation/create, 사용자에게 추가 정보 요청), logging이 그것입니다.

변경 알림은 notifications/tools/list_changed처럼 응답이 없는 JSON-RPC notification으로 전달됩니다8.

용어누구의 일인가한 줄
에이전트형 시스템우산 용어워크플로와 에이전트를 모두 포괄
에이전트모델이 주도경로를 스스로 정해 과업을 끝낸다
워크플로개발자가 고정정해진 코드 경로(5패턴)를 따른다
증강된 LLM빌딩블록검색·도구·메모리로 보강된 모델
하네스모델을 감싸는 장치루프·도구·컨텍스트를 바깥에서 구동
스킬모델이 불러옴필요할 때 로드하는 지침 묶음
도구하네스가 연결, 모델이 호출외부 능력을 호출 가능하게
메모리하네스가 유지턴·세션을 잇는 상태
MCP연결 프로토콜도구·데이터를 1:1 전용 연결로 잇는 표준

“이 폴더의 테스트를 고쳐 줘”라는 한 줄을 받았다고 해 봅시다. 하네스는 먼저 모델에게 목표와 사용할 수 있는 도구 목록을 건넵니다(계획). 모델이 “파일을 읽겠다”고 답하면 하네스가 실제로 read_file을 실행하고(행동), 그 내용을 다시 모델에게 돌려줍니다(관찰).

여기서 관찰이 단순한 텍스트가 아니라 환경의 실측값(ground truth)이라는 점이 중요합니다. 모델은 테스트를 한 번 돌려 본 실제 실행 결과를 보고 진척을 평가하며, 그걸 근거로 다음 도구를 고릅니다1. 이는 앞서 본 OpenAI 루프의 4단계(LLM 호출 → 도구 실행 → 결과 append → 재실행)와 정확히 맞물립니다2.

그리고 정지는 막연한 “완료 선언”이 아닙니다. 테스트가 통과하고 모델이 더 이상 도구를 호출하지 않은 채 원하는 타입의 출력을 낼 때 루프가 끝납니다(final output). 만약 모델이 헤매며 도구만 계속 호출하면, max_turns에 걸려 MaxTurnsExceeded로 멈춥니다2. 이 한 바퀴가 그림의 루프이고, 모델이 아니라 하네스가 돌립니다.

  • 에이전트형 시스템이 워크플로와 에이전트를 포괄하는 우산 용어임을 안다.
  • 에이전트와 워크플로의 차이를 “경로를 누가 정하나”로 설명할 수 있다.
  • 에이전트가 비용·지연·오류 누적을 감수하는 선택임을 알고, 단순 프롬프트→평가→다단계 순서를 안다.
  • 모든 시스템의 빌딩블록이 “검색·도구·메모리로 증강된 LLM”임을 안다.
  • 하네스의 정지 조건이 final output 또는 max_turns/예외로 구현됨을 안다.
  • 도구 스키마가 함수 시그니처+docstring+Pydantic으로 만들어짐을 안다.
  • 스킬의 점진적 공개 3레벨과 name 64자/description 1024자 제약을 안다.
  • MCP의 host/client/server 1:1 구조와 tools/resources/prompts 제어 주체 구분을 안다.
  1. Anthropic — Building effective agents 2 3 4 5 6 7 8 9 10 11 12

  2. OpenAI Agents SDK — Running agents 2 3 4 5 6 7 8

  3. OpenAI Agents SDK — Tools 2 3

  4. OpenAI Agents SDK (Python) — 문서 홈 2 3 4 5

  5. Anthropic Claude Docs — Agent Skills overview 2 3 4 5 6

  6. GitHub — anthropics/skills

  7. Model Context Protocol — Introduction

  8. Model Context Protocol — Architecture overview 2 3 4 5