AI智能体重构旅行规划：Prompt工程与FastAPI实时票务接口实战

1. 旅行规划工作流为什么需要AI智能体重构

做过旅行规划的人都有一个共同感受：这件事看起来简单，实际上是一个典型的多约束优化问题。你要同时考虑时间窗口、预算上限、交通衔接、景点开放时间、个人偏好、同行人意见，甚至还要留出应对突发状况的缓冲。传统做法是打开十几个标签页，在攻略社区、票务平台、地图服务之间反复横跳，最后用备忘录拼出一份勉强能看的行程表。这个过程消耗的精力远超旅行本身的愉悦。

我过去几年帮朋友做过不少行程规划，最开始也是纯手工操作，后来尝试用脚本抓数据，再后来接入大模型做辅助。踩过的坑包括：模型给出的车次信息是过期的、景点推荐和实际地理位置完全对不上、生成的行程时间安排根本跑不通。这些问题的根源在于，单纯靠Prompt工程调用大模型，它只能基于训练数据里的“记忆”来回答，而票务信息、实时余票、临时停运这类动态数据，模型本身是不知道的。

所以真正可用的旅行规划工作流，必须是一个AI智能体架构：大模型负责理解需求、拆解任务、生成方案，外部工具负责提供实时数据、执行具体查询。这两者通过一套清晰的接口协议串联起来，才能让整个系统既有“脑子”又有“手脚”。本文要拆解的就是这样一套完整实践——从Prompt工程的设计思路，到用FastAPI搭建实时票务查询接口，再到智能体如何编排整个流程。

这套方案适合几类人参考：一是想入门AI智能体开发但不知道从什么场景切入的开发者；二是有一定Python基础、想做一个实际项目练手的后端工程师；三是对旅行规划有高频需求、愿意花点时间搭建自己工具的效率爱好者。不需要你精通机器学习，但需要你能看懂Python代码、理解HTTP接口的基本概念。

2. 智能体架构设计与核心思路拆解

2.1 为什么选择“大模型+工具调用”而不是纯Prompt方案

纯Prompt方案的本质是让模型在一次对话中完成所有推理和输出。你给它一段需求描述，它直接吐出一份行程。这个模式在信息静态、约束简单的场景下能用，但旅行规划恰恰是信息高度动态的场景。车次余票每分钟都在变，航班价格随时浮动，景点可能临时闭馆。模型训练数据再新，也不可能覆盖这些实时信息。

我实测过让模型直接推荐车次，它给出的车次号、发车时间、历时看起来都很合理，但去官方渠道一查，要么车次不存在，要么时间对不上。这不是模型能力问题，是信息时效性问题。工具调用的思路就是承认模型的边界：模型擅长理解意图、组织语言、做逻辑推理，但不擅长记住实时数据。那就把实时查询交给专门的接口，模型只负责决定“什么时候该查什么”。

这个架构选择带来的直接好处是：行程方案的准确性由数据源保证，而不是靠模型“猜”。你查到的车次就是真实存在的车次，你看到的余票就是当前余票。模型的价值体现在它能把多个查询结果整合成一份连贯的、符合用户偏好的行程，而不是替代数据源。

2.2 智能体的三个核心模块划分

整套系统我拆成三个模块来设计，每个模块职责清晰，方便单独调试和替换。

第一个模块是意图理解与任务规划。用户输入一段自然语言，比如“下周五从北京去上海，两天一夜，想去看展和吃本帮菜，预算控制在两千以内”。这个模块要提取出出发地、目的地、时间、天数、偏好标签、预算约束这些结构化信息，然后规划出需要执行哪些查询任务：查车次、查展馆信息、查餐厅推荐、估算费用。

第二个模块是工具执行层。每个查询任务对应一个具体的工具函数，比如车次查询工具、天气查询工具、景点搜索工具。这些工具通过FastAPI暴露成HTTP接口，智能体通过发送请求来调用。工具层不关心用户意图，只负责接收参数、返回结构化数据。

