---
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，重新整理不丟失，可另存多組切換

## 🚀 使用方式

### 本地開發

```bash
npm install
npm run dev
```

### 建置

```bash
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.