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_ 的公开边界。请另行查看提供商条款；本指南未检查真实聊天请求。