에이전틱 AI (Agentic AI) 시스템 구축: 실제 코드를 활용한 실무 튜토리얼

개요: "장난감 에이전트"에서 프로덕션 시스템으로

에이전틱 시스템 (Agentic systems)은 단순한 그래프입니다. 즉, 작업을 수행하는 노드 (LLM 호출, 도구 (tools), 다른 에이전트), 다음에 무엇이 일어날지 결정하는 엣지 (edges), 그리고 모든 것이 읽고 쓰는 상태 (state) 객체로 구성됩니다. LangGraph는 이 그래프를 명시적으로 만들어 주며, 이를 통해 모든 것이 스파게티 코드로 변하지 않으면서도 계획 루프 (planning loops), 인간 체크포인트 (human checkpoints), 재시도 (retries), 그리고 멀티 에이전트 패턴 (multi-agent patterns)을 추가할 수 있습니다.
langchain-ai.github
+1

Python, LangChain 모델, 그리고 LangGraph의 StateGraph를 사용한다고 가정합니다. 예제는 모든 import 문보다는 구조에 집중합니다. 각 블록을 작은 파일에 붙여넣고 모델과 도구를 연결한 후 실행할 수 있습니다.
docs.langchain
+1

핵심 설정: 상태 (state) 및 기본적인 도구 호출 (tool-calling) 에이전트

"에이전트가 현재 알고 있는 모든 것"을 나타내는 상태 스키마 (state schema)를 정의합니다. LangGraph는 이를 노드 간의 계약 (contract)으로 사용합니다.
langchain

python
from typing import TypedDict, List
from langgraph.graph import StateGraph, END
from langchain_core.messages import AnyMessage, HumanMessage
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool

class AgentState(TypedDict):
messages: List[AnyMessage]
plan: str
scratchpad: str

@tool
def get_weather(city: str) -> str:
"""도시의 현재 날씨를 조회합니다."""
# 더미 구현 (Dummy implementation)
return f"{city}의 날씨는 항상 맑습니다."

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)

tools = [get_weather]
llm_with_tools = llm.bind_tools(tools)

이제 단일 노드 도구 호출 에이전트를 구축합니다. 노드는 도구가 바인딩된 LLM을 호출합니다. 모델이 도구 호출 (tool calls)을 생성하면 LangGraph가 자동으로 도구를 실행하고 결과를 메시지 (messages)에 추가합니다.
langchain-ai.github

python
def agent_node(state: AgentState) -> AgentState:
response = llm_with_tools.invoke(state["messages"])
return {"messages": state["messages"] + [response]}

graph = StateGraph(AgentState)
graph.add_node("agent", agent_node)
graph.set_entry_point("agent")
graph.add_edge("agent", END)
app = graph.compile()

이제 최소한의 상태를 가진 도구 호출 에이전트 (tool-calling agent)를 갖추게 되었습니다. 다음과 같이 호출해 보세요:

python
result = app.invoke({"messages": [HumanMessage(content="What's the weather in London?")]})

가공되지 않은 대화 기록 (conversation history)과는 별개인, 예를 들어 작업 수준의 목표 (task-level goal)를 지원하도록 이 최소한의 상태를 어떻게 확장할 수 있을까요?

관리자(Supervisor)를 통한 멀티 에이전트 오케스트레이션 (Multi-agent orchestration)

일반적인 패턴은 "관리자 + 전문가 (supervisor + specialists)" 구조입니다. 하나의 LLM이 하위 에이전트(예: "planner", "researcher", "coder")에게 작업을 라우팅합니다. LangGraph를 사용하면 각 에이전트를 노드(node) 또는 공유 상태 (shared state)를 읽고 쓸 수 있는 서브그래프 (subgraph)로 만들 수 있습니다.
reddit
+1

상태 (state)에 역할을 정의하고 노드를 분리합니다:

python
class MultiState(TypedDict):
messages: List[AnyMessage]
active_role: str # "planner" | "researcher" | "coder" | "done"

planner_llm = llm
researcher_llm = llm_with_tools
coder_llm = llm

def planner_node(state: MultiState) -> MultiState:
resp = planner_llm.invoke(
state["messages"] + [
HumanMessage(content="You are a planner. Break the user goal into steps.")
]
)
return {
"messages": state["messages"] + [resp],
"active_role": "researcher",

Rizwan Saleem | https://rizwansaleem.co