agent-">最小模型调用：从零搭建 Python Agent 服务

很多开发者在接触 Agent 时，第一反应是写几行代码让模型“说一句话”，跑通便觉得大功告成。然而，这样的脚本距离一个可维护、可测试、可扩展的工程服务还有很长的路。真正有价值的起点，是把模型调用放进规范的工程结构里：配置如何注入、数据如何流转、客户端如何封装、服务如何编排、安全边界如何划定、测试反馈如何闭环。这些要素必须同时出现，服务才算真正立得住。

本文将从零开始，逐步搭出一个最小但完整的 Python Agent 服务骨架，重点不在于模型能力本身，而在于工程结构的完整性。

一、为什么“最小”不等于“最简”

“最小模型调用”的含义容易被误解。它指的是功能范围最小，而不是工程质量最低。一个最小服务同样应该具备清晰的分层、明确的职责边界和可验证的行为。

如果我们只写一个函数，把密钥、请求、解析、打印全部塞在一起，会立刻遇到几个问题：

• 密钥硬编码，无法在不同环境间切换；
• 模型请求散落在业务逻辑中，替换或升级时牵一发动全身；
• 没有稳定的输入输出结构，调用方需要了解模型细节；
• 无法在不消耗真实资源的情况下做自动化测试；
• 一旦上线，任何异常都只能靠日志猜测。

因此，“最小”应该理解为：保留一条完整链路，但每层只做一件事。这样做的好处是，后续增加工具调用、对话记忆、多轮编排时，只需在既有骨架上扩展，而不用推倒重来。

二、整体结构设计

一个最小可用的 Agent 服务，可以划分为以下几层：

1. 配置层：集中管理运行参数、模型标识、超时时间、密钥来源等。
2. DTO 层：定义请求与响应的数据结构，隔离内外部表示。
3. 客户端层：封装与模型服务的通信细节，包括重试、超时和错误映射。
4. 服务编排层：组织调用流程，处理业务规则，是 Agent 逻辑的核心。
5. 安全边界：控制密钥、输入输出、访问范围与资源消耗。
6. 测试反馈层：提供默认不依赖真实模型的测试路径，并支持显式开启真实调用。

下面依次展开。

三、配置层：把环境差异挡在代码之外

配置的第一原则是：代码不关心值从哪里来，只关心值是否合法。常见做法是使用环境变量配合配置对象。

from dataclasses import dataclass
import os
@dataclass(frozen=True)
class Settings:
    model_name: str
    api_base: str
    api_key: str
    timeout_seconds: float
    enable_real_model: bool
    @classmethod
    def from_env(cls) -> "Settings":
        return cls(
            model_name=os.getenv("AGENT_MODEL", "default-model"),
            api_base=os.getenv("AGENT_API_BASE", ""),
            api_key=os.getenv("AGENT_API_KEY", ""),
            timeout_seconds=float(os.getenv("AGENT_TIMEOUT", "30")),
            enable_real_model=os.getenv("AGENT_ENABLE_REAL", "false").lower() == "true",
        )

这里有几个关键点：

• enable_real_model 默认关闭，意味着默认测试不会触发真实调用；
• 配置对象不可变（frozen=True），避免运行期被意外修改；
• 缺失密钥时不直接抛异常，而是留待客户端层统一判断，便于测试替换。

配置层还要避免把密钥写进日志。建议在打印配置时对敏感字段做掩码处理。

四、DTO 层：让数据流动有形状

DTO（数据传输对象）的职责是定义清晰的输入输出契约。它不包含业务逻辑，只承载数据。

from dataclasses import dataclass, field
from typing import List, Optional
@dataclass
class Message:
    role: str
    content: str
@dataclass
class AgentRequest:
    messages: List[Message]
    temperature: float = 0.7
    max_tokens: Optional[int] = None
@dataclass
class AgentResponse:
    content: str
    model: str
    usage: dict = field(default_factory=dict)
    raw: Optional[dict] = None

使用 DTO 的好处在于：

• 内部逻辑与外部协议解耦，模型接口变化时只需调整客户端层；
• 类型明确，便于静态检查和单元测试；
• 请求与响应可被序列化，方便记录与回放。

在实际项目中，还可以加入 trace id、耗时等字段，为后续可观测性打基础。

五、客户端层：封装通信细节

客户端层只做一件事：把 DTO 请求发给模型服务，再把返回结果转成 DTO 响应。它不应包含业务判断。

