把 onagent 串進你的應用

各個元件如何組合起來

一次串接由四樣東西構成，正好對應這一頁的四個章節。

1. onagent CLI — 一個命令列工具，讓你在終端機（或指令稿／CI 工作）裡完成登入與管理 app，而不必只能透過瀏覽器的 console 操作。
2. console 裡的一個 app — 一個命名空間（appId），底下擁有一把 API key、一個 allowed origin、一組 tool，以及選填的自訂 system prompt。
3. tool 定義 — 一份 YAML 檔（或用 console 的 tool 編輯器），描述你的頁面對外提供的每項能力：名稱、一段供 LLM 判斷何時該呼叫它的說明，以及一個 JSON Schema 形式的參數結構。
4. 瀏覽器端 SDK（@onagent/bridge） — 嵌在你的頁面裡，它會對後端開一條 WebSocket、註冊你的 tool handler，並讓你呼叫 bridge.prompt(text)，由 LLM 推理該請求，再把 tool call 派發回你的頁面。

執行時的流程是：你的頁面呼叫 bridge.prompt("...")，後端的推論服務決定要呼叫你宣告的哪些 tool （也可能都不呼叫），SDK 透過 WebSocket 收到該呼叫，執行你註冊的對應 handler，再把結果回報給後端。

取得 onagent CLI 並登入

onagent 是 console API 的命令列客戶端。它能做的每件事，也都可以透過瀏覽器的 console 完成—— 看哪個比較合你的工作流程就用哪個。一旦開始寫指令稿（CI、批次推送 tool 等），CLI 會快得多。

安裝

如果你的環境有 Go 工具鏈，直接從 module 路徑安裝：

$ go install github.com/tim72117/onagent/cmd/onagent@latest

這會在你的 Go bin 目錄裡放一個 onagent 執行檔。不需要另外下載、也沒有獨立的套件登錄中心—— CLI 就住在它所連線的後端的同一個儲存庫裡。

登入

onagent 支援兩種登入方式。兩者最後都會把 bearer token 快取在本機（放在你的個人設定目錄裡）， 所以之後的每個指令都不會再問你一次。

# 互動式環境建議用這個
$ onagent login --web

# 無頭環境／沒有瀏覽器可用
$ onagent login

用這個指令確認是否成功：

$ onagent app list
# 只要列出 app 清單（就算是空的）就代表已經登入。
# 出現 "not logged in" 代表 onagent login 還沒成功。

完整指令參考

每個子指令都接受一個選填的 -api <url> 旗標；下表為求簡潔而省略。

appId 必須符合 ^[a-zA-Z0-9][a-zA-Z0-9_-]*$——以英文字母或數字開頭， 之後可以是英文字母、數字、-、_ 的任意組合。

建立 app、發放 key、設定 allowed origin

這三件事都可以用 CLI 或 console 的網頁 UI 完成——哪個方便就用哪個；兩者操作的是同一筆 app 紀錄。

$ onagent app create my-app
Created app "my-app".

或是在 console 裡：登入 /app 後點 + New app。

