arcgis-ai-components

ArcGIS AI Components

自然言語チャットを通じてユーザーがマップデータを操作できるように、Web マップに AI アシスタント機能を追加する場合は、このスキルを使用してください。これは 5.0 の新しいパッケージ（@arcgis/ai-components）で、4.x に相当するものはありません。

ベータ版： AI Components は 5.0 時点でベータ版です。API は今後のリリースで変更される可能性があります。

インポートパターン

CDN（AI Components に推奨）

SDK の CDN 経由で読み込むと、AI コンポーネントは自動的に登録されます。

<script type="module" src="https://js.arcgis.com/5.0/"></script>

ESM の直接インポート（ビルドツール）

import "@arcgis/ai-components/components/arcgis-assistant";
import "@arcgis/ai-components/components/arcgis-assistant-navigation-agent";
import "@arcgis/ai-components/components/arcgis-assistant-data-exploration-agent";
import "@arcgis/ai-components/components/arcgis-assistant-help-agent";
import "@arcgis/ai-components/components/arcgis-assistant-agent";

ユーティリティ関数

import {
  invokeTextPrompt,
  invokeStructuredPrompt,
  invokeToolPrompt,
  sendTraceMessage,
  getEmbeddings,
  cosineSimilarity,
} from "@arcgis/ai-components/utils";

コアアーキテクチャ

AI アシスタントは、コンポーネント＋エージェントのアーキテクチャを使用します。

• arcgis-assistant - チャット UI コンテナーです。会話を管理し、ユーザーメッセージを登録済みのエージェントに振り分け、応答を表示します。
• エージェントコンポーネント - アシスタントのスロットに配置する子要素です。各エージェントは、ナビゲーション、データ探索、ヘルプなど、特定の領域を担当します。アシスタントは各クエリをどのエージェントが処理するかを調整します。

arcgis-assistant
  ├── arcgis-assistant-navigation-agent      (pan, zoom, go to locations)
  ├── arcgis-assistant-data-exploration-agent (query data, statistics, charts)
  ├── arcgis-assistant-help-agent            (answer questions about the map/agents)
  └── arcgis-assistant-agent                 (custom agent wrapper)

基本設定

最小限の例（CDN）

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>AI Assistant</title>
    <script type="module" src="https://js.arcgis.com/5.0/"></script>
    <style>
      html,
      body {
        height: 100%;
        margin: 0;
      }
    </style>
  </head>
  <body>
    <calcite-shell>
      <arcgis-map id="my-map" item-id="c13bffcad4a244a99062e915e9bc1dc3">
        <arcgis-zoom slot="top-left"></arcgis-zoom>
      </arcgis-map>
      <calcite-shell-panel slot="panel-end" width="l">
        <calcite-panel>
          <arcgis-assistant
            reference-element="#my-map"
            heading="Map Assistant"
            description="Ask questions about the data on this map."
            entry-message="Hello! I can help you explore this map."
          >
            <arcgis-assistant-navigation-agent></arcgis-assistant-navigation-agent>
            <arcgis-assistant-data-exploration-agent></arcgis-assistant-data-exploration-agent>
            <arcgis-assistant-help-agent></arcgis-assistant-help-agent>
          </arcgis-assistant>
        </calcite-panel>
      </calcite-shell-panel>
    </calcite-shell>
  </body>
</html>

arcgis-assistant コンポーネント

プロパティ

プロパティ	属性	型	デフォルト	説明
referenceElement	reference-element	string | HTMLArcgisMapElement	-	必須。 arcgis-map の CSS セレクターまたは要素への参照です。エージェントにマップのコンテキストを提供します。
heading	heading	string	-	アシスタントパネルの上部に表示されるタイトル
description	description	string	-	アシスタントの機能を説明するサブタイトル
entryMessage	entry-message	string	-	ユーザーがチャットを開始する前に表示されるウェルカムメッセージ
suggestedPrompts	-	string[]	-	クリック可能なチップとして表示されるおすすめのプロンプトの配列（JavaScript からのみ設定可能）
keepSuggestedPrompts	keep-suggested-prompts	boolean	false	ユーザーがメッセージを送信した後も、おすすめのプロンプトを表示したままにします
feedbackEnabled	feedback-enabled	boolean	false	アシスタントのメッセージに「高評価／低評価」のフィードバックボタンを表示します
logEnabled	log-enabled	boolean	false	エージェントの実行ログ（ツール呼び出し、推論手順）を表示します
copyEnabled	copy-enabled	boolean	false	ユーザーがアシスタントのメッセージ内容をコピーできるようにします
messages	-	ChatMessage[]	[]	会話履歴（読み取り／書き込み可能）

