SuiteHub/agent-profiles
4
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6465e27d2238bd04f4f847457b35574a32fb9806
agent-profiles/research/carto-for-agents-architecture-notes.md
T

18 KiB
Raw Blame History

🏗️ CARTO for Agents — 架构研究笔记

分析日期: 2026-07-21 研究者: Huawei 目的: 提取 CARTO for Agents 架构思路，对照 AgentGIS Cloud Platform，发现可借鉴的方向

一、总体架构图

┌────────────────────────────────────────────────────────────────────┐
│                    CARTO for Agents 三层能力                        │
├────────────────────────────────────────────────────────────────────┤
│                                                                    │
│  🧑 人机界面层                                                     │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │  Claude.ai │ ChatGPT │ Gemini │ Claude Desktop │ MCP Inspector│  │
│  └──────────────┬───────────────────────────┬──────────────────┘  │
│                 │                           │                      │
│  ┌──────────────▼──────────────┐ ┌──────────▼──────────────┐      │
│  │    CARTO MCP Server         │ │   CARTO Agent Skills    │      │
│  │    (托管 MCP Server)        │ │   (本地技能 playbook)   │      │
│  │                            │ │                          │      │
│  │  - Platform tools          │ │  Utility Tier            │      │
│  │  - Interactive tools       │ │  Platform Tier           │      │
│  │  - Workflows as MCP Tools  │ │  Use-case Pattern Tier   │      │
│  └──────────────┬──────────────┘ └──────────┬──────────────┘      │
│                 │                           │                      │
│                 └──────────┬────────────────┘                     │
│                            │ 调用                                 │
│                 ┌──────────▼──────────────┐                       │
│                 │      CARTO CLI          │                       │
│                 │   (@carto/carto-cli)    │                       │
│                 │   npm install -g        │                       │
│                 └──────────┬──────────────┘                       │
│                            │                                      │
└────────────────────────────┼──────────────────────────────────────┘
                             │
              ┌──────────────┴──────────────┐
              │       数据/计算层            │
              │  BigQuery / Snowflake /     │
              │  Redshift / Databricks /    │
              │  Oracle（数据永不离开）       │
              └─────────────────────────────┘

二、三大组件的精要分析

2.1 CARTO CLI —— 平台能力的"API 化"

不是普通的 CLI。 它是一个完整覆盖 CARTO 平台操作的命令集合，设计上同时面向人类和 Agent。

关键设计点：

设计特征 说明 对我们的启发
一人一 Agent 通用 同一个 carto 命令，人类在终端用，Agent 在 shell 调用 ✅ agc CLI 已经走在这条路上
输出可编程 JSON 输出，Agent 直接解析 ✅ 我们的 agc 应统一输出格式
连接管理 carto credentials create token/spa/m2m — Agent 自动创建作用域精细的令牌 ⚠️ 我们现在 API Key 是手动管理
无状态 每次调用通过本地 profile 认证，不维护与 Agent 的持久会话 ✅ 符合我们的设计

核心洞察： CLI 是 Agent 访问平台能力的最小公约数接口。Agent 不需要理解 REST API 的路径、认证头、分页逻辑——只需 carto <verb> <noun> <flags>。

2.2 CARTO MCP Server —— 标准化协议接入

MCP（Model Context Protocol）是 Anthropic 提出、逐渐成为事实标准的 AI <-> 工具协议。CARTO 建了一个托管 MCP Server，把平台能力暴露给任何兼容 MCP 的客户端。

三类工具设计：

Platform tools                    Interactive tools                Workflows tools
┌──────────────────────┐        ┌──────────────────────┐        ┌──────────────────────┐
│ list_connections     │        │ view_map             │        │ run_workflow         │
│ browse_tables        │        │ load_builder_map     │        │ get_workflow_status  │
│ describe_table       │        │                      │        │ get_workflow_results │
│ search_maps          │        │ 返回交互式地图嵌入     │        │                      │
│                      │        │ 仅 MCP Apps 客户端    │        │ 同步/异步模式         │
│ 返回 JSON → Agent 推理 │       │ 支持内联渲染          │        │                      │
└──────────────────────┘        └──────────────────────┘        └──────────────────────┘

关键设计决策：

  • 用 OAuth（U2M/M2M）作为主要认证方式，API Token 为辅
  • SSO 企业用户通过独立 URL 入口
  • 支持把已发布的工作流暴露为 MCP Tool（这是精髓——见下文 4.1 节）

2.3 CARTO Agent Skills —— 专家知识的封装

这是最值得我们借鉴的模块。不是给 Agent 喂一堆文档让它自己悟，而是把领域的专业知识编码成可加载的 playbook。

三层架构设计：

Use-case Pattern Tier          ← 用户自然语言触发（"做个热点分析"）
    ├── carto-hotspot-analysis
    ├── carto-spatial-autocorrelation
    ├── carto-site-selection
    ├── carto-trade-area-analysis
    ├── carto-gwr
    ├── carto-composite-scoring
    ├── carto-spatial-enrichment
    ├── carto-routing-od-analysis
    ├── carto-territory-planning
    ├── carto-geocoding
    └── carto-arcgis-migration      ← 甚至覆盖了从 Esri 迁移这个复杂场景
               ↑ 依赖
