Human Review을 적용한 제한된 LangGraph Tool-Calling Agent 구축
명시적인 단계 제한, 위험한 작업에 대한 사람의 승인, 반복 가능한 테스트 케이스를 활용해 LangGraph tool-calling agent를 평가하는 실용적인 패턴을 소개합니다.
요약 · TL;DR
그래프 단계 제한으로 실행 범위를 정하고, HumanInTheLoopMiddleware로 위험한 tool call을 일시 중지하며, 승인·거부·제한 동작을 확인할 수 있는 소규모 고정 테스트 세트를 사용하세요. 예시는 시작점으로 활용해야 하며, 모델과 tool의 동작은 자체 환경에서 테스트해야 합니다.
핵심 요점
- 그래프 recursion limit는 agent에 명확한 실행 경계를 제공하지만, agent가 작업을 완료한다는 보장은 아닙니다.
- 그래프에 checkpointer와 thread ID가 있으면 human review를 통해 tool 실행을 일시 중지했다가 나중에 재개할 수 있습니다.
- 테스트 입력, 예상 결과, tool fixture, 실행 제한을 고정해 평가를 반복 가능하게 유지하세요.
- 거부된 작업과 제한 초과를 명시적으로 테스트하세요. 어느 쪽도 성공적인 복구와는 동일하지 않습니다.
목차 (6)
Tool-calling agent에는 좋은 프롬프트만 필요한 것이 아닙니다. 중지 경계, 위험한 작업을 처리할 계획, 동작을 재현 가능하게 만드는 테스트가 필요합니다. LangGraph에서는 그래프 recursion limit와 선택한 tool에 대한 human-in-the-loop(HITL) review를 결합할 수 있습니다. 그런 다음 몇 번의 성공적인 실행에 의존하지 않고 고정된 케이스로 workflow를 평가할 수 있습니다.
아래 예시는 설명을 위한 것이며, 테스트된 구성은 아닙니다. 호환되는 LangChain 및 LangGraph 패키지가 설치된 Python 환경, tool calling을 지원하는 chat model, 그리고 직접 구현한 tool이 있다고 가정합니다. 사용 중인 환경에서 버전과 model provider 매개변수를 확인하세요.
Tool을 추가하기 전에 경계를 정하세요
recursion limit는 그래프 실행 단계를 제한합니다. 이는 안전 경계이지 agent가 완료된다는 약속이 아니며, tool call 수에 대한 정확한 제한도 아닙니다. 단계가 계산되는 방식은 그래프 구조의 영향을 받기 때문입니다. 실행이 제한에 도달하면 그래프 recursion error가 발생할 것으로 예상하고, 이를 미완료 실행으로 처리하세요. 성공적인 답변으로 간주해서는 안 됩니다.
평가 중에는 작은 제한으로 시작한 다음, 테스트 케이스에서 workflow에 더 많은 단계가 필요하다는 사실이 확인될 때만 제한을 높이세요. 또한 tool operation의 범위를 좁게 유지하세요. 그래프 수준의 제한으로는 tool이 이미 수행한 side effect를 되돌릴 수 없습니다.
Review를 위해 일시 중지할 수 있는 tool call 구성하기
이 예시는 HITL middleware와 함께 create_agent를 사용합니다. write_file tool은 승인 또는 거부를 위해 중단되고, read_data는 중단되지 않습니다. Tool 구현과 model 이름은 placeholder입니다. 선택한 model과 endpoint가 agent에서 사용하는 매개변수와 tool-calling 동작을 지원하는지 확인하세요.
from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver
# Replace these placeholders with your own tool implementations.
tools = [write_file, read_data]
agent = create_agent(
model="your-tool-capable-chat-model",
tools=tools,
middleware=[
HumanInTheLoopMiddleware(
interrupt_on={
"write_file": {"allowed_decisions": ["approve", "reject"]},
"read_data": False,
}
)
],
checkpointer=InMemorySaver(),
)
config = {
"configurable": {"thread_id": "evaluation-case-001"},
"recursion_limit": 8,
}
result = agent.invoke(
{"messages": [{"role": "user", "content": "Save the approved summary."}]},
config=config,
version="v2",
)
InMemorySaver는 하나의 프로세스에서 실행되는 prototype 또는 테스트에 적합하지만, 프로세스가 다시 시작되면 영속적으로 유지되지 않습니다. 배포된 workflow에는 persistent checkpointer를 사용하세요. LangChain HITL 가이드에서는 실행을 일시 중지하고 재개하려면 checkpointer와 thread ID가 필요하다고 설명합니다. 출처: Human-in-the-loop.
실행 결과로 interrupt가 반환되면 요청된 작업과 인수를 reviewer에게 보여 주세요. 동일한 thread에서 decision을 전달해 재개하세요. Decision 순서는 interrupt에 포함된 action 순서와 일치해야 합니다. 거부하는 action에는 reject를 사용하세요. respond는 side effect를 거부하는 기능이 아니라 human answer를 tool result로 반환하는 기능입니다.
from langgraph.types import Command
# Use the same config, including the same thread ID, to resume.
result = agent.invoke(
Command(resume={"decisions": [{"type": "reject", "message": "Outside the approved scope."}]}),
config=config,
version="v2",
)
평가를 반복 가능하게 만들기
간결한 테스트 세트를 version control에 보관하세요. 각 케이스에는 사용자 요청, 예상되는 tool 동작, review 필요 여부, 예상 최종 상태를 지정해야 합니다. 테스트에는 무해한 fixture 또는 mocked tool을 사용하세요. 평가 케이스가 실제 파일에 쓰거나 production data를 변경하도록 하지 마세요.
| 케이스 | 설정 | 예상 결과 |
|---|---|---|
| 안전한 읽기 | read_data를 통해 정보 요청 | HITL interrupt 없음; tool result 반환 |
| Review가 필요한 쓰기 | 허용된 쓰기 요청 | 쓰기가 실행되기 전에 interrupt 발생; 승인하면 실행 허용 |
| 거부된 쓰기 | 쓰기를 요청한 후 거부 | write tool이 실행되지 않음; 거부 feedback이 agent에 반환됨 |
| 단계 제한 경계 | workflow가 완료되지 않도록 하는 fixture 사용 | 구성된 경계에서 실행이 중지되고 미완료로 기록됨 |
각 실행에 대해 케이스 ID, 구성된 제한, tool call, interrupt decision, 완료 상태, 오류를 기록하세요. 해당 필드를 예상 결과와 비교하세요. 최종 자연어 응답만으로 판단하지 마세요. Agent가 잘못된 action을 수행한 뒤에도 그럴듯한 답변을 생성할 수 있습니다.
실패 처리: 일시 중지, 거부 또는 중지
HITL은 일반적인 retry mechanism이 아니라 통제된 일시 중지입니다. Reviewer는 구성된 policy에 따라 승인, 수정, 거부 또는 응답할 수 있습니다. 거부하면 요청된 tool call을 건너뛰고 거부 feedback을 agent에 반환합니다. 이후 agent가 완료할지, 다른 action을 요청할지, 실패할지는 후속 동작에 따라 달라지므로 해당 경로를 테스트하세요.
그래프가 recursion limit에 도달하면 실행을 limit failure로 기록하고 state와 tool history를 확인하세요. 이미 side effect를 수행했을 수 있는 실행을 자동으로 replay하지 마세요. 가능한 경우 tool을 idempotent하게 만들거나, operation을 반복하기 전에 별도의 확인을 요구하세요. 제공된 문서는 checkpoint를 사용한 일시 중지와 재개를 설명하지만, 임의의 tool 또는 model failure에서 자동 복구된다는 내용은 제시하지 않습니다.
Troubleshooting 체크리스트
- Interrupt가 표시되지 않음: Tool 이름이
interrupt_onmapping과 일치하는지, 해당 policy에서 review를 활성화했는지 확인하세요. - Resume 시 일시 중지된 실행을 찾을 수 없음: 동일한 checkpointer와 thread ID를 사용하고 있는지 확인하세요.
- 실행이 너무 일찍 중지됨: 구성된 recursion limit와 그래프 경로를 확인하세요. 테스트 케이스가 이를 정당화할 때만 제한을 높이세요.
- 거부된 action이 실행된 것처럼 보임: Review 전에 tool이 호출되지 않았는지, reviewer가
respond가 아니라reject를 사용했는지 확인하세요. - 테스트 결과가 실행마다 달라짐: Tool fixture와 테스트 입력을 고정하고, 설정에서 허용하는 경우 model response를 제어하거나 stub 처리하세요. 입력만 고정한다고 해서 model output이 결정론적으로 변하는 것은 아닙니다.
실무 규칙
recursion limit로 그래프 작업을 제한하고, HITL로 영향이 큰 tool call을 통제하며, 소규모의 명시적인 테스트 세트로 정상 경로와 실패 경로를 모두 확인하세요. Interrupt된 실행, 거부된 실행, 제한을 모두 사용한 실행을 서로 다른 결과로 취급하세요. 이러한 구분을 통해 agent를 더 쉽게 평가하고 더 안전하게 변경할 수 있습니다.
FAQ
LangGraph의 recursion limit는 tool call 수를 제한하나요?
정확히 그렇지는 않습니다. Recursion limit는 그래프 실행 단계를 제한하며, 그 안에 포함될 수 있는 tool call 수는 그래프 구조에 따라 달라집니다. 제한 초과는 미완료 실행으로 처리하고 해당 경계를 테스트하세요.
Human review를 거친 tool call을 재개하려면 무엇이 필요한가요?
Checkpointer를 구성하고 thread ID를 제공한 다음, 동일한 thread와 persistence context를 사용해 재개해야 합니다. Reviewer는 중단된 각 action에 대한 decision을 제공합니다.
HITL은 실패한 tool call을 자동으로 재시도하나요?
아니요. 문서에 설명된 HITL workflow는 human decision을 위해 일시 중지한 다음 review된 action을 실행하거나 건너뜁니다. 임의의 tool 또는 model failure에 대한 자동 retry를 보장하지는 않습니다.
거부된 tool call은 어떻게 테스트해야 하나요?
무해한 tool 또는 mocked tool을 사용하고, interrupt를 발생시킨 다음 action을 거부하세요. Tool이 실행되지 않았고 실행 결과에 거부 feedback이 기록되었는지 검증해야 합니다.
관련 글
Guides
도구 승인과 복구 기능을 갖춘 개인정보 보호형 LangGraph 에이전트 만들기
민감한 데이터를 처리하는 에이전트에서 LangGraph의 사람 검토, 체크포인팅, 실행 횟수 제한, 자격 증명 보호 도구를 활용하는 실용적인 패턴을 알아봅니다.
Guides
LangGraph 도구 호출: 실행 제한과 실패 복구
무제한 실행 대신 재시도 예산, 사람의 승인, 명시적인 복구 경로를 사용하는 LangGraph 프로덕션 운영 에이전트를 구축하는 방법을 알아봅니다.
Guides
API 인시던트 진단을 위한 제한된 LangGraph 에이전트 구축
읽기 전용 진단 도구를 호출하고, 실행을 제한하며, 실패를 명확히 드러내고, 위험한 작업 전에 일시 중지하는 LangGraph 인시던트 진단 에이전트를 구축합니다.
Guides
도구 호출, 사람 승인, 실행 제한을 적용한 LangGraph 고객 지원 에이전트 구축
고객 지원 분류를 위한 실용적인 LangGraph 패턴을 살펴봅니다. 요청을 라우팅하고 조회 도구를 호출하며, 환불을 사람의 승인 대기 상태로 일시 중지하고 그래프 실행 범위를 제한하는 방법을 다룹니다.