第三个模块是方案生成与校验。工具返回的数据汇总后，再交给模型做最终行程编排。模型需要把车次时间、景点开放时间、餐厅营业时间、交通接驳时间全部对齐，生成一份时间线合理的行程。生成之后还要做一轮校验，检查有没有时间冲突、预算超支、路线绕远这些问题。

这三个模块的边界要划清楚，否则调试的时候会很痛苦。我的经验是，意图理解出问题就去看Prompt和解析逻辑，数据不对就去查工具接口，行程不合理就检查方案生成的约束条件。模块化设计让排查问题的路径变得明确。

2.3 技术选型的考量与取舍

后端框架选FastAPI，理由很直接：异步支持好、自动生成接口文档、类型校验强、上手快。旅行规划场景里，车次查询、景点搜索这些操作都是IO密集型的，异步框架能显著提升并发效率。而且FastAPI的Pydantic模型定义和智能体的结构化输出天然契合，工具函数的入参和出参都可以用Pydantic模型来约束，减少格式错误。

模型侧我选择支持Function Calling能力的通用大模型接口。Function Calling是关键，它让模型能输出结构化的工具调用请求，而不是自由文本。没有这个能力，你就得用正则表达式去解析模型输出，维护成本极高且容易出错。

数据源方面，车次查询是核心难点。官方票务平台有公开的查询接口，但需要注意请求频率控制和数据解析的稳定性。我的做法是封装一层适配器，把不同来源的数据统一成内部格式，这样即使某个数据源调整了返回结构，也只需要改适配器，不影响上层逻辑。

注意：涉及票务平台的查询接口，务必控制请求频率，避免对目标服务造成压力。建议加入本地缓存和请求间隔控制，同一查询条件在短时间内重复请求时直接返回缓存结果。

3. Prompt工程在旅行规划场景的落地要点

3.1 系统Prompt的结构化设计方法

系统Prompt是整个智能体的“行为准则”，它决定了模型如何理解自己的角色、如何拆解任务、如何调用工具。我见过很多项目把系统Prompt写成一段模糊的角色描述，比如“你是一个旅行助手，帮助用户规划行程”。这种写法对简单对话够用，但对需要精确工具调用的智能体来说远远不够。

我的做法是把系统Prompt拆成几个明确的功能区块。第一个区块是角色定义，说清楚模型的身份和能力边界。第二个区块是任务拆解规则，告诉模型收到用户请求后应该按什么顺序思考。第三个区块是工具调用规范，列出所有可用工具的名称、用途、参数格式，以及什么情况下该调用哪个工具。第四个区块是输出格式约束，规定最终行程的呈现结构。

这种结构化写法的好处是可维护。当你要新增一个工具时，只需要在工具调用规范区块里加一段描述，不用重写整个Prompt。当输出格式需要调整时，也只改对应的区块。我试过把系统Prompt从五百字扩展到两千字左右，模型的任务完成率有明显提升，尤其是工具调用的准确率。

3.2 意图识别与槽位填充的Prompt技巧

用户输入往往是模糊的。“帮我安排一下去杭州的行程”这句话里，出发地缺失、时间缺失、天数缺失、偏好缺失。智能体需要先做一轮澄清追问，把关键槽位补齐，再进入正式规划。

这里有个技巧：不要让模型自由决定问什么，而是给它一个必填槽位清单和选填槽位清单。必填槽位包括出发地、目的地、出发日期、行程天数。选填槽位包括预算范围、交通偏好、住宿偏好、兴趣标签、同行人构成。模型的任务是检查用户输入中哪些必填槽位缺失，然后生成追问话术。

追问话术也有讲究。不要一次问所有缺失信息，那样用户体验很差。我的做法是让模型按优先级分批追问，第一轮先问出发地和日期这种硬性约束，第二轮再问偏好类信息。而且追问时要给出默认选项，比如“出发日期大概是这周末还是下周？如果还没定，我可以先按最近的周五来规划”。这样用户回答起来负担小，对话轮次也少。

3.3 工具调用Prompt的编写规范与避坑

