실시간 투두 리스트

실시간 투두 리스트 (Todo list · Deep Agents 프론트엔드 패턴)

모든 에이전트 상호작용이 채팅은 아니에요. 에이전트가 다단계 계획을 실행 중일 때는 진행 상황을 가장 잘 보여주는 게 실시간으로 갱신되는 투두 리스트예요. 이 패턴은 todos 배열을 에이전트 상태에서 직접 읽어 각 항목의 상태를 렌더링해요. 채팅에 쓰는 것과 같은 useStream 훅 위에 만든 진행 대시보드랍니다.

출처: 공식문서

어떻게 동작하나

Deep agents는 TodoListMiddleware를 선택하면 todos 상태 채널을 노출해요. 이 미들웨어는 write_todos 도구를 추가하고 에이전트가 계획을 진행하면서 작업 상태를 추적해요. useStream 훅은 이 상태를 stream.values.todos로 노출하고, UI가 반응형으로 렌더링해요.

작업 계획은 opt-in이에요. TodoListMiddleware 없이는 stream.values.todos가 없어요.

흐름:

  1. 사용자가 요청 제출
  2. 에이전트가 계획을 만들고 상태에 todos 채움
  3. 에이전트가 각 todo를 pending → in_progress → completed로 전환하며 실행
  4. stream.values.todos가 실시간 갱신
  5. UI가 현재 상태로 투두 리스트를 다시 렌더링

useStream 설정

에이전트에서 TodoListMiddleware를 활성화해요.

from deepagents import create_deep_agent
from langchain.agents.middleware import TodoListMiddleware
agent = create_deep_agent(
    model="openai:gpt-5.5",
    middleware=[TodoListMiddleware()],
)

그다음 useStream을 그 에이전트에 연결하고 stream.values에서 todos를 읽어요. 코드 예시는 useStream<typeof myAgent>로 타입 안전한 스트림 상태를 만드는 방식이에요. React/Vue/Svelte/Angular 각자의 훅(@langchain/react, @langchain/vue, @langchain/svelte, @langchain/angular)이 있어요.

import { useStream } from "@langchain/react";
const AGENT_URL = "http://localhost:2024";
const stream = useStream<typeof myAgent>({ apiUrl: AGENT_URL, assistantId: "deep_agent_todo_list" });
const todos = stream.values?.todos ?? [];

TodoList 컴포넌트 만들기

투두 리스트는 각 항목을 상태 아이콘, 색상 코드, 시각적 스타일로 렌더링해요. 완료 수와 전체에서 백분율(percentage)을 계산해 진행률을 보여줘요. React 컴포넌트(TodoList, ProgressBar, TodoItem)는 todos.filter(t => t.status === "completed").length 등으로 완료 수와 진행률을 계산해요.

각 항목은 상태별 설정(icon, textClass, bgClass, iconClass)을 갖는데, in_progress 아이콘은 animate-pulse로 현재 활성 작업을 강조해요.

진행률 계산

todos 배열에서 바로 진행 지표를 유도해요.

const completed = todos.filter((t) => t.status === "completed").length;
const inProgress = todos.filter((t) => t.status === "in_progress").length;
const pending = todos.filter((t) => t.status === "pending").length;
const percentage = todos.length ? Math.round((completed / todos.length) * 100) : 0;

이 값들은 에이전트가 상태를 바꿀 때마다 반응형으로 갱신돼요.

채팅 메시지와 결합

투두 리스트는 일반 채팅 UI와 함께 동작해요. 지속적인 사이드바/헤더 패널로 보여주고, 그 아래 채팅 메시지를 배치하는 레이아웃을 권해요. todos.length > 0일 때만 투두 리스트를 보여주면, 에이전트가 계획을 만들기 전에 빈 컴포넌트로 공간을 낭비하지 않아요.

유스 케이스

  • 프로젝트 계획: 프로젝트를 작업으로 쪼개 순차 처리
  • 리서치 워크플로: 각 리서치 질문이 todo가 되어 조사·완료
  • 데이터 처리: ingestion, validation, transformation, export 단계별로 todo
  • 온보딩 플로우: 설정 단계를 진행하며 체크
  • 보고서 생성: 데이터 수집, 추세 분석, 요약 작성, 출력 포맷을 todo로

빈 상태·로딩 상태 처리

에이전트가 계획을 만들기 전 초기 상태를 처리해요. todos.length === 0 && !isLoading이면 null을, todos.length === 0 && isLoading이면 "Agent is creating a plan..." 스피너를 보여줘요.

모범 사례

  • 투두 리스트를 눈에 띄게 배치하세요. 계획 기반 에이전트의 핵심 진행 지표예요.
  • 상태 전환에 애니메이션을 넣어 반응성을 높이세요.
  • in_progress 항목은 하나만 강조하세요.
  • 완료 항목은 접거나 흐릿하게 처리하세요.
  • "67% complete" 같은 진행률 숫자를 보여주세요.
  • stream.values가 반응형으로 갱신되므로 수동 폴링/리프레시는 추가하지 마세요.

더 알아보기 (Learn more)