deer-flow/frontend/AGENTS.md

Agents Architecture

Overview

DeerFlow is built on a sophisticated agent-based architecture using the LangGraph SDK to enable intelligent, stateful AI interactions. This document outlines the agent system architecture, patterns, and best practices for working with agents in the frontend application.

Architecture Overview

Core Components

┌────────────────────────────────────────────────────────┐
│                    Frontend (Next.js)                  │
├────────────────────────────────────────────────────────┤
│  ┌──────────────┐    ┌──────────────┐    ┌──────────┐  │
│  │ UI Components│───▶│ Thread Hooks │───▶│ LangGraph│  │
│  │              │    │              │    │   SDK    │  │
│  └──────────────┘    └──────────────┘    └──────────┘  │
│         │                    │                  │      │
│         │                    ▼                  │      │
│         │            ┌──────────────┐           │      │
│         └───────────▶│ Thread State │◀──────────┘      │
│                      │  Management  │                  │
│                      └──────────────┘                  │
└────────────────────────────────────────────────────────┘
                              │
                              ▼
┌────────────────────────────────────────────────────────┐
│              LangGraph Backend (lead_agent)            │
│  ┌────────────┐  ┌──────────┐  ┌───────────────────┐   │
│  │Main Agent  │─▶│Sub-Agents│─▶│  Tools & Skills   │   │
│  └────────────┘  └──────────┘  └───────────────────┘   │
└────────────────────────────────────────────────────────┘

Project Structure

tests/
├── e2e/                    # E2E tests (Playwright, Chromium, mocked backend)
└── unit/                   # Unit tests (mirrors src/ layout, powered by Vitest)
src/
├── app/                    # Next.js App Router pages
│   ├── api/                # API routes
│   ├── workspace/          # Main workspace pages
│   └── mock/               # Mock/demo pages
├── components/             # React components
│   ├── ui/                 # Reusable UI components
│   ├── workspace/          # Workspace-specific components
│   ├── landing/            # Landing page components
│   └── ai-elements/        # AI-related UI elements
├── core/                   # Core business logic
│   ├── api/                # API client & data fetching
│   ├── artifacts/          # Artifact management
│   ├── config/              # App configuration
│   ├── i18n/               # Internationalization
│   ├── mcp/                # MCP integration
│   ├── messages/           # Message handling
│   ├── models/             # Data models & types
│   ├── settings/           # User settings
│   ├── skills/             # Skills system
│   ├── threads/            # Thread management
│   ├── todos/              # Todo system
│   └── utils/              # Utility functions
├── hooks/                  # Custom React hooks
├── lib/                    # Shared libraries & utilities
├── server/                 # Server-side code (Not available yet)
│   └── better-auth/        # Authentication setup (Not available yet)
└── styles/                 # Global styles

Technology Stack

• LangGraph SDK (@langchain/langgraph-sdk@1.5.3) - Agent orchestration and streaming
• LangChain Core (@langchain/core@1.1.15) - Fundamental AI building blocks
• TanStack Query (@tanstack/react-query@5.90.17) - Server state management
• React Hooks - Thread lifecycle and state management
• Shadcn UI - UI components
• MagicUI - Magic UI components
• React Bits - React bits components

Interaction Ownership

• src/app/workspace/chats/[thread_id]/page.tsx owns composer busy-state wiring.
• src/core/threads/hooks.ts owns pre-submit upload state and thread submission.
• src/hooks/usePoseStream.ts is a passive store selector; global WebSocket lifecycle stays in App.tsx.

Resources

• LangGraph Documentation
• LangChain Core Concepts
• TanStack Query Documentation
• Next.js App Router

Contributing

When adding new agent features:

1. Follow the established project structure
2. Add comprehensive TypeScript types
3. Implement proper error handling
4. Write unit tests under tests/unit/ (run with pnpm test) and E2E tests under tests/e2e/ (run with pnpm test:e2e)
5. Update this documentation
6. Follow the code style guide (ESLint + Prettier)

License

This agent architecture is part of the DeerFlow project.