용어집

《에이전트 하네스 기초: 루프와 통제》의 용어 66개. 레슨 본문에서 처음 등장하는 용어에 마우스를 올리면 정의를 볼 수 있습니다.

용어	정의	출처
하네스	모델을 감싸는 제어 코드의 총칭 — 도구를 실행하고, 루프를 돌리고, 언제 멈추고 언제 사람을 기다릴지 결정한다. 모델은 액션을 제안할 뿐이고, 그 액션이 실행되는지 그리고 루프가 계속되는지는 하네스가 재정한다.	How tool use works — Claude API
에이전트	루프 안에서 환경 피드백에 기반해 도구를 사용하는 LLM. 모델이 동적으로 자신의 프로세스를 지휘하고 루프 안에서 어떤 도구를 쓸지 결정하며, 미리 정의된 코드 경로를 따르지 않는다.	Building Effective AI Agents — Anthropic Engineering
워크플로	LLM과 도구가 사전 정의된 코드 경로를 통해 오케스트레이션되는 시스템 — 먼저 무엇을 하고, 어느 분기를 택할지가 모두 사람에 의해 미리 정해져 있다.	Building Effective AI Agents — Anthropic Engineering
루프	모델이 제안 → 도구 실행 → 결과를 모델에 피드백하는 반복 과정. 한 번의 도구 호출 왕복은 루프가 한 바퀴만 돈 특수한 경우다.	Building Effective AI Agents — Anthropic Engineering
제어 흐름의 결정	'다음 경로를 어디로 택할지'에 대한 판단. 워크플로에서는 하드코딩되어 있고, 에이전트에서는 모델이 루프 안에서 동적으로 결정한다 — 이것이 둘 사이의 경계다.	The 2026 Agent Engineering Roadmap — GitHub (codejunkie99/agent-roadmap-2026)
루프 제어	모델→도구→모델을 구동하는 while 루프로, stop_reason을 읽어 다음 라운드를 돌지 멈출지 결정한다. 하네스의 심장이다.	The 2026 Agent Engineering Roadmap — GitHub (codejunkie99/agent-roadmap-2026)
도구 디스패치	모델이 '이 도구를 이 파라미터로 호출하라'고 제안한 뒤, 그 요청을 실제 함수로 라우팅해 실행하고, 출력을 tool_result로 다시 담는 코드.	The 2026 Agent Engineering Roadmap — GitHub (codejunkie99/agent-roadmap-2026)
컨텍스트 관리	루프가 생성하는 히스토리를 관리하는 하네스 부품 — 어디에 둘지, 얼마를 남길지, 어떻게 압축하거나 요약할지 결정해, 컨텍스트가 어텐션 예산을 다 소진할 때까지 부풀어 오르는 것을 막는다.	The 2026 Agent Engineering Roadmap — GitHub (codejunkie99/agent-roadmap-2026)
액션을 제안	매 턴 모델의 유일한 일 — 현재 대화를 보고 '다음에 하고 싶은 일'에 대한 구조화된 요청을 발행하며, 결코 실행하지 않는다.	How tool use works — Claude API
승인 밸브	영향이 큰 것으로 표시된 도구를 실행하기 전에 삽입된 일시 정지로, 사람에게 '지금 이것을 하려 합니다'를 보여 주고 끄덕임이 있을 때만 실행하며, 거부되면 is_error를 반환한다.	LLM06:2025 Excessive Agency — OWASP Gen AI Security Project
왕복	완전한 도구 호출 사이클 하나: 모델이 tool_use를 반환하고, 호스트가 도구를 실행하고, tool_result를 포장해 대화에 덧붙이고, 다음 요청을 보낸다. 루프는 왕복을 반복하는 것이다.	How tool use works — Claude API
환경 피드백	모델에 입력으로 피드백되는 도구 실행 결과. 모델은 이 피드백에 기반해 다음 단계를 결정한다 — 이것이 루프를 앞으로 구동하는 연료다.	Building Effective AI Agents — Anthropic Engineering
자율성	에이전트가 동적으로 자신의 다음 단계와 어떤 도구를 쓸지 결정하는 속성. 에이전트를 유용하게 만드는 것이며, 동시에 더 높은 비용과 에러 누적 증폭 위험을 뜻한다.	Building Effective AI Agents — Anthropic Engineering
while 루프	stop_reason을 조건으로 하는 while 구조로, 한 번의 왕복을 코드로 바꾼다: stop_reason이 여전히 tool_use인 동안 다음 라운드를 돈다.	The 2026 Agent Engineering Roadmap — GitHub (codejunkie99/agent-roadmap-2026)
네 단계	왕복들을 루프로 연결하는 고정 시퀀스: 요청을 보낸다 → stop_reason과 tool_use 블록을 읽는다 → 도구를 실행해 tool_result에 담는다 → 히스토리에 덧붙여 다시 보낸다.	How tool use works — Claude API
stop_reason	모델 응답에서 왜 멈췄는지 나타내는 필드: tool_use는 도구를 원하며 루프가 계속되고, end_turn은 마무리하며 루프가 끝난다.	How tool use works — Claude API
tool_use	모델이 도구 호출을 요청하기 위해 발행하는 콘텐츠 블록으로, id / name / input을 싣는다. 도구를 쓰고 싶다는 뜻이지, 이미 썼다는 뜻이 아니다.	How tool use works — Claude API
tool_result	도구 실행 출력을 모델에 다시 포장하는 콘텐츠 블록으로, tool_use_id로 어느 호출에 답하는지 밝히고, content에 출력을 싣고, 실패했을 때는 is_error를 붙인다.	Handle tool calls — Claude API
end_turn	모델이 더 이상 도구를 원하지 않고 마쳤다고 생각함을 뜻하는 stop_reason 값. 루프가 자연히 끝나고 최종 텍스트를 사용자에게 반환한다.	How tool use works — Claude API
tool_use_id	tool_result의 필드로, '이것이 어느 tool_use 호출에 대한 응답인지' 밝히며, tool_use 블록의 id를 매칭해 식별한다. 한 턴의 여러 도구가 이것에 의존해 일대일 대응을 유지한다.	Handle tool calls — Claude API
is_error	tool_result의 선택적 필드로, 도구 실행이 실패했을 때 true로 설정해, 모델이 이 호출이 성공하지 못했음을 알고 다른 인자로 재시도하거나 다른 경로를 택할 수 있게 한다.	Handle tool calls — Claude API
callModel	뼈대 루프의 의사코드 호출로, '모델에 요청을 보낸다'를 나타낸다. 실제 구현은 SDK의 client.messages.create로 바뀐다.	How tool use works — Claude API
executeTool	뼈대 루프의 호출로, '호스트가 실제로 가서 모델이 지목한 도구를 돌린다'를 나타낸다. 액션은 이 단계에서 일어나지, tool_use가 도착했을 때가 아니다.	How tool use works — Claude API
어텐션 예산	컨텍스트를 파싱하는 모델의 유한한 자원. 새 토큰마다 이것을 소모하며, 컨텍스트가 길수록 모델이 그 컨텍스트에서 정보를 정확히 회상하는 능력이 나빠진다.	Effective context engineering for AI agents — Anthropic Engineering
정지 조건	호스트가 강제하는 명시적 규칙 — 최대 반복 횟수 같은 — 으로, 모델 자신의 end_turn과 독립적으로 루프를 멈춰, 제어를 여러분 쪽에 둔다.	Building Effective AI Agents — Anthropic Engineering
최대 턴 수	가장 기본적인 하드 스톱 조건: 루프가 몇 바퀴 돌 수 있는지의 천장으로, 모델이 무엇을 원하든 표시에서 멈춘다.	Building Effective AI Agents — Anthropic Engineering
하드 스톱	경계에서 무조건 정지하고 루프를 끝내는 정지 조건 — 자동으로는 아무것도 계속되지 않는다. 최대 턴 수와 예산 소진이 여기 속한다. 종단 상태다.	Building Effective AI Agents — Anthropic Engineering
소프트 스톱	재개 가능한 일시 정지로, 루프가 의도적으로 체크포인트에서 멈추고 제어를 사람에게 넘기며, 답하면 그 정확한 지점에서 이어갈 수 있다. 끝이 아니다.	Building Effective AI Agents — Anthropic Engineering
카운터	루프 밖에서 유지되는 변수로, 라운드를 거쳐 누적되며 루프가 몇 바퀴 돌았는지 기록한다. 최대 턴 게이트가 판단할 수 있게 하는 것이다.	Building Effective AI Agents — Anthropic Engineering
체크포인트	사슬의 노드에 설정된 일시 정지 지점으로, '이것이 틀리면 이후 전부가 헛수고'인 곳에서 루프가 중간 상태를 드러내 검증받거나 사람 피드백을 기다리게 한다.	Building Effective AI Agents — Anthropic Engineering
needsHumanApproval	소프트 스톱 예제의 술어로, '다음 액션이 사람의 승인이 먼저 필요한가?'를 판단한다. 매칭되면 루프가 멈추고 사람의 응답을 기다리며 장면을 넘긴다.	Building Effective AI Agents — Anthropic Engineering
작업 완료	네 정지 조건 중 가장 부드러운 것 — 모델이 끝났다고 판단해 end_turn을 반환한다. 결정 권한은 모델에 있지만, 정말 끝냈는지 도중에 포기했는지 확인해야 한다.	Building Effective AI Agents — Anthropic Engineering
스냅숏	소프트 스톱 일시 정지에서 넘기는 재개 가능한 상태 — 현재 메시지들과 막힌 대기 중인 액션을 함께 포장해, 사람이 처리한 뒤 그 정확한 지점에서 이어갈 수 있게 한다.	Building Effective AI Agents — Anthropic Engineering
과잉 설계	복잡성이 결과를 입증 가능하게 개선하지 않을 때 메커니즘을 쌓아 올리는 것. 복잡성은 분명히 결과를 개선할 때만 더해야 하지만 — 최대 턴 같은 정지 조건은 저비용 고수익 제어라, 이 범주가 아니다.	Building Effective AI Agents — Anthropic Engineering
누적 증폭	한 번의 잘못된 단계 뒤 이후 모든 턴이 실수 위에 계속 쌓여 편향을 증폭시킨다. 예외는 던져지지 않고 각 단계는 합리적으로 보이지만, 에러가 사슬을 따라 복리로 불어난다.	Building Effective AI Agents — Anthropic Engineering
컨텍스트 비대화	매 루프 턴이 히스토리에 메시지 둘을 쌓고, 추가만 하고 빼지 않아, 각 요청이 점진적으로 더 긴 컨텍스트를 나른다. 요청이 느려지고 비싸진다.	Effective context engineering for AI agents — Anthropic Engineering
컨텍스트 부패	컨텍스트가 길어질수록 핵심 정보가 노이즈에 잠기고 모델이 '볼 수 있지만 붙잡을 수 없다' — 회상이 길이에 따라 완만한 기울기로 나빠지지, 갑작스러운 절벽이 아니다.	Effective context engineering for AI agents — Anthropic Engineering
데드 루프	호스트 코드가 틀린 기계적 결함 (가령 루프 본문 끝에서 response 재대입을 잊음)으로, stop_reason이 옛 값에 얼어붙고, while이 영구히 참이 되며, 프로세스가 멈춰 선다.	How tool use works — Claude API
공회전	코드는 완전히 옳고 루프가 정당하게 매 턴 요청을 보내고 도구를 실행하는데, 새로운 진척이 전혀 없다 — 같은 도구를 반복 호출해 거의 동일한 빈 결과를 받는 것처럼.	Building Effective AI Agents — Anthropic Engineering
무진행 감지	공회전을 위해 만든 하드 게이트: 호스트가 '새로운 일이 일어나고 있는가'를 지켜보고, N턴 연속으로 같은 도구가 거의 동일한 출력을 반환하면 무진행이라 판단해 빠져나온다.	Building Effective AI Agents — Anthropic Engineering
예산 상한	루프에 설정한 명시적 비용 천장으로, 턴 수나 토큰(돈)으로 센다. 천장에 도달하면 멈춘다; 턴으로는 가볍고 토큰으로는 실제 비용에 더 가깝다.	Building Effective AI Agents — Anthropic Engineering
예산 소진	턴 수 곱하기 턴당 컨텍스트가 곱해져 비용이 통제를 벗어나 오른다. 공회전에 빠진 에이전트는 아무것도 끝내지 못하고 밤새 상당한 API 지출을 태울 수 있다.	Building Effective AI Agents — Anthropic Engineering
컨텍스트 거버넌스	루프가 생성하는 히스토리를 폴백으로 능동적으로 관리하기 — 오래된 턴을 압축하고, 초기 결과를 요약하고, 관련 없는 중간 산출물을 버려, 턴당 비용에 브레이크를 건다.	Effective context engineering for AI agents — Anthropic Engineering
조기 정지	이미 밀린 루프를 뭔가 이상해 보이는 순간 멈추는 것으로, 전체 예산을 태우게 두지 않는다. 체크포인트와 함께 작동해 에러가 아직 작을 때 자른다.	Building Effective AI Agents — Anthropic Engineering
한계 수익이 체감	유한 자원으로서의 컨텍스트 속성 — 추가 히스토리 조각마다 점진적으로 더 적은 가치를 가져온다. 그래서 모든 히스토리 덩어리가 '이게 아직 가치 있는가'를 정당화해야 한다.	Effective context engineering for AI agents — Anthropic Engineering
과도한 에이전시	예기치 못한, 모호한, 또는 조작된 LLM 출력에 반응해 해로운 액션이 수행되는 취약점 — 오작동 원인이 무엇이든 상관없이. 모델이 실제 권한에 연결되면 나쁜 출력이 파괴를 촉발할 수 있다.	LLM06:2025 Excessive Agency — OWASP Gen AI Security Project
중단	세 휴먼 개입 중 가장 무딘 것 — 모델이 이번 턴에 무엇을 하려 하든, 전체 루프가 종료되고 더 이상 요청이 나가지 않는다. 중단 후에는 '그다음'이 없다.	Building Effective AI Agents — Anthropic Engineering
조향	대화에 새로운 사람의 메시지를 밀어 넣어, 모델이 다음에 기대는 것을 바꾸고, 루프는 새 지시를 실어 가며 계속 돈다. 조향은 방향을 바꾸지, 루프가 사느냐를 바꾸지 않는다.	Building Effective AI Agents — Anthropic Engineering
승인	한 특정 영향 큰 액션에 대한 개입 — 루프가 거기 도달해 멈추고 '지금 이것을 하려 합니다'를 보여 주고, 사람이 예라고 할 때만 실행하며; 아니오면 건너뛰거나 취소한다. 승인 후 루프는 리듬을 재개한다.	LLM06:2025 Excessive Agency — OWASP Gen AI Security Project
휴먼 인 더 루프	사람이 몇몇 중요한 지점에서 돌이킬 수 없는 액션이 착지하기 전에 '잠깐'이라 말할 기회를 얻는 제어로, 사후에 로그만 보는 것이 아니다.	LLM06:2025 Excessive Agency — OWASP Gen AI Security Project
사람의 게이트	하네스 자체의 자동 게이트를 넘어선 수동 체크포인트로, '잘못하면 되돌릴 수 없는' 몇 안 되는 지점을 지키며 자동화의 신뢰가 사람의 현장 판단을 필요로 하는 곳이다.	LLM06:2025 Excessive Agency — OWASP Gen AI Security Project
돌이킬 수 없는	한 단계로 되돌릴 수 없거나 엄청난 비용으로만 되돌릴 수 있는 액션 (데이터베이스 드롭, 자금 이동, 외부 게시, 프로덕션 설정 변경). 승인 게이트가 이것들 앞에 와야 한다.	LLM06:2025 Excessive Agency — OWASP Gen AI Security Project
영향 범위	작업이 잘못됐을 때 그 영향 범위와 돌이킬 수 없음의 척도. 영향 범위가 클수록 확인 지점을 더 일찍 게이트해야 한다.	LLM06:2025 Excessive Agency — OWASP Gen AI Security Project
반사실 테스트	돌이킬 수 있음을 판단하는 자가 점검: 이 액션이 돌고 틀렸다면, 한 단계로 저비용으로 되돌릴 수 있는가? 아니라면 게이트가 일찍 가야 한다.	LLM06:2025 Excessive Agency — OWASP Gen AI Security Project
askHuman	승인 밸브 안의 호출로, 사람에게 승인 결정을 요청한다. 터미널에서는 '대기 중인 액션을 출력하고 한 줄 입력을 읽는다'를 뜻한다. executeTool 전에 완료돼야 한다.	LLM06:2025 Excessive Agency — OWASP Gen AI Security Project
@anthropic-ai/sdk	공식 Node SDK. 이것으로 뼈대 의사코드 callModel을 실제 client.messages.create로 바꾸며, 같은 stop_reason 루프를 구동한다.	How tool use works — Claude API
client.messages.create	모델 요청을 보내는 SDK 메서드로, model / max_tokens / tools / messages를 받는다. 루프의 callModel을 실제로 대체하는 것이다.	How tool use works — Claude API
runToolUses	이번 턴의 tool_use 블록들을 받아 실제로 각각을 돌리고, 각각을 tool_result에 포장하는 함수. 승인 밸브와 try/catch가 모두 안에 산다.	Handle tool calls — Claude API
runAgent	전체 하네스 루프를 나르는 진입 함수로, 메시지, 네 제어 밸브, 요청 전송, 도구 실행을 stop_reason이 더 이상 tool_use가 아닐 때까지 함께 연결한다.	How tool use works — Claude API
signatureOf	무진행 감지 시그니처 함수 — 이번 턴의 tool_use 이름과 파라미터를 하나의 문자열로 연결해, 이전 턴과 비교해 공회전을 감지하는 데 쓴다.	Building Effective AI Agents — Anthropic Engineering
response.usage	모델 응답의 필드로 이번 턴의 토큰 소비 (input_tokens + output_tokens)를 보고한다. 토큰으로 센 예산 상한의 기초다.	Building Effective AI Agents — Anthropic Engineering
input_schema	도구 정의의 JSON 스키마로 입력 구조를 서술한다. 모델이 매칭하도록 tool_use input을 구성해, 파라미터가 도구 요구사항을 따르게 한다.	Handle tool calls — Claude API
try/catch	도구 실행 주위의 에러 허용 래퍼 — 던질 때 하네스를 크래시시키지 말고, 에러를 is_error tool_result로 포장해 돌려보내, 모델이 재시도하거나 회전할 기회를 준다.	Handle tool calls — Claude API
제어 밸브	루프에 용접된 제어 메커니즘의 총칭으로, 각각 한 지점을 지킨다 — 최대 턴 수, 예산 상한, 무진행 감지, 영향 큰 액션 승인. 위치는 임의가 아니다.	The 2026 Agent Engineering Roadmap — GitHub (codejunkie99/agent-roadmap-2026)
정책 밸브	승인 밸브의 일반화 — 도구를 이름으로 allow (바로 통과), ask (실행 전 확인), deny (언제나 거부) 계층으로 라우팅하며, executeTool 전에 판단한다.	LLM06:2025 Excessive Agency — OWASP Gen AI Security Project
HIGH_IMPACT	외부에서 보이거나 돌이킬 수 없는 결과를 만드는 액션 (write_file, http_post, delete_file). 이것들에만 승인을 게이트하고; 무해한 읽기와 쿼리는 바로 통과한다.	LLM06:2025 Excessive Agency — OWASP Gen AI Security Project