arcgis-ai-components

ArcGIS AI Components

在为 Web 地图添加 AI 助手功能、让用户能够通过自然语言聊天与地图数据交互时，请使用此功能。这是 5.0 中的新软件包（@arcgis/ai-components），在 4.x 中没有对应版本。

Beta： AI Components 在 5.0 中处于 Beta 阶段。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 助手采用组件 + Agent架构：

• arcgis-assistant - 聊天 UI 容器。管理对话，将用户消息路由到已注册的 Agent，并显示回复。
• Agent 组件 - 助手的插槽子组件。每个 Agent 负责特定领域（导航、数据探索、帮助）。助手会协调由哪个 Agent 处理每个查询。

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 选择器或元素引用。为 Agent 提供地图上下文。
heading	heading	string	-	显示在助手面板顶部的标题
description	description	string	-	描述助手功能的副标题文本
entryMessage	entry-message	string	-	用户开始聊天前显示的欢迎消息
suggestedPrompts	-	string[]	-	以可点击标签形式显示的建议提示词数组（仅通过 JS 设置）
keepSuggestedPrompts	keep-suggested-prompts	boolean	false	用户提交消息后仍保留显示建议提示词
feedbackEnabled	feedback-enabled	boolean	false	在助手消息上显示赞成/反对反馈按钮
logEnabled	log-enabled	boolean	false	显示 Agent 执行日志（工具调用、推理步骤）
copyEnabled	copy-enabled	boolean	false	允许用户复制助手消息内容
messages	-	ChatMessage[]	[]	对话历史记录（可读/可写）

方法

方法	返回值	描述
clearChatHistory()	void	清除对话并重置助手
submitMessage(message)	void	以编程方式向助手提交用户消息
componentOnReady()	Promise<this>	在组件完全加载后解析

事件

事件	详情	描述
arcgisSubmit	{ message: string }	用户提交消息时触发
arcgisReady	-	助手初始化并就绪时触发
arcgisFeedback	AssistantMessage	用户对消息提供反馈时触发
arcgisError	Error	Agent 执行期间发生错误时触发
arcgisInterrupt	-	用户中断正在进行的响应时触发
arcgisInterruptCancel	-	取消中断时触发
arcgisInterruptSubmit	-	中断期间提交新消息时触发
arcgisCancel	-	取消处理时触发

内置 Agent

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

回答有关地图、图层、元数据以及其他已注册 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");

自定义 Agent

使用 arcgis-assistant-agent 向助手注册自定义 Agent。

定义自定义 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>

自定义 Agent 的实用函数

函数	说明
invokeTextPrompt(options)	向大模型发送文本提示词并获取文本响应
invokeStructuredPrompt(options)	发送提示词并获取结构化（JSON）响应
invokeToolPrompt(options)	发送包含工具定义的提示词以调用函数
sendTraceMessage(data)	将跟踪／调试消息发送到助手日志
getEmbeddings(texts)	生成文本嵌入向量，用于语义搜索
cosineSimilarity(a, b)	计算两个嵌入向量之间的余弦相似度

AI Agent 的 Web 地图要求

要让 Agent 在 Web 地图上有效工作：

1. 图层元数据 - 图层必须包含完善的元数据（描述、字段别名、标签）。
2. 嵌入向量 - Web 地图应将嵌入向量存储为项目资源。详情请参阅 Web 地图设置指南。
3. 用户要求：
   • 已登录 ArcGIS Online 组织的具名用户（不包括试用版／公共账户）
   • 用户必须有权访问 Web 地图及其图层
   • 必须在组织设置中启用 AI 助手
   • 不得在组织设置中屏蔽 Beta 应用
   • 用户必须具有使用 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 元素，为 Agent 提供上下文。

   
   <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>
   

   影响： Agent 无法获取地图上下文，也无法执行导航或数据查询。它们可能静默失败或返回错误。

2. 未注册 Agent：助手本身没有内置智能——必须至少添加一个 Agent 组件。

   
   <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 具名用户。匿名用户或公共用户无法使用助手。

   影响： 助手面板可能会显示，但 Agent 调用会因身份验证错误而失败。显示助手界面之前，请务必检查身份验证状态。

4. 图层元数据不完善：Agent 依靠图层描述、字段别名和嵌入向量来理解地图数据。缺少元数据的图层会导致响应质量低下或内容无关。

   影响： 数据探索 Agent 可能会误认字段或给出不准确的摘要。

5. 将 suggestedPrompts 设置为 HTML 属性：suggestedPrompts 属性接受数组，只能通过 JavaScript 设置，不能作为 HTML 属性设置。

   
   <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 - 包含导航、数据探索和帮助 Agent 的 AI 助手组件

相关技能

• 查看 arcgis-core-maps，了解如何设置助手引用的地图。
• 查看 arcgis-widgets-ui，了解 Calcite 布局组件（calcite-shell、calcite-shell-panel）。
• 查看 arcgis-interaction，了解非 AI 的地图交互方式（弹出窗口、命中测试）。