01 Flask最小API服务

在本地终端中运行的 Agent 只能服务于当前开发环境。若需要提供给前端页面、其他服务或外部用户调用，就需要为 Agent 增加 HTTP 接口，将其封装成 Web API 服务。

Flask 是 Python 生态中常用的轻量级 Web 框架，适合用于构建结构简单、启动成本低的 API 服务。对于 Agent 项目，Flask 可以作为一层 HTTP 包装，将内部 Agent 调用暴露为标准接口。

在这个结构中，客户端负责发送请求，Flask 负责接收请求并调用对应处理函数，Agent 负责执行实际逻辑，最终由 Flask 将处理结果返回给客户端。

一、安装Flask

bash

pip install flask

Flask 的依赖较少，安装完成后可以先验证版本。

验证一下：

bash

python -c "import flask; print(flask.__version__)"

如果能看到版本号，说明 Flask 已安装成功。

二、最小应用

最小 Flask 应用主要包含两部分：创建应用实例和定义路由。

python

from flask import Flask

# 创建Flask应用实例
app = Flask(__name__)

# 定义路由：当用户访问 "/" 时，执行下面的函数
@app.route("/")
def hello():
    return "Agent服务已启动！"

以上代码即可定义一个可响应请求的 Web 服务。各部分作用如下：

代码	作用
`Flask(__name__)`	创建应用实例，`__name__`告诉Flask去哪里找资源文件
`@app.route("/")`	路由装饰器，把URL路径`/`和下面的函数绑定
`def hello()`	视图函数，处理请求并返回响应
`return "..."`	返回的内容会发给客户端

三、运行服务

将上述代码保存为app.py，然后使用flask命令启动服务：

bash

flask --app app run

终端会输出类似信息：

 * Serving Flask app 'app'
 * Running on http://127.0.0.1:5000 (Press CTRL+C to quit)

浏览器访问http://127.0.0.1:5000，即可看到"Agent服务已启动！"。

3.1 省略 --app 参数

如果文件名为app.py或wsgi.py，可以省略--app参数：

bash

flask run

Flask 会自动查找app.py。

3.2 指定端口

默认端口是 5000。如果端口被占用，可以指定其他端口：

bash

flask --app app run --port 8080

3.3 局域网可访问

默认情况下，服务只监听本机地址（127.0.0.1）。如果需要允许同一局域网中的其他设备访问，可以指定监听地址：

bash

flask --app app run --host 0.0.0.0

启动后，其他设备可以通过当前机器的 IP 地址访问服务。

四、Debug模式

开发阶段通常需要频繁修改代码。开启 Debug 模式后，代码变更会触发服务自动重启，并在出错时提供更详细的调试信息。

bash

flask --app app run --debug

输出会多一行：

 * Debug mode: on
 * Restarting with stat
 * Debugger is active!

修改app.py并保存后，服务会自动重启，刷新浏览器即可看到最新结果。

注意：Debug 模式仅适用于开发环境，不应在生产环境开启。 Debug 模式下的交互式调试器允许在浏览器中执行 Python 代码，存在严重安全风险。

五、理解请求和响应

访问http://127.0.0.1:5000/时，请求处理流程如下：

用户浏览器 → 发送HTTP请求(GET /) → Flask收到请求 → 执行hello()函数 → 返回响应 → 用户看到页面

具体步骤为：

用户发一个HTTP请求到Flask
Flask根据URL找到对应的视图函数
视图函数执行，返回结果
Flask把结果包装成HTTP响应发回去

在 Agent 服务中，对应流程可以表示为：

客户端 → 发送POST请求(携带用户消息) → Flask → 调用Agent处理 → 返回Agent的回答

六、第一个Agent API

下面定义一个基础 Agent 接口。示例暂不接入真实 Agent，只保留请求解析和响应返回结构：

python

from flask import Flask, request

app = Flask(__name__)


@app.route("/chat", methods=["POST"])
def chat():
    # 从请求体中获取JSON数据
    data = request.get_json()
    user_message = data.get("message", "")

    # 这里后面会替换成真正的Agent调用
    reply = f"收到你的消息: {user_message}"

    return {"reply": reply}


@app.route("/health")
def health():
    """健康检查接口"""
    return {"status": "ok"}


if __name__ == "__main__":
    app.run(debug=True)

该示例包含两个接口：

接口	方法	作用
`/chat`	POST	接收用户消息，返回Agent回复
`/health`	GET	健康检查，返回服务状态

可以使用curl测试：

bash

# 健康检查
curl http://127.0.0.1:5000/health

# 发送消息
curl -X POST http://127.0.0.1:5000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "你好"}'

返回结果：

json

{"reply": "收到你的消息: 你好"}

至此，一个 Agent API 的基础骨架已经完成。后续接入真实 Agent 时，只需要将reply = f"收到你的消息: {user_message}"替换为实际调用逻辑。

七、项目结构

实际项目中，可以先采用以下文件结构：

my-agent-api/
├── app.py          # Flask应用入口
├── agent.py        # Agent逻辑（LangChain等）
├── requirements.txt
└── .env            # 环境变量（API Key等）

在功能较少时，app.py即可满足需求。随着对话逻辑、配置管理、日志等功能增加，再逐步拆分模块。

八、总结

Flask 最小 API 服务主要包含以下部分：

Flask(__name__)：创建应用
@app.route()：定义路由
request.get_json()：获取请求数据
return {}：返回JSON响应

通过这些基础能力，可以将本地 Agent 封装为可通过 HTTP 调用的服务。

下一篇将继续介绍路由和 JSON 响应，包括动态 URL、HTTP 方法以及请求数据的常见读取方式。

01 Flask最小API服务 ​

一、安装Flask ​

二、最小应用 ​

三、运行服务 ​

3.1 省略 --app 参数 ​

3.2 指定端口 ​

3.3 局域网可访问 ​

四、Debug模式 ​

五、理解请求和响应 ​

六、第一个Agent API ​

七、项目结构 ​

八、总结 ​

01 Flask最小API服务

一、安装Flask

二、最小应用

三、运行服务

3.1 省略 --app 参数

3.2 指定端口

3.3 局域网可访问

四、Debug模式

五、理解请求和响应

六、第一个Agent API

七、项目结构

八、总结