エージェント

@nocobase/app-plugin-agents は、AI チャット、モデルの設定、業務のスキル、マシン上のエージェントを提供します。業務のページの横にチャットを追加したり、エージェントにチームの文章のルールに従わせたり、マシン上のコーディングアシスタントを接続してタスクを実行させたりできます。

機能

プラグインはページとコンポーネントを提供します。メニューとチャットをどこに表示するか、どの業務データにアクセスできるかはアプリが選びます。登録したあとも、これらの画面をアプリに追加する必要があります。

エージェントを接続する 2 つの方法

両方の方法を一緒に使えます。以下の最初の 2 つのシナリオはモデル API を使い、3 つ目はマシンを接続します。モデル API の会話では、ホストのソースコードに直接アクセスしたり、プロジェクトのテストを実行したりはできません。

シナリオと例

アプリを作成する から始めるか、最後にリンクした 完全なサンプル を実行します。アプリの既存のデータベースの設定はそのままにし、モデルサービスの例には DeepSeek を使います。サンプルの画面は英語です。コマンドは apps/agents-guide で実行します。

開発用のプロンプト は、プロジェクトで作業するコーディングエージェントに送ります。会話のプロンプト は、アプリのチャットの画面で使います。以下のプロンプトは読者向けに簡略化しており、スクリーンショットは元の検証済みの会話のものです。最後の検証の範囲を参照してください。

シナリオ 1：アプリに AI との会話を追加する

開発用のエージェントに、次の依頼を渡します。

ページの右側に、ヘッダーのボタンから開く AI チャットのパネルを追加してください。モデルを選び、メッセージを送り、返信を止め、あとで会話を続けられるようにしてください。各自が自分のチャットだけを見られるようにしてください。

ページを組み込んだら、Models → Add service でサービスを追加します。この例では次を使います。

Fetch models をクリックし、自分のアカウントで利用できる chat のモデルを選びます。embedding と rerank のモデルは会話には使えません。Test connection を実行し、成功したら保存します。サービスを開き直したとき、キーのフィールドを空にしておくと、保存済みのキーが保たれます。サービスの設定については DeepSeek のドキュメント を参照してください。

ヘッダーの Agent chat をクリックし、モデルを選んでメッセージを試します。

この機能の紹介を一文で書いてください：アプリの中で AI とチャットし、戻ってきたときに会話を続けられる。

完了の条件返信が届き、Conversations から会話を開き直しても履歴を読めること。

モデル API の会話には、Machine agents の項目は必要ありません。注文を照会したり承認を処理したりするには、関連する業務のツールと認可を組み込みます。

シナリオ 2：業務のスキルを使ってリリースノートを生成する

チームの文章のルールを業務のスキルとして保存し、専用の会話で再利用します。開発の依頼は、たとえば次のとおりです。

「Draft release notes」ボタンを追加してください。私が提供する変更点とテスト結果を、チームの形式で下書きにしてください。足りない詳細をでっち上げたり、直接公開したりしないでください。

この例の release-notes スキルは、スタイルガイドを読んでから、Summary、Changes、Verification のセクションを作ります。テスト結果が提供されなければ、Verification not provided と書きます。文章を下書きするだけで、プロジェクトのファイルを変更したり公開したりはしません。

1. サンプルのスキルをダウンロード し、Skills → Import でインポートして、その slug が release-notes であることを確認します。
2. ページで、SKILL.md と補助ファイルの references/style.md を確認します。
3. ヘッダーのファイルのアイコン Draft release notes をクリックし、このスキルを使う会話を開きます。

この入口は、有効なサービスから最初の chat のモデルを選びます。送信の前に切り替えることもできます。クリックするたびに新しい会話が作られます。既存の下書きを続けるには Conversations を使います。通常の Agent chat の入口では、このスキルは自動では選ばれません。

新しい会話で次を試します。

チームのルールで英語のリリースノートを書いてください。モデルの設定とチャットのパネルを追加し、Skills のメニューの項目がない問題を修正し、関連する 17 件のテストに合格しました。

