AI Agent / 系统课时

部署 Agent 服务

部署 Agent 服务

这节把一个已经能运行的 Agent 包装成可发布服务:用 HTTP API 暴露入口,用容器固定运行环境,用环境变量注入配置,并通过健康检查、请求 ID 和结构化日志留下上线后的诊断证据。

学习目标

  • 能把 Agent 封装为稳定的 HTTP 服务并构建容器镜像
  • 能用环境变量区分镜像与运行配置,避免把密钥写进镜像
  • 能通过健康检查、请求 ID 和延迟日志完成上线验收

先确定发布边界

部署时要把“业务代码”和“运行环境”分开。镜像只保存代码与依赖;模型地址、密钥、日志级别、端口等放到运行时配置;日志、指标和追踪再送到可观测平台。这样同一个镜像才能在测试、预发和生产环境复用。

Agent 服务发布拓扑

把上一课的业务入口封装为 HTTP

把代码保存为 app.py,与 order_tool.py、order_flow.py 放在同一目录。启动时创建虚构订单库。课堂的随机令牌只对应一个测试身份,令牌由部署环境注入。真实服务应从受信认证中间件校验会话,并解析当前租户和用户身份。

python
import hmac
import json
import logging
import os
import sys
import time
import uuid
from contextlib import asynccontextmanager
from dataclasses import asdict
from pathlib import Path
from tempfile import TemporaryDirectory

from fastapi import FastAPI, Request
from fastapi.concurrency import run_in_threadpool
from fastapi.responses import JSONResponse

from order_flow import State, handle
from order_tool import OrderServiceError, Principal, SQLiteOrders, seed_demo

HTTP_STATUS = {
    "ok": 200, "unauthenticated": 401, "invalid_request": 400,
    "unsupported_intent": 422, "order_unavailable": 404,
    "lookup_timeout": 504, "lookup_unavailable": 503,
    "payload_too_large": 413, "unsupported_media_type": 415,
}
logger = logging.getLogger("order-demo")
if not logger.handlers:
    logger.addHandler(logging.StreamHandler(sys.stdout))
logger.setLevel(logging.INFO)
logger.propagate = False


@asynccontextmanager
async def lifespan(app):
    token = os.environ.get("DEMO_TOKEN", "")
    if len(token) < 16:
        raise RuntimeError("set a random DEMO_TOKEN of at least 16 characters")
    with TemporaryDirectory() as temp:
        path = Path(temp) / "orders.sqlite3"
        seed_demo(path)
        app.state.orders = SQLiteOrders(path)
        app.state.token = token.encode("utf-8")
        yield


app = FastAPI(lifespan=lifespan)


@app.get("/healthz")
def health():
    return {"status": "alive"}


@app.get("/readyz")
def ready():
    try:
        app.state.orders.ready()
    except OrderServiceError:
        return JSONResponse({"status": "not_ready"}, status_code=503)
    return {"status": "ready"}


def unique_object(pairs):
    data = {}
    for key, value in pairs:
        if key in data:
            raise ValueError("duplicate field")
        data[key] = value
    return data


async def read_request(request):
    media_type = request.headers.get("content-type", "").split(";", 1)[0].strip().lower()
    if media_type != "application/json":
        return None, State("unsupported_media_type", "请发送 JSON 请求。")
    body = bytearray()
    async for part in request.stream():
        if len(body) + len(part) > 2048:
            return None, State("payload_too_large", "请求过大。")
        body.extend(part)
    try:
        return json.loads(body.decode("utf-8"), object_pairs_hook=unique_object), None
    except (ValueError, RecursionError):
        return None, State("invalid_request", "请求 JSON 无效。")