$ onagent key issue my-app
API key for "my-app" (shown once — copy it now, it can't be retrieved again):
  sk_live_ab12cd34...
Issuing a new key later immediately revokes this one.

$ onagent app origin set my-app https://your-site.example.com
Set "my-app"'s allowed origin to "https://your-site.example.com".

請填你的頁面實際被服務的那個 origin——協定 + 主機 + 連接埠，不要帶路徑、 也不要有結尾斜線（例如 https://your-site.example.com，而不是 https://your-site.example.com/ 或 .../app）。在 console UI 裡， 同一個欄位在該 app 的頁面上標示為 Allowed origin。

定義 tool 並推送上去

一個 tool 就是你的頁面對 LLM 開放的一項能力：一個供它呼叫的名稱、一段告訴模型何時該用它的說明， 以及一組 JSON Schema 形式的參數。定義 tool 有兩種方式——為每個 tool 手寫一份 YAML 檔， 再用 onagent tool create 推上去；或是使用 console 內建的 tool 編輯器。 兩者寫入的是同一份底層定義；看你有多少個 tool、以及想不想把它們納入版本控制來決定。 onagent tool create 一次依名稱新增或取代一個 tool——絕不會動到這個 app 的其他 tool。

tool.yaml 結構

一份檔案描述一個 tool——以下是它的欄位：

name: search_products
description: Search the product catalog by keyword.
parameters:
  type: object
  properties:
    query:
      type: string
      description: The search keywords.
    maxResults:
      type: integer
  required:
    - query
kind: query   # LLM 需要拿回實際的搜尋結果

第二個 tool，沒有寫 kind（預設為 action）：

name: add_to_cart
description: Add a product to the current user's shopping cart.
parameters:
  type: object
  properties:
    productId:
      type: string
      description: The product's unique ID.
    quantity:
      type: integer
      description: How many units to add. Defaults to 1 if omitted.
    giftWrap:
      type: string
      enum: [none, standard, premium]   # 把 LLM 限制在這三個選項之中
  required:
    - productId
# 省略 kind → 預設為 "action"

action 與 query — 兩者都會阻塞，差別在 LLM 看得到什麼

kind 欄位決定兩種呼叫流程。以目前的後端而言，兩者都是阻塞式的—— tool call 一定會讓進行中的請求等到你的頁面回應為止。差別在於那個回應會被怎麼處理，而不在於平台會不會等它。

推送 tool

把上面每份 YAML 各自存成一個檔案，再一個一個推上去——這會新增該 tool，或在同名 tool 已存在時取代它：

$ onagent tool create my-app search_products.yaml
Saved "search_products" to "my-app".
$ onagent tool create my-app add_to_cart.yaml
Saved "add_to_cart" to "my-app".

onagent 會先在本機驗證檔案，通過才送出。最常見的驗證失敗原因：

• tool 名稱不合法 — 不符合 ^[a-zA-Z_][a-zA-Z0-9_]*$（不能有連字號、不能以數字開頭、不能有空白）。
• tool 缺少 description。
• 缺少 parameters.type — 整個 parameters 區塊（或它的 type 欄位）被省略了。

要讀回目前已儲存的內容（例如拿來跟本機檔案比對差異，或從 console 編輯器的狀態產生一份新檔案）：

$ onagent tool list my-app

要從 app 移除一個 tool：

$ onagent tool delete my-app add_to_cart

設定自訂的 thought（system prompt）

除了各個 tool 自己的說明之外，一個 app 還可以帶有它自己給「負責挑選 tool 的 agent」的自訂指示—— 語氣、領域規則，任何超出「呼叫對應的 tool」之外的要求：

$ onagent app thought set my-app "Always confirm destructive actions before calling them."
Set "my-app"'s thought.

傳入空字串即可清除它，退回平台的預設值。

限制 prompt 的長度上限

平台會對「單一則終端使用者 prompt 可以有多少字元」施加一個系統層級的上限（由營運後端的人透過 MAX_PROMPT_LENGTH 環境變數設定）。每個 app 還可以另外設定自己更嚴格的上限—— app 自己的設定只能縮小實際生效的上限，永遠無法把它放寬到超過系統層級的值：

$ onagent app maxpromptlength set my-app 200
Set "my-app"'s max prompt length to 200 characters.

傳入 clear 而不是數字，即可移除這個 app 專屬的上限，退回系統層級的預設值。 超過實際上限的 prompt 會被拒絕，但連線會保持開啟——SDK 會收到一個帶有 prompt_too_long 代碼的錯誤，形式與配額不足的拒絕相同。

寫任何前端程式碼之前先試跑

只要一個 app 已經定義好 tool，console 的 Playground 就能讓你對它送出 prompt，並觀察 LLM 如何決定 要不要呼叫、以及怎麼呼叫這些 tool，完全不需要先架好一個真的頁面。在 console 裡選定該 app， 再從側邊欄開啟 Playground（在手機版是固定在底部的按鈕）。 它走的是與 @onagent/bridge 相同的後端 session／tool call 協定， 所以在這裡成功的 tool call，等到真的有頁面回應時行為也會一致——唯一的差別只是「另一端由誰產生 tool_result」。

Mock 範本

這兩個內建的 mock 範本來自 console 的 tool 建立精靈，而不是手寫的 YAML——把一個 tool 建成 click_button 或 fill_form 範本，會鎖定它的參數名稱 （label，或 field／value），但 enum 選項仍可自由編輯， 而 Playground 的模擬按鈕／欄位會立即跟著更新。

嵌入 SDK 並實作 tool handler

@onagent/bridge 是瀏覽器端的客戶端：它會對你的 onagent 後端開一條 WebSocket、 註冊你提供的 tool handler，並提供 prompt(text) 來發動一次請求。 在連線就緒之前發出的呼叫，它會先緩衝起來，等連線開啟後再一次送出， 所以你不需要自己去檢查什麼「ready」旗標。

安裝

$ npm install @onagent/bridge

建立 bridge

import { AgentBridge } from "@onagent/bridge";

const bridge = new AgentBridge({
  url: "wss://onagents.dev/ws",
  appId: "my-app",
  apiKey: "YOUR_APP_API_KEY",
  tools: {
    search_products: async ({ query, maxResults }) => {
      const results = await searchCatalog(query, maxResults);
      return results; // kind: query → 這個值會被餵回給 LLM
    },
    add_to_cart: ({ productId, quantity }) => {
      cartStore.add(productId, quantity ?? 1);
      // kind: action（預設）→ 只有成功／失敗會傳到 LLM，
      // 這裡回傳的任何值都會被模型忽略。
    },
  },
  onAssistantMessage: (text) => showInChat(text),
  onError: (err) => console.error("onagent error", err),
});

建構子選項：

實作 tool handler

tools 裡的每一個鍵，都必須對應到你已推送到平台上的某個 tool 名稱 （透過 tool create 或 console 編輯器）。handler 會收到該次呼叫已解析的參數， 並依該 tool 的 kind 回傳（或 resolve 出）合適的值：

• 對 action 類型的 tool，回傳值會被 LLM 忽略——只有你的 handler 有沒有拋出例外會決定成功或失敗，別指望模型看得到回傳的內容。
• 對 query 類型的 tool，你回傳的任何東西（同步回傳、或由 Promise resolve）都會被序列化並直接餵回 LLM 的推理過程。沒有任何地方會事先宣告它的形狀，所以請回傳「這則 prompt 真正需要的東西」。
• 拋出例外（或非同步 handler 的 Promise 被 reject）會把失敗連同錯誤訊息一起回報給後端。

用 defineTool 寫具型別的 handler

把 tools 寫成一個普通物件，代表每個 handler 都是從 args: any 開始—— 型別系統會相信你斷言的任何形狀，而沒有人在執行時真正驗證過它。 defineTool 把 handler 與一個 parseArgs 函式配成一對， 由後者同時驗證原始酬載、並賦予 Args 型別，於是 handler 本身就是完整具型別的：

import { AgentBridge, defineTool } from "@onagent/bridge";

interface SearchArgs { query: string; maxResults?: number; }

function parseSearchArgs(raw: unknown): SearchArgs {
  const r = raw as Partial<SearchArgs>;
  if (typeof r?.query !== "string") throw new Error("query must be a string");
  return { query: r.query, maxResults: r.maxResults };
}

const searchProducts = defineTool(
  "search_products",
  parseSearchArgs,
  async ({ query, maxResults }) => { // 完整具型別：是 SearchArgs，不是 any
    return await searchCatalog(query, maxResults);
  }
);

const bridge = new AgentBridge({
  url: "wss://onagents.dev/ws",
  appId: "my-app",
  apiKey: "YOUR_APP_API_KEY",
  tools: [searchProducts], // ToolEntry[]，不是 { name: handler } 對應表
});

Args 的真正來源是 parseArgs 的回傳型別，而不是一句光禿禿的 as Args 斷言。它可以像上面那樣是幾行手寫的驗證，也可以包一層 schema 函式庫的 .parse 方法；SDK 不會替你決定。parseArgs 拋出的例外會原封不動地往外傳出該 handler， 因此會被當成一般的 { ok: false, error } tool 結果回報，與其他 handler 錯誤的處理方式完全相同—— 不需要再學一套獨立的錯誤處理路徑。

如上所示，tools 可以直接接受一個 ToolEntry[] 陣列——建構子會把它轉換成 與普通物件相同的 Record<string, ToolHandler> 形式，內部使用的是對外匯出的 toToolRecord 輔助函式。如果你需要先把多個來源的 tool 陣列合併起來，再交給 AgentBridge，也可以自己呼叫 toToolRecord。兩筆共用同一個 name 的項目 ——不論是在同一個陣列裡、或跨越多個被合併的陣列——都會立刻拋出例外， 而不是像 { ...a, ...b } 那樣讓後面的鍵無聲地蓋掉前面的。

送出 prompt

建立完成後，用自然語言的請求呼叫 bridge.prompt(text)。整個呼叫就是這樣—— 它只接受文字，沒有別的參數：

searchInput.addEventListener("submit", (e) => {
  e.preventDefault();
  bridge.prompt(userInput.value);
});

LLM 會推理這則 prompt、從你宣告的 tool 中挑出零個或多個來呼叫，SDK 則自動把每次呼叫派發給對應的 handler。 結果與任何自然語言回覆，會透過 onAssistantMessage／onError 以及你自己 handler 的副作用浮現出來——沒有另一個「context」參數可以跟著 prompt 文字一起傳； 模型推理所需要的任何狀態，都應該改由一次 query 類型的 tool call 回傳給它。

呼叫 bridge.close() 可以永久關閉這條連線——之後不會再嘗試重新連線。

在用 Claude Code 嗎？有一個免設定的 skill

如果你是在 Claude Code 裡面串接 onagent，onagent-cli-setup 這個 skill 可以帶你走完整段流程—— 偵測安裝狀態、登入、建立 app、發放金鑰、設定 origin，以及推送 tools.yaml。 它是上述所有步驟的互補路徑，而不是替代品：不論走哪一條，底層的 CLI 指令與 tools.yaml 結構都完全相同，所以就算由 Claude Code 代勞實際操作，這一頁仍然值得讀。

安裝這個 skill

它以 npm 套件形式發布，內含五個平台的預編譯 onagent 執行檔 （Windows、macOS Intel／Apple Silicon、Linux x64／arm64）——在任何一個平台上都不需要另外 go install 或自行編譯。

# 專案層級：.claude/skills/onagent-cli-setup/
$ npx -p @onagent/claude-skill claude-skill-onagent

# 改成使用者層級：~/.claude/skills/onagent-cli-setup/
$ npx -p @onagent/claude-skill claude-skill-onagent --user

這是一次明確的、由使用者主動觸發的安裝（而不是 postinstall 掛鉤）—— 執行它是它唯一會碰到你 .claude/ 目錄的時機。日後重新執行會覆蓋已安裝的版本， 這也就是更新這個 skill 的方式。

疑難排解

針對最常遇到的問題的快速解答。