🧭 LangGraph 완전 정복 ④ — LangGraph와 Tool의 연결

“이제 LLM은 말뿐 아니라 행동할 수 있다.”
LangGraph에서 Tool을 노드로 연결하여, LLM이 직접 도구를 활용하는 방법.

---

⚙️ 1. Tool이란 무엇인가?

LangGraph에서 Tool은 “LLM이 직접 호출 가능한 외부 함수형 리소스”입니다.
즉, LLM이 자연어로 문제를 이해하고, 그에 따라 Python 함수나 API를 직접 실행할 수 있도록 하는 연결 단위예요.

예를 들어 LLM이 “서울의 날씨 알려줘”라고 했을 때,
→ get_weather("Seoul") 함수를 직접 실행하는 것이 바로 Tool 호출입니다.

---

🔩 2. LangChain과의 차이

비교 항목	LangChain Agent	LangGraph ToolNode
호출 방식	LLM이 ReAct 패턴을 통해 Tool 호출	그래프 내에서 Tool이 하나의 Node로 표현
제어 방식	추상적 (에이전트가 알아서)	명시적 (개발자가 흐름 설계)
장점	빠른 시작	구조적 디버깅, 조건 제어
예시	initialize_agent(tools, llm)	graph.add_node("weather_tool", tool_func)

LangGraph는 “에이전트의 행동(Act)”을 개발자가 직접 설계할 수 있게 해줍니다.
즉, 자동화보다 통제 가능한 자율성을 제공합니다.

---

🧠 3. 기본 예시: 날씨 API Tool 연결

from langgraph.graph import StateGraph
from langchain_openai import ChatOpenAI
import requests

# 상태 정의
class WeatherState:
    city: str
    report: str

# Tool (외부 API 호출)
def get_weather(state: WeatherState):
    city = state.city
    # 실제로는 OpenWeather API 등 호출 가능
    fake_response = {"Seoul": "맑음 ☀️", "Busan": "흐림 🌥️"}
    state.report = fake_response.get(city, "정보 없음")
    print(f"[Tool 호출] {city} 날씨: {state.report}")
    return state

# LLM 노드
def ask_user(state: WeatherState):
    llm = ChatOpenAI(model="gpt-4o-mini")
    prompt = f"{state.city}의 날씨를 요약해서 말해줘: {state.report}"
    reply = llm.invoke(prompt)
    print(f"[LLM 응답] {reply.content}")
    return state

# 그래프 구성
graph = StateGraph(WeatherState)
graph.add_node("weather_tool", get_weather)
graph.add_node("llm_summary", ask_user)
graph.add_edge("weather_tool", "llm_summary")

graph.set_entry_point("weather_tool")
graph.set_finish_point("llm_summary")

app = graph.compile()
app.invoke({"city": "Seoul"})

🧩 실행 결과 예시:

[Tool 호출] Seoul 날씨: 맑음 ☀️
[LLM 응답] 서울의 날씨는 맑으며, 좋은 날씨입니다.

이렇게 LangGraph에서는 LLM과 Tool의 호출 순서를 명시적으로 정의합니다.

---

🔀 4. 여러 ToolNode 병렬 호출하기

LangGraph에서는 여러 ToolNode를 병렬 실행할 수도 있습니다.
예를 들어, “날씨 + 뉴스 + 환율”을 동시에 가져오는 구조죠.

from langgraph.graph import StateGraph
import asyncio

class MultiState:
    weather: str
    news: str
    fx: str

async def get_weather(state): state.weather = "맑음"; return state
async def get_news(state): state.news = "국제 뉴스 업데이트"; return state
async def get_fx(state): state.fx = "1 USD = 1,350 KRW"; return state

async def merge_result(state):
    print(f"{state.weather} / {state.news} / {state.fx}")
    return state

graph = StateGraph(MultiState)
graph.add_node("weather", get_weather)
graph.add_node("news", get_news)
graph.add_node("fx", get_fx)
graph.add_node("merge", merge_result)