メソッド

メソッド	戻り値	説明
clearChatHistory()	void	会話を消去し、アシスタントをリセットします
submitMessage(message)	void	ユーザーメッセージをプログラムからアシスタントに送信します
componentOnReady()	Promise<this>	コンポーネントの読み込みが完了すると解決します

イベント

イベント	詳細	説明
arcgisSubmit	{ message: string }	ユーザーがメッセージを送信したときに発生します
arcgisReady	-	アシスタントが初期化され、準備が整ったときに発生します
arcgisFeedback	AssistantMessage	ユーザーがメッセージにフィードバックを提供したときに発生します
arcgisError	Error	エージェントの実行中にエラーが発生したときに発生します
arcgisInterrupt	-	ユーザーが処理中の応答を中断したときに発生します
arcgisInterruptCancel	-	中断がキャンセルされたときに発生します
arcgisInterruptSubmit	-	中断中に新しいメッセージが送信されたときに発生します
arcgisCancel	-	処理がキャンセルされたときに発生します

組み込みエージェント

arcgis-assistant-navigation-agent

地図のナビゲーション要求に対応します。パン、ズーム、特定の場所やフィーチャへの移動を行います。

<arcgis-assistant reference-element="#my-map">
  <arcgis-assistant-navigation-agent></arcgis-assistant-navigation-agent>
</arcgis-assistant>

ユーザープロンプトの例：「ニューヨーク市にズーム」「最大のフィーチャに移動」「北にパン」

プロパティ：

プロパティ	属性	型	説明
referenceElement	reference-element	string | HTMLArcgisMapElement	地図の参照を上書きします（設定されていない場合は、親アシスタントから継承します）

arcgis-assistant-data-exploration-agent

レイヤーデータをクエリして分析します。統計、フィルター、フィーチャ数、データの概要を扱います。

<arcgis-assistant reference-element="#my-map">
  <arcgis-assistant-data-exploration-agent></arcgis-assistant-data-exploration-agent>
</arcgis-assistant>

ユーザープロンプトの例：「総人口はいくつですか？」「面積が大きい上位5つのフィーチャを表示」「値が100を超えるフィーチャはいくつありますか？」

プロパティ：

プロパティ	属性	型	説明
referenceElement	reference-element	string | HTMLArcgisMapElement	地図の参照を上書きします

arcgis-assistant-help-agent

地図、そのレイヤー、メタデータ、および登録済みの他のエージェントの機能に関する質問に回答します。

<arcgis-assistant reference-element="#my-map">
  <arcgis-assistant-help-agent></arcgis-assistant-help-agent>
</arcgis-assistant>

ユーザープロンプトの例：「この地図にはどのレイヤーがありますか？」「どのようなことを手伝えますか？」「データについて説明してください」

プロパティ：

プロパティ	属性	型	説明
referenceElement	reference-element	string | HTMLArcgisMapElement	地図の参照を上書きします

アシスタントの設定

推奨プロンプトの設定（JavaScript）

const assistant = document.querySelector("arcgis-assistant");
assistant.suggestedPrompts = [
  "What is the total change in wheat production from 2017 to 2022?",
  "Go to the county that produced the most wheat in 2022.",
  "How many counties produced less wheat in 2022 than in 2017?",
];

開発者向け機能の有効化

<arcgis-assistant
  reference-element="#my-map"
  log-enabled
  copy-enabled
  feedback-enabled
  heading="Data Explorer"
  description="Ask questions about the map data."
  entry-message="Welcome! Try asking about the data."
>
  
</arcgis-assistant>

イベントのリッスン

const assistant = document.querySelector("arcgis-assistant");

assistant.addEventListener("arcgisSubmit", (event) => {
  console.log("User submitted:", event.detail.message);
});