工具调用的Prompt编写是最容易出问题的环节。常见错误包括：工具描述太模糊导致模型不知道什么时候该调用、参数说明不完整导致模型传错格式、多个工具功能重叠导致模型选错。

我的规范是每个工具的描述必须包含四个要素：工具名称要语义明确，比如search_train_schedule比query好得多；功能描述要用一句话说清楚这个工具做什么、返回什么；参数列表要逐个说明参数名、类型、是否必填、示例值；调用时机要明确写出什么条件下应该调用这个工具。

避坑方面，我踩过最深的坑是工具参数的类型不一致。比如日期参数，有的工具期望2024-01-15这种字符串格式，有的期望时间戳。模型在调用时经常搞混。解决办法是在Prompt里统一约定所有日期参数使用YYYY-MM-DD格式，然后在工具函数入口做格式转换。另一个坑是模型倾向于一次性调用多个工具，但有些工具之间存在依赖关系，比如必须先查到车次才能查到达后的接驳交通。这种情况下要在Prompt里明确写出工具调用的依赖顺序。

实操心得：在系统Prompt里加一条规则——“每次最多调用两个无依赖关系的工具，有依赖关系的工具必须等前一个返回结果后再调用”。这条规则能显著减少工具调用混乱的情况。

4. FastAPI实时票务查询接口的完整实现

4.1 项目目录结构与依赖管理

一个清晰的项目结构能让后续开发少走很多弯路。我的FastAPI项目目录是这样组织的：

travel-agent/ ├── app/ │ ├── __init__.py │ ├── main.py # FastAPI应用入口 │ ├── config.py # 配置管理 │ ├── models/ │ │ ├── __init__.py │ │ ├── request.py # 请求体模型 │ │ └── response.py # 响应体模型 │ ├── routers/ │ │ ├── __init__.py │ │ ├── train.py # 车次查询路由 │ │ ├── attraction.py # 景点查询路由 │ │ └── weather.py # 天气查询路由 │ ├── services/ │ │ ├── __init__.py │ │ ├── train_service.py # 车次查询业务逻辑 │ │ └── cache.py # 缓存服务 │ └── utils/ │ ├── __init__.py │ └── http_client.py # HTTP客户端封装 ├── requirements.txt └── README.md

这个结构的核心思路是路由层、服务层、模型层分离。路由层只负责接收请求和返回响应，不写业务逻辑。服务层处理具体的查询、解析、缓存逻辑。模型层定义请求和响应的数据结构。这样当票务数据源的接口发生变化时，只需要改服务层的适配代码，路由和模型基本不动。

依赖管理用requirements.txt，核心依赖包括：fastapi、uvicorn、httpx（异步HTTP客户端）、pydantic、cachetools（本地缓存）。版本号建议锁定，避免自动升级带来的兼容性问题。

4.2 车次查询接口的参数设计与数据模型

车次查询接口的入参设计要考虑智能体调用的便利性。核心参数包括：出发站、到达站、出发日期。可选参数包括：出发时间段、车次类型偏好。返回结构要包含足够的信息供模型做行程编排：车次号、出发时间、到达时间、历时、各席别余票状态、票价。

用Pydantic定义请求和响应模型：

from pydantic import BaseModel, Field from typing import Optional, List from datetime import date class TrainQueryRequest(BaseModel): from_station: str = Field(..., description="出发站名称") to_station: str = Field(..., description="到达站名称") travel_date: date = Field(..., description="出发日期") depart_time_start: Optional[str] = Field(None, description="出发时间下限，格式HH:MM") depart_time_end: Optional[str] = Field(None, description="出发时间上限，格式HH:MM") class TrainTicketInfo(BaseModel): seat_type: str = Field(..., description="席别名称") price: float = Field(..., description="票价") remaining: str = Field(..., description="余票数量或状态描述") class TrainSchedule(BaseModel): train_no: str = Field(..., description="车次号") from_station: str = Field(..., description="出发站") to_station: str = Field(..., description="到达站") depart_time: str = Field(..., description="出发时间") arrive_time: str = Field(..., description="到达时间") duration: str = Field(..., description="历时") tickets: List[TrainTicketInfo] = Field(default_factory=list, description="席别余票信息") class TrainQueryResponse(BaseModel): success: bool = Field(..., description="查询是否成功") message: str = Field("", description="附加信息") schedules: List[TrainSchedule] = Field(default_factory=list, description="车次列表")

