docs: add AGENTS.md

2026-04-03 14:22:13 +08:00 · 2026-02-06 14:32:48 +08:00
parent bbb1a731a5
commit 30cd2387f2
1 changed files with 100 additions and 0 deletions
--- a/frontend/AGENTS.md
+++ b/frontend/AGENTS.md
@@ -0,0 +1,100 @@
+# Agents Architecture
+
+## Overview
+
+DeerFlow is built on a sophisticated agent-based architecture using the [LangGraph SDK](https://github.com/langchain-ai/langgraph) 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
+
+```
+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
+│   ├── citations/          # Citation handling
+│   ├── 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
+
+## Resources
+
+- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/)
+- [LangChain Core Concepts](https://js.langchain.com/docs/concepts)
+- [TanStack Query Documentation](https://tanstack.com/query/latest)
+- [Next.js App Router](https://nextjs.org/docs/app)
+
+## Contributing
+
+When adding new agent features:
+
+1. Follow the established project structure
+2. Add comprehensive TypeScript types
+3. Implement proper error handling
+4. Write tests for new functionality
+5. Update this documentation
+6. Follow the code style guide (ESLint + Prettier)
+
+## License
+
+This agent architecture is part of the DeerFlow project.