assistant.addEventListener("arcgisFeedback", (event) => {
  const { feedback } = event.detail;
  console.log("Feedback:", feedback); // { positive: true } or { positive: false }
});

assistant.addEventListener("arcgisError", (event) => {
  console.error("Assistant error:", event.detail);
});

プログラムからのメッセージ送信

const assistant = document.querySelector("arcgis-assistant");
await assistant.componentOnReady();

// Submit a message as if the user typed it
assistant.submitMessage("Show me the top 10 features by population");

カスタムエージェント

arcgis-assistant-agent を使用して、アシスタントにカスタムエージェントを登録します。

カスタムエージェントの定義

import { invokeTextPrompt } from "@arcgis/ai-components/utils";

const assistant = document.querySelector("arcgis-assistant");
const customAgent = document.querySelector("arcgis-assistant-agent");

customAgent.agentRegistration = {
  name: "weather-agent",
  description:
    "Answers questions about current weather conditions at map locations.",
  systemPrompt:
    "You are a weather assistant. Use the provided tools to get weather data.",
  tools: [
    {
      name: "getWeather",
      description: "Get current weather for a location",
      parameters: {
        type: "object",
        properties: {
          latitude: { type: "number", description: "Latitude" },
          longitude: { type: "number", description: "Longitude" },
        },
        required: ["latitude", "longitude"],
      },
      execute: async ({ latitude, longitude }) => {
        const response = await fetch(
          `https://api.weather.gov/points/${latitude},${longitude}`,
        );
        const data = await response.json();
        return JSON.stringify(data.properties);
      },
    },
  ],
};

<arcgis-assistant reference-element="#my-map">
  <arcgis-assistant-agent></arcgis-assistant-agent>
  <arcgis-assistant-navigation-agent></arcgis-assistant-navigation-agent>
</arcgis-assistant>

カスタムエージェント向けユーティリティ関数

関数	説明
invokeTextPrompt(options)	テキストプロンプトを LLM に送信し、テキスト応答を取得します
invokeStructuredPrompt(options)	プロンプトを送信し、構造化された（JSON）応答を取得します
invokeToolPrompt(options)	関数呼び出し用のツール定義を含むプロンプトを送信します
sendTraceMessage(data)	トレース／デバッグメッセージをアシスタントのログに送信します
getEmbeddings(texts)	セマンティック検索用のテキスト埋め込みを生成します
cosineSimilarity(a, b)	2 つの埋め込みベクトル間のコサイン類似度を計算します

AI エージェント向け Web マップの要件

エージェントが Web マップを効果的に利用するには、次の要件があります。

1. レイヤーのメタデータ - レイヤーには適切なメタデータ（説明、フィールドのエイリアス、タグ）が必要です。
2. 埋め込み - Web マップには、アイテムリソースとして保存された埋め込みが必要です。詳細については、Web マップのセットアップガイドを参照してください。
3. ユーザー要件：
   • ArcGIS Online 組織のサインイン済みの名前付きユーザーであること（トライアルアカウントやパブリックアカウントは不可）
   • ユーザーが Web マップとそのレイヤーにアクセスできること
   • 組織の設定で AI アシスタントが有効になっていること
   • 組織の設定でベータアプリがブロックされていないこと
   • AI アシスタントを使用する権限がユーザーのロールに付与されていること

レイアウトパターン

サイドパネルレイアウト（推奨）

<calcite-shell>
  <arcgis-map id="map" item-id="YOUR_WEBMAP_ID">
    <arcgis-zoom slot="top-left"></arcgis-zoom>
    <arcgis-expand slot="top-left">
      <arcgis-legend></arcgis-legend>
    </arcgis-expand>
  </arcgis-map>
  <calcite-shell-panel slot="panel-end" width="l">
    <calcite-panel>
      <arcgis-assistant
        reference-element="#map"
        heading="Map Assistant"
        entry-message="Ask me anything about this map."
      >
        <arcgis-assistant-navigation-agent></arcgis-assistant-navigation-agent>
        <arcgis-assistant-data-exploration-agent></arcgis-assistant-data-exploration-agent>
        <arcgis-assistant-help-agent></arcgis-assistant-help-agent>
      </arcgis-assistant>
    </calcite-panel>
  </calcite-shell-panel>