これらの変更点とテストの件数は文章の材料です。プロジェクトの実際の結果に置き換えてください。文章をまとめることは、エージェントがテストを実行したことを意味しません。

完了の条件下書きがチームの形式に従い、提供した事実だけを含み、実際のツールの記録でスキルと補助ファイルが読まれたことを確認できること。

入口が開かない場合は、モデルが利用できるか、スキルの slug、サーバーの Provider の登録を確認してください。エラーのフィードバックと再試行のロジックは client/components/release-notes-button.tsx にあります。

シナリオ 3：マシン上のコーディングアシスタントを呼び出す

PC やサーバー上のコーディングツールを接続すると、アプリからタスクを送り、進捗と結果を確認できます。開発用のプロンプト：

私のマシン上のコーディングアシスタントを接続して、アプリから利用できるアシスタントを選び、タスクを送り、その進捗と結果を確認できるようにしてください。

配布物を準備する。 このサンプルは、アプリの CLI と Runner の依存関係と設定をすでに宣言しています。サンプルのディレクトリで実行します。

pnpm nocobase cli build --universal
pnpm nocobase cli build --runner --universal

コマンドには npm へのアクセスが必要で、対象のマシンには Node.js 24 が必要です。配布物は storage/runners/dist に書き出されます。初回のセットアップ後にアプリを再起動します。これらのコマンドは、本番のアプリをビルドしません。

マシンを接続する。

1. 対象のマシンにコーディングツールをインストールしてサインインします。ツールが単独で動くことを確認します。
2. Runtimes で個人用または共有の接続を作成し、許可するコーディングツールを選びます。
3. ページのインストールと Runner の登録の手順に従います。ツール、サインイン、モデルの報告を待ちます。
4. Machine agents で、利用できるツールとモデルの組み合わせを追加して有効にします。マシンがオンラインでも、エージェントが有効になっているわけではありません。
5. Agent chat → Switch to runner agents を開き、エージェントを選びます。

マシン上のエージェントは、Models のキーとは別に、コーディングツールのモデルの認証情報を使います。タスクが始まらない場合は、ツールのサインイン、モデルが利用できるか、エージェントの有効化、実行の枠、ローカルの方針を確認してください。

まずワークスペースについて尋ねます。

今どの作業ディレクトリにいて、どんなファイルがありますか？見るだけで、何も変更しないでください。

完了の条件記録に実行したコマンド、作業ディレクトリ、出力が含まれ、実行が completed になっていること。

通常の Runner の会話には専用のワークスペースがあり、アプリのソースに自動で入ることはありません。業務のプロジェクトで作業するには、チャットで入力されたホストのパスを信頼するのではなく、サーバーが認可したプロジェクトのディレクトリをアプリが提供する必要があります。組み込んだら、小さなタスクを試します。

このプロジェクトのチャットのボタンに、英語と中国語のツールチップのテキストを追加してください。ほかの動作は同じままにしてください。

プロジェクトのタスクでは、コードの差分とチェックの結果も確認します。この例で検証したのは会話のワークスペースでの読み取り専用の実行だけで、プロジェクトの編集やビルドは検証していません。

主な仕組みと実装

ファイルと画面の関係

モデルの設定、インポートしたスキル、チャットの履歴は実行時のデータで、ソースの配布物には含まれません。サンプルを起動したら、モデルを設定してスキルをインポートしてください。

プラグインと管理ページを登録する

ここで使う Default テンプレートには、すでに Agents の依存関係が含まれていますが、登録はされていません。これらのコマンドで登録し、データベースの変更をプレビューして適用します。

pnpm nocobase plugin register agents --dry-run --json
pnpm nocobase plugin register agents --json
pnpm nocobase db apply --dry-run --json
pnpm nocobase db apply --json

登録により、3 つのプラグインの一覧が更新されます。データベースのコマンドは、プラグインのマイグレーションとシードデータを適用します。一般的なインストールとアップグレードの手順については プラグインを管理する を参照してください。

client/routes.ts で、管理ページをアプリに組み込みます。

たとえば、Models にメニューのラベルとアイコンを追加します。

