도구 승인과 복구 기능을 갖춘 개인정보 보호형 LangGraph 에이전트 만들기
민감한 데이터를 처리하는 에이전트에서 LangGraph의 사람 검토, 체크포인팅, 실행 횟수 제한, 자격 증명 보호 도구를 활용하는 실용적인 패턴을 알아봅니다.
요약 · TL;DR
LangGraph의 휴먼 인 더 루프 미들웨어를 사용해 민감한 도구 호출을 일시 중지하고, 검토하거나 거부한 뒤 체크포인트에서 재개하세요. 엄격한 도구 경계, 자격 증명 격리, 실행 한도를 함께 적용하세요.
핵심 요점
- 자격 증명은 도구 구현 내부에 보관하고, 모델에는 필요한 최소한의 인자만 전달하세요.
- 안전한 읽기는 허용하되, 민감한 쓰기나 쿼리에는 사람의 검토를 요구하세요.
- 영구 체크포인터와 안정적인 thread ID를 사용해 중단된 작업을 재개하세요.
- 그래프 실행을 제한하고, 도구를 멱등하게 만들거나 재시도해도 안전하도록 설계하세요.
- 체크포인트에 저장된 상태와 인터럽트 페이로드를 민감한 데이터로 취급하세요.
목차 (5)
개인정보 보호를 고려한 에이전트라면 도구 호출이 안전한지 모델의 판단에 맡겨서는 안 됩니다. 자격 증명은 대화 외부에 두고, 각 도구가 수행할 수 있는 작업을 제한하며, 민감한 작업은 사람의 검토를 위해 일시 중지하세요. LangGraph의 휴먼 인 더 루프 미들웨어는 일시 중지 및 재개 기능을 제공하지만, 데이터 처리, 권한 부여, 실행 한도는 애플리케이션에서 직접 정의해야 합니다.
이 가이드에서는 고객 레코드를 조회하고 데이터베이스 변경을 요청할 수 있는 에이전트의 간단한 패턴을 구성합니다. 아래 코드는 예시이며 여기서 테스트한 것은 아닙니다. 배포하기 전에 사용 중인 환경에 맞춰 패키지 버전과 도구 시그니처를 확인하세요.
1. 모델 컨텍스트와 자격 증명 분리하기
프롬프트나 도구 인자에 비밀번호, API 키, 세션 쿠키 또는 제한 없이 사용할 수 있는 데이터베이스 자격 증명을 넣지 마세요. 대신 도구가 제한된 작업만 수행하도록 하고, 실행 시점에 애플리케이션의 비밀 관리 메커니즘을 통해 자격 증명을 가져오게 하세요. 모델에는 작업을 선택하는 데 필요한 데이터만 표시해야 합니다.
예를 들어, 임의의 SQL과 연결 정보를 받는 범용 도구보다 find_customer_record(customer_id)와 같은 도구를 사용하는 편이 좋습니다. 권한은 도구 자체에서 검증하세요. 사용자의 요청만으로 해당 레코드에 접근할 권한이 입증되는 것은 아닙니다.
사람의 검토는 추가적인 통제 수단이지, 권한 부여 시스템이 아닙니다. 검토자가 판단에 필요한 정보는 확인할 수 있게 하되, 검토 화면과 로그에 불필요한 개인 정보나 비밀 정보가 표시되지 않도록 하세요.
2. 민감한 작업에 대한 검토 설정하기
제공된 LangChain 휴먼 인 더 루프 문서에서는 정책에 따라 도구 호출을 확인하는 미들웨어를 설명합니다. 조건에 맞는 호출은 실행을 중단할 수 있으며, 체크포인터는 그래프 상태를 저장해 나중에 실행을 재개할 수 있도록 합니다. 문서에 설명된 결정에는 승인, 인자 수정, 피드백과 함께 거부, 사용자에게 질문하는 도구에 응답하기가 포함됩니다.
다음은 설정 예시입니다. 자리표시자 도구를 애플리케이션의 접근 규칙과 입력 검증을 적용하는 구현으로 바꾸세요.
from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver
agent = create_agent(
model="YOUR_CONFIGURED_MODEL",
tools=[read_customer_record, update_customer_record],
middleware=[
HumanInTheLoopMiddleware(
interrupt_on={
"read_customer_record": False,
"update_customer_record": {
"allowed_decisions": ["approve", "edit", "reject"]
},
},
description_prefix="Review requested customer-data change",
),
],
# For production, use a persistent checkpointer appropriate to your stack.
checkpointer=InMemorySaver(),
)
InMemorySaver는 프로토타이핑에는 적합하지만, 프로세스가 재시작된 뒤에도 복구할 수 있는 내구성 있는 저장소는 아닙니다. 문서에서는 사람 검토 인터럽트를 처리하려면 체크포인터가 필요하다고 안내하며, AsyncPostgresSaver와 MongoDBSaver 같은 영구 저장 옵션을 제시합니다. 체크포인트에 저장하는 데이터에 적합한 접근 제어, 보존 규칙, 암호화를 갖춘 저장소를 선택하세요. 체크포인트에는 메시지와 도구 인자가 포함될 수 있으므로, 자격 증명을 제외하더라도 민감한 사용자 데이터가 저장될 수 있습니다.
일부 호출만 검토해야 한다면 문서에서 조건부 인터럽트를 위한 when 술어도 지원합니다(langchain>=1.3.3 필요). 예를 들어 승인된 작업 공간 밖에서 수행되는 쓰기나 읽기 전용이 아닌 쿼리를 일시 중지할 수 있습니다. 문자열 접두사 검사를 완전한 SQL 보안 정책으로 간주하지 마세요. 데이터베이스 계층과 도구 계층에서도 안전한 작업만 허용해야 합니다.
3. 동일한 실행을 일시 중지하고 검토한 뒤 재개하기
안정적인 thread ID를 사용해 애플리케이션이 대기 중인 검토를 올바른 대화와 연결할 수 있게 하세요. 해당 식별자와 검토 인터페이스를 보호해야 합니다. thread ID를 가지고 있다고 해서 작업을 승인할 권한이 생기는 것은 아닙니다.
from langgraph.types import Command
config = {"configurable": {"thread_id": "conversation-123"}}
result = agent.invoke(
{"messages": [{"role": "user", "content": "Update this customer's address"}]},
config=config,
version="v2",
)
if result.interrupts:
# Present the requested action to an authenticated reviewer.
# Resume only after recording that reviewer's decision.
result = agent.invoke(
Command(resume={"decisions": [{"type": "reject", "message": "Verify the request first."}]}),
config=config,
version="v2",
)
여러 도구 호출이 일시 중지된 경우 결정 순서는 인터럽트 요청에 포함된 작업 순서와 일치해야 합니다. 부작용이 있는 작업을 거부하려면 reject를 사용하세요. 문서에 따르면 respond는 합성된 도구 결과를 제공합니다. 이 옵션은 사용자에게 묻는 형태의 도구에 답할 때 사용해야 하며, 쓰기 작업을 거부하는 용도가 아닙니다.
4. 실행을 제한하고 복구를 고려해 설계하기
검토를 위해 일시 중지하는 것만으로 모델이 도구를 계속 요청하는 일을 막을 수는 없습니다. 호출에 그래프 재귀 한도를 설정하고, 한도 오류가 발생하면 제어된 방식으로 중단하세요. 적절한 한도는 작업에 따라 다릅니다. 모델과 도구 단계의 유용한 최대 시퀀스를 기준으로 정하고, 한도에 도달하는 상황을 테스트하세요.
config = {
"configurable": {"thread_id": "conversation-123"},
"recursion_limit": 12,
}
이 예시 설정은 그래프 단계 수를 제한하지만, 느린 도구, 대용량 출력, 외부 부작용의 반복을 방지한다고 보장하지는 않습니다. 네트워크 및 데이터베이스 호출에 타임아웃을 설정하고, 도구 출력을 제한하며, 입력을 검증하세요. 재시도 가능한 작업에는 멱등성 제어를 적용하거나 변경 사항을 적용하기 전에 현재 상태를 확인하세요. 도구가 성공한 뒤 에이전트가 결과를 기록하기 전에 실행이 실패하면, 무조건 재시도할 경우 작업이 두 번 수행될 수 있습니다.
복구 시에는 대기 중인 작업과 그 권한이 여전히 유효한지 확인한 뒤에만 동일한 체크포인트의 thread를 재개하세요. 검토가 진행되는 동안 사용자의 권한이나 대상 레코드가 변경되었다면, 오래된 인자를 그대로 실행하지 말고 거부하거나 다시 검증하세요.
5. 개인정보 보호 및 실패 점검 목록
프로덕션에 배포하기 전에 다음 사항을 확인하세요.
- 도구 구현이 자격 증명을 비공개로 가져오며 도구 결과나 오류에 자격 증명을 반환하지 않습니다.
- 각 도구가 사용자 권한을 확인하고, 필요한 최소한의 인자만 받습니다.
- 체크포인트, 인터럽트 페이로드, 로그, 검토자 화면에 대한 접근 및 보존 제어가 정의되어 있습니다.
- 검토자가 관련 없는 개인 정보를 보지 않고도 대상과 결과를 파악할 수 있습니다.
- 거부 시 도구가 실행되지 않으며, 재시도로 부작용이 중복되지 않습니다.
- 실행 단계 한도, 도구 타임아웃, 출력 한도가 설정되어 있고, 중단되거나 실패한 작업을 보고할 명확한 경로가 마련되어 있습니다.
핵심은 사람의 승인을 최소 권한, 데이터 최소화, 도구 수준의 검증을 대신하는 수단이 아니라 보안 워크플로의 한 체크포인트로 취급하는 것입니다.
FAQ
LangGraph 휴먼 인 더 루프 미들웨어는 일시 중지된 에이전트 상태를 저장하나요?
인터럽트 전후의 상태를 저장하기 위해 LangGraph 지속성 기능을 사용합니다. 체크포인터가 필요하며, 프로덕션 배포에서는 영구 저장소를 선택하고 적절한 접근 및 보존 제어를 적용해야 합니다.
민감한 도구 호출을 거부할 때 respond 결정을 사용해야 하나요?
아니요. 문서에서는 respond가 합성된 성공 도구 결과를 제공하는 동작으로 설명하며, 사용자에게 묻는 도구에 답하는 경우 등에 사용하도록 안내합니다. 부작용이 있는 작업을 거부하려면 reject를 사용하세요.
LangGraph 에이전트에서 자격 증명을 비공개로 유지하려면 어떻게 해야 하나요?
자격 증명을 도구의 실행 환경이나 비밀 관리 계층에 보관하세요. 프롬프트, 모델에 표시되는 도구 인자, 도구 결과, 인터럽트 메시지 또는 로그에 넣지 마세요.
사람의 승인을 받으면 에이전트가 무한히 실행되는 것을 막을 수 있나요?
아니요. 승인 미들웨어는 설정된 도구 호출을 검토하는 기능을 담당합니다. 실행 한도, 도구 타임아웃, 출력 제한, 안전한 재시도 동작은 별도로 추가해야 합니다.
관련 글
Guides
Human Review을 적용한 제한된 LangGraph Tool-Calling Agent 구축
명시적인 단계 제한, 위험한 작업에 대한 사람의 승인, 반복 가능한 테스트 케이스를 활용해 LangGraph tool-calling agent를 평가하는 실용적인 패턴을 소개합니다.
Guides
도구 호출, 사람 승인, 실행 제한을 적용한 LangGraph 고객 지원 에이전트 구축
고객 지원 분류를 위한 실용적인 LangGraph 패턴을 살펴봅니다. 요청을 라우팅하고 조회 도구를 호출하며, 환불을 사람의 승인 대기 상태로 일시 중지하고 그래프 실행 범위를 제한하는 방법을 다룹니다.
Guides
LangGraph 도구 호출: 실행 제한과 실패 복구
무제한 실행 대신 재시도 예산, 사람의 승인, 명시적인 복구 경로를 사용하는 LangGraph 프로덕션 운영 에이전트를 구축하는 방법을 알아봅니다.
Guides
API 인시던트 진단을 위한 제한된 LangGraph 에이전트 구축
읽기 전용 진단 도구를 호출하고, 실행을 제한하며, 실패를 명확히 드러내고, 위험한 작업 전에 일시 중지하는 LangGraph 인시던트 진단 에이전트를 구축합니다.