용어집
《관측 가능성과 디버깅: 에이전트가 밟는 모든 단계를 들여다보기》의 용어 78개. 레슨 본문에서 처음 등장하는 용어에 마우스를 올리면 정의를 볼 수 있습니다.
| 용어 | 정의 | 출처 |
|---|---|---|
| 비결정적 | 같은 입력을 줘도 서로 다른 응답이 나올 수 있는 시스템의 성질. 에이전트가 이런 시스템이며, '재현해서 브레이크포인트를 건다'는 전통적인 디버깅 직관을 무너뜨린다. | Writing effective tools for agents — with agents — Anthropic Engineering |
| 궤적 분기 | 한 단계의 실패가 에이전트로 하여금 완전히 다른 궤적을 탐색하게 만들고, 이어지는 모든 턴이 그 잘못된 가지 위에서 자라 예측할 수 없는 결과로 이어지는 것. | How we built our multi-agent research system — Anthropic Engineering |
| 턴을 넘어 쌓이는 누적 | 에이전트는 상태를 가지고 있고 에러는 누적된다. 오랜 시간 돌면서 수많은 도구 호출에 걸쳐 상태를 유지하므로 에러가 턴마다 쌓인다. | How we built our multi-agent research system — Anthropic Engineering |
| 창발적 동작 | 따로 프로그래밍하지 않아도 멀티 에이전트 시스템에서 생겨나는 동작. 예컨대 리드 에이전트에 가한 작은 변경이 서브에이전트의 행동을 예측할 수 없게 바꿔 놓는다. | How we built our multi-agent research system — Anthropic Engineering |
| 평가 트랙 | 앞 코스에서 만든 종료 상태 채점, 검증기, 평가 세트. '망가졌는가'에만 답하고 '왜'에는 답하지 않는다. | How we built our multi-agent research system — Anthropic Engineering |
| 에이전트처럼 생각하기 | 시스템에서 쓰는 것과 완전히 동일한 프롬프트와 도구로 시뮬레이션을 꾸리고, 에이전트가 일하는 모습을 한 단계씩 지켜보는 것. | How we built our multi-agent research system — Anthropic Engineering |
| 추상화 계층 | 프레임워크가 LLM 호출, 도구 정의, 호출 연결을 단순화하려고 덧붙이는 중간 계층. 밑에 깔린 프롬프트와 응답을 가린다. | Building Effective AI Agents — Anthropic Engineering |
| 샌드박스 | 행동을 취할 수 있는 에이전트를 적절한 가드레일과 함께 광범위하게 테스트하는 격리된 환경. | Building Effective AI Agents — Anthropic Engineering |
| 도구 경계 | 결정론적 시스템과 비결정적 에이전트가 맞닿는 계약면. 기록에 흔적을 남기는 유일한 위치다. | Building Effective AI Agents — Anthropic Engineering |
| 그라운드 트루스 | 실행 중 에이전트가 각 단계에서 환경으로부터 얻는 실제 피드백. 도구 호출 결과나 코드 실행 결과 같은 것이다. | Building Effective AI Agents — Anthropic Engineering |
| 원본 트랜스크립트 | 한 실행 안의 모든 도구 호출에 대한 도구 이름과 전체 파라미터, 그리고 모든 도구 응답에 대한 완전한 반환값 또는 에러. 1차 증거다. | Writing effective tools for agents — with agents — Anthropic Engineering |
| 자기 보고 | 에이전트가 자기 자신에 대해 쓴 글. 마무리 요약, 추론 구간, 도구 실행 후의 자체 평가가 여기 속하며 모두 2차 자료다. | Writing effective tools for agents — with agents — Anthropic Engineering |
| 사고 사슬 | 모델이 답을 내기 전에 쓰는 추론 과정. CoT로 줄여 쓴다. | Writing effective tools for agents — with agents — Anthropic Engineering |
| 네 가지 질문 | 트랜스크립트를 읽는 체크리스트. 잘못된 도구를 불렀는가, 맞는 도구를 잘못된 파라미터로 불렀는가, 호출이 너무 적었는가, 도구 응답을 잘못 처리했는가. | Writing effective tools for agents — with agents — Anthropic Engineering |
| tool_use | 모델이 어느 도구를 부를지 지정하는 콘텐츠 블록. 도구 이름과 모델이 생성한 완전한 파라미터 객체를 담는다. | Writing effective tools for agents — with agents — Anthropic Engineering |
| tool_result | 하네스가 실제로 도구를 돌린 뒤 돌려주는 블록. 성공이면 완전한 반환값, 실패면 에러 내용과 에러 플래그다. | Writing effective tools for agents — with agents — Anthropic Engineering |
| is_error | 도구 결과에 붙는 에러 플래그. '도구가 내용을 돌려줬다'와 '도구가 에러를 던졌다'를 가른다. | Writing effective tools for agents — with agents — Anthropic Engineering |
| 콘텐츠 팜 | SEO에 최적화되어 검색 순위는 높지만 권위는 낮은 출처. 사람이 하는 테스트에서 초기 에이전트가 학술 PDF나 개인 블로그보다 이쪽을 일관되게 골랐다. | How we built our multi-agent research system — Anthropic Engineering |
| 트랜스크립트 | 디스크에 영속화된 대화 메시지. Claude Code가 세션 기록을 JSONL 파일로 쓰는 것 같은 것이다. | Monitoring — Claude Code Official Documentation |
| 구조화된 로그 | 각 단계를 필드가 있는 JSON 기록으로 바꾸는 것. 증거를 사람이 읽을 수 있을 뿐 아니라 거르고 집계하고 분포를 분석할 수 있게 된다. | Writing effective tools for agents — with agents — Anthropic Engineering |
| 산문형 로그 | 구조를 자연어에 인코딩하는 로그 쓰기. 읽기는 매끄럽지만 사람만 디코딩할 수 있다. | Writing effective tools for agents — with agents — Anthropic Engineering |
| JSON Lines | 파일 하나, 각 줄이 완결된 JSON 객체 하나, 줄 사이에 쉼표가 없고 바깥을 감싸는 배열도 없다. 흔히 JSONL로 쓴다. | Writing effective tools for agents — with agents — Anthropic Engineering |
| session_id | 한 세션의 식별자. 여러 턴에 걸쳐 그대로 유지되며 '이 세션은 총 얼마를 썼는가, 권한 모드를 바꿨는가'에 답한다. | Monitoring — Claude Code Official Documentation |
| prompt_id | 사용자 프롬프트 하나의 식별자. 그것이 촉발한 모든 모델 요청과 도구 호출이 이 값을 공유한다. | Monitoring — Claude Code Official Documentation |
| 상관관계 ID | '촉발 사건 하나'에 주는 ID 번호. 그 촉발이 낳은 모든 사건이 그것을 복사해 간다. 인프라가 전혀 필요 없고 그냥 필드 하나다. | Monitoring — Claude Code Official Documentation |
| duration_ms | 한 단계에 쓴 밀리초. 성능 병목을 찾는 데 쓰고 '멈춰 있는가'를 보는 데도 쓴다. | Writing effective tools for agents — with agents — Anthropic Engineering |
| tool_input | 도구로 보낸 파라미터. PostToolUse 페이로드가 직접 제공하며 완전한 호출 기록의 절반을 이룬다. | Hooks reference — Claude Code Official Documentation |
| tool_response | 도구가 돌려준 결과. tool_input 과 함께 한 번의 발화가 주는 완전한 왕복 기록을 이룬다. | Hooks reference — Claude Code Official Documentation |
| error | 기록에 붙는 에러 필드. 실패할 때만 존재하며, 위치를 짚을 때 가장 먼저 거르는 필드다. | Writing effective tools for agents — with agents — Anthropic Engineering |
| 메트릭 | 숫자 한 벌. 개별 도구 호출과 작업 전체의 실행 시간, 총 도구 호출 수, 총 토큰 소비, 도구 에러다. | Writing effective tools for agents — with agents — Anthropic Engineering |
| 중복 호출 | 같은 도구 호출이 많이 반복되는 것. 페이지네이션이나 토큰 상한 파라미터의 크기를 다시 맞춰야 한다는 신호인 경우가 많다. | Writing effective tools for agents — with agents — Anthropic Engineering |
| 잘못된 파라미터 에러 | 유효하지 않은 파라미터로 인한 도구 에러가 많은 것. 도구 설명에 더 명확한 서술이나 더 나은 예시가 필요하다는 것을 가리킨다. | Writing effective tools for agents — with agents — Anthropic Engineering |
| 에러율 | 에러 건수를 호출 수로 나눈 비율 메트릭. 절대 수치 대신 이것으로 건강 상태를 본다. | Writing effective tools for agents — with agents — Anthropic Engineering |
| 종단 신호 | 내부 재시도가 완전히 포기한 뒤에야 나오는 에러 이벤트. '이 요청이 최종적으로 실패했다'를 뜻한다. | Monitoring — Claude Code Official Documentation |
| 멈춤 의심 | 어떤 프롬프트의 마지막 기록에 에러가 있고 그 뒤로 기록이 없는 상태. '에러에서 회복했다'와 대비된다. | Monitoring — Claude Code Official Documentation |
| 임계치 | '얼마부터가 비정상인가'를 판정하는 선. 1차 자료에는 숫자가 없고, 에러 예산도 SLO도 마찬가지다. | Monitoring — Claude Code Official Documentation |
| SIEM | 보안 정보 및 이벤트 관리 시스템. 이상 탐지, 기준선 수립, 세션 간 상관 분석, 알림이 모두 이쪽의 책임이다. | Monitoring — Claude Code Official Documentation |
| 감사 추적 | 최종 사용자 신원 속성을 붙이면 도구 결정, 도구 결과, MCP 연결, 권한 모드 변경이 이루는 사용자별 기록. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| 스팬 | 시작과 끝이 있는 작업 한 조각의 기록. 이름, 시작 시각, 종료 시각, 속성 몇 개를 가지며 자기 부모 스팬을 지목할 수 있다. | Monitoring — Claude Code Official Documentation |
| 트레이스 | 부모-자식 관계로 이어진 스팬 트리 전체. 완전한 요청 하나가 시작부터 끝까지 겪은 모든 일을 트리로 읽는 것이다. | Monitoring — Claude Code Official Documentation |
| claude_code.interaction | 퍼스트파티 트레이스에서 사용자 프롬프트 하나에 대응하는 루트 스팬의 이름. | Monitoring — Claude Code Official Documentation |
| 서브에이전트 | Agent 도구를 통해 띄워지는 하위 에이전트. 그 모델 요청과 도구 스팬이 부모 에이전트의 도구 스팬 아래로 중첩된다. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| 익스포터 | 스팬을 포장해 밖으로 보내는 일을 맡은, 프로세스 안쪽의 코드. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| 컬렉터 | 스팬을 받는 중계소 또는 백엔드 서비스. 익스포터가 여기로 데이터를 보내고, 그 대시보드에서 트리를 본다. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| 조용한 실패 | 엔드포인트에 닿지 못하거나 백엔드가 데이터를 거부해도 에이전트는 정상적으로 돌고, 텔레메트리는 버려지며, 애플리케이션에는 에러가 드러나지 않는 기본 동작. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| 배치 내보내기 | 텔레메트리를 모아 두었다가 일정 간격으로 내보내는 메커니즘. 기본값으로 메트릭은 60초, 트레이스와 로그는 5초마다다. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| service.name | 데이터가 어느 서비스에서 왔는지 식별하는 리소스 속성. CLI 는 기본적으로 claude-code 로 보고한다. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| claude_code.session.count | 세션이 시작되자마자 나오는 카운팅 메트릭. 내보내기 설정이 작동했는지 검증하는 가장 값싼 탐침이다. | Monitoring — Claude Code Official Documentation |
| TRACEPARENT | 트레이스 id 와 현재 스팬 id 를 담은 표준 형식의 환경 변수. Bash 와 PowerShell 서브프로세스가 자동으로 물려받는다. | Monitoring — Claude Code Official Documentation |
| W3C 트레이스 컨텍스트 | 트레이스 id 와 현재 스팬 id 를 담은 표준 형식의 문자열. 받는 쪽은 자기가 어디에 붙어야 하는지 알게 된다. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| CLAUDE_CODE_ENHANCED_TELEMETRY_BETA | 켜면 에이전트 루프의 각 단계가 트레이싱 백엔드에서 들여다볼 수 있는 스팬이 되는 스위치. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| 훅 | Claude Code 생명주기의 특정 지점에서 자동으로 실행되는 사용자 정의 셸 명령, HTTP 엔드포인트, 또는 LLM 프롬프트. | Hooks reference — Claude Code Official Documentation |
| 매처 | 훅이 언제 발화할지 결정하는 일치 규칙. 생략하거나 와일드카드로 두면 훅 하나로 전부 기록한다. | Hooks reference — Claude Code Official Documentation |
| PreToolUse | 모델이 도구 파라미터를 만든 뒤, 도구 호출을 처리하기 전에 실행되는 이벤트. | Hooks reference — Claude Code Official Documentation |
| PostToolUse | 도구가 성공적으로 실행된 뒤 발화하는 이벤트. 입력에 tool_input 과 tool_response 를 함께 담는다. | Hooks reference — Claude Code Official Documentation |
| SessionStart | 세션당 한 번 발화하는 이벤트. 새 세션을 열 때와 기존 세션을 재개할 때 모두 울린다. | Hooks reference — Claude Code Official Documentation |
| Stop | 턴당 한 번 주기의 턴 종료 이벤트. UserPromptSubmit 과 짝지으면 한 턴의 경과 시간을 계산할 수 있다. | Hooks reference — Claude Code Official Documentation |
| 페이로드 | 이벤트가 발화하고 매처가 일치했을 때 핸들러에 넘겨지는 JSON 컨텍스트. | Hooks reference — Claude Code Official Documentation |
| OTEL_* | 텔레메트리 내보내기에 관련된 환경 변수 묶음. Claude Code 는 자신이 띄우는 모든 서브프로세스에서 이것을 제거하며 훅도 포함된다. | Hooks reference — Claude Code Official Documentation |
| 디버그 로그 | 어느 훅이 일치했는지, 종료 코드가 무엇인지, stdout 과 stderr 전문이 무엇인지를 기록하는 로그 파일. | Hooks reference — Claude Code Official Documentation |
| 다섯 단계 워크플로 | 이 코스가 직접 배열한 디버깅 절차. prompt id 로 좁히기, 첫 이탈 지점 찾기, 재생하며 관찰하기, 같은 구성 요소를 반복해서 두들기기, 고친 뒤 실패 지점부터 복구하기. | How we built our multi-agent research system — Anthropic Engineering |
| 좁히기 | 첫째 단계. prompt id 로 걸러 범위를 '에이전트가 깨졌다'에서 '이 id 아래 열몇 개 이벤트'로 줄이는 것. | Monitoring — Claude Code Official Documentation |
| 첫 이탈 지점 | 동작이 기대에서 벗어나기 시작하는 첫 단계. 끝에서 보이는 황당한 것들은 대개 하류의 잡음이다. | How we built our multi-agent research system — Anthropic Engineering |
| 전염 | 이탈 지점 이후의 단계들. 똑같이 황당해 보이지만 잘못된 전제 위에서 계속 밀고 나간 것일 뿐이다. | How we built our multi-agent research system — Anthropic Engineering |
| 재생 | 동일한 프롬프트와 도구로 시뮬레이션을 꾸리고 단계별로 지켜보며 실패 양상을 곧바로 밀어내는 것. | How we built our multi-agent research system — Anthropic Engineering |
| 스텁 클라이언트 | 네트워크 요청을 보내지 않고 고정된 배열의 사전 응답 객체를 순서대로 반환하는 대역. 모델 쪽을 재현 가능하게 만든다. | How we built our multi-agent research system — Anthropic Engineering |
| 응답 큐 | 스텁 클라이언트가 순서대로 꺼내 쓰는 배열. 각 원소가 완전한 stop_reason, 콘텐츠 블록, usage 를 담는다. | How we built our multi-agent research system — Anthropic Engineering |
| 도구 테스트 에이전트 | 결함 있는 도구를 주면 반복해서 써 본 뒤 실패를 피하도록 도구 설명을 다시 쓰는 에이전트. 수십 번 테스트하면 핵심적인 미묘함과 버그를 찾아낸다. | How we built our multi-agent research system — Anthropic Engineering |
| trace_id | 실행마다 하나씩 붙는 id. 같은 스트림에 흩어진 기록을 같은 실행으로 되묶는다. | Monitoring — Claude Code Official Documentation |
| span_id | 이 기록 자신의 id. 다른 기록이 이것을 가리켜 '나는 네 아래다'라고 선언한다. | Monitoring — Claude Code Official Documentation |
| parent_id | 부모 기록의 id 를 가리키는 필드. 디스크의 JSONL 에서 트리를 재구성하는 근거다. | Monitoring — Claude Code Official Documentation |
| MAX_ROUNDS | 루프 반복 횟수의 하드 게이트. 넘으면 에러를 던지고 중단을 기록하며 0 이 아닌 코드로 끝낸다. | Building Effective AI Agents — Anthropic Engineering |
| stop_reason | 하네스 루프가 계속 돌지 끝낼지를 구동하는 모델 응답의 필드. | Building Effective AI Agents — Anthropic Engineering |
| HEAD_CHARS | 로그의 내용 발췌마다 최대 몇 글자를 남길지 정하는 줄. 0 으로 두면 한 글자도 디스크에 닿지 않는다. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| shape | 값의 타입과 규모를 서술하는 기록의 필드. 문자열인지 객체인지, 얼마나 긴지, 어떤 키가 있는지다. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| 메트릭 요약 | 총 라운드 수, 도구 호출 수, 토큰, 에러 수, 총 소요 시간을 한 줄로 내는 것. 관측 가능성 세 종 세트의 한 조각이다. | Writing effective tools for agents — with agents — Anthropic Engineering |
| compare-runs.mjs | 두 실행의 로그를 읽어 기록 종류와 도구 이름별로 나란히 비교하고, 에러가 있으면 0 이 아닌 코드로 끝내는 비교 스크립트. | Writing effective tools for agents — with agents — Anthropic Engineering |
| 게이트 | 종료 코드에 배선된 판정. 0 이 아닌 코드는 CI 나 cron, 그 밖에 '0 이 아니면 알림'인 어떤 곳에서든 받아 낼 수 있다. | Writing effective tools for agents — with agents — Anthropic Engineering |