import httpx
class ModelClient:
    def __init__(self, settings: Settings):
        self.settings = settings
    def complete(self, request: AgentRequest) -> AgentResponse:
        if not self.settings.enable_real_model:
            raise RuntimeError("真实模型调用未开启")
        payload = {
            "model": self.settings.model_name,
            "messages": [m.__dict__ for m in request.messages],
            "temperature": request.temperature,
        }
        headers = {"Authorization": f"Bearer {self.settings.api_key}"}
        with httpx.Client(timeout=self.settings.timeout_seconds) as client:
            resp = client.post(self.settings.api_base, json=payload, headers=headers)
            resp.raise_for_status()
            data = resp.json()
        return AgentResponse(
            content=data["choices"][0]["message"]["content"],
            model=data.get("model", self.settings.model_name),
            usage=data.get("usage", {}),
            raw=data,
        )

要点说明：

• 真实调用必须显式开启，默认路径会直接拒绝，保证测试安全；
• 超时由配置统一控制，避免请求悬挂；
• 错误通过异常向上抛出，由服务层决定如何处理；
• 保留 raw 字段，便于排查问题，但不应泄露到外部接口。

六、服务编排层：Agent 逻辑的落脚点

服务层是 Agent 的核心。它负责组织流程：校验输入、调用客户端、处理异常、整理输出。

class AgentService:
    def __init__(self, client: ModelClient):
        self.client = client
    def run(self, request: AgentRequest) -> AgentResponse:
        if not request.messages:
            raise ValueError("messages 不能为空")
        try:
            response = self.client.complete(request)
        except Exception as exc:
            raise RuntimeError(f"模型调用失败: {exc}") from exc
        return response

看起来简单，但这一层是后续扩展的关键位置：

• 加入工具调用时，可在此解析模型输出并执行工具；
• 加入多轮记忆时，可在此维护会话状态；
• 加入限流与降级时，可在此插入策略。

服务层应保持无状态（或显式管理状态），以便水平扩展。

七、安全边界：不可忽视的底线

安全边界至少覆盖三个方面：

1. 密钥安全：密钥只从环境读取，不写入代码库，不打印完整值。
2. 调用开关：默认关闭真实调用，避免测试环境和 CI 意外消耗资源。
3. 输入输出约束：对输入长度、角色合法性做校验；对输出不做盲目信任，必要时做过滤。

def validate(request: AgentRequest, max_chars: int = 8000) -> None:
    total = sum(len(m.content) for m in request.messages)
    if total > max_chars:
        raise ValueError("输入超过长度限制")
    for m in request.messages:
        if m.role not in {"system", "user", "assistant"}:
            raise ValueError(f"非法角色: {m.role}")

这些检查应在服务层入口处统一执行，而不是散落在各处。

八、测试反馈：默认安全，显式真实

测试策略的核心是：默认路径完全不依赖真实模型。

class FakeClient:
    def complete(self, request: AgentRequest) -> AgentResponse:
        return AgentResponse(
            content="echo: " + request.messages[-1].content,
            model="fake",
        )
def test_agent_service_echo():
    service = AgentService(FakeClient())
    resp = service.run(AgentRequest(messages=[Message("user", "hello")]))
    assert resp.content == "echo: hello"

对真实模型的测试，则通过环境变量显式开启：

import pytest
@pytest.mark.skipif(
    os.getenv("AGENT_ENABLE_REAL", "false").lower() != "true",
    reason="未开启真实模型测试",
)
def test_real_call():
    settings = Settings.from_env()
    service = AgentService(ModelClient(settings))
    resp = service.run(AgentRequest(messages=[Message("user", "ping")]))
    assert resp.content

这样做的价值在于：

• CI 中默认全部通过，不依赖外部服务；
• 开发者需要验证真实链路时，只需设置一个环境变量；
• 真实测试与单元测试分离，失败定位更清晰。

九、小结与下一步

本文从工程结构角度，完整搭建了一个最小 Python Agent 服务：配置集中管理、DTO 定义契约、客户端封装通信、服务层组织逻辑、安全边界守住底线、测试反馈保证可重复验证。默认测试不需要真实密钥，真实调用必须显式开启，这一约定贯穿始终。

这个骨架的价值不在于它现在能做什么，而在于它为后续扩展留好了位置。接下来可以在此基础上逐步加入工具调用、多轮对话、流式输出、可观测性等能力，而每一次扩展都只需在对应层内完成，不会破坏整体结构。工程化的意义，正在于此。