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) — 提供商数据处理参考资料；未观察该任务的实际流量。