当你的 API 用户从「人类开发者」变成「AI Agent」，设计的优先级就完全变了。Agent 不看你的文档（除非你写了 llms.txt），它会从接口的参数名、描述、响应结构里推断怎么用。本文分享我们在构建龙虾出行 Agent API 时的设计原则。
原则一：参数用自然语言，不用内部编码
传统 OTA 的机票搜索要求传 from_code=SHA，开发者得先查机场三字码表。Agent 哪知道 SHA 是上海？语义化 API 应该接受 from=上海，在服务端自动解析成三字码。
// 传统 API（对 Agent 不友好）
{ "from_code": "SHA", "to_code": "SZX", "trip_mode": "domestic" }
// 语义化 API（Agent 直接能用）
{ "from": "上海", "to": "深圳", "date": "2026-08-01" }把领域知识的复杂度留在服务端。Agent 只需说「上海到深圳」，你帮它处理三字码、行程模式、坐标解析这些细节。
原则二：错误要告诉 Agent 怎么改
传统 API 的错误是给人看的：「参数错误」。Agent 看到这个会懵——哪个参数？怎么改？语义化的错误要带 hint：
{
"error": {
"code": "CITY_REQUIRED",
"message": "city "锦江" 像是品牌名，需要明确城市",
"hint": "请改用城市名，如「上海」；品牌用 brand 参数"
}
}Agent 看到 hint 就知道该怎么修参数，而不是盲目重试或放弃。这把「客服成本」从用户转移到了接口设计——一次设计好，所有 Agent 都受益。
原则三：响应带摘要，Agent 不用自己组织语言
Agent 调完接口后，要把结果告诉用户。如果响应只有结构化字段，Agent 还得消耗 token 自己写一段「东方航空 MU5357，晚上 8 点半出发...」。不如直接在响应里给 summary：
这个 summary 是预先写好的、经过人工优化的自然语言。Agent 直接用，既省 token，又保证表达质量一致。
原则四：用 suggestions 引导下一步（HATEOAS for Agents）
Agent 调完搜索后，接下来该干嘛？翻页？筛选？下单？与其让 Agent 猜，不如在响应里告诉它：
"suggestions": [
{ "action": "next_page", "reason": "还有更多航班（共167条）" },
{ "action": "filter_by_brand", "reason": "可按航司缩小范围" }
]这是 HATEOAS（超媒体作为应用状态引擎）思想在 Agent 时代的复兴。Agent 不靠硬编码的流程，靠响应里的引导自然推进。
原则五：写一份 llms.txt
llms.txt 是给 AI 爬虫和 Agent 的「使用说明书」，放在站点根目录。它用简洁的 Markdown 列出你的能力、接口、参数、示例。Agent 第一次接触你的服务时，读这份文件就能上手。
这不是替代 OpenAPI 文档——OpenAPI 给开发者用，llms.txt 给 Agent 用。两者面向不同读者，写法完全不同：前者精确详尽，后者简洁直觉。
好的 Agent API 不是「让 AI 能调」，而是「让 AI 想调、会调、调得对」。语义化设计是这一切的起点。