import { BrainCircuit } from 'lucide-react';
import { modelsRoute } from '@nocobase/app-plugin-agents/client/routes';

// Use this entry inside the application's existing defineAppRoutes contribution.
const modelsPage = {
  ...modelsRoute,
  navigation: { title: 'agentDemo.models', icon: BrainCircuit },
};

modelsRoute を展開すると、そのページのコンポーネント、サインインの要件、認可、子ルートが保たれます。ほかのページも同じように組み立て、元の appRoutes と一緒にエクスポートします。/main などのデプロイの接頭辞はランタイムが扱うので、ページのパスには含めないでください。メニューがない場合は、ルートの登録とユーザーの権限を確認してください。Models は settings:agents.services の認可を使います。

チャットのコンポーネントとアカウントの状態

このサンプルは、Registry からチャットの画面をインストールしています。

pnpm exec shadcn add @nocobase/agent-chat

pnpm add @nocobase/app-plugin-agents@1.0.0-beta.29 --save-exact
pnpm nocobase skills sync --dry-run --json
pnpm nocobase skills sync --json

プラグインの client/chat は会話の状態とフックを提供し、Registry のコンポーネントがそれを表示します。ほかのレイアウトのコンポーネントは下では省いています。

<AgentsProvider>
  {/* Preserve the application's existing layout and route providers. */}
  <header><ChatHeaderButton /></header>
  <div className="relative flex min-h-0 flex-1">
    <main className="relative min-w-0 flex-1 overflow-hidden">
      <Outlet />
    </main>
    <ChatPanel />
  </div>
  <ChatFloatingButton />
</AgentsProvider>

ChatPanel は main の横に置かれます。ヘッダーとモバイルのボタンは会話の状態を共有します。

AgentsProvider はこのサンプルが所有するコンポーネントで、プラグインの ChatProvider を包んでいます。サインインしたユーザーの ID を React の key と memoryScope に使い、身元が変わるとクエリーのキャッシュとパネルの状態をクリアして、前のアカウントのチャットを再利用しないようにしています。サーバーも引き続き、会話の所有とアクセスを確認します。

業務の会話でスキルを選ぶ

プロジェクトの .agents/skills/ にある開発用のスキルは、コーディングツールがプラグインを組み込むのを導きます。アプリの Skills ライブラリーにある業務のスキルは、実行時のタスクを導きます。両者が自動で同期されることはありません。

リリースノートのスキルには、SKILL.md と references/style.md が含まれます。インポート後、server/providers/agents.ts が名前付きのスコープでそれを選び、server/providers/index.ts が Provider を読み込みます。主要なコードは次のとおりです。

const agents = this.app.container.resolve(agentsToken);
agents.onlineAgent.configurator.registerOnlineAgentScope(
  'release-notes',
  async () => {
    const skill = (await agents.skills.list()).find(
      (item) => item.slug === 'release-notes',
    );
    if (!skill)
      throw new Error('Create the release-notes Skill before using this scope.');
    return {
      agentId: 'online',
      tool: ['bash', 'skill'],
      skill: [skill.id],
      systemPromptTemplate:
        'Help write release notes from the supplied facts. Use the release-notes Skill and its supporting style guide when the user requests release notes. Never claim an unperformed check succeeded.',
    };
  },
);

agentsToken はプラグインの公開のサービスの入口です。サーバーは、slug で 1 つのスキルと、それを読むのに必要な skill と bash のツールを選びます。systemPromptTemplate はリリースノートのルールを加えます。スコープは機能を選ぶもので、業務上の権限は付与しません。

ReleaseNotesButton は、認証済みのアプリの API クライアントを使い、次のボディを POST /api/agents/conversations に送ります。

{
  "agentId": "online",
  "title": "Draft release notes",
  "config": { "scope": ["release-notes"] },
  "selectedModel": { "modelService": "deepseek", "model": "deepseek-flash" }
}

作成後、ボタンは panel.openChat({ conversationId }) を呼び出して会話を開きます。modelService は設定済みのサービスを識別し、model はそのサービスで有効になっている必要があります。release-notes のスコープのない通常の会話では、このスキルは自動では選ばれません。

