README.md

metadata

title: Agent Studio
emoji: 🤖
colorFrom: purple
colorTo: blue
sdk: static
sdk_version: '1'
app_file: dist/index.html
pinned: false

🤖 Agent Studio

一個基於 React 18 + Vite + Tailwind CSS 的 AI Agent 工作室，支援串流聊天、多步工具呼叫與多 Agent 切換。

✨ 功能

• 即時串流聊天 — 接駁任何 OpenAI 相容端點（OpenRouter / Groq / Cohere / 自訂），SSE 打字機效果
• 完整對話歷史 — 聊天頁每次送完整對話，不只最新一則
• 多步工具呼叫迴圈 — 自訂實作（非 LangGraph），最多 6 步，邊跑邊顯示每個 assistant / tool 訊息
• 工具管理 — 加入 / 移除工具（內建 search_web、calculate）
• 多 Agent 切換 — Researcher / Writer / Analyst，各自注入不同的 system prompt
• 主題切換 — 深色 / 亮色，走 CSS 變數，記憶至 localStorage
• 錯誤可見 — 401/400/429、逾時、網路錯誤都會顯示在對話裡，不會靜默失敗
• 對話匯出 — 匯出 Agent 頁的對話為 JSON
• 設定持久化 — API 設定存瀏覽器 localStorage，重新整理不丟失，可另存多組切換

🚀 使用方式

本地開發

npm install
npm run dev

建置

npm run build
npm run preview

部署至 Hugging Face Spaces

1. 於 HF Spaces 建立新 Space（Static 模式，免費）
2. 上傳整個專案（已含建置好的 dist/）
3. 提交後 HF 會從 dist/index.html 伺服已建置好的靜態檔案

✅ 完全免費 — 不需要 app_build_command，dist/ 已預先建置好。

⚠️ 不要指望 HF Secrets：Static Space 沒有 API_KEY Secret 機制 （那是 Docker / Gradio 的功能）。金鑰是填在網頁的輸入框裡，只存在你的 瀏覽器 localStorage，直接從瀏覽器連到供應商 API。

📁 目錄結構

agent-studio/
├── README.md                # 本檔（含 HF YAML frontmatter）
├── package.json
├── vite.config.js           # base: './'，讓資產用相對路徑
├── tailwind.config.js       # 語意化色板，接 index.css 的 CSS 變數
├── postcss.config.js
├── index.html
├── public/vite.svg
├── src/
│   ├── main.jsx
│   ├── index.css            # .theme-dark / .theme-light 變數
│   ├── App.jsx              # 導覽、設定、主題（單一 apiConfig 來源）
│   ├── components/
│   │   ├── ChatInterface.jsx    # 串流聊天
│   │   ├── AgentInterface.jsx   # 工具呼叫迴圈 UI
│   │   └── ExportDialog.jsx
│   ├── store/agentStore.js      # 迴圈、請求、錯誤處理
│   └── utils/
│       ├── tools.js             # 工具定義 + OpenAI 格式轉換
│       ├── agents.js            # Agent 角色與 system prompt
│       └── calc.js              # 安全四則運算解析器（無 eval）
└── dist/                    # 已建置好的靜態檔案（可直接伺服）

⚙️ 設定

項目	說明	預設值
API URL	OpenAI 相容端點	https://openrouter.ai/api/v1
API Key	供應商金鑰	空（需手動填入）
Model	模型 id	nvidia/nemotron-3-ultra-550b-a55b:free

聊天頁與 Agent 頁共用同一組設定，任一頁修改都會同步。

🔒 安全設計

• calculate 工具用遞迴下降解析器求值，只接受數字與 + - * / ( ) . %。 絕不用 Function() / eval() 執行模型輸出的字串（避免被 prompt injection 挾持成遠端碼執行）。
• API Key 只存在瀏覽器 localStorage，程式碼裡沒有任何金鑰。
• 所有外部請求都經過 CORS，不經任何中間伺服器。

⚠️ 已知限制

• search_web 是模擬的：純前端沒有網路存取權限（只能跨域打設定裡的 API）， 所以 search_web 回傳的是佔位文字。要真的搜尋需自架一個後端代理。
• 自訂工具只有格式、沒有執行器：加入的自訂工具會送進 API 讓模型呼叫， 但本機沒有對應實作，會回傳「未實作」。
• Agent 迴圈是同步的：stream: false，每一步等完整回應，複雜任務可能較慢； 單步逾時 120 秒。
• 匯出只含 Agent 頁的對話，聊天頁是獨立狀態。
• 對話不跨重新整理：聊天頁與 Agent 頁的訊息都存在記憶體（React state / zustand）， 重整頁面會清空。只有 API 設定與主題會寫進 localStorage。

📄 License

MIT License.