@app.post("/agent/run")
async def run(request: Request):
    request_id = uuid.uuid4().hex
    started = time.perf_counter()
    scheme, _, credential = request.headers.get("authorization", "").partition(" ")
    if scheme.lower() != "bearer" or not hmac.compare_digest(
        credential.encode("utf-8"), app.state.token
    ):
        state = handle(None, None, app.state.orders)
    else:
        data, failure = await read_request(request)
        state = failure or await run_in_threadpool(
            handle, data, Principal("team-a", "USER-001"), app.state.orders
        )

    code = HTTP_STATUS[state.status]
    headers = {"X-Request-ID": request_id, "Cache-Control": "no-store"}
    if code == 401:
        headers["WWW-Authenticate"] = "Bearer"
    response = {"requestId": request_id, "status": state.status, "message": state.message}
    if state.order is not None:
        response["order"] = asdict(state.order)

    logger.info(json.dumps({
        "event": "order_lookup", "request_id": request_id,
        "status": state.status, "http_status": code,
        "latency_ms": round((time.perf_counter() - started) * 1000, 2),
    }))
    return JSONResponse(response, status_code=code, headers=headers)

启动并验收

将下列依赖保存为 requirements.txt。版本用于复现本地课堂验证。

text
fastapi==0.162.0
uvicorn==0.54.0

在 Python 3.11 虚拟环境安装 python -m pip install -r requirements.txt。以下 Bash 命令将服务绑定到本机。前两课的业务测试通过后再启动。

bash
export DEMO_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(24))')"
python -m uvicorn app:app --host 127.0.0.1 --port 8000 --no-access-log &
ORDER_DEMO_PID=$!

服务启动后,在同一 Bash 会话发送真实 HTTP 请求。令牌仅供本地演练。结束本地演练时可运行 kill "$ORDER_DEMO_PID"。

bash
curl -fsS --max-time 3 http://127.0.0.1:8000/healthz
curl -fsS --max-time 3 http://127.0.0.1:8000/readyz
curl -fsS --max-time 3 http://127.0.0.1:8000/agent/run \
  -H "Authorization: Bearer $DEMO_TOKEN" -H 'Content-Type: application/json' \
  -d '{"intent":"order_status","order_id":"ORD-20260904-001"}'

两个探针分别返回 {"status":"alive"} 和 {"status":"ready"}。业务返回 HTTP 200、status: "ok"、由服务器生成的 requestId 和状态为 SHIPPED 的订单。再次发送一个合法但不存在的编号,应返回 404 且没有 order。去掉令牌应返回 401。使用返回的请求 ID 检查同一条 order_lookup 日志。

用同一个入口构建容器

保存下面内容为 Dockerfile。将工作目录保持为示例文件所在目录。令牌只在运行时注入,镜像内用非 root 用户运行。

dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN python -m pip install --no-cache-dir -r requirements.txt
COPY app.py order_flow.py order_tool.py ./
USER 10001:10001
CMD ["python", "-m", "uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000", "--no-access-log"]

有可用容器引擎时,先结束本地演练服务,在已导出课堂令牌的同一 Bash 会话启动容器。宿主机端口只绑定到环回地址。容器内部监听容器网络接口,方便端口映射。

bash
docker build -t order-agent-demo:1.0 .
docker run -d --rm --name agent-demo -p 127.0.0.1:8000:8000 -e DEMO_TOKEN order-agent-demo:1.0

容器启动后重复上面的探针和业务请求,并用 docker logs agent-demo 核对请求 ID。演练完成后用 docker stop agent-demo 结束容器。

验收与回滚

存活探针验证进程是否能响应。就绪探针额外验证课堂订单库可读。两者都不应实际发起模型调用。生产入口还应限制总请求时长、并发和请求大小,分别设置下游超时,并监测拒绝率与错误率。多副本共享业务数据时,使用统一的受控订单服务,不能把课堂临时库当成持久存储。

上线时先跑上一课的应用测试,再验证新实例的就绪、业务读取、未授权和不存在路径,并核对请求 ID、错误率和延迟。保留上一版镜像摘要与兼容配置。切回上一版后重复同一验收;若涉及业务数据或数据库迁移,还需要独立验证回滚兼容性。课堂容器标签可读,生产应使用不可变摘要或启用标签不可变策略。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

部署 Agent 服务

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通