这个模型定义的好处是，FastAPI会自动生成接口文档，智能体在调用前可以通过文档了解参数格式。而且Pydantic会在请求进入时做类型校验，参数格式不对直接返回422错误，不会进入业务逻辑。

4.3 异步查询与缓存策略的实现细节

车次查询是IO密集型操作，用异步方式实现能显著提升吞吐量。核心查询逻辑放在服务层：

import httpx from cachetools import TTLCache from app.models.response import TrainQueryResponse, TrainSchedule, TrainTicketInfo cache = TTLCache(maxsize=500, ttl=300) class TrainService: def __init__(self): self.client = httpx.AsyncClient(timeout=10.0) async def query_trains(self, from_station: str, to_station: str, travel_date: str) -> TrainQueryResponse: cache_key = f"{from_station}_{to_station}_{travel_date}" if cache_key in cache: return cache[cache_key] try: raw_data = await self._fetch_from_source( from_station, to_station, travel_date ) schedules = self._parse_schedules(raw_data) result = TrainQueryResponse( success=True, schedules=schedules ) cache[cache_key] = result return result except Exception as e: return TrainQueryResponse( success=False, message=f"查询失败: {str(e)}" ) async def _fetch_from_source(self, from_station, to_station, travel_date): # 实际的数据源请求逻辑 # 这里需要根据具体数据源的接口规范来实现 pass def _parse_schedules(self, raw_data) -> list: # 将原始数据解析为TrainSchedule列表 pass

缓存策略用TTL（Time To Live）控制，车次余票信息设置5分钟过期比较合理。太短了缓存没意义，太长了数据可能过期。缓存键用出发站、到达站、日期的组合，保证不同查询条件不会互相污染。

注意：缓存只适用于查询类接口，不适用于任何涉及订单操作的场景。余票信息本身有时效性，缓存时间不宜超过5分钟。

4.4 接口的异常处理与降级方案

外部数据源不可控，接口必须做好异常处理和降级。我的做法是分三层处理：第一层是请求超时和网络异常，捕获后返回“查询超时，请稍后重试”；第二层是数据解析异常，说明数据源返回格式变了，记录日志并返回“数据格式异常”；第三层是数据为空，说明确实没有符合条件的车次，返回空列表并附上提示。

降级方案方面，如果主数据源不可用，可以切换到备用数据源。备用数据源可以是另一个查询渠道，也可以是本地缓存的最近一次查询结果。我在服务层加了一个fallback_enabled配置项，开启后当主数据源连续失败三次，自动切换到备用逻辑。

class TrainService: def __init__(self): self.failure_count = 0 self.fallback_enabled = True async def query_trains(self, from_station, to_station, travel_date): try: result = await self._query_primary(from_station, to_station, travel_date) self.failure_count = 0 return result except Exception as e: self.failure_count += 1 if self.fallback_enabled and self.failure_count >= 3: return await self._query_fallback(from_station, to_station, travel_date) raise e

这套异常处理机制在实际运行中能挡住大部分临时故障，用户侧感知到的就是偶尔慢一点，而不是直接报错。

5. 智能体与FastAPI的联调与工作流编排

5.1 工具注册与Function Calling的对接方式

智能体要调用FastAPI接口，需要把接口封装成模型能识别的工具定义。以车次查询为例，工具定义大致是这样的结构：

{ "name": "search_train_schedule", "description": "查询指定日期从出发站到到达站的车次信息，返回车次号、时间、余票和票价", "parameters": { "type": "object", "properties": { "from_station": { "type": "string", "description": "出发站名称，如'北京南'" }, "to_station": { "type": "string", "description": "到达站名称，如'上海虹桥'" }, "travel_date": { "type": "string", "description": "出发日期，格式YYYY-MM-DD" } }, "required": ["from_station", "to_station", "travel_date"] } }

