How: LangGraph Agent 구현 (Tools + Graph)

LangGraph Agent 구현

구현 순서

Tool 정의 (RAG Tool, KG Tool, Calc Tool)
Agent State 정의 — 리듀서를 반드시 붙인다
Agent Node / Tool Node 구현
StateGraph 조립
터미널 테스트

이것이 오늘의 핵심이다.

여기서 가장 많이 막히는 곳: 상태 리듀서

# 틀림 — 두 번째 자리에 설명 문자열이 들어갔다
messages: Annotated[Sequence[BaseMessage], "대화 메시지"]

# 맞음
from langgraph.graph.message import add_messages
messages: Annotated[Sequence[BaseMessage], add_messages]

Annotated 의 두 번째 인자는 주석 자리가 아니라 LangGraph 가 리듀서로 읽는 자리다. 리듀서는 노드가 돌려준 값을 기존 값과 어떻게 합칠지 정하는 함수다. 호출할 수 없는 값을 넣으면 조용히 무시되고, 채널은 기본 동작인 '마지막 값으로 덮어쓰기'가 된다.

그러면 tools 노드가 ToolMessage 하나만 돌려주는 순간 앞의 SystemMessage·HumanMessage· AIMessage 가 전부 사라진다. 다음 agent 노드는 ToolMessage 하나만 OpenAI 로 보내고, 앞선 tool_calls 메시지가 없으므로 API 가 400 을 돌려준다. 증상은 "도구를 부르는 질문만 실패한다" 로 나타나므로 원인이 상태 정의에 있다는 것을 알아채기 어렵다. 상태가 쌓이지 않고 마지막 것만 남는다면 리듀서부터 본다.

class AgentState(MessagesState) 로 상속해도 같은 리듀서가 붙는다. 앞의 p8w8-d2-core reading 이 그 방식으로 써 두었으니 둘 중 아무거나 골라도 된다.

두 번째 자리: 도구를 언제 끊을 것인가

W4 에서 쓰던 AgentExecutor(max_iterations=10) 자리가 LangGraph 에는 없다. 같은 일을 하는 것은 실행 옵션의 recursion_limit 이다.

graph.invoke({"messages": messages}, {"recursion_limit": 20})

agent -> tools -> agent 한 바퀴가 두 스텝이므로 설정값의 두 배로 잡는다. 이것을 걸지 않으면 같은 도구를 계속 되부르는 에이전트를 끊을 자리가 없다.

세 번째 자리: 서비스를 도구 안으로 들여보내기

@tool 함수의 인자는 LLM 이 채운다. 그러니 rag_service 를 인자로 둘 수 없다. 바깥 함수가 서비스를 받고 그 안에서 도구를 정의해 클로저로 잡는 것이 create_rag_tool 이다. 도구의 반환값은 문자열이어야 하므로 SearchResult 리스트를 search_as_text 로 직렬화한다.