把 Agent Skill 包成 API:从本地调用到服务化落地

引子

前面我们聊过 Skill 是什么,也聊过怎么写一个可复用的 Skill。

但只在本地 Agent 里能用,其实还不够。

很多真正有价值的 Skill,最后都会遇到同一个问题:我已经把业务流程沉淀成 Skill 了,能不能让 Java 后端、小程序、内部系统也调用它?

比如你写了一个 weather-query Skill,里面已经定义好了:

  • 什么时候把城市名解析成经纬度
  • 什么时候查天气预报接口
  • 什么时候读取天气字段说明
  • 什么时候给出出行或跑步建议
  • 最终回答应该按什么格式返回

本地 Agent 能跑通,说明这套流程是有价值的。但如果只有你自己的电脑能用,它就还是一个“个人工具”;如果能包装成 HTTP API,它才开始变成一个“团队能力”。

这篇文章就围绕这个问题展开:如何把我们写的 Skill,不只是给本地 Agent 调用,而是包装成 API,对外提供服务。

先看最终接口效果预览:

GET /query/stream?question=北京明天适合户外跑步吗?

服务端通过 SSE 持续推送事件,调用方只需要监听最终的 final 事件:

event: start
data: {"success":true,"message":"agent query started","request_id":"req_123"}

event: progress
data: {"message":"正在读取 Skill","step":"read_skill"}

event: final
data: {"success":true,"answer":"来源: Open-Meteo\n建议: 明天上午更适合跑步...","source":"langgraph-agent","error":null,"meta":{"elapsed_ms":12345}}

event: done
data: {"success":true}

后面我们就围绕这个接口,拆清楚为什么要这么设计、具体怎么实现,以及最后怎么测试通过。

本文目录:

一、为什么 Skill 需要 API 化
二、Skill 对外提供 API 的几种方式
三、LangGraph 到底是什么
四、为什么推荐 LangGraph Agent Runtime
五、整体架构怎么设计
六、关键实现细节和原理
七、一次请求是怎么跑完的
八、用一个例子测试通过
九、总结


一、为什么 Skill 需要 API 化

先说结论:Skill 的价值不只是“提示词复用”,而是“业务能力复用”。

一个成熟的 Skill,通常不只是几段提示词。它往往包含三类东西:

Skill = 工作流程 + 参考资料 + 可执行脚本

以 weather-query 为例,它可能长这样:

skills/
└── weather-query/
    ├── SKILL.md
    ├── references/
    │   └── open-meteo-api.md
    └── scripts/
        ├── weather-api/
        │   └── query.py
        └── geocoding/
            └── query.py

其中:

  • SKILL.md 是工作流说明,告诉 Agent 先做什么、后做什么;
  • references/ 是上下文资料,比如接口文档、字段说明、口径规则;
  • scripts/ 是确定性执行代码,比如请求天气接口、请求地理编码接口。

这已经不是一个简单提示词了。它更像一个“会读文档、会调用工具、会组织回答的小型业务专家”。

问题来了:业务系统要怎么用它?

如果一个 Java 后端想回答“北京明天适合户外跑步吗?”,它并不想知道:

  • 城市名怎么转经纬度;
  • 天气接口叫什么;
  • 小时级降雨概率、风速、体感温度字段怎么取;
  • 返回结果怎么解释;
  • 没有数据时应该怎么回答。

Java 后端最理想的调用方式是:

GET /query/stream?question=北京明天适合户外跑步吗?

然后通过 SSE 监听最终结果:

event: final
data: {"success":true,"answer":"来源: Open-Meteo\n查询意图: ...","source":"langgraph-agent","error":null}

event: done
data: {"success":true}

这就是 Skill API 化的核心目标:

把本来只能在 Agent 环境里触发的业务能力,封装成稳定的 HTTP 服务,让普通业务系统也能调用。


二、Skill 对外提供 API 的几种方式

要把 Skill 变成 API,大体有三种路线。

2.1 方案一:服务器上安装 Codex 这类 Agent

最直观的方式是:既然本地 Codex 能调用 Skill,那就在服务器上也安装 Codex 或类似 Agent,然后 API 服务收到请求后,去驱动这个 Agent。

流程大概是:

调用方
  |
  v
HTTP 服务
  |
  v
服务器上的 Codex / Agent
  |
  v
加载本地 Skill
  |
  v
执行任务并返回结果

这个方案的优点是上手快。你本地怎么跑,服务器上大体也可以照着配置。

但它也有几个问题:

维度
服务器安装 Agent 方案
优点
改造少,最接近本地使用方式
缺点
服务边界不清晰,进程管理、并发、权限控制更复杂
适合场景
内部低频工具、个人自动化、快速验证

这里最大的风险是:Agent 本身不是为稳定 HTTP 服务边界设计的。

它能完成任务,但你还要额外处理很多服务化问题,比如并发请求、超时控制、日志、鉴权、文件权限、错误码转换等。

所以这个方案适合做验证,不一定适合长期承载业务接口。

2.2 方案二:把 Skill 逻辑重写成普通后端代码