这个定义要注册到模型的工具列表里。当模型判断需要查询车次时，它会输出一个工具调用请求，包含工具名和参数。智能体框架捕获这个请求，转换成HTTP请求发给FastAPI接口，拿到响应后再把结果喂回模型。

这里的关键是参数映射要准确。模型输出的参数名必须和FastAPI接口的入参名一致，否则会报422错误。我的做法是在工具定义里把参数名写得和Pydantic模型完全一致，减少映射环节。

5.2 多轮对话中的上下文管理与状态保持

旅行规划通常需要多轮对话。用户第一轮说“想去杭州”，第二轮补充“下周五出发”，第三轮说“预算一千五”。智能体需要记住前面轮次的信息，不能每轮都重新问一遍。

上下文管理我采用槽位状态机的思路。维护一个会话状态对象，记录当前已填充的槽位和缺失的槽位。每轮对话后更新状态，然后检查是否所有必填槽位都已填充。如果填充完毕，进入规划阶段；如果有缺失，生成追问话术。

class ConversationState: def __init__(self): self.slots = { "from_station": None, "to_station": None, "travel_date": None, "duration_days": None, "budget": None, "preferences": [] } self.required_slots = ["from_station", "to_station", "travel_date", "duration_days"] self.history = [] def update(self, extracted_info: dict): for key, value in extracted_info.items(): if key in self.slots and value: self.slots[key] = value def get_missing_required(self) -> list: return [s for s in self.required_slots if not self.slots[s]] def is_ready(self) -> bool: return len(self.get_missing_required()) == 0

这个状态对象在会话期间保持，每轮对话把用户输入和模型提取的信息更新进去。当is_ready()返回True时，触发完整的规划流程。

5.3 完整工作流的串联与执行顺序

整个工作流的执行顺序是这样的：

第一步，接收用户输入，调用模型做意图识别和槽位提取。模型返回结构化的槽位信息，更新到会话状态。

第二步，检查槽位完整性。如果有缺失，生成追问话术返回给用户，等待下一轮输入。如果完整，进入第三步。

第三步，根据用户需求规划查询任务列表。比如需要查去程车次、返程车次、景点信息、天气信息。每个任务对应一个工具调用。

第四步，按依赖关系依次执行工具调用。无依赖的可以并行，有依赖的串行。比如先查去程车次，确定到达时间后再查当天下午的景点。

第五步，汇总所有工具返回的数据，交给模型生成最终行程方案。模型需要把时间线对齐，检查冲突，输出结构化行程。

第六步，对生成的行程做一轮自动校验。检查项包括：时间是否冲突、预算是否超支、路线是否合理。校验不通过则让模型重新生成，最多重试两次。

这个流程在实际运行中，从用户输入完整需求到输出行程方案，耗时大约在10到20秒之间，主要时间花在工具调用和模型生成上。如果命中缓存，可以缩短到5秒以内。

6. 常见问题与排查技巧实录

6.1 工具调用失败的高频原因与修复

工具调用失败是调试阶段最常见的问题。我整理了几种典型情况：

其中“模型不调用工具直接编造答案”这个问题最隐蔽，因为模型编造的内容看起来往往很合理。我的应对方法是在系统Prompt里加一条硬性规则：“任何涉及车次、票价、余票、天气的信息，必须通过工具查询获得。如果工具调用失败，如实告知用户查询失败，不得编造数据。”这条规则加上之后，编造情况基本消失。

6.2 票务数据解析的稳定性处理

票务数据源的返回格式可能随时调整，解析逻辑要有足够的容错性。我的做法是防御式解析：不假设字段一定存在，每个字段读取时都给默认值；不假设数据一定是预期类型，读取后做类型转换和校验；不假设列表一定非空，空列表走正常返回流程。

