Skip to content
BranchesTags

Repository files navigation

Chat Gun

chat-gun

License LangGraph OpenTelemetry MCP Qwen Tavily Brave Search Opik Origins

English | 繁體中文 | 简体中文

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

Chat Gun demo

Chat home screen

Agent response and activity

Tool-assisted agent result

架構

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://localhost:2024/ok

再檢查 BFF_LANGGRAPH_API_URL 是否指向正在執行的 LangGraph API。

Research synthesis failed ... fetch failed

確認模型或 Tool provider 的 API key、base URL 與網路連線。使用 Qwen／Alibaba Cloud Bailian 時，可以先測試：

Test-NetConnection dashscope.aliyuncs.com -Port 443

需要 proxy 時，在 backend/.env 設定 HTTPS_PROXY、HTTP_PROXY 與 NO_PROXY，然後重新啟動 Backend。

文件

License

Apache License 2.0。詳見 LICENSE。

About

🤖 A full-stack Agent Chat Runtime for pre-production validation, built with act, TypeScript, and LangGraph JS combining streaming, multimodal, HITL, and tools with durable Task/Step execution, retry budgets, idempotency, compensation, distributed locks, context governance, OpenTelemetry tracing, model fallback, cost tracking, and Opik evaluation.

Topics

agentai-agentchatbotlanggraphmcpmulti-agentqwen

Resources

Readme
License
Activity

Stars

135 stars

Watchers

14 watching

Forks

18 forks
Report repository

Releases

Packages

Contributors

Languages