# 병렬 실행 엣지 구성
graph.add_edge("weather", "merge")
graph.add_edge("news", "merge")
graph.add_edge("fx", "merge")

graph.set_entry_point("weather")  # 병렬 시작점
graph.set_finish_point("merge")

app = graph.compile()
asyncio.run(app.ainvoke({}))

📊 Mermaid 시각화:

✅ ToolNode는 비동기(async) 함수로 정의하면 자동 병렬 실행이 가능합니다.

---

🧩 5. LangChain Runnable과 통합

LangGraph의 노드는 Runnable 객체를 그대로 사용할 수도 있습니다.
즉, LangChain에서 이미 만든 체인·Tool·LLM을 그래프에 삽입 가능하죠.

from langchain.tools import Tool
from langgraph.graph import StateGraph
from langchain_openai import ChatOpenAI

# LangChain Tool 정의
def calc(x, y): return x + y
sum_tool = Tool(name="add", func=calc, description="두 수를 더함")

class CalcState:
    result: int

def run_tool(state: CalcState):
    state.result = sum_tool.run(5, 7)
    return state

def summarize(state: CalcState):
    llm = ChatOpenAI(model="gpt-4o-mini")
    reply = llm.invoke(f"7과 5를 더하면 {state.result}입니다. 한 줄 요약해줘.")
    print(reply.content)
    return state

graph = StateGraph(CalcState)
graph.add_node("tool", run_tool)
graph.add_node("summary", summarize)
graph.add_edge("tool", "summary")
graph.set_entry_point("tool")
graph.set_finish_point("summary")
app = graph.compile()
app.invoke({})

이렇게 하면 기존 LangChain 자산을 그대로 재사용하면서 LangGraph의 구조적 제어를 얹을 수 있습니다.

---

🧱 6. 조건부 Tool 호출 (ToolCondition)

LLM의 판단에 따라 특정 Tool만 실행하도록 할 수도 있습니다.

def choose_tool(state):
    # LLM이 툴 선택 로직 수행했다고 가정
    state.tool_choice = "weather" if "날씨" in state.query else "news"
    return state

graph.add_node("chooser", choose_tool)
graph.add_conditional_edges("chooser", lambda s: s.tool_choice)

이 방식은 다음 회차의 ReAct 그래프 설계의 기초가 됩니다. (LLM이 스스로 “어떤 도구를 언제 쓸지” 결정)

---

🧭 7. 다음 회차 예고

👉 5편: ReAct 패턴과 LangGraph 에이전트화

• LLM의 Reasoning → Action → Observation 루프 설계
• ToolCondition + MemorySaver를 활용한 자율적 의사결정 흐름 구현

---

🎓 8. 더 깊이 배우기 위한 고급 확장 학습 가이드

주제	학습 이유	추천 학습 방향
LangChain Runnable 체계	LangGraph 내부 호출 구조의 핵심	RunnableLambda, RunnableParallel, RunnableMap
Async & Await 병렬 Tool 설계	여러 API Tool 병렬 실행	asyncio, await app.ainvoke()
Tool 선택 논리(Policy Design)	LLM의 “어떤 도구를 쓸지” 판단 제어	ToolCondition, LLM 선택 프롬프트
Custom ToolKit 구성	프로젝트별 Tool 세트 설계	“검색, 요약, 계산, DB” 등 기능화
Graph Logging & Visualization	Tool 실행 흐름 추적	graph.visualize("toolflow.png"), 상태 로그
LangGraph + LangServe	Tool 포함 그래프를 서비스화	REST API / WebSocket 기반 배포

---

📚 핵심 요약

• ToolNode는 “LLM의 손”이다.
• LangGraph에서 Tool을 노드로 연결하면, LLM이 직접 API·함수·데이터를 활용할 수 있다.
• 병렬 호출, 조건 호출, Runnable 통합으로 실전 에이전트 아키텍처가 완성된다.

💡 다음은 LLM이 스스로 “어떤 도구를 쓸지” 결정하고 피드백을 통해 수정하는 단계다.