</calcite-shell>

ウィジェット展開レイアウト

<arcgis-map id="map" item-id="YOUR_WEBMAP_ID">
  <arcgis-zoom slot="top-left"></arcgis-zoom>
  <arcgis-expand slot="top-right">
    <arcgis-assistant
      reference-element="#map"
      heading="Assistant"
      entry-message="How can I help?"
    >
      <arcgis-assistant-navigation-agent></arcgis-assistant-navigation-agent>
      <arcgis-assistant-data-exploration-agent></arcgis-assistant-data-exploration-agent>
      <arcgis-assistant-help-agent></arcgis-assistant-help-agent>
    </arcgis-assistant>
  </arcgis-expand>
</arcgis-map>

よくある落とし穴

1. reference-element がない：アシスタントがエージェントにコンテキストを提供するには、arcgis-map 要素への参照が必要です。

   
   <arcgis-assistant heading="Assistant">
     <arcgis-assistant-navigation-agent></arcgis-assistant-navigation-agent>
   </arcgis-assistant>
   <arcgis-map id="map" item-id="abc123"></arcgis-map>
   

   
   <arcgis-assistant reference-element="#map" heading="Assistant">
     <arcgis-assistant-navigation-agent></arcgis-assistant-navigation-agent>
   </arcgis-assistant>
   <arcgis-map id="map" item-id="abc123"></arcgis-map>
   

   **影響：**エージェントはマップのコンテキストを得られず、ナビゲーションやデータクエリを実行できません。エラーが表示されずに失敗するか、エラーを返します。

2. エージェントが登録されていない：アシスタント自体に組み込みのインテリジェンスはないため、少なくとも 1 つのエージェントコンポーネントを組み込む必要があります。

   
   <arcgis-assistant reference-element="#map" heading="Assistant">
   </arcgis-assistant>
   

   
   <arcgis-assistant reference-element="#map" heading="Assistant">
     <arcgis-assistant-navigation-agent></arcgis-assistant-navigation-agent>
     <arcgis-assistant-data-exploration-agent></arcgis-assistant-data-exploration-agent>
     <arcgis-assistant-help-agent></arcgis-assistant-help-agent>
   </arcgis-assistant>
   

   **影響：**ユーザーはメッセージを入力できますが、処理されることはありません。応答も生成されません。

3. 認証されていないユーザー：AI コンポーネントには、AI アシスタントの権限を持つ、サインイン済みの ArcGIS Online 名前付きユーザーが必要です。匿名ユーザーやパブリックユーザーはアシスタントを使用できません。

   **影響：**アシスタントパネルは表示される場合がありますが、エージェントの呼び出しは認証エラーで失敗します。アシスタントの UI を表示する前に、必ず認証状態を確認してください。

4. レイヤーのメタデータが不十分：エージェントは、マップデータを理解するためにレイヤーの説明、フィールドのエイリアス、埋め込みを利用します。メタデータが不足しているレイヤーでは、応答の質が低下したり、的外れな応答になったりします。

   **影響：**データ探索エージェントがフィールドを誤認したり、不正確な要約を提示したりすることがあります。

5. suggestedPrompts を HTML 属性として設定している：suggestedPrompts プロパティは配列を受け取るため、HTML 属性ではなく JavaScript で設定する必要があります。

   
   <arcgis-assistant suggested-prompts="What is the total?"></arcgis-assistant>
   

   // Correct: set via JavaScript
   const assistant = document.querySelector("arcgis-assistant");
   assistant.suggestedPrompts = [
     "What is the total population?",
     "Go to the largest city",
   ];
   

   **影響：**HTML 属性の文字列として設定された場合、提案プロンプトは何も通知されずに無視されます。

参考サンプル

• ai-assistant - ナビゲーション、データ探索、ヘルプの各エージェントを備えた AI アシスタントコンポーネント

関連スキル

• アシスタントが参照するマップのセットアップについては、arcgis-core-maps を参照してください。
• Calcite レイアウトコンポーネント（calcite-shell、calcite-shell-panel）については、arcgis-widgets-ui を参照してください。
• マップ操作の非 AI アプローチ（ポップアップ、ヒットテスト）については、arcgis-interaction を参照してください。