def safe_get(data: dict, key: str, default=None): """安全获取字典值，处理键不存在或值为None的情况""" value = data.get(key, default) return value if value is not None else default def parse_train_schedule(raw: dict) -> TrainSchedule: return TrainSchedule( train_no=safe_get(raw, "train_no", "未知车次"), from_station=safe_get(raw, "from_station", ""), to_station=safe_get(raw, "to_station", ""), depart_time=safe_get(raw, "depart_time", ""), arrive_time=safe_get(raw, "arrive_time", ""), duration=safe_get(raw, "duration", ""), tickets=parse_tickets(safe_get(raw, "tickets", [])) )

另外建议加一层数据校验：解析完成后检查关键字段是否为空，如果关键字段缺失比例超过阈值，记录警告日志并返回部分数据，而不是直接报错。这样即使数据源有小幅调整，接口也能降级可用。

6.3 行程方案不合理时的调试思路

模型生成的行程方案可能出现时间冲突、路线绕远、预算超支等问题。调试这类问题要分两步走：先确认工具返回的数据是否正确，再检查模型生成时的约束条件是否明确。

如果工具数据正确但方案不合理，通常是Prompt里的约束条件不够具体。比如模型不知道两个景点之间的交通时间，就会排出“上午故宫、下午长城”这种实际上跑不通的行程。解决办法是在Prompt里加入时间估算规则：同城景点间交通按30分钟估算，跨区按60分钟估算，并明确要求模型在行程中预留交通时间。

另一个常见问题是预算计算不准确。模型可能只算了交通和门票，忘了餐饮和住宿。我的做法是在Prompt里给出预算构成模板：交通费、住宿费、餐饮费、门票费、其他杂费，要求模型逐项估算并汇总。这样生成的预算方案更完整，用户参考价值更高。

6.4 性能优化与请求频率控制

当智能体频繁调用票务查询接口时，性能问题会凸显出来。我做了几项优化：

第一，缓存分层。本地内存缓存做第一层，TTL设5分钟；如果本地缓存未命中，查Redis做第二层，TTL设15分钟。两层都未命中才请求数据源。

第二，请求合并。同一会话中如果多个查询任务涉及相同的出发站、到达站、日期组合，合并成一次查询，结果复用。

第三，频率限制。对数据源的请求加令牌桶限流，每秒最多发起2次请求，避免触发数据源的风控机制。

第四，异步并发。无依赖关系的查询任务用asyncio.gather并发执行，比如同时查去程车次和返程车次，总耗时从两次串行的4秒降到并行的2秒左右。

实操心得：限流阈值不要设得太高，宁可慢一点也不要触发数据源的风控。我一开始设了每秒5次，结果连续几次被临时限制访问，后来降到每秒2次就稳定了。

7. 从原型到可用产品的经验总结

这套系统我从最初的原型到相对稳定可用，前后迭代了大概两个月。最开始的想法很简单：用模型加几个查询接口拼一个行程助手。实际做下来发现，难点不在模型调用，而在工程细节的把控。

Prompt工程方面，最大的体会是约束要具体。不要指望模型自己理解“合理安排时间”这种模糊要求，要把规则拆成可执行的条目。比如“两个景点之间必须预留至少30分钟交通时间”“每天安排的景点不超过3个”“午餐时间固定在12:00到13:00之间”。规则越具体，生成结果越稳定。

接口设计方面，返回结构要稳定。即使数据源返回格式变化，对外的接口结构不要变。这样智能体侧的解析逻辑不用跟着改。我在服务层和路由层之间加了一层数据转换，把外部数据源的格式差异全部消化在服务层内部。

调试方面，日志要详细。每次工具调用的入参、出参、耗时都记录到日志里。出问题的时候，先看日志定位是哪个环节出的错，比盲目改代码效率高得多。我在日志里加了请求ID，一次会话的所有操作可以通过请求ID串联起来，排查多轮对话问题时特别有用。

后续如果要继续扩展，有几个方向可以考虑：接入更多数据源提升查询覆盖率、加入用户偏好学习让推荐更个性化、支持多人协同规划让同行人可以共同编辑行程。但这些都是锦上添花，核心的智能体加工具调用架构已经能覆盖大部分旅行规划场景了。