123 lines
4.1 KiB
Markdown
123 lines
4.1 KiB
Markdown
# PROJECT KNOWLEDGE BASE
|
|
|
|
**Generated:** 2026-01-13
|
|
|
|
---
|
|
|
|
## OVERVIEW
|
|
|
|
Multi-agent research system demonstrating **FileSystem-based Context Engineering** using LangChain's DeepAgents framework. Includes Python orchestrator, Rust port via Rig framework, and Next.js chat UI.
|
|
|
|
---
|
|
|
|
## STRUCTURE
|
|
|
|
```
|
|
/
|
|
research_agent/ # Python DeepAgent orchestrator (see AGENTS.md)
|
|
context_engineering_research_agent/ # Extended agent with 5 strategies
|
|
deep-agents-ui/ # Next.js React frontend (see AGENTS.md)
|
|
rust-research-agent/ # Rust implementation (see AGENTS.md)
|
|
rig-deepagents/ # Pregel-based middleware runtime
|
|
rig-rlm/ # Recursive Language Model agent
|
|
tests/ # pytest test suite (see AGENTS.md)
|
|
skills/ # Project-level skills (SKILL.md per skill)
|
|
research_workspace/ # Agent output directory (ephemeral)
|
|
deepagents_sourcecode/ # Vendor: upstream library reference
|
|
```
|
|
|
|
---
|
|
|
|
## WHERE TO LOOK
|
|
|
|
| Task | Location | Notes |
|
|
|------|----------|-------|
|
|
| Modify orchestrator | `research_agent/agent.py` | SubAgent assembly, tools, middleware |
|
|
| Add research tool | `research_agent/tools.py` | `tavily_search`, `think_tool` |
|
|
| Autonomous researcher logic | `research_agent/researcher/` | Three-phase workflow |
|
|
| Context strategies | `context_engineering_research_agent/context_strategies/` | 5 patterns |
|
|
| Frontend components | `deep-agents-ui/src/app/components/` | Chat UI |
|
|
| Rust Pregel runtime | `rust-research-agent/rig-deepagents/src/pregel/` | Graph execution |
|
|
| Rust middleware | `rust-research-agent/rig-deepagents/src/middleware/` | Tool injection |
|
|
| Add new skill | `skills/{skill-name}/SKILL.md` | YAML frontmatter + instructions |
|
|
|
|
---
|
|
|
|
## CONVENTIONS
|
|
|
|
### Deviations from Standard Patterns
|
|
|
|
- **Backend factory pattern**: Always use `backend_factory(rt: ToolRuntime)` - middleware depends on this signature
|
|
- **SubAgent naming**: Use `researcher`, `explorer`, `synthesizer` - hardcoded in prompts
|
|
- **File paths**: Paths starting with "/" route to `research_workspace/`; others are in-memory
|
|
- **Korean comments**: Docstrings and some comments in Korean (bilingual codebase)
|
|
|
|
---
|
|
|
|
## ANTI-PATTERNS
|
|
|
|
- **DO NOT** commit `.env` files (contains API keys)
|
|
- **DO NOT** instantiate researcher directly - use `get_researcher_subagent()`
|
|
- **DO NOT** skip `think_tool()` between searches - explicit reflection required
|
|
- **NEVER** write raw JSON to user - always format responses (see `deepagents_cli/tools.py`)
|
|
- **NEVER** lie to exit early - complete TODO items fully (see `researcher/runner.py`)
|
|
|
|
---
|
|
|
|
## COMMANDS
|
|
|
|
### Python Development
|
|
|
|
```bash
|
|
uv sync # Install dependencies
|
|
langgraph dev # Start backend (port 2024)
|
|
uv run ruff format . # Format code
|
|
uv run ruff check . # Lint
|
|
uv run mypy . # Type check
|
|
uv run pytest tests/ # Run tests
|
|
```
|
|
|
|
### Frontend Development
|
|
|
|
```bash
|
|
cd deep-agents-ui
|
|
yarn install && yarn dev # Dev server (port 3000)
|
|
yarn build # Production build
|
|
yarn lint && yarn format # Lint + format
|
|
```
|
|
|
|
### Rust Development
|
|
|
|
```bash
|
|
cd rust-research-agent/rig-deepagents
|
|
cargo test # Run tests (159)
|
|
cargo clippy -- -D warnings # Lint (strict)
|
|
cargo build --features checkpointer-sqlite # Build with features
|
|
```
|
|
|
|
---
|
|
|
|
## ENVIRONMENT VARIABLES
|
|
|
|
Copy `env.example` to `.env`:
|
|
|
|
| Variable | Required | Purpose |
|
|
|----------|----------|---------|
|
|
| `OPENAI_API_KEY` | Yes | gpt-4.1 model |
|
|
| `TAVILY_API_KEY` | Yes | Web search |
|
|
| `LANGSMITH_API_KEY` | No | Tracing (`lsv2_pt_...`) |
|
|
| `ANTHROPIC_API_KEY` | No | Claude models + caching |
|
|
|
|
---
|
|
|
|
## SUBDIRECTORY KNOWLEDGE
|
|
|
|
See AGENTS.md files in:
|
|
- `research_agent/AGENTS.md` - Orchestrator details
|
|
- `context_engineering_research_agent/AGENTS.md` - Context strategies
|
|
- `deep-agents-ui/AGENTS.md` - Frontend architecture
|
|
- `tests/AGENTS.md` - Test organization
|
|
- `rust-research-agent/AGENTS.md` - Rust overview (3 tiers)
|
|
- `rust-research-agent/rig-deepagents/AGENTS.md` - Middleware architecture
|
|
- `rust-research-agent/rig-rlm/AGENTS.md` - Recursive LLM pattern
|