agent-ui

概觀

什麼是 agent-ui？

agent-ui 是由 ui.inference.sh 提供、專為 React 和 Next.js 應用打造的「開箱即用」Agent 元件。與其從零開始手刻一個 AI 聊天介面，你只要安裝一個現成的 Agent UI，再搭配由 @inferencesh/sdk 驅動的簡單 API proxy 路由即可。

這個元件打包了打造現代 AI 助理常見會用到的核心元素：

• 可直接嵌入的 chat/agent 介面
• 透過 proxy 路由連到推理後端的執行階段串接
• 支援串流回應（streaming responses）
• 可擴充工具（tools）、人工核准流程與更進階的 agent flow（透過底層的 ui.inference.sh 設定）

如果你想在 Next.js app 內上線 AI 助理、SaaS copilot，或其他 agent 型 UI，agent-ui 能在極少樣板程式碼的情況下，提供一個可上線的起始點。

agent-ui 適合誰使用？

agent-ui 適合下列類型的使用者：

• 希望在 React 或 Next.js app 中擁有設計精緻聊天／agent UI，但不想從零設計元件的 前端工程師。
• 想把 AI copilot 或助理能力整合到既有儀表板、SaaS 產品或內部系統中的 產品團隊。
• 比起手寫前端請求邏輯，更傾向設定 proxy 路由與環境變數的 偏向 API 的工程師。

如果你已經：

• 正在使用 Next.js（App Router）或類似的 React 技術堆疊
• 對 環境變數 與 API key 不陌生
• 知道如何在 TypeScript/React 專案中配置路由與元件

那你會對這個技能感到相當上手。

agent-ui 解決哪些問題？

在導入 AI 功能時，agent-ui 能幫你避開許多常見的摩擦點：

• 不必自訂聊天 UI —— 省去從零打造訊息列表、輸入框與載入狀態的時間。
• 不需要臨時拼湊 fetch 邏輯 —— proxy 路由由 @inferencesh/sdk 處理，避免你重複撰寫串流與錯誤處理的程式碼。
• 設定更單純 —— 只要傳入一個 agentConfig 物件（模型 ref、描述、system prompt），而不用手動把設定一層層穿過 UI。

這讓 agent-ui 成為一個從「我們有 API key」快速進到「我們有可用的 agent UI」的強力選項。

什麼情況下 agent-ui 是好選擇？

以下情境特別適合使用 agent-ui：

• 你正在開發 Next.js app（尤其使用 app/ 目錄架構）。
• 你希望有一個 預先打造好的 agent UI，外觀現代，並採用 shadcn 風格的生態系。
• 你可以輕鬆設定 inference proxy 路由與環境變數。

以下情況就可能不那麼適合：

• 你的前端技術堆疊並非 React/Next.js。
• 你需要完全客製化的聊天 UI 與高度特殊的互動模式，與一般 agent 介面差異很大。
• 你無法在環境中管理或暴露 INFERENCE_API_KEY。

使用方式

1. 在你的 agent workspace 安裝技能

要將 agent-ui 技能加入支援 Agent Skills 的 workspace，可透過 skills CLI 安裝：

npx skills add https://github.com/inferen-sh/skills --skill agent-ui

這會從 inferen-sh/skills repository 抓取 agent-ui 技能的 metadata。安裝完成後，請開啟 ui/agent-ui 資料夾中的 SKILL.md 以查看上游的詳細說明。

2. 在 Next.js 專案中安裝 agent-ui 元件

接著，在你實際要渲染 UI 的 Next.js app 裡，以技能中提到的 shadcn-style 指令，自 ui.inference.sh 安裝 Agent 元件：

# 安裝 agent 元件
npx shadcn@latest add https://ui.inference.sh/r/agent.json

# 為 proxy 路由安裝 SDK
npm install @inferencesh/sdk

這兩個步驟會：

• 從 ui.inference.sh 拉入 Agent UI 模組（React 元件以及相關 UI 接線）。
• 安裝 @inferencesh/sdk，供你在 Next.js app 中建立 inference proxy 路由使用。

你可以在任一既有的 Next.js（App Router）專案中執行這些指令。開始前請確認已安裝 Node.js、npm（或其他套件管理工具），以及可正常運作的開發環境。

3. 在 Next.js 中設定 API proxy 路由

agent-ui 預期前端是與後端的 proxy 路由溝通，而不是直接從瀏覽器呼叫推理服務。技能文件提供了一個基於 @inferencesh/sdk 的最小 Next.js 路由範例：

// app/api/inference/proxy/route.ts
import { route } from '@inferencesh/sdk/proxy/nextjs';
export const { GET, POST, PUT } = route;

實作重點：

• 將此檔案放在 Next.js App Router 專案的 app/api/inference/proxy/route.ts。
• @inferencesh/sdk/proxy/nextjs 提供的 route helper 會幫你輸出 HTTP handler（GET、POST、PUT），因此不需要自行寫 routing 邏輯。
• 這個 endpoint 會成為你傳給 Agent 元件的 proxyUrl。

如果你的專案路徑配置不同，只要保持實際路徑與你在 proxyUrl 中設定的一致即可。

4. 設定 INFERENCE_API_KEY 環境變數

接下來，在本機環境設定你的推理服務 API key。技能說明使用一個 INFERENCE_API_KEY 變數：

# .env.local
INFERENCE_API_KEY=inf_...

步驟：

1. 在 Next.js 專案根目錄建立或開啟 .env.local。
2. 將實際取得的 API key 替換掉 inf_...。
3. 重新啟動開發伺服器，讓 .env.local 的變更生效。

請務必保密這個 key，並避免將 .env.local commit 到版本控制系統中。

