Chat Gun
Chat Gun 是一套以 React、TypeScript 與 LangGraph JS 建構的全端 Agent Chat 應用。它支援多 Agent 對話、串流回覆、Tool Calling、圖片輸入與 Human-in-the-Loop，並透過 BFF 統一處理瀏覽器與 LangGraph Runtime 之間的 API 流量。
核心功能
- Agent-workflows：
- Deep Researcher 負責多步驟研究與引用驗證。
- Chat Assistant 處理一般對話。
- Math Solver 執行算式與數值運算。
- MCP Agent 則透過 Tool Calling 使用 native 與 MCP tools。
- Streaming：即時串流回答與執行活動，並支援 Cancellation 與 Exception handling，讓使用者能中止進行中的請求並看見明確的錯誤狀態。
- HITL：天氣地點不明確時，Agent 會列出候選地點向使用者確認，再接續原本的 thread 執行。
- Multimodal input：接受 PNG、JPEG 與 WebP 圖片，透過 vision model 分析內容並納入回答或研究流程。
- Native Tools：內建計算、由 Tavily Search API 提供的網路搜尋、網頁擷取、目前天氣與天氣預報工具，Agent 可依問題選擇合適工具。
- MCP integration：可選擇載入 Filesystem 與 Brave Search MCP Server；Brave Search 以選配 MCP Tool 的形式擴充搜尋能力。
- Model providers：支援 Qwen、OpenAI-compatible 與 CCR-compatible endpoints，統一由 LLM Gateway 處理模型能力與呼叫介面。
- API Gateway：BFF 集中處理 API key authentication、將已驗證 API key 映射為 Trusted Principal context、CORS、request size validation、Timeout、Cancellation propagation 與 Rate limiting；啟用驗證時，client 提供的 identity／tenant headers 不會被當成可信身分來源。
- Observability & Evaluation：提供 Metrics 與 OpenTelemetry，並可啟用 Opik tracing、versioned datasets 與 experiments 來追蹤及評估 Agent 行為。
📌 預設僅適用於本地開發。公開部署前，請啟用 Authentication、設定明確的 CORS allowlist、妥善管理 Secrets 與資料庫憑證，並依部署架構配置共享 Rate limiting、TLS 與 Reverse Proxy。若需要跨重啟或多實例恢復 Agent 執行，請改用 durable checkpointer。
Demo
架構
Browser
-> frontend: Vite + React 19 + TypeScript
-> bff: Node + TypeScript
-> backend: LangGraph JS + TypeScript
-> Model Provider / Native Tools / MCP Tools
| 目錄 | 用途 | 本地預設 port |
|---|---|---|
frontend/ |
Chat UI、串流狀態、工具結果與圖片輸入 | 5173 |
bff/ |
API gateway、驗證、代理、逾時與限流 | 8787 |
backend/ |
LangGraph agents、模型整合、Tools 與 MCP | 2024 |
本地開發時，Frontend 會把 /api/* 代理至 BFF；LangGraph 請求經由 /api/langgraph/* 轉送到 Backend。模型、Tool 與 MCP credential 只保留在 Server 端。
http://localhost:5173/app/
-> http://127.0.0.1:8787/api/langgraph/*
-> http://localhost:2024
Agents
| Graph ID | 名稱 | 用途 |
|---|---|---|
deep_researcher |
Deep Researcher | 深度研究、來源整理、工具調用、天氣查詢與圖片理解 |
chatbot |
Chat Assistant | 一般對話 |
math_agent |
Math Solver | 數學問題與運算 |
mcp_agent |
MCP Agent | 使用已啟用的 native／MCP tools |
Frontend 提供 qwen-plus、qwen-max 與 qwen-turbo，預設選用 qwen-plus。Backend 可針對不同 Agent 指定模型。
系統需求
- Node >= 22
- npm >= 10.8.x
- Qwen API key，或可用的 OpenAI-compatible／CCR-compatible endpoint
- Tavily Search API key（使用內建
web_search時需要） - Brave Search API key（啟用 Brave Search MCP Server 時需要，選用）
- Docker 與 Docker Compose（選用）
安裝
git clone https://github.com/HsienW/chat-gun.git
cd chat-gun
cd backend && npm ci
cd ../bff && npm ci
cd ../frontend && npm ci
cd ..
PowerShell：
git clone https://github.com/HsienW/chat-gun.git
Set-Location chat-gun
Set-Location backend
npm ci
Set-Location ..\bff
npm ci
Set-Location ..\frontend
npm ci
Set-Location ..
設定
Backend
從範例建立本地設定：
cp backend/.env.example backend/.env
PowerShell：
Copy-Item backend/.env.example backend/.env
使用 Qwen 時，至少填入：
LLM_PROVIDER=qwen
QWEN_API_KEY=your_qwen_api_key
Deep Researcher 的內建 web_search 使用 Tavily Search API：
TAVILY_API_KEY=your_tavily_api_key
也可以連接其他模型端點：
# OpenAI-compatible
LLM_PROVIDER=openai-compatible
OPENAI_COMPATIBLE_BASE_URL=https://your-endpoint.example/v1
OPENAI_COMPATIBLE_API_KEY=your_api_key
OPENAI_COMPATIBLE_MODEL=your_model
# CCR-compatible
LLM_PROVIDER=ccr
CCR_BASE_URL=http://127.0.0.1:3456/v1
CCR_API_KEY=your_api_key
CCR_MODEL=your_model
其他模型、圖片、天氣、Tool 與 MCP 設定請參閱 backend/.env.example。不要將 API key 或其他 credential 提交到版本控制。
BFF
cp bff/.env.example bff/.env
PowerShell：
Copy-Item bff/.env.example bff/.env
| 環境變數 | 用途 |
|---|---|
BFF_LANGGRAPH_API_URL |
LangGraph API URL |
BFF_ALLOWED_ORIGINS |
允許存取 BFF 的瀏覽器 origins |
BFF_REQUIRE_AUTH |
是否要求 API key 或 Bearer token；啟用時還需要對應的 Trusted Principal profile |
BFF_API_KEYS |
通常留空；若設定，每個 key 仍需有對應的 Principal profile |
BFF_API_KEY_PRINCIPALS_JSON |
以 API key 為索引的 Principal profile JSON，包含 principalId、principalType、tenantId、roles 與 scopes |
BFF_LEGACY_HEADER_MODE |
是否繼續向 Backend 傳送相容用的 x-bff-user-id；預設為 true |
BFF_MAX_BODY_BYTES |
Request body 上限 |
BFF_UPSTREAM_TIMEOUT_MS |
Upstream request timeout |
BFF_RATE_LIMIT_REDIS_URI |
Redis rate limiter；留空時使用 in-memory limiter |
其他 BFF 選項請參閱 bff/.env.example。
啟用 BFF authentication 時，每個 API key 都必須具有 Trusted Principal profile；只設定 BFF_API_KEYS 會因缺少可信身分資料而回傳 401。BFF 會忽略 client 傳入的 x-user-id／x-tenant-id，並依 profile 產生及轉送 x-bff-* headers 至 Backend。Resource-level authorization 由需要保護的 Tool 或 workflow 顯式啟用。
BFF_REQUIRE_AUTH=true
BFF_API_KEY_PRINCIPALS_JSON={"replace-with-a-long-random-key":{"principalId":"local-user","principalType":"user","tenantId":"local","roles":[],"scopes":[]}}
BFF_API_KEY_PRINCIPALS_JSON 的 JSON key 本身就是 credential，請只透過環境變數或 secret manager 提供，不要提交到版本控制。
Frontend
本地開發不需要建立 frontend/.env。Frontend 預設使用同源 /api/langgraph；分開部署時可指定 BFF URL：
VITE_LANGGRAPH_API_URL=https://api.example.com/api/langgraph
圖片輸入限制請參閱 frontend/.env.example。VITE_* 會出現在瀏覽器 bundle，不能用來保存 secret。
本地開發
分別啟動 Backend、BFF 與 Frontend。
# Terminal 1
cd backend
npm run dev
# Terminal 2
cd bff
npm run dev
# Terminal 3
cd frontend
npm run dev
開啟 http://localhost:5173/app/。
可使用 BFF 的健康檢查確認服務狀態：
curl http://127.0.0.1:8787/api/health
curl http://127.0.0.1:8787/api/ready
PowerShell：
Invoke-RestMethod http://127.0.0.1:8787/api/health
Invoke-RestMethod http://127.0.0.1:8787/api/ready
/api/ready 會檢查 BFF 是否能連上 LangGraph Backend。
Tools
| Tool | 用途 | 必要設定 |
|---|---|---|
calculator_tool |
算術運算 | 無 |
web_search |
Tavily Search API | TAVILY_API_KEY |
web_fetch |
HTTP／HTTPS 網頁擷取 | 無 |
current_weather |
Open-Meteo 目前天氣 | 無 |
weather_forecast |
Open-Meteo 天氣預報 | 無 |
可以使用 TOOL_ALLOWLIST、TOOL_DENYLIST、TOOL_TIMEOUT_MS 與個別 Tool 設定限制可用範圍。web_fetch 預設只允許 port 80、443，並拒絕不安全的 private network address。
MCP
MCP tools 預設不會在啟動時載入。啟用 Filesystem MCP：
MCP_LOAD_ON_START=true
MCP_FILESYSTEM_ENABLED=true
MCP_FILESYSTEM_PATH=/absolute/path/to/workspace
MCP_FILESYSTEM_ALLOWED_ROOTS=/absolute/path/to/workspace
讓 Deep Researcher 使用 MCP tools：
DEEP_RESEARCHER_MCP_ENABLED=true
啟用選配的 Brave Search MCP Server：
MCP_BRAVE_SEARCH_ENABLED=true
BRAVE_API_KEY=your_brave_api_key
MCP_FILESYSTEM_PATH 必須位於 MCP_FILESYSTEM_ALLOWED_ROOTS 內。多個 root 在 Windows 使用 ; 分隔，在 Linux／macOS 使用 :。
Observability
BFF 提供 metrics endpoint：
curl http://127.0.0.1:8787/api/metrics
OpenTelemetry 預設關閉。連接 OTLP collector：
OTEL_ENABLED=true
OTEL_SERVICE_NAME=chat-gun
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_EXPORTER_OTLP_PROTOCOL=http
OTEL_SAMPLE_RATE=1
Opik 可用於開發期間的 Agent tracing 與 Weather evaluation。它預設關閉；啟用 hosted tracing 時應使用非正式環境資料，並保持 redaction 開啟。
OPIK_ENABLED=true
OPIK_API_KEY=your_opik_api_key
OPIK_WORKSPACE=your_workspace
OPIK_REDACT_ENABLED=true
執行 evaluation：
cd backend
npm run eval:opik
Docker Compose
Docker Compose 會啟動 PostgreSQL、Redis、LangGraph API 與 BFF，並由 BFF 提供建置後的 Frontend。
在專案根目錄建立 .env：
QWEN_API_KEY=your_qwen_api_key
TAVILY_API_KEY=your_tavily_api_key
啟動服務：
docker compose up --build
開啟 http://localhost:8123/app/。
Compose 預設使用 Qwen。改用其他 provider 或啟用額外 Backend 功能時，請把對應環境變數加入 docker-compose.yml 的 langgraph-api.environment。
測試
Backend：
cd backend
npm run lint
npm run test
npm run build
BFF：
cd bff
npm run test
npm run build
Frontend：
cd frontend
npm run lint
npm run test
npm run build
疑難排解
Frontend 出現 Invalid URL
VITE_LANGGRAPH_API_URL 必須是完整 URL。若 Frontend 與 BFF 使用同一個 origin，移除這個設定即可。
VITE_LANGGRAPH_API_URL=http://localhost:5173/api/langgraph
/api/langgraph/* 回傳 502
先確認 BFF 與 Backend 狀態：
Invoke-RestMethod http://127.0.0.1:8787/api/ready
Invoke-RestMethod http://lo