Agent‑Nativeの使い方：TypeScript AI Agentフレームワークのインストールと開発チュートリアル

Agent-Native導入手順の結論

公式の概念説明では、UIとAgentが共有する対象として、actions、データ、アプリケーション状態の3つが示されています。公式の主要概念に照らすと、Agent-Nativeはチャット欄だけを既存画面に足す仕組みではなく、業務操作をUIとAgentの双方から扱うTypeScriptアプリを作りたいチーム向けです。まず公式CLIで最小アプリを作り、actionの入力検証、認可、状態の同期を確かめてから、データベースと公開先の適合性を確認して機能を広げてください。

この記事は、TypeScriptでAgentアプリを構築する開発者が、プロジェクト作成から最初の共有actionまで進めるための手順です。
業務UIにAgent操作を加えるチームは、同じデータを扱う際の権限境界と失敗時の動きを確認できます。
遠隔開発や継続稼働を検討する技術担当者には、依存関係と公開前の確認項目もまとめています。

最終更新：2026年9月25日。CLIやAPIの記述は、公式リポジトリと公式ドキュメントを基準に確認してください。なお、Zutcloudの環境での起動・性能測定値は提示されていないため、本記事では実測結果として扱いません。

適用するアプリの見極め

Agent-Nativeを候補にするのは、ユーザーが画面上で行う操作とAgentに依頼する操作を、同じ業務ルールとデータに結び付けたい場合です。たとえば、担当者がUIで案件情報を直し、Agentにも同じ案件の要約や更新を依頼するアプリでは、操作を共有できる設計が役立ちます。

一方、既存サイトに会話欄を追加するだけで、Agentがアプリ内データを変更しない場合は、アプリケーション全体の構成を持ち込む必要性を先に検討してください。既存バックエンドの業務処理を安全に公開できるなら、既存APIと画面を維持し、Agent部分だけを追加する方が変更範囲を抑えられることがあります。

判断の目安は次のとおりです。

選択肢	適する条件	導入前に確認する点
Agent-Nativeでアプリを構成	UIとAgentが同じ業務操作や状態を扱う	既存データモデル、認証、公開先との適合性
既存アプリにAgent機能を追加	UIや業務APIを大きく作り替えたくない	既存APIに認可と入力検証があるか
チャットUIのみを追加	Agentがアプリ内データを変更しない	会話機能だけで要件を満たすか

プロジェクト作成と依存関係

Agent-Nativeの導入手順でプロジェクトを作るには

まず公式Quickstartを開き、そこに記載されたCLIコマンドをそのまま実行します。コマンド名、テンプレート、必要なNode.jsやパッケージマネージャーの条件は更新される可能性があるため、古い記事のコマンドを転記せず、作業時点の手順を基準にしてください。公式資料で確認できない最低バージョンは推測して固定しないでください。

作成後は、生成された設定ファイルと依存一覧を読み、起動スクリプト、環境変数の読み込み方法、データ保存先を確認します。テンプレートが起動しただけでは、実際のAgent接続や永続化まで準備できたとは限りません。リポジトリの開発ガイドも参照し、開発時の前提とアプリ公開時の設定を分けてください。

確認対象	作業内容	未確認のまま進めた場合
Node.js・パッケージ管理	Quickstartと生成ファイルの条件を照合	CLI実行や依存導入で環境差が出る
テンプレート	含まれる画面、サーバー処理、設定を把握	サンプル機能を本番機能と誤認する
環境変数	必須項目と秘密情報の扱いを確認	ローカル値や秘密情報を誤って公開する
データ保存	使用するデータベースと永続化方式を確認	再起動後に状態が残らない可能性がある

UIとAgentで共有するactionの実装

actionsの定義方法を確認し、共有したい業務操作をactionとして設計します。actionは単なるAgent向けの命令文ではありません。入力の形、実行処理、戻り値を決め、UIとAgentが同じ業務ルールへ到達する入口として扱います。

たとえば、案件名を変更する処理なら、入力スキーマで識別子と新しい名前の形式を検証し、実行処理では呼び出し元の権限を確かめてから保存します。UI側は同じactionを呼び出し、Agent側は公式のaction登録方法で公開します。以下は業務ロジックの構造例であり、Agent-NativeのAPI名や実行可能な登録コードを示すものではありません。

type Actor = {
  id: string;
  canEditProjects: boolean;
};

type RenameInput = {
  projectId: string;
  name: string;
};

async function renameProject(input: RenameInput, actor: Actor) {
  if (!input.projectId.trim() || !input.name.trim()) {
    throw new Error("入力を確認してください");
  }

  if (!actor.canEditProjects) {
    throw new Error("この操作は許可されていません");
  }

  return projectRepository.rename(input.projectId, input.name);
}