5. 在頁面中渲染 Agent 元件

當元件與 proxy 路由都就位後，你就可以在任一 Next.js 頁面裡渲染 Agent UI。技能中提供了精簡範例：

import { Agent } from "@/registry/blocks/agent/agent";

export default function Page() {
  return (
    <Agent
      proxyUrl="/api/inference/proxy"
      agentConfig={{
        core_app: { ref: 'openrouter/claude-haiku-45@0fkg6xwb' },
        description: 'a helpful ai assistant',
        system_prompt: 'you are helpful.',
      }}
    />
  );
}

關鍵要點：

• proxyUrl：指向你建立的 API proxy 路由（此例為 /api/inference/proxy），Agent UI 會透過它收發訊息。
• agentConfig：用來設定底層 agent 的物件，包括：
  • core_app.ref：後端所使用的模型或 app 的引用。
  • description：對助理用途的可讀性描述。
  • system_prompt：用來塑造行為的簡短 system prompt。

你可以將這個頁面範例放在 app/agent/page.tsx 或專案中任一既有路由。

6. 自訂與擴充 agent-ui

技能的 SKILL.md 提到包含 tools、approvals 與 widgets 等功能（透過 ui.inference.sh）。要善用這些功能，你可以循序漸進地：

• 調整 agentConfig，試不同的 model ref、描述與 system prompt。
• 瀏覽安裝後的 @/registry/blocks/agent/agent 底下的 Agent 模組檔案，了解 UI 的建構方式與支援的 props。
• 把 Agent UI 併入更具體的應用流程（例如客服後台、導覽 onboarding copilot，或內部營運助理）。

由於 agent-ui 是以 React 元件形式提供，你可以將它包在各種 layout、modal、tabs 裡，或搭配你既有的導覽與驗證機制使用。

7. 安裝後推薦檢視的檔案

在 skills-aware workspace 中安裝 agent-ui 技能後，建議優先開啟：

• ui/agent-ui/SKILL.md – 上游的快速入門與設定細節。

接著就可以依照該文件指引，將流程映射到你的實際 Next.js 專案，並依據自家模型與後端限制做調整。

常見問題（FAQ）

使用 agent-ui 一定要 Next.js 嗎？能單獨搭配 React 嗎？

技能中的設定流程與 proxy 路由範例，是針對使用 app/api 路由慣例與 @inferencesh/sdk/proxy/nextjs 的 Next.js 特別撰寫的。雖然 UI 本身是建立在 React 之上，但本技能文件所記錄與支援的整合路徑，是以 Next.js App Router 風格的 API 路由為主。

如果你是用純 React 或其他框架，就需要自行重現 proxy 行為並改寫範例；這種整合方式並未在本技能中提供完整文件。

agent-ui 與自己從零做一個 chat UI 有什麼差別？

使用 agent-ui 時，你會：

• 從 ui.inference.sh 安裝一個預先打造的 Agent component。
• 只需透過一個 proxy 路由 和一個 環境變數 就能接上推理後端。

你不需要：

• 自己設計與寫出完整的訊息列表、輸入區與串流顯示狀態。
• 手寫收發訊息的 fetch 呼叫與錯誤處理邏輯。

同時，你仍可透過 agentConfig 掌控設定，可隨時更換 model ref、描述和 system prompt，而不必動到 UI 的內部實作。

在這個架構裡，@inferencesh/sdk 的角色是什麼？

@inferencesh/sdk 負責 server-side proxy 路由 的實作：

import { route } from '@inferencesh/sdk/proxy/nextjs';
export const { GET, POST, PUT } = route;

透過這個 helper，你可以：

• 提供一個單一 endpoint（範例為 /api/inference/proxy）讓 Agent UI 溝通。
• 把底層協定細節與 HTTP 方法（GET、POST、PUT）的處理交給 SDK，而不用寫自訂程式碼。

如此一來，你能更輕鬆地維護與調整推理服務整合，而不需重寫 UI。

要如何變更 agent 的模型或行為？

你只要更新傳入 Agent 元件的 agentConfig 即可。例如：

<Agent
  proxyUrl="/api/inference/proxy"
  agentConfig={{
    core_app: { ref: 'openrouter/claude-haiku-45@0fkg6xwb' },
    description: 'a helpful ai assistant',
    system_prompt: 'you are helpful.',
  }}
/>

若要改變行為，你可以：

• 將 core_app.ref 換成其他支援的模型或 app。
• 更新 description 以反映助理角色（例如：「customer support copilot」）。
• 調整 system_prompt，微調語氣與職責邊界。

可再參考你所使用的推理後端文件，了解支援的參數值與額外設定選項。

agent-ui 可以用在正式環境（production）嗎？

agent-ui 技能提供的是一個可實際運作的 React/Next.js Agent 元件，加上一個偏向正式應用場景的 proxy 路由模式。不過，是否能真正達到 production 等級，仍取決於你如何：

• 管理 API keys 與環境變數。
• 在 /api/inference/proxy 周邊加入 身份驗證（authentication）、權限控管（authorization） 與 頻率限制（rate limiting）。
• 監控、記錄並保護送往推理後端的流量。

這個技能提供的是穩健的起始架構，但在正式上線前，仍建議加上自家的安全性、可觀察性與錯誤處理策略。

到哪裡可以看到 agent-ui 的上游文件？

在透過以下指令安裝技能之後：

npx skills add https://github.com/inferen-sh/skills --skill agent-ui

請開啟：

• ui/agent-ui/SKILL.md

這個檔案由 inferen-sh/skills repository 維護，包含 agent-ui 元件的上游快速入門（安裝指令、proxy 路由範例、環境變數設定與元件使用範例）。