Agent-Native 的 Chat 範本包含代理可呼叫的 hello action。TypeScript 開發者可以新增一個呼叫相同 action 的小型 React 路由，修改一個回傳值，再比較兩處結果。本指南依循 Agent-Native 文件中的範例；BIG CHANGE 檢查了文件和範本原始碼，但沒有執行應用程式。

關鍵變化

  • 發生了什麼變化：同一個 action 可以向代理工具和 React 查詢提供同一項具型別的操作。本例的問候邏輯只存在一個檔案中。
  • 為何重要：開發者可以檢查程式碼修改後，兩個呼叫端是否收到相同結果，減少分別維護聊天與頁面問候邏輯的可能性。但這無法證明呼叫端共用已儲存的應用程式狀態。
  • 需要留意：聊天介面若顯示實際 action 呼叫和回傳值，請比較這些資訊。模型產生一句看似合理的話，並不能單獨證明它呼叫了 hello。將此模式用於重要操作前，應分別評估授權、驗證及狀態寫入。

設定文件所述的 Chat 範本

你需要 Node.js 22.22 或更新版本、pnpm、程式碼編輯器，以及供聊天呼叫使用的 OpenAI API 金鑰。可以先設定介面，再連接模型。檢查時，core 套件和 npm 登錄庫在 2026 年 10 月 18 日均顯示版本 0.209.2。官方建立命令使用會變動的 @latest；操作前請再次確認版本。

  1. 在新目錄中建立並啟動獨立的 Chat 應用程式：
Terminal
   npx --yes @agent-native/core@latest create my-app --standalone --template chat
   cd my-app
   corepack enable
   pnpm install
   pnpm dev

開啟 pnpm dev 印出的本機 URL，選擇 Continue as local dev。如果 8080 連接埠已被占用，埠號可能遞增。產生的應用程式包含 actions/hello.ts。

  1. 透過 Custom keys 和你的 OpenAI API 金鑰連接聊天代理，再於 Settings 選擇可用模型。環境變數指南說明，Custom keys 將限定作用範圍的憑證存入應用程式中由資料庫支援的加密儲存區。不要把金鑰加入版本控制，也不要放入瀏覽器可見的 VITE_ 變數。模型請求使用金鑰擁有者的供應商帳戶；傳送敏感資料前，請查看其目前價格及資料控制說明。本指南沒有測量每項任務的費用或資料保留行為。
  2. 在 Get started 聊天中輸入：Call the hello action for Alex. 文件 入門指南列出的預期回覆是 Hello, Alex!。介面若提供工具詳細資料，請確認它呼叫了 hello，輸入為 name: "Alex"，並回傳該訊息。只有相同句子而沒有呼叫證據，仍無法確定。
  3. 查看 actions/hello.ts。固定版本的 Chat 範本定義了 Zod name 輸入、GET action 及 mcpTool: true。保留這些屬性。建立 app/routes/hello.tsx，加入以下小型頁面：
TypeScript
   import { useActionQuery } from "@agent-native/core/client/hooks";
   import { useState } from "react";

   export default function HelloRoute() {
     const [name, setName] = useState("Alex");
     const { data } = useActionQuery("hello", { name });

     return (
       <main>
         <label htmlFor="greeting-name">Name</label>
         <input
           id="greeting-name"
           value={name}
           onChange={(event) => setName(event.target.value)}
         />
         <p>{data?.message}</p>
       </main>
     );
   }

重新啟動 pnpm dev，讓它偵測新路由，再於印出的本機 URL 後加上 /hello。輸入欄位為 Alex 時，文件所述結果是 Hello, Alex!。

  1. 在現有的 run 函式中（位於 actions/hello.ts），只替換回傳敘述：
TypeScript
   return { message: `Welcome, ${name}.` };

重新整理 /hello，再要求聊天為 Alex 呼叫 hello。文件預期兩處都出現 Welcome, Alex.。比較頁面顯示的訊息與聊天中的 action 結果；若有工具詳細資料，也一併檢查。頁面將輸入保存在 React 狀態中；此問候 action 不會讀取或寫入共用紀錄。

檢查項目

修改回傳敘述前

修改回傳敘述後

/hello 的輸入為 Alex

Hello, Alex!

Welcome, Alex.

聊天 action 結果，輸入為 name: "Alex"

Hello, Alex!

Welcome, Alex.

這些是文件中的預期值。認定實驗完成前，請記錄你實際看到的值及可取得的呼叫詳細資料。

如果缺少 pnpm，請在產生的應用程式中執行 corepack enable。發生 peer dependency 錯誤時，官方指南建議先執行 npx clear-npx-cache 再重試。若聊天顯示 Connect AI，先完成供應商設定，再診斷 action。若沒有 /hello，建立路由後請重新啟動開發伺服器。這些是文件記載的復原步驟，並非我們觀察到的結果。

來源與延伸閱讀

  • Agent-Native 入門指南記載建立流程、代理提示、React hook、預期回覆及復原步驟。其 action 摘錄省略了固定範本中的一項屬性，因此應直接修改原本產生的 action。
  • 固定版本的 Chat hello action確認原始碼屬性，包括 mcpTool: true，對應的 commit 為 8e8419361fb415682cdf0e0e68538671dbb6aed3。這份快照無法證明日後建立應用程式時會安裝什麼。
  • 環境變數文件說明金鑰作用範圍、模型選擇及 VITE_ 的公開邊界。請另外查閱供應商條款；本指南沒有檢查真實聊天請求。