Platform Tier                  ← 按产品面组织
    ├── carto-create-workflow
    ├── carto-manage-builder-maps
    ├── carto-import-export-data
    ├── carto-data-observatory
    ├── carto-develop-app          ← vibe coding 完整空间应用
               ↑ 依赖
Utility Tier                   ← 基础原语
    ├── install & auth
    ├── sql query
    ├── explore data
    └── (被其他技能作为依赖加载)

每个 skill 的触发方式不是硬编码的，而是通过关键词匹配 + 用户意图自动路由。Agent 从用户请求中识别"hotspot"→ 自动加载 carto-hotspot-analysis。

这就是把分析师多年的经验编码成 Agent 能直接遵守的 playbook，省去了每次从头探索 API 的试错成本。

三、对我们 AgentGIS 平台的架构启发

🔑 启发一：把平台能力包装成 CLI + Skill 双接口

现状： 我们已经有 agc CLI，但 Agent 集成主要靠 API Key 直接调 suite-market API。

建议方向：

AI Agent (Claude Code / Codex / 自研)
    │
    ├── 直接调 API → 能力完整但 Agent 需要"学习"REST 语义
    │
    └── agc <subcommand> <args> → Agent 只需要记一组 CLI 命令
    │
    └── Agent Skill playbook → 告诉 Agent "做 xx 分析时，先用哪个命令，再做什么"

具体来说：

  1. agc CLI 补全：目前只跑套件。可以扩展为：
    • agc auth login|token — 认证管理
    • agc suite search|inspect|run — 套件操作
    • agc data import|export|list — 数据管理
    • agc compliance check — 合规检查
    • agc org stats — 组织统计
  2. Skill 目录：在 SuiteHub/agent-profiles 下建 agent-skills/ 目录，写一套针对我们平台的 skill playbook。

⚡ 启发二：MCP Server 暴露平台能力给外部 Agent

现状： Agent 集成方式单一（API Key → suite-market API），且没有标准化协议。

建议方向：

  1. 搭建一个 MCP Server 暴露 AgentGIS 核心能力：
    • list_suites — 搜索可用套件
    • inspect_suite — 查看套件详情（参数说明、版本）
    • run_suite — 触发本地执行（返回执行 ID）
    • check_compliance — 对给定脚本做合规检测
    • query_suite_results — 查询历史执行结果
  2. 这样 Claude / ChatGPT / 自研 Agent 都能通过标准协议接入
  3. 认证用现有 API Key 体系即可（MCP Server 支持 API Token 方式）

🧠 启发三：Agent Skill 三层架构 —— 把领域知识编码为 Playbook

这是最核心的启发。 我们的平台生态天然适合三层 Skill 架构：

┌─ Use-case Tier（分析模式）─────────────────────────────────────┐
│  分析套件（Analysis Suite）                                      │
│  • 地理围栏分析（当用户说"做个围栏分析"）                        │
│  • POI 叠加分析                                                 │
│  • 空间统计（莫兰 I、热点分析）                                  │
│  • 数据质量报告                                                 │
│                                                                │
│  迁移套件（Migration Suite）                                     │
│  • 从某 GIS 平台迁移到 AgentGIS（参考 carto-arcgis-migration）   │
└────────────────────────────────────────────────────────────────┘
                          ↑ 依赖
┌─ Platform Tier（产品操作）──────────────────────────────────────┐
│  • 套件搜索与运行                                               │
│  • 合规检测流程                                                 │
│  • 数据导入导出                                                 │
│  • 发布流程                                                     │
│  • 平台管理（查看健康状态、审计日志）                            │
└────────────────────────────────────────────────────────────────┘
                          ↑ 依赖
┌─ Utility Tier（基础原语）───────────────────────────────────────┐
│  • 安装 & 认证                                                  │
│  • agc CLI 基础命令用法                                         │
│  • 基础镜像操作（docker run 隔离执行理解）                       │
│  • Gitea Packages 下载模式                                      │
└────────────────────────────────────────────────────────────────┘

每个 Skill 文件包含：

  • triggers：触发关键词（Agent 据此自动加载）
  • dependencies：依赖的底层 skill
  • steps：操作步骤，每一步引用具体 CLI 命令
  • examples：示例输入输出

🔐 启发四：Workflow → MCP Tool —— 固化合规的分析流程

这是最惊艳的设计。 CARTO 允许你把一个 Workflow（分析流程）一键发布为 MCP Tool。效果：

  1. 分析师（人）在 Workflows 里搭建、审核、固化分析流程
  2. 一键发布为 MCP Tool → 分析流程变成了一个可调用函数
  3. Agent 只需要提供输入参数，不需要再推导分析逻辑

对应到我们平台：

