LangGraph — 止まるエージェントを作る

목표

LangGraph 로 재고를 물어보는 작은 에이전트를 만듭니다. 그래프, 쌓이는 상태, 조건부 갈래, 멈추는 루프, 도구 노드, 실패 경로, 체크포인터, 경로 기록까지 여덟 단계입니다.

모델은 부르지 않습니다

판단하는 노드를 규칙으로 둡니다. 이 실습이 가르치는 것은 모델 호출이 아니라 그래프이기 때문입니다 — 언제 멈출지, 무엇을 상태로 들고 다닐지, 도구가 실패하면 어디로 갈지. 에이전트에서 실제로 어려운 곳이 거기이고, 모델을 붙이는 것은 나중에 노드 하나를 바꾸는 일입니다.

형식

/root/work/agent/graph.py 에 아래를 둡니다.

• build_graph(checkpoint: bool = False) — compile 된 그래프를 돌려줍니다.
• CATALOG — 품목별 재고 딕셔너리(5단계부터).

상태에는 최소한 question, steps(리스트), tries(정수), answer 를 둡니다.

그래프 하나를 세우고 돌려 본다

mkdir -p /root/work/agent 후 graph.py 에 build_graph() 를 두세요. StateGraph 를 만들고 노드 하나를 붙여 compile() 한 것을 돌려줍니다. 상태에 steps 리스트를 두고 노드가 자기 이름을 남기게 하세요.

build_graph().invoke() 가 돌고 steps 에 노드 이름이 남습니다

상태가 쌓이게 만든다

노드를 두 개로 늘리고 둘 다 steps 에 이름을 남기게 하세요. Annotated[list, operator.add] 를 안 쓰면 마지막 것만 남습니다 — 지나온 길이 사라집니다.

서로 다른 노드 두 개 이상을 지나고 steps 에 전부 남습니다

질문에 따라 갈래를 나눈다

add_conditional_edges 로 갈래를 만드세요. '재고' 가 들어간 질문은 lookup 노드로, 아니면 다른 노드로 갑니다.

'재고' 질문은 lookup 을 지나고 인사말은 지나지 않습니다

돌되 반드시 멈춘다

찾지 못하면 다시 시도하는 루프를 만드세요. 상태에 tries 를 두고 상한(3회 정도) 을 둡니다. 상한이 없으면 재귀 한도에 걸려 예외로 죽습니다.

루프가 2회 이상 돌고 5회 이내에 스스로 멈춥니다

도구의 결과를 실제로 쓴다

CATALOG 딕셔너리를 3건 이상 두고(품목: 수량), lookup 이 질문에서 품목을 찾아 조회하게 하세요. 조회한 값이 answer 에 실제로 들어가야 합니다.

CATALOG 의 값이 answer 에 반영됩니다

도구 실패는 예외가 아니라 경로다

목록에 없는 것을 물으면 fallback 노드로 가서 '찾지 못했다' 를 답으로 만드세요. 빈손을 그대로 넘기면 지어내게 되고, 그것이 환각의 가장 흔한 경로입니다.

없는 품목 질문이 fallback 을 지나고 answer 가 '모른다' 는 뜻을 담습니다

대화를 이어 붙인다

build_graph(checkpoint=True) 를 받게 하고 MemorySaver 를 붙이세요. thread_id 로 상태가 갈리는지 확인합니다 — 같은 id 는 이어지고 다른 id 는 따로 남습니다.

get_state 로 상태가 남고 thread_id 별로 따로 관리됩니다

지나온 길을 기록한다

서로 다른 갈래를 타는 질문 두 개를 돌려 {질문: [노드, ...]} 를 /root/work/agent/08-trace.json 에 저장하세요. 기록이 실제 실행과 달라지면 그 기록으로는 아무것도 진단할 수 없습니다.

08-trace.json 의 경로가 실제 실행과 일치하고 두 경로가 서로 다릅니다