projectRepositoryはアプリ側で用意する保存処理です。実装では、入力の形式確認だけでなく、対象データへのアクセス権、操作の記録、保存失敗時の応答も設計してください。UIとAgentが同じ関数を呼ぶこと自体は、認証や認可が自動的に保証されることを意味しません。

共有状態とアクセス権の検証

最初の動作確認では、UIで変更した値をAgentが読み取れるか、Agentの変更がUIに反映されるかを、同一の業務データで確認します。次に、許可された利用者と許可されない利用者で同じ操作を試し、拒否がサーバー側でも行われることを確かめます。公式アクセス制御の説明を参照し、認証情報の受け渡しとactionごとの認可条件を実装に対応させてください。

検証操作	確認する結果	不合格時の見直し
UIで値を変更しAgentから参照	Agentが最新の保存値を扱う	UIの一時状態と永続データを区別する
Agentから許可された変更を実行	UIと保存データの双方に反映	更新通知や再取得の経路を確認する
権限のない利用者が変更を要求	サーバー側で拒否し、理由を安全に返す	UIだけに依存した認可を取り除く
不正な形式や存在しない対象を指定	更新せず、利用者が理解できる失敗を返す	入力スキーマと例外処理を見直す

同じactionをUIとAgentが呼び出せることは、同じユーザー権限で安全に実行できることの証明ではありません。画面側のボタン制御だけでなく、各リクエストの認証、対象データの認可、失敗時の記録を個別に確かめてください。

データベースとの連携は、サーバーとデータベースの説明でフレームワークの想定と同期方法を確認してから組み込みます。モデルや外部ツールについても、公式資料に明記された接続方法だけを前提にし、未記載の提供元や互換性を動作保証として扱わないでください。

公開前の環境確認と段階的な展開

公開先の判断では、アプリを置けるかだけでなく、必要な環境変数、データの永続化、ログの取得方法、バックグラウンド処理の要否を確認します。単一アプリの公開手順と公開範囲・データベース要件を照合し、さらに本番環境変数の説明で秘密情報の設定方法を確認してください。公式資料にないホストや構成を、対応済みと断定することはできません。

選択肢	向く状況	判断材料
ローカル開発	CLIと依存関係を手元で確認したい	OS、ランタイム、パッケージ管理
遠隔の開発環境	開発端末から独立した実行環境が必要	接続方法、永続ストレージ、稼働条件
試験公開	認証・データ保存を含め利用者目線で確認したい	環境変数、ログ、復旧手順
本番公開	運用担当と障害対応を含めて準備できている	監視、バックアップ、権限管理、更新手順

公開前は、次の項目を一つずつ確認してください。

• [ ] 公式QuickstartのCLIとテンプレートを使い、クリーンな環境から起動できる。
• [ ] actionの入力検証が、UIとAgentの双方からの呼び出しで機能する。
• [ ] 未認証・権限不足・対象なし・保存失敗の応答を確認した。
• [ ] UIとAgentが同じ保存済みデータを読み書きすることを確認した。
• [ ] 環境変数に秘密情報を含め、リポジトリやログへ出さない設定にした。
• [ ] データベースの永続化、ログ確認、障害時の復旧担当を決めた。
• [ ] 小規模な試験公開で操作記録と失敗時の挙動を確認してから対象を広げる。

遠隔開発環境を選ぶときの判断

Agent-Nativeの開発にMacが必須だとは、ここで確認した公式情報からは言えません。Node.jsや依存パッケージの条件を満たす環境があり、macOS固有の検証が不要なら、既存の開発端末や要件に合うサーバーを使う選択肢もあります。

ただし、手元の端末だけで開発すると、端末停止中の処理継続、チームでの環境統一、macOSを含む確認環境の確保が課題になる場合があります。macOS上での開発・検証が要件に含まれるなら、Mac miniのレンタル環境を候補に加え、必要なOS、接続方法、データ保存と稼働条件が要件に合うかを確認してください。フレームワークの動作性能や特定構成での実測を示すものではありません。

最小アプリの起動後に、依存関係、データベース、継続稼働の要件を整理し、遠隔環境が必要な場合だけ候補を比較するのが堅実です。macOSでの作業環境を短期間確保したい、または導入前に利用条件を確認したい場合は、Zutcloudのヘルプセンターで案内を確認し、購入・常設環境との違いを踏まえて選んでください。長期にわたり安定した高負荷処理を続ける場合や、特定の物理接続が不可欠な場合は、レンタルより専用の自社環境が適することがあります。

関連記事

• AIエージェントのフレームワーク選定と使い分け
• アクション実行に欠かせないFunction Callingの仕組み
• エージェントのファイル操作を安全に設計する方法