Skills ページの Global attachment は、以降の Runner のタスクにスキルをまとめて加えます。モデル API の会話のスキルは選ばないため、上のサーバーのスコープが必要です。

実行とツールへのアクセス

コードでは、agentId: 'online' は native という名前のモデル API のバックエンドを選びます。マシンのタスクは、特定のエージェントの ID と runner のバックエンドを使います。どちらも agentsToken.onlineAgent の会話のサービスを共有します。モデル API のバックエンドは、JSON Schema による構造化されたバックグラウンドの実行にも対応しています。Runner には独自のタスクのキューがあり、そのバックグラウンドのインターフェースには対応していません。

モデル API のバックエンドの仮想シェルは、/skills を読み、/tmp に書き込めます。ホストのファイルシステムにはアクセスできず、プロジェクトの Node、Python、ビルド、テストを直接実行することもできません。注文の照会などの業務操作には、サーバー側で身元、入力、データアクセスを確認する、登録されたツールか許可された CLI のコマンドが必要です。タスクにドキュメントの検索が必要な場合は、ナレッジベース を追加します。

AI 開発の制約と検証

組み込みの際に確認すること

開発用のエージェントは、インストールされた .agents/skills/nocobase-app-plugin-agents/SKILL.md と、タスクに関係するリファレンスを読むべきです。依存関係をインストールまたはアップグレードしたら、pnpm nocobase skills sync を実行し、公開のエクスポートと型を確認します。ガイダンスと実装が異なる場合は、インターフェースを確認してから使ってください。

Runner のアクセスはマシンとコーディングツールの方針に依存し、Runner 自体はファイルシステムのサンドボックスではありません。プロンプトとスキルは、コードレベルの認可や実行時の検証の代わりにはなりません。

組み込みを確認する

まず、よくある操作の確認を開発用のエージェントに依頼します。

チャットの返信が動作し、開き直しても履歴が残っていることを確認してください。アカウントを切り替えたら、前の人のチャットから何か見えてしまいませんか？

業務のスキルやマシンのタスクを追加した場合は、上の表の該当する行も確認します。モデルの主張は、正しい設定、スキルの使用、コードの実行を証明しません。接続の状態、ツールの記録、実際の結果を確認してください。

サンプルのアプリのディレクトリで、関連する自動テストを実行します。

pnpm exec vitest run tests/client/client-routes.test.ts tests/client/app-locale-coverage.test.ts tests/client/page-permission-titles.test.ts tests/client/release-notes-button.test.tsx

引き渡しの前に、プロジェクトのチェックに従って pnpm check を実行し、パッケージのチェック、lint、フォーマット、型、テスト、ビルドを網羅します。ケースと結果を確認してください。テストが見つからないまま正常終了しても、検証にはなりません。ほかの方法については テスト を参照してください。

サンプルの検証の範囲

これらの結果は、2026-10-29 に、Default テンプレート 1.0.0-beta.84、Agents 1.0.0-beta.29、SQLite、DeepSeek deepseek-flash、Runner 0.1.0-beta.20、Codex 0.165.0 を使って記録したものです。

完全な pnpm check、本番のビルドとデプロイ、複数アカウントでのブラウザーの検収、ロールの全組み合わせ、業務の書き込み、添付ファイルの解析、プロジェクトの編集とビルドは未検証のままです。狭い画面とダークのページは限定的に確認しただけで、中国語の IME、言語とモバイルの全組み合わせ、モデルのストリーミングの停止も完全には検証していません。このガイドの簡略化したプロンプトは再実行しておらず、スクリーンショットと結果は元の会話のものです。

サンプルのソース

• 完全なサンプル：コミット b91adc8 に固定され、3 つのシナリオの組み込みのコードを含みます。
• セットアップと検証：バージョン、インストール、起動、テスト、制限。
• ソースの ZIP をダウンロード：そのコミットに一致し、シークレット、実行時のデータ、依存関係を除いています。