小节三：Route 为什么只做参数校验，不应该直接实现 Agent Main Loop？

多同学在这里最容易犯的毛病，就是觉得既然 Route 已经拿到了请求，那索性把主逻辑也一口气写进去。但从长期维护看，这么做几乎一定会越写越乱。先看一张分层图，脑子里有了结构，再去读代码会轻松很多。

这张图把边界切得很清楚：Flask Route 负责接收 HTTP 请求、做参数校验、返回 JSON；AgentService 负责流程协调、会话管理和任务编排；AgentEngine 则只关注提示词、模型、工具调用和回答生成。说白了，Route 保持“薄”，不是为了好看，而是为了把会不断膨胀的业务逻辑拦在外面。

这点非常重要。

看起来我们完全可以写：

@app.post("/api/v1/chat")
def chat():
    prompt = ...
    while True:
        ...

但这样做会破坏前面整个课程架构。

Route 应该保持“薄”

理想 Route：

读取请求
 ↓
验证
 ↓
service.chat()
 ↓
返回 JSON

它应该尽量短。

为什么？

因为 Route 的变化来自：

HTTP 协议

而 AgentEngine 的变化来自：

Agent Runtime

两者变化原因不同。

薄不等于随意。一个常见写法是 str(payload.get("message", ""))，看起来省事，却会把数字 123 接受成字符串 "123"。API 边界应先检查 isinstance(message, str)，再 strip()；类型不对就明确返回 400。数据强制转换适合我们主动定义的兼容规则，不适合偷偷掩盖调用错误。

AgentService 做业务协调

当前版本 Service 只有：

生成 run_id
调用 engine
返回结果

后面会逐渐增加：

SessionManager
RunManager
Persistence
Trace

所以 Service 是非常关键的中间层。

AgentEngine 继续保持纯粹

AgentEngine 不应该知道：

HTTP Header
Status Code
Flask request
JSON Response

它只需要处理：

task
context
tools
state

这样未来换成 FastAPI，甚至不用 Web Framework，Engine 都不用改。

一个非常实用的判断标准

如果你的 AgentEngine 代码里出现：

from flask import request

通常意味着边界开始混了。

反过来，如果 Route 里出现：

while True
ToolRegistry
ContextBuilder
Provider

也说明 Route 太重。