第二种方式是更传统的后端思路:直接把 SKILL.md 里的流程翻译成 Java、Python 或 Go 代码。

比如:

如果问题命中天气查询
  -> 先做城市地理编码
  -> 再调天气预报接口
如果城市无法识别
  -> 返回澄清问题
最后按固定模板给出天气建议

这个方案看起来很稳,因为它完全变成了普通工程代码。

但问题也很明显:你失去了 Skill 的灵活性。

Skill 原来最有价值的地方,是把“流程说明、接口文档、判断策略、输出要求”放在一个 Agent 能理解的工作包里。现在你把它重新写死在后端代码里,后续每次调整业务规则,都要改代码、发版、回归。

这就有点可惜了。

2.3 方案三:用 LangGraph 实现 Agent Skills 架构

第三种方式,也是这篇文章重点讲的方式:

HTTP 服务本身不重写 Skill 业务流程,而是实现一个轻量 Agent Runtime。Runtime 读取完整 Skill 包,让 Agent 按 SKILL.md 决策、读资料、调脚本、组织答案。

也就是说,我们不是把 Skill “翻译成代码”,而是把 Skill “放进一个可服务化的 Agent 运行时”。

整体感觉像这样:

调用方
  |
  v
FastAPI /query/stream
  |
  v
LangGraph Agent Runtime
  |
  v
读取 SKILL.md / references / scripts
  |
  v
调用脚本查询业务接口
  |
  v
持续返回 SSE 事件,最终通过 final 事件给出 answer

这个方案的关键点是:HTTP 服务只负责运行时能力,业务流程仍然留在 Skill 包里。

它既保留了 Skill 的可维护性,也把对外服务边界做清楚了。


三、LangGraph 到底是什么

说到这里,有些同学可能会问:LangGraph 是什么?它和 LangChain 又是什么关系?

先不用被名字吓到。通俗地说:

LangGraph 是一个用来搭建 Agent 工作流的编排框架。它把一次复杂的 AI 任务,拆成多个节点、状态和工具调用,再按一定路线跑完整个流程。

如果说普通的大模型调用像这样:

用户问题 -> 模型 -> 回答

那 LangGraph 更像这样:

用户问题
  |
  v
节点 A:理解意图
  |
  v
节点 B:选择工具
  |
  v
节点 C:调用外部脚本或接口
  |
  v
节点 D:汇总结果并回答

它的核心不是“多调几次模型”,而是把 Agent 的行动过程变得更可控。

一个典型 LangGraph 应用里,通常会有这几个概念:

概念
可以怎么理解
State
当前任务的上下文,比如用户问题、工具结果、历史消息
Node
一个处理步骤,比如调用模型、执行工具、整理答案
Edge
步骤之间怎么流转,比如执行完工具后回到模型继续判断
Tool
Agent 能调用的外部能力,比如读文件、查接口、跑脚本
ReAct Agent
一种常见模式:模型先推理,再选择工具,再根据工具结果继续推理

为什么这对 Skill API 很重要?

因为 Skill API 不是简单的问答接口。它需要让 Agent 先读 SKILL.md,再按需读 references/,然后执行 scripts/,最后组织答案。

这天然就是一个多步骤流程。

如果只用普通的模型调用,你要自己维护这些步骤之间的状态和循环;用 LangGraph,就可以把这个过程变成一个明确的 Agent Runtime。

简单来说:

普通模型调用:适合一次问答
LangGraph:适合多步骤、有工具、有状态的 Agent 任务

这也是为什么本文会选择 LangGraph 来包装 Skill,而不是只写一个普通的 LLM 调用接口。


四、为什么推荐 LangGraph Agent Runtime

LangGraph 的价值不在于“多包装一层框架”,而在于它天然适合做 Agent 工作流。

一个 Skill API 服务至少需要这些能力:

  • 能给模型一个明确的 system prompt;
  • 能让模型根据用户问题选择工具;
  • 能限制工具权限;
  • 能控制最多执行多少步;
  • 能在工具调用和最终回答之间保留状态;
  • 能把 Agent 最后一条回答提取出来返回给 API。

这和 LangGraph 的 ReAct Agent 模式非常契合。

我们可以把 Skill 服务理解成一个小型运行时:

LangGraph Agent Runtime
├── 模型:负责理解问题、规划步骤、组织回答
├── 文件工具:负责读取 SKILL.md 和 references
├── 脚本工具:负责执行 skill/scripts 下的确定性代码
└── 控制层:负责超时、步数、错误和返回格式

这里有一个很重要的设计原则:

模型负责“判断和编排”,脚本负责“确定性执行”。

千万不要让模型直接猜接口参数,也不要让模型直接拼复杂业务请求。

更稳的方式是:

  • 接口调用、鉴权、分页、字段映射,放到 scripts/ 里;
  • 判断何时调用哪个脚本,放到 SKILL.md 里;
  • HTTP 服务只提供工具和运行环境。

这样边界才清楚。


五、整体架构怎么设计

根据 skill-api/README.md 里的方案,我们可以把整个系统拆成四层:

调用方(Java后端/小程序…
— 以上为试看内容(约 40%),开通会员后阅读全文 —