一个套件（Suite）本质上就是一个固化的分析流程（workflow.yaml + scripts/）。那我们就可以：

  • 允许平台管理员把经过合规检测的套件标记为"可 MCP 调用"
  • 暴露到 MCP Server 上，Agent 直接 run_suite(suite_id, inputs)
  • Agent 不需要知道套件内部怎么运行——只需要知道："我想做围栏分析，传入中心点坐标和半径"

这就解决了 Agent 系统里最核心的张力：概率性推理 ↔ 确定性执行。

  • 不确定性（Agent 推理）→ 决定"做什么"
  • 确定性（已审阅的套件）→ 决定"怎么做"

📋 启发五：语义模型（Sematic Model）—— 告诉 Agent 数据长什么样

CARTO 基于 Apache Ossie 开放标准定义语义模型，扩展了空间字段描述：

# 语义模型核心结构
version: "0.1.1"
semantic_model:
  - name: "数据集描述"
    datasets:
      - name: "table_name"
        fields:
          - name: "geom"
            description: "空间字段业务含义"
            custom_extensions:
              - vendor_name: CARTO
                data: '{"spatial_data": {"type": "polygon", "srid": 4326}}'
    relationships:
      - name: "数据集间关系"
        from/to/ai_context
    metrics:
      - name: "可复用计算指标"
        expression/description

对我们的意义： 如果我们想实现"Agent 根据自然语言描述自动选择合适的套件并填参执行"，语义模型是关键。但目前这个阶段，我们还没有 Agent 直接跟数据仓库交互的需求（套件是封闭的），可以列为中期规划。

🔄 启发六：ARC → AgentGIS 迁移技能

CARTO 做了 carto-arcgis-migration，处理从 Esri 迁移到 CARTO 的全流程。我们平台未来也可能面临类似场景——从其他 GIS 平台迁移到 AgentGIS。

如果将来有需求，可以参照同样的三阶段设计：

  1. Discover — 盘点源平台资产，生成迁移计划供审批
  2. Migrate data — 迁移数据到目标仓库
  3. Migrate config — 迁移配置/脚本到套件格式

四、三个最值得立即动手的方向

按投入产出比排序：

方向 1（高优先级）：ACl "agc" CLI 扩展 + Skill 目录

预计投入：低。Skill 是 markdown 文件，CLI 扩展是增量开发。

  • 在 SuiteHub/agent-profiles 下建 agent-skills/ 目录
  • 先写 1-2 个 Utility skill（安装认证、基础操作）
  • 再写 1 个 Use-case skill（"做一个围栏分析"的完整引导）
  • 扩展 agc CLI 添加几个 Agent 友好子命令

方向 2（中-高优先级）：MCP Server

预计投入：中。需要搭一个轻量 MCP Server 容器。

  • 在阿里云 ECS 部署 agentgis-mcp-server 容器
  • 先用 mk_ API Key 认证
  • 暴露 3-5 个核心工具（list_suites, inspect_suite, run_suite, check_compliance）
  • 对接 Claude Code / ChatGPT 测试

方向 3（中长期）：Workflow as Tool / Suite as Tool

预计投入：较高。需要修改发布流程 + 合规检测 + MCP 集成。

  • 在套件模型中增加 mcp_enabled: bool 字段
  • 合规检测通过后可标记为 MCP 可调用
  • MCP Server 读取可调用套件列表，暴露为 tools
  • Agent 传入参数 -> MCP Server -> 触发 agc run -> 返回结果

五、与 ArcGIS 迁移的类比思考（长期）

CARTO 的迁移故事核心论点：

  1. 架构差异 — ArcGIS 拷贝数据到封闭存储 vs CARTO 在数据仓库原生执行
  2. 成本结构 — 按席位 vs 按用量
  3. Agent 化 — 迁移本身就是 Agent 驱动的

我们的平台从第一天就是"数据不离开本地"模式，没有历史包袱。但如果将来需要吸引从传统 GIS 平台迁移的用户，可以借鉴他们的三阶段迁移模式和 readiness assessment 流程。

六、总结

维度 CARTO for Agents AgentGIS Cloud Platform 可借鉴程度
CLI 覆盖度 全平台操作 仅 agc run ⭐⭐⭐ 扩展 CLI
MCP 协议 原生支持 无 ⭐⭐⭐ 新建 MCP Server
Agent Skill 目录 3 层 15+ skill 无 ⭐⭐⭐ 建 skill 目录
Workflow → Tool 一键发布为 MCP Tool 概念匹配（套件 = 流程） ⭐⭐⭐ 中期实现
语义模型 Apache Ossie + 空间扩展 无 ⭐⭐ 远期规划
迁移工具 三阶段 Agent 驱动 无 ⭐ 按需
In-product AI Agent Builder 内嵌聊天 暂不考虑 ⭐ 排除

一句话总结： CARTO for Agents 的三个设计——CLI 全平台覆盖、MCP 标准化协议接入、Skill playbook 编码领域知识——都是我们 AgentGIS 平台在 Agent 集成层可以（也应该）做的事情。Skill 架构和 Workflow as Tool 是最契合我们现状、投入产出比最高的方向。

笔记归档：research/carto-for-agents-architecture-notes.md

Reference in New Issue View Git Blame Copy Permalink