Privagent

# Tool List **Private AI Agent — Your data never leaves your machine.** Vue 3 + FastAPI + LangGraph + PostgreSQL/pgvector Privacy-focused local AI Agent. Autonomous decision-making tool calls (knowledge base retrieval, internet search, in-depth research, etc.), with long-term memory, SSE streaming output, and MCP external tool access. All data stored locally, API key stored only on the backend. [](.) [](.) [](.) [](.) ## Why This Project - **Complete Agent Loop** — Not just a simple Chatbot. LangGraph 6-node state graph drives autonomous decision-making: Recall → Plan → Act → Observe → Decide → Summarize. Agent decides "whether to use tools, which tool to use, and when to stop". - **6 Built-in Tools** — Knowledge base retrieval (including semantic search and section indexing strategy), internet search, web scraping, in-depth research (multi-round search + comprehensive report), mathematical calculation, and configuration diagnosis - **MCP Protocol Support** — Access to external MCP Server (stdio/SSE), automatic discovery and registration of tools, Agent ready to use - **API Key Security** — Frontend does not touch any model API key. All sensitive configurations injected through environment variables, Provider Profile isolated storage - **369 Unit Tests Passed** — Covering Agent full chain, tool registration, SSE events, RAG pipeline - **One-click Deployment with Docker** — `docker compose up -d` to start the complete 5-container stack ## Quick Start ### Prerequisites - Docker & Docker Compose - DeepSeek API Key (or other OpenAI compatible API) ### 1. Configure Environment Variables ```bash cp backend/.env.example backend/.env ``` Edit `backend/.env`, fill in necessary API keys: ```bash # Required — model conversation DEEPSEEK_API_KEY=sk-xxxxxxxxxxxx # Recommended — semantic retrieval (degrades to keyword matching if not filled) EMBEDDING_API_KEY=sk-xxxxxxxxxxxx EMBEDDING_PROVIDER=openai_compatible EMBEDDING_MODEL=BAAI/bge-m3 EMBEDDING_BASE_URL=https://api.siliconflow.cn/v1 ``` > **Security Tip**: API key stored only on the backend, not sent to the frontend. `.env` file should not be submitted to version control. ### 2. Start ```bash docker compose up -d ``` ### 3. Access | Service | URL | |------|-----| | Frontend | http://127.0.0.1:3000 | | API | http://127.0.0.1:8000 | | Swagger | http://127.0.0.1:8000/docs | | Health | http://127.0.0.1:8000/health | ### 4. Configure Provider Open Settings → Quick Configuration → Select preset (recommended for mainland users to select `DeepSeek + BGE-M3`) → Fill in API Key → Activate ## Architecture ``` ┌─ Frontend (Vue 3) ──────────────────────────────────────────┐ │ QuestionView (Agent Q&A) SettingsView (Configuration) │ │ ├─ useAgentChat (SSE Stream) ├─ Provider Profile │ │ ├─ Tool Cards / Source Labeling ├─ MCP Service Management │ │ └─ Tool History / Conversation Export └─ Memory Management / Configuration Wizard │ └──────────────────────────────┬──────────────────────────────┘ │ SSE / REST ┌──────────────────────────────┴──────────────────────────────┐ │ Backend (FastAPI) │ │ ┌─ Agent Routes ─────────────────────────────────────────┐ │ │ │ /api/v1/agent/chat/stream (SSE Streaming Agent) │ │ │ │ /api/v1/agent/chat/resume (Human Approval Recovery) │ │ │ └────────────────────────────────────────────────────────┘ │ │ ┌─ Agent Service (LangGraph) ────────────────────────────┐ │ │ │ START → recall → plan → act → observe → decide → END │ │ │ │ ↑ ↓ │ │ │ │ summarize ←──────────────────────── │ │ │ └────────────────────────────────────────────────────────┘ │ │ ┌─ ToolRegistry (6 tools) ───────────────────────────────┐ │ │ │ kb_search | web_search | web_fetch | deep_research │ │ │ │ calculator | config_status │ │ │ └────────────────────────────────────────────────────────┘ │ │ ┌─ MCPService ───────────────────────────────────────────┐ │ │ │ Stdio/SSE Transmission → Tool Discovery → ToolSpec Registration → Callable │ │ │ └────────────────────────────────────────────────────────┘ │ └──────────────────────────────┬──────────────────────────────┘ │ ┌──────────────────────────────┴──────────────────────────────┐ │ Storage: PostgreSQL/pgvector | Redis | Local File System │ └─────────────────────────────────────────────────────────────┘ ``` ## Agent Decision-making Process ``` User Query │ ▼ [Recall] ← Load Session History + Preference Memory │ ▼ [Plan] ← LLM Judgment: Direct Answer? Use Tool? │ ├─ Direct Answer → [Summarize] → Return Answer │ └─ Use Tool → [Act] ← Execute Tool (Human Approval if risk≥local_write) │ ▼ [Observe] ← Record Result │ ▼ [Decide] ← Continue? Stop? Synthesize Answer? │ ├─ continue → Back to [Plan] └─ stop → [Summarize] → Return Answer (with Source Labeling) ``` ## Built-in Tools | Tool | Risk Level | Description | |------|---------|------| | `kb_search` | read_only | pgvector semantic search + optional DeepSeek Rerank | | `web_search` | network | Bing meta search (ddgs), can be disabled | | `web_fetch` | network | Web content scraping, SSRF protection | | `deep_research` | network | Multi-round search → disassembly → scraping → comprehensive report | | `calculator` | read_only | Safe mathematical expression calculation | | `config_status` | read_only | Query Provider/Embedding/Rerank configuration status | Risk level `≥ local_write` tools require human confirmation (LangGraph interrupt). ## Supported Document Formats | Format | Parsing Library | Description | |------|--------|------| | `.md` / `.markdown` | Built-in | Markdown structure preserved | | `.txt` | Built-in | Plain text cleaning | | `.pdf` | pypdf | PDF text extraction | | `.docx` | python-docx | Word paragraph + table extraction | ## Configuration Instructions All sensitive configurations injected through **environment variables**, not hardcoded in code or configuration files. ### Environment Variables Reference (backend/.env) | Variable | Required | Description | |------|------|------| | `DEEPSEEK_API_KEY` | Recommended | DeepSeek model API key | | `DEEPSEEK_BASE_URL` | No | Model API address (default: https://api.deepseek.com) | | `DEEPSEEK_MODEL` | No | Model name (default: deepseek-v4-flash) | | `EMBEDDING_API_KEY` | Recommended | Embedding service API key | | `EMBEDDING_PROVIDER` | No | `hashing` or `openai_compatible` | | `EMBEDDING_MODEL` | No | Embedding model name | | `EMBEDDING_BASE_URL` | No | Embedding API address | | `RETRIEVAL_RERANK_PROVIDER` | No | `none` or `deepseek` | | `APP_VERSION` | No | Application version number (default: 1.0.0) | | `APP_ENV` | No | `dev` or `prod` | Complete reference see [`backend/.env.example`](backend/.env.example). ### Provider Profile (Recommended) Configure through Settings page, support one-click switching: | Preset | Model | Embedding | Suitable Scenario | |------|------|-----------|---------| | DeepSeek + Hashing | deepseek-chat | Local hashing | Quick experience, no embedding key required | | DeepSeek + Jina | deepseek-chat | Jina v5 | Overseas network, free quota | | **DeepSeek + BGE-M3** | deepseek-chat | SiliconFlow BGE-M3 | **Recommended for mainland users**, stable domestic | ## Deployment Precautions ### Security Principles 1. **API key stored only on the backend**. `.env` or Provider Profile keys not sent to the frontend. 2. **Do not expose ports to the public network**. This application has no authentication mechanism. If remote access is required, add Nginx + HTTPS + Basic Auth. 3. **Modify default password**. `docker-compose.yml` PostgreSQL password should be modified. 4. **Do not submit `.env`**. Added to `.gitignore`, prohibit submission of real API key. ### Search Engine - Default use **Bing** (through ddgs meta search library), no API Key required - DuckDuckGo not available in mainland China network, Bing available - Switch engine: modify `WEB_SEARCH_ENGINE` environment variable ### Resource Requirements | Component | Minimum Configuration | |------|---------| | CPU | 2 cores | | RAM | 4 GB (including PostgreSQL + Redis) | | Disk | 2 GB (excluding knowledge base documents) | ## MCP Configuration (Model Context Protocol) Access external MCP Server, automatically discover tools and register to Agent. ### SSE Transmission Settings → MCP Service → New → Fill in URL → Connect ### Stdio Transmission ```json { "name": "local-filesystem", "transport": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"], "enabled": true, "auto_connect": true } ``` ## Development ### Local Running ```bash # Backend cd backend python -m venv .venv pip install -r requirements.txt cp .env.example .env # Edit and fill in API key python -m pytest tests/ # Frontend cd frontend npm install npm run dev ``` ### Code Quality ```bash ruff check app/ tests/ # Lint ruff format app/ tests/ # Format pytest tests/ -q # 350+ tests, release gate npm run build # Frontend build ``` ### Verification Commands ```bash # Agent eval benchmark python scripts/agent_eval.py --save-baseline # Smoke verification python scripts/smoke_preflight.py python scripts/smoke_full_rag.py ``` Current v1.0.0 release candidate verification result: `pytest` 369/369, `ruff`, `npm run build`, `smoke_preflight.py`, `smoke_full_rag.py` all passed; Agent eval baseline 30/33 (91%), RAG quality 7/9. Release steps see [`Release Checklist`](docs/release-checklist.md). ## Technical Decisions 1. **LangGraph instead of LangChain Agent** — Explicit state graph fully controllable 2. **Local application without authentication** — No JWT/multi-user complexity introduced 3. **Provider Profile isolation** — API key stored only on the backend 4. **MCP as tool extension boundary** — Agent tools can be infinitely extended 5. **Environment variable configuration priority** — Sensitive values not into code, not into version control ## License MIT