把 Agent 包装成稳定 API,从脚本到服务

前几篇我们把简历 Agent 从"会输出"一路推到了"带证据、能给建议"。但所有代码都长这样:

result = agent.run_sync(resume_text)
print(result.output)

这在自己机器上调试没问题。可一旦要交给前端页面、别的系统、或者自动化流程去调,这种脚本就不够了——它没有地址、没有边界、出错时也不知道该怎么告诉调用方。

今天这篇,把 Agent 包成一个能被稳定调用的 API 服务。核心一句话:

Agent 负责智能分析,FastAPI 负责对外提供服务,Pydantic 负责定义输入输出边界。

一、先定义输入边界:AnalyzeRequest

用户传进来的东西,不能照单全收。今天定义了请求模型:

class AnalyzeRequest(BaseModel):
    resume_text: str = Field(
        min_length=20,
        max_length=8000,
        description="待分析的简历文本,不能太短,也不能无限长",
    )
    target_role: str | None = Field(
        default=None,
        max_length=80,
        description="目标岗位,例如:AI Agent 工程师、数据工程师",
    )

它的作用是:在请求进入 Agent 之前,先把不合理的数据拦在门外。

• 简历文本太短 → 不进 Agent
• 文本太长 → 不进 Agent
• 字段格式不对 → FastAPI 直接返回错误

这一步让我明白一个事实:AI 应用不能直接相信用户输入。输入边界越清楚,后面的 Agent 越稳定。把脏数据挡在门口,比让模型在内部纠错便宜得多。

二、再定义输出边界:AnalyzeResponse

光管输入不够,输出也得有统一格式。今天定义了响应模型:

class AnalyzeResponse(BaseModel):
    profile: ResumeAnalysis
    target_role: str | None = None
    warnings: list[str] = Field(default_factory=list)

以前可能直接把分析结果一股脑返回:

{ "summary": "...", "skills": [] }

现在包成统一外层:

{
  "profile": { "...": "Agent 分析结果" },
  "target_role": "AI Agent 工程师",
  "warnings": []
}

好处是:以后内部的 ResumeAnalysis 再怎么变复杂,API 外层结构依然稳定。

这是工程化里一条很重要的原则:

内部模型可以演进,但对外接口要尽量稳定。

调用方只认 profile / target_role / warnings 这三样,你内部怎么重构都不影响他。

三、FastAPI 的价值:一句顶五件事

把接口挂起来的关键就一行:

@app.post("/analyze_resume", response_model=AnalyzeResponse)

response_model=AnalyzeResponse 这句话告诉 FastAPI:这个接口的返回值必须符合 AnalyzeResponse 的结构。

于是 FastAPI 自动帮你做完五件事:

• 请求参数校验
• 响应结果校验
• JSON 转换
• API 文档生成(Swagger)
• 错误信息返回

这也是 PydanticAI 和 FastAPI 天生一对的原因:PydanticAI 管 Agent 的结构化输出,FastAPI 管 Web API 的结构化输入输出。 两端都用 Pydantic 定义边界,衔接没有缝隙。

四、整体调用链路

今天的简历服务已经跑通这条链:

用户 / 前端
   ↓  AnalyzeRequest 校验输入
   ↓  FastAPI 接口
   ↓  analyze_resume(resume_text)
   ↓  PydanticAI Agent
   ↓  ResumeAnalysis
   ↓  AnalyzeResponse 包装输出
   ↓  返回 JSON

它比单个脚本更像一个真实项目,已经具备后端服务的雏形。

五、总结:把模型放进工程边界

今天最大的收获:

AI 应用不是"调用一次大模型"就结束了,而是要把模型能力放进一个稳定的工程边界里。