Agent-Native の Chat テンプレートには、エージェントが呼び出せる hello action があります。TypeScript 開発者は、同じ action を呼ぶ小さな React ルートを追加し、戻り値を一つ変えて二つの結果を比較できます。本ガイドは Agent-Native の公式例に沿っています。BIG CHANGE は文書とテンプレートのソースを確認しましたが、アプリは実行していません。
大きな変化
- 変わること：一つの action から、エージェントのツールと React のクエリに同じ型付き操作を提供できます。この例では、あいさつのコードが一つのファイルにあります。
- 重要な理由：コード変更後に、二つの呼び出し元が同じ結果を受け取るか確認できます。チャットとページで別々のあいさつ処理を維持する可能性を減らせますが、保存済みのアプリ状態を共有していることの証明にはなりません。
- 確認する点：チャット画面に実際の action 呼び出しと戻り値が表示される場合は、それらを比較してください。モデルのもっともらしい文章だけでは
helloを呼んだ証拠になりません。重要な操作に使う前に、認可、入力検証、状態の書き込みを別々に評価してください。
文書にある Chat テンプレートを設定する
Node.js 22.22 以降、pnpm、コードエディター、チャット呼び出し用の OpenAI API キーが必要です。モデル接続前でも UI の設定はできます。確認した core パッケージと npm レジストリでは、2026年10月18日のバージョンは 0.209.2 でした。公式の生成コマンドは変動する @latest を使うため、作業前に再確認してください。
- 新しいディレクトリに独立した Chat アプリを作成し、起動します。
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 が含まれます。
- 接続には Custom keys と自分の OpenAI API キーでチャットエージェントを接続し、Settings で利用可能なモデルを選びます。環境変数ガイドによると、Custom keys はスコープ付きの認証情報を、アプリの暗号化されたデータベースベースの保管領域に保存します。キーをソース管理やブラウザー公開の
VITE_変数に入れないでください。モデルリクエストはキー所有者のプロバイダーアカウントを使います。機密情報を送る前に最新料金とデータ管理を確認してください。ここではタスク費用もデータ保持の動作も測定していません。 - Get started のチャットで
Call the hello action for Alex.と入力します。入門ガイドの期待される返信はHello, Alex!です。ツールの詳細が表示される場合は、helloがname: "Alex"で呼ばれ、そのメッセージが返ったことを確認します。同じ文章だけで呼び出しの証拠がなければ、判断はできません。 - ファイル
actions/hello.tsを確認します。固定した Chat テンプレートには Zod のname入力、GET action、mcpTool: trueがあります。これらは残してください。次の小さなページをapp/routes/hello.tsxに作ります。
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! です。
- 既存の
run関数（actions/hello.ts内）で、return 文だけを置き換えます。
return { message: `Welcome, ${name}.` }; ページ /hello を更新し、チャットにも再度 Alex に対して hello を呼ぶよう依頼します。文書上は両方で Welcome, Alex. が期待されます。ページの表示とチャットの action 結果を、利用可能ならツール詳細も含めて比較してください。ページの入力は React の状態に保存されます。このあいさつ action は共有レコードを読み書きしません。
確認対象 | return 変更前 | return 変更後 |
|---|---|---|
| | |
チャット action 結果、入力は | | |
これらは文書に示された期待値です。実験を完了したと判断する前に、自分の画面の値と、確認できる呼び出し詳細を記録してください。
コマンド pnpm がなければ、生成されたアプリで corepack enable を実行します。peer dependency エラーには、公式ガイドが再試行前の npx clear-npx-cache を提案しています。チャットに Connect AI が出る場合は、action の問題を調べる前にプロバイダー設定を終えます。/hello がなければルート作成後に開発サーバーを再起動してください。いずれも文書上の対処法で、私たちが観測した結果ではありません。
出典と参考資料
- Agent-Native 入門ガイドは、生成手順、エージェントへの指示、React hook、期待される返信、対処法を説明しています。action の抜粋には固定テンプレートのプロパティが一つ省略されているため、生成済み action を直接編集してください。
- 固定した Chat の
helloactionで、mcpTool: trueなどのソース属性を、commit8e8419361fb415682cdf0e0e68538671dbb6aed3で確認できます。このスナップショットは、後日の生成処理が何をインストールするかを証明しません。 - 環境変数はキーのスコープ、モデル選択、公開される
VITE_の境界を説明しています。プロバイダーの条件は別途確認してください。本ガイドは実際のチャットリクエストを調査していません。
