Deep Agents 프론트엔드 개요

Deep Agents 프론트엔드 개요 (Frontend Overview)

Deep Agents로 만든 에이전트의 작업 흐름을 실시간으로 시각화하는 프론트엔드를 만들고 싶다면 이 문서부터 시작하면 돼요. 서브에이전트 진행 상황, 작업 계획, 스트리밍 콘텐츠, 그리고 IDE 같은 샌드박스 경험을 어떻게 렌더링하는지 패턴 단위로 정리해 둔 가이드예요. createDeepAgent로 만든 에이전트에서 이런 프론트엔드를 어떻게 구성하는지 설명해요.

출처: 공식문서

왜 UI에서 위임(delegation)을 보여줘야 하나요

Deep Agents는 단일한 불투명한 어시스턴트 버블 하나를 보여주는 대신, 코디네이터(coordinator), 서브에이전트 발견(discovery), 커스텀 상태, 그리고 샌드박스 기반 아티팩트를 SDK로 노출해요. 덕분에 사용자가 오래 걸리는 작업이 어떻게 쪼개지고 완료되는지 직접 들여다볼 수 있지요. 이 패턴들은 v1 프론트엔드 SDK 패키지를 기준으로 해요. 더 이른 버전을 쓰고 있다면 React, Vue, Svelte, Angular용 마이그레이션 가이드를 참고하면 돼요.

아키텍처

Deep Agents는 coordinator-worker 구조를 사용해요. 메인 에이전트가 작업을 계획하고 각각 격리된 환경에서 도는 전문화된 서브에이전트에게 위임하지요. 프론트엔드에서는 v1 stream 핸들이 루트 스트림에 코디네이터 메시지를 노출하고, 특정 서브에이전트 뷰를 위한 서브에이전트 발견 스냅샷(discovery snapshots)도 제공해요.

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
    subagents=[
        {
            "name": "researcher",
            "description": "Research assistant",
            "system_prompt": "You are a research assistant.",
        }
    ],
)

프론트엔드에서 연결할 때는 createAgent와 똑같이 useStream을 쓰면 돼요. 타입 세이프한 스트림 상태를 위해 타입 파라미터를 넘기고요. Deep agent 패턴은 stream.subagents, useMessages(stream, subagent) 같은 셀렉터 헬퍼, 그리고 stream.values.todos 같은 커스텀 상태 값을 활용해 서브에이전트 전용 UI를 렌더링해요.

import { useStream } from "@langchain/react";

function App() {
  const stream = useStream<typeof agent>({
    apiUrl: "http://localhost:2024",
    assistantId: "agent",
  });

  // Deep agent state beyond messages
  const todos = stream.values?.todos;
  const subagents = [...stream.subagents.values()];
}

SDK가 노출하는 것들

딥 에이전트 UI는 보통 최종 답변 이상이 필요해요. 프론트엔드 SDK는 사용자가 신경 쓰는 실행 단계의 구조화된 투영(structured projections)을 제공하지요.

stream.messages — 코디네이터 대화와 최종 종합(synthesis)
stream.subagents — 전문 작업자들의 실시간 발견(상태·작업 메타데이터 포함)
stream.values — todos, 계획, 보고서 섹션, 샌드박스 메타데이터 등 에이전트가 기록하는 공유 상태
Tool-call 상태 — 파일시스템·검색·브라우저·도메인 도구를 진행률·결과가 담긴 카드로 렌더링
Interrupts — 실행 상태를 잃지 않고 사용자 승인이나 누락 입력을 위해 위임 작업을 일시 중지

이 구조 덕분에 단순한 채팅 대화록이 아니라 IDE, 태스크 보드, 워크플로 모니터에 가까운 인터페이스를 만들 수 있어요.

패턴 (Patterns)

Subagent streaming — 스트리밍 콘텐츠·진행 추적·접을 수 있는 카드로 전문화 서브에이전트를 표시
Todo list — 에이전트가 작업 계획(task planning)을 켰을 때 실시간 todo 리스트로 진행 상황 추적
Sandbox — 샌드박스가 뒷받침하는 파일 브라우저·코드 뷰어·diff 패널로 IDE 같은 UI 구성

마크다운 메시지, 툴 호출, human-in-the-loop 같은 LangChain 프론트엔드 패턴은 딥 에이전트에서도 그대로 동작해요. Deep Agents가 같은 LangGraph 런타임 위에 있기 때문에 useStream이 동일한 핵심 API를 제공하기 때문이에요. 더 저수준의 그래프 시각화가 필요하면 LangGraph 프론트엔드 패턴에서 그래프 노드와 상태 키를 UI 컴포넌트에 직접 매핑하는 법을 볼 수 있어요.

더 알아보기 (Learn more)

React·Vue·Svelte·Angular용 v1 마이그레이션 가이드
Deep Agents 개요와 커스터마이제이션 가이드

Deep Agents 프론트엔드 개요