AI-translated from English; not yet reviewed by a fluent editor.

# 透過聊天和 React 頁面檢查同一個 Agent-Native action

> 從代理聊天和 React 路由呼叫 Chat 範本的 hello action，修改一個回傳值，並在核對工具呼叫證據時比較文件所述結果。

By BIG CHANGE Editorial

Published: 2026-10-19T10:08:15.758Z
Updated: 2026-10-19T10:08:15.758Z
Canonical: https://bigchange.ai/blog/agent-native-chat-react-action-parity-guide

![Conceptual charcoal illustration of one laptop showing two blank side-by-side work areas: conversation shapes on the left and a plain input and output area on the right.](https://bigchange.ai/api/media/file/agent-native-chat-react-comparison-hero-v1.png)
AI-generated conceptual illustration by BIG CHANGE; no actual product interface, action invocation or test result is depicted.

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

## 關鍵變化

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

## 設定文件所述的 Chat 範本

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

1. 在新目錄中建立並啟動獨立的 Chat 應用程式：

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

2. 透過 **Custom keys** 和你的 OpenAI API 金鑰連接聊天代理，再於 Settings 選擇可用模型。[環境變數指南](https://www.agent-native.com/docs/environment-variables/)說明，Custom keys 將限定作用範圍的憑證存入應用程式中由資料庫支援的加密儲存區。不要把金鑰加入版本控制，也不要放入瀏覽器可見的 `VITE_` 變數。模型請求使用金鑰擁有者的供應商帳戶；傳送敏感資料前，請查看其目前價格及[資料控制說明](https://developers.openai.com/api/docs/guides/your-data)。本指南沒有測量每項任務的費用或資料保留行為。
3. 在 Get started 聊天中輸入：`Call the hello action for Alex.` 文件 [入門指南](https://www.agent-native.com/docs/)列出的預期回覆是 `Hello, Alex!`。介面若提供工具詳細資料，請確認它呼叫了 `hello`，輸入為 `name: "Alex"`，並回傳該訊息。只有相同句子而沒有呼叫證據，仍無法確定。
4. 查看 `actions/hello.ts`。[固定版本的 Chat 範本](https://github.com/BuilderIO/agent-native/blob/8e8419361fb415682cdf0e0e68538671dbb6aed3/templates/chat/actions/hello.ts)定義了 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!`。

5. 在現有的 `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 入門指南](https://www.agent-native.com/docs/)記載建立流程、代理提示、React hook、預期回覆及復原步驟。其 action 摘錄省略了固定範本中的一項屬性，因此應直接修改原本產生的 action。
- [固定版本的 Chat `hello` action](https://github.com/BuilderIO/agent-native/blob/8e8419361fb415682cdf0e0e68538671dbb6aed3/templates/chat/actions/hello.ts)確認原始碼屬性，包括 `mcpTool: true`，對應的 commit 為 `8e8419361fb415682cdf0e0e68538671dbb6aed3`。這份快照無法證明日後建立應用程式時會安裝什麼。
- [環境變數文件](https://www.agent-native.com/docs/environment-variables/)說明金鑰作用範圍、模型選擇及 `VITE_` 的公開邊界。請另外查閱供應商條款；本指南沒有檢查真實聊天請求。

## Sources

- [Agent-Native 入門指南](https://www.agent-native.com/docs/) — [Agent-Native 入門指南](https://www.agent-native.com/docs/) 記載建立流程、代理提示、React hook、預期回覆及復原步驟。其 action 摘錄省略了固定範本中的一項屬性，因此應直接修改原本產生的 action。
- [固定版本的 Chat hello action](https://github.com/BuilderIO/agent-native/blob/8e8419361fb415682cdf0e0e68538671dbb6aed3/templates/chat/actions/hello.ts) — [固定版本的 Chat `hello` action](https://github.com/BuilderIO/agent-native/blob/8e8419361fb415682cdf0e0e68538671dbb6aed3/templates/chat/actions/hello.ts) 確認 commit `8e8419361fb415682cdf0e0e68538671dbb6aed3` 中的原始碼屬性，包括 `mcpTool: true`。這份快照無法證明日後建立應用程式時會安裝什麼。
- [固定版本的 core 套件](https://github.com/BuilderIO/agent-native/blob/8e8419361fb415682cdf0e0e68538671dbb6aed3/packages/core/package.json) — 套件版本、Node 要求與授權條款。
- [Agent-Native 環境變數](https://www.agent-native.com/docs/environment-variables/) — [環境變數文件](https://www.agent-native.com/docs/environment-variables/) 說明金鑰作用範圍、模型選擇及 `VITE_` 的公開邊界。請另外查閱供應商條款；本指南沒有檢查真實聊天請求。
- [OpenAI API 資料控制](https://developers.openai.com/api/docs/guides/your-data) — 供應商資料處理參考資料；未觀察此任務的實際流量。