API 与 Agent 配置

场景与目标

• 目标：构建一个智能旅行规划助手，通过接收用户的输入（出发地、目的地、预算、偏好等），调用外部地图 API 获取真实数据，最终生成一份结构化的专属旅行计划。
• 适用场景：旅行规划 App、私人管家服务或行程管理工具。
• 核心逻辑：利用 AI Agent 调用 API 工具获取真实地理位置信息，进行逻辑推理与结构化输出。（对接高德地图搜索POI 2.0 API）。

实现步骤

数据存储

详见总览中数据存储部分。

逻辑与状态配置

高德地图 API 配置

为了确保 AI 推荐的地点是真实存在的，我们可以接入高德地图 API。

高德地图 API 搜索 POI 2.0开发指南：https://lbs.amap.com/api/webservice/guide/api-advanced/newpoisearch 

1. 添加 API：进入 API 面板，新建一个 API 配置，命名为 搜索POI 2.0。

2. 请求方法与 URL：

   • 请求方法： GET
   • URL：https://restapi.amap.com/v5/place/text?parameters

3. 配置参数 (Query)：根据官方文档和需求配置以下必填/常用参数：

   • keywords：搜索关键字（如：美食、景点名称）
   • region：目标城市
   • city_limit：true（限制在特定城市内搜索）
   • show_fields：children,business,navi（获取更多维度数据，如营业时间和花费）
   • page_size：10
   • key：你的高德开发者 API KEY

4. 请求示例：https://restapi.amap.com/v5/place/text?keywords=美食region=杭州市&city_limit=true&show_fields=children,business,navi&page_size=10&key=你的API_KEY

5. 调试与解析：在调试界面点击发送测试请求。成功返回数据后， Zion 将自动解析返回结果。点击保存配置即可。

5. 精简响应数据：保留 AI 规划所需的核心字段即可，例如 name（名称）、location（经纬度坐标）、cost（花费）和 rating（评分）。

6. 确定入参：确保 URL 中的查询参数已正确映射为 API 的“输入参数”。填写show_fields、key默认值。

AI Agent 配置

接下来配置 AI Agent，它将作为整个规划系统的“大脑”。

1. 输入参数

定义 Agent 需要接收的变量，这些变量将由前端用户填写并传入：

• departure (文本)
• destination (文本)
• traveler_count (长整数)
• personal_budget (无限精度小数)
• start_date (日期)
• end_date (日期)
• requirements (文本)

2. 提示词

根据需求撰写提示词。可选择复制并粘贴以下完整提示词到系统指令框中：

# 角色
资深旅行规划专家

# 任务
根据以下出行信息，利用 `pois` 搜索工具获取目的地真实数据，并生成一份详尽、合理的结构化旅行计划。

## 需求输入
1. 出发地：{{departure}}
2. 目的地：{{destination}}
3. 出发日期：{{start_date}}
4. 返程日期：{{end_date}}
5. 出行人数：{{traveler_count}}
6. 人均预算：{{personal_budget}}
7. 特殊要求：{{requirements}}

## 工作流
1. **数据检索策略**：
   - 必须通过 `pois` 工具获取目的地实时数据。
   - 分阶段检索：确认住宿点后，围绕住宿点所在区域，多次调用工具检索景点（110000）与餐饮（050000）。
   - 动态补全：若初次搜索结果评分低或数据缺失，须更换关键词再次请求，直至满足行程量。

2. **逻辑编排原则**：
   - **地理聚类**：利用 `location` 经纬度，将同一区域的 POI 编排在同一时段，最小化交通耗时。
   - **住宿逻辑**：除非跨城，否则尽量保持住宿点固定，减少搬运行李频率。
   - **预算核验**：严格参考 `business.cost`。总花费 = (Σ景点门票 + Σ餐饮 + Σ住宿) * traveler_count。必须控制在 {{personal_budget}} 内。
   - **时效核验**：严格参考 `business.opentime_today`。严禁在非营业时间安排游览。

3. **结构化输出**：
   - 严格按照 JSON 结构返回数据。
   - `reason` 字段需结合 POI 的 `tag` 或 `rating` 给出专业推荐理由。

# 任务限制
- 严禁虚构任何不存在的地点。
- 所有推荐必须有真实的经纬度数据支撑。

3. 工具

在 Agent 的工具面板中，添加前面配置好的 搜索POI 2.0 API。

• 工具名称：命名为 pois（与提示词中的名称保持一致，可以避免因理解偏差导致的调用失败）。
• 参数描述：为工具的输入参数添加清晰的描述指导 AI 如何调用。

4. 结构化输出开启结构化输出，使其对齐数据库模型。这能确保返回的 JSON 数据可被行为流直接解析并入库。

• 根节点：body
• 顶层字段：title, summary
• 嵌套数组：itineraries数组（对应每日行程表，包含 day_number, summary 以及子数组 detail）
• 深层明细：detail 数组（对应具体打卡点，包含 location_name, location_geo, cost, transportation 等）

验证 (Verification)

配置完成后，使用调试功能进行测试。

第一步：运行测试会话

填入模拟数据，例如：

• 目的地 (destination): 杭州
• 时间区间: 2026-04-27 至 2026-04-29
• 需求 (requirements): 喜欢自然风光

预期结果：观察执行结果，AI 应当成功触发 pois 工具，执行多次真实的高德 API 搜索操作（如搜索西湖附近的景点）。

第二步：检查输出结果

查看 AI 最终吐出的结果结构。

预期结果：AI 返回 JSON 对象，包含为期3天的行程。内部不仅拥有真实的地点（如灵隐寺），还包含计算好的预估花费、经纬度坐标以及具体的交通耗时建议。