from dotenv import load_dotenv
load_dotenv(".env", override=True)
%load_ext autoreload
%autoreload 2The autoreload extension is already loaded. To reload it, use:
%reload_ext autoreload
Planning: TODO Lists
많은 에이전트들은 장기적이고 복잡한 작업을 수행하는 데 중요한 내비게이션 도구로 TODO 목록을 사용합니다. Claude Code는 계획 모드를 활용하여 작업을 실행하기 전에 구조화된 TODO 목록을 생성하며, Claude Code 프롬프트를 기반으로 한 TodoWrite라는 특정 도구를 사용합니다. 각 TODO 항목은 두 가지 핵심 구성 요소로 이루어집니다: 내용(짧고 구체적인 작업 설명)과 상태(보류 중, 진행 중, 완료됨).
TODO 목록의 어려움은 컨텍스트 창이 커짐에 따라 주의를 유지하는 데 있습니다. 평균적인 Manus 작업은 약 50개의 도구 호출을 사용하며, 이는 상당한 컨텍스트 부패 위험을 초래합니다. 에이전트는 긴 대화나 복잡한 작업 중 주제를 벗어나거나 초기 목표를 잊기 쉽습니다. 마누스와 같은 에이전트는 TODO 목록을 지속적으로 재작성하고 업데이트함으로써 컨텍스트 종료 시점에 목표를 효과적으로 재확인합니다. 이는 작업에 집중하는 것을 돕고 임무 이탈을 방지합니다.
State
이전 강의에서처럼 커스텀 상태를 가진 create_agent를 사용하게 됩니다.
상태 객체는 워크플로우의 여러 단계 간에 컨텍스트를 저장하고 전달하기 위한 주요 메커니즘입니다. State는 그래프의 스키마와 상태에 적용할 업데이트를 지정하는 리듀서 함수로 구성됩니다.
DeepAgent 스킴에는 messages, todo, files 세 가지 기본 요소가 정의됩니다.
messages는 첫 번째 강의에서 설명한AgentState에서 상속됩니다.add_messages리듀서는 새로운 메시지를 메시지 목록의 끝에 추가합니다.
todo는Todo작업의 목록입니다. 각 작업은 설명인content와 상태인status(pending, in_progress, completed)를 가집니다.- 커스텀 리듀서가 정의되지 않았으므로 업데이트 시 목록을 덮어씁니다.
files은 상태에 포함된 가상 파일 시스템으로, 다음 강의에서 탐색할 예정입니다.
writefile ./src/deep_agents_from_scratch/todo_tools.py
"""작업 계획 및 진행 상황 추적을 위한 할일 관리 도구.
이 모듈은 에이전트가 복잡한 워크플로우를 계획하고
다단계 작업을 통해 진행 상황을 추적할 수 있게 하는
구조화된 작업 목록을 만들고 관리하기 위한 도구를 제공합니다.
"""
from typing import Annotated
from langchain_core.messages import ToolMessage
from langchain_core.tools import InjectedToolCallId, tool
from langgraph.prebuilt import InjectedState
from langgraph.types import Command
from .prompts import WRITE_TODOS_DESCRIPTION
from .state import DeepAgentState, Todo
@tool(description=WRITE_TODOS_DESCRIPTION, parse_docstring=True)
def write_todos(
todos: list[Todo],
tool_call_id: Annotated[str, InjectedToolCallId],
) -> Command:
"""작업 계획 및 추적을 위해 에이전트의 할일 목록을 생성하거나 업데이트합니다.
Args:
todos: content와 status가 있는 Todo 항목 목록
tool_call_id: 메시지 응답을 위한 도구 호출 식별자
Returns:
새로운 할일 목록으로 에이전트 상태를 업데이트하는 Command
"""
return Command(
update={
"todos": todos,
"messages": [
ToolMessage(
f"할일 목록을 {todos}로 업데이트했습니다.",
tool_call_id=tool_call_id,
)
],
}
)
@tool(parse_docstring=True)
def read_todos(
state: Annotated[DeepAgentState, InjectedState],
tool_call_id: Annotated[str, InjectedToolCallId],
) -> str:
"""에이전트 상태에서 현재 할일 목록을 읽습니다.
이 도구는 에이전트가 현재 할일 목록을 검색하고 검토하여 남은 작업에
집중하고 복잡한 워크플로우를 통한 진행 상황을 추적할 수 있게 합니다.
Args:
state: 현재 할일 목록을 포함하는 주입된 에이전트 상태
tool_call_id: 메시지 추적을 위한 주입된 도구 호출 식별자
Returns:
현재 할일 목록의 형식화된 문자열 표현
"""
todos = state.get("todos", [])
if not todos:
return "현재 할일 목록에 항목이 없습니다."
result = "현재 할일 목록:\n"
for i, todo in enumerate(todos, 1):
status_emoji = {"pending": "⏳", "in_progress": "🔄", "completed": "✅"}
emoji = status_emoji.get(todo["status"], "❓")
result += f"{i}. {emoji} {todo['content']} ({todo['status']})\n"
return result.strip()Overwriting ./src/deep_agents_from_scratch/todo_tools.py
그래프
첫 번째 강의에서처럼 create_agent를 사용하여 에이전트를 구축합니다. 우리는 에이전트가 할일 목록을 사용하도록 하는 데 집중할 예정입니다. Manus 접근 방식을 따라 각 작업 후에 할일 목록을 낭독하고, 위에서 방금 생성한 도구들을 사용할 것입니다.
from src.deep_agents_from_scratch.prompts import TODO_USAGE_INSTRUCTIONS
show_prompt(TODO_USAGE_INSTRUCTIONS)╭──────────────────────────────────────────────────── Prompt ─────────────────────────────────────────────────────╮ │ │ │ Based upon the user's request: │ │ 1. Use the write_todos tool to create TODO at the start of a user request, per the tool description. │ │ 2. After you accomplish a TODO, use the read_todos to read the TODOs in order to remind yourself of the plan. │ │ 3. Reflect on what you've done and the TODO. │ │ 4. Mark you task as completed, and proceed to the next TODO. │ │ 5. Continue this process until you have completed all TODOs. │ │ │ │ IMPORTANT: Always create a research plan of TODOs and conduct research following the above guidelines for ANY │ │ user request. │ │ IMPORTANT: Aim to batch research tasks into a *single TODO* in order to minimize the number of TODOs you have │ │ to keep track of. │ │ │ │ │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
from IPython.display import Image
from langchain_core.tools import tool
from src.deep_agents_from_scratch.prompts import TODO_USAGE_INSTRUCTIONS
from src.deep_agents_from_scratch.state import DeepAgentState
from src.deep_agents_from_scratch.todo_tools import read_todos, write_todos
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
# 모의 검색 결과
search_result = """Model Context Protocol(MCP)는 Anthropic에서 개발한 개방형 표준 프로토콜로,
AI 모델과 도구, 데이터베이스, 기타 서비스 같은 외부 시스템 간의 원활한 통합을 가능하게 합니다.
이는 표준화된 통신 계층으로 작동하여 AI 모델이 일관되고 효율적인 방식으로 다양한 소스의 데이터에
접근하고 활용할 수 있도록 합니다. 본질적으로 MCP는 데이터 교환을 위한 통합 언어를 제공함으로써
AI 어시스턴트를 외부 서비스에 연결하는 프로세스를 단순화합니다."""
# 모의 검색 도구
@tool(parse_docstring=True)
def web_search(query: str):
"""특정 주제에 대한 웹 정보를 검색합니다.
이 도구는 웹 검색을 수행하고 주어진 쿼리에 대한 관련 결과를 반환합니다.
인터넷에서 모든 주제에 대한 정보를 수집해야 할 때 이 도구를 사용하세요.
Args:
query: 검색 쿼리 문자열입니다. 원하는 정보에 대해 구체적이고 명확하게 작성하세요.
Returns:
검색 엔진의 검색 결과입니다.
Example:
web_search("의료 분야의 머신러닝 응용")
"""
return search_result
# create_agent를 직접 사용하여 에이전트 생성
model = init_chat_model(model="anthropic:claude-sonnet-4-20250514", temperature=0.0)
tools = [write_todos, web_search, read_todos]
# 모의 연구 지시사항 추가
SIMPLE_RESEARCH_INSTRUCTIONS = """중요: web_search 도구에 단 한 번만 호출하고 도구가 제공한 결과를 사용하여 사용자의 질문에 답하세요."""
# 에이전트 생성
agent = create_agent(
model,
tools,
system_prompt=TODO_USAGE_INSTRUCTIONS
+ "\n\n"
+ "=" * 80
+ "\n\n"
+ SIMPLE_RESEARCH_INSTRUCTIONS,
state_schema=DeepAgentState,
)
# 에이전트 표시
display(Image(agent.get_graph(xray=True).draw_mermaid_png()))
상태에 todos가 없고 사용자 연구 요청이 있는 상태로 그래프를 시작합니다.
from typing import Any
from utils import format_messages
inputs: Any = {
"messages": [
{
"role": "user",
"content": "Model Context Protocol (MCP)에 대한 짧은 요약을 제공해 주세요.",
}
],
"todos": [],
}
result = agent.invoke(inputs)
format_messages(result["messages"])╭─────────────────────────────────────────────────── 🧑 Human ────────────────────────────────────────────────────╮ │ Model Context Protocol (MCP)에 대한 짧은 요약을 제공해 주세요. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────── 📝 AI ─────────────────────────────────────────────────────╮ │ MCP(Model Context Protocol)에 대한 정보를 조사하여 짧은 요약을 제공하겠습니다. │ │ │ │ 🔧 Tool Call: write_todos │ │ Args: { │ │ "todos": [ │ │ { │ │ "content": "Model Context Protocol (MCP)에 대한 웹 검색을 수행하여 정의, 목적, 주요 특징 등의 정보를 │ │ 수집", │ │ "status": "pending" │ │ }, │ │ { │ │ "content": "수집된 정보를 바탕으로 MCP에 대한 짧고 명확한 요약 작성", │ │ "status": "pending" │ │ } │ │ ] │ │ } │ │ ID: toolu_01XrCWewjJNNB35rJmKmBF8e │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────── 🔧 Tool Output ─────────────────────────────────────────────────╮ │ 할일 목록을 [{'content': 'Model Context Protocol (MCP)에 대한 웹 검색을 수행하여 정의, 목적, 주요 특징 등의 │ │ 정보를 수집', 'status': 'pending'}, {'content': '수집된 정보를 바탕으로 MCP에 대한 짧고 명확한 요약 작성', │ │ 'status': 'pending'}]로 업데이트했습니다. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────── 📝 AI ─────────────────────────────────────────────────────╮ │ │ │ 🔧 Tool Call: web_search │ │ Args: { │ │ "query": "Model Context Protocol MCP definition purpose features" │ │ } │ │ ID: toolu_015zqT9dZEUhzKiP7DGubAXn │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────── 🔧 Tool Output ─────────────────────────────────────────────────╮ │ Model Context Protocol(MCP)는 Anthropic에서 개발한 개방형 표준 프로토콜로, │ │ AI 모델과 도구, 데이터베이스, 기타 서비스 같은 외부 시스템 간의 원활한 통합을 가능하게 합니다. │ │ 이는 표준화된 통신 계층으로 작동하여 AI 모델이 일관되고 효율적인 방식으로 다양한 소스의 데이터에 │ │ 접근하고 활용할 수 있도록 합니다. 본질적으로 MCP는 데이터 교환을 위한 통합 언어를 제공함으로써 │ │ AI 어시스턴트를 외부 서비스에 연결하는 프로세스를 단순화합니다. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────── 📝 AI ─────────────────────────────────────────────────────╮ │ │ │ 🔧 Tool Call: read_todos │ │ Args: {} │ │ ID: toolu_01J9skaYfwqeRDxtq4AkWKs5 │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────── 🔧 Tool Output ─────────────────────────────────────────────────╮ │ 현재 할일 목록: │ │ 1. ⏳ Model Context Protocol (MCP)에 대한 웹 검색을 수행하여 정의, 목적, 주요 특징 등의 정보를 수집 (pending) │ │ 2. ⏳ 수집된 정보를 바탕으로 MCP에 대한 짧고 명확한 요약 작성 (pending) │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────── 📝 AI ─────────────────────────────────────────────────────╮ │ │ │ 🔧 Tool Call: write_todos │ │ Args: { │ │ "todos": [ │ │ { │ │ "content": "Model Context Protocol (MCP)에 대한 웹 검색을 수행하여 정의, 목적, 주요 특징 등의 정보를 │ │ 수집", │ │ "status": "completed" │ │ }, │ │ { │ │ "content": "수집된 정보를 바탕으로 MCP에 대한 짧고 명확한 요약 작성", │ │ "status": "in_progress" │ │ } │ │ ] │ │ } │ │ ID: toolu_01DUdr3sZxvDd61eeGR6Gtgg │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────── 🔧 Tool Output ─────────────────────────────────────────────────╮ │ 할일 목록을 [{'content': 'Model Context Protocol (MCP)에 대한 웹 검색을 수행하여 정의, 목적, 주요 특징 등의 │ │ 정보를 수집', 'status': 'completed'}, {'content': '수집된 정보를 바탕으로 MCP에 대한 짧고 명확한 요약 작성', │ │ 'status': 'in_progress'}]로 업데이트했습니다. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────── 📝 AI ─────────────────────────────────────────────────────╮ │ ## Model Context Protocol (MCP) 요약 │ │ │ │ **Model Context Protocol (MCP)**는 Anthropic에서 개발한 개방형 표준 프로토콜입니다. │ │ │ │ ### 주요 특징: │ │ - **목적**: AI 모델과 외부 시스템(도구, 데이터베이스, 서비스) 간의 원활한 통합 지원 │ │ - **기능**: 표준화된 통신 계층 역할을 하여 AI 모델이 다양한 데이터 소스에 일관되고 효율적으로 접근 가능 │ │ - **장점**: 데이터 교환을 위한 통합 언어를 제공하여 AI 어시스턴트와 외부 서비스 연결 과정을 단순화 │ │ │ │ 본질적으로 MCP는 AI 시스템이 외부 리소스와 상호작용할 때 필요한 복잡성을 줄이고, 표준화된 방식으로 데이터를 │ │ 주고받을 수 있게 해주는 프로토콜입니다. │ │ │ │ 🔧 Tool Call: write_todos │ │ Args: { │ │ "todos": [ │ │ { │ │ "content": "Model Context Protocol (MCP)에 대한 웹 검색을 수행하여 정의, 목적, 주요 특징 등의 정보를 │ │ 수집", │ │ "status": "completed" │ │ }, │ │ { │ │ "content": "수집된 정보를 바탕으로 MCP에 대한 짧고 명확한 요약 작성", │ │ "status": "completed" │ │ } │ │ ] │ │ } │ │ ID: toolu_016T6iFQGQYgfaVKaNptreqp │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────── 🔧 Tool Output ─────────────────────────────────────────────────╮ │ 할일 목록을 [{'content': 'Model Context Protocol (MCP)에 대한 웹 검색을 수행하여 정의, 목적, 주요 특징 등의 │ │ 정보를 수집', 'status': 'completed'}, {'content': '수집된 정보를 바탕으로 MCP에 대한 짧고 명확한 요약 작성', │ │ 'status': 'completed'}]로 업데이트했습니다. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────── 📝 AI ─────────────────────────────────────────────────────╮ │ │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