智能体 Agent 自动化配置实现

写好一次配置体系，以后每个新项目只改 JSON，配置代码零重写。这就是今天要聊的事。

实际开发中，项目的配置管理是个高频场景。每次新建项目都要重新设计结构、手写数据类、处理字段映射... 这些重复劳动既耗时又容易出错。更头疼的是换项目时配置代码往往不能直接搬过来，得改这改那。

你有没有想过：为什么每次都要从头做这些事？能不能只做一次，以后一直复用？

本文围绕 Pydantic 配置管理主要澄清四个问题：

1. 1. 一套 三层继承 + 聚合根 的配置类架构设计
2. 2. JSON 键值与 Python 类的 自动映射 及命名兼容
3. 3. 敏感信息的 环境变量兜底注入 机制
4. 4. 将整套能力封装为 Skill 模板，实现 1 到 N 的跨项目复用

搞清楚这四个问题，基本就能做到换个项目只改 JSON。

关注“AI老马” —【获取资源】&【进群交流】

1，配置类的三层架构

一个 JSON 配置文件，怎么对应到代码里的类？

最直觉的做法是把所有配置塞进大字典，用到的地方 config["agent"]["default"]["model"] 这样一级级取。能用，但没有类型提示、没有默认值校验、重构时全靠搜索替换。项目一大就很难维护。

所以这里用的是 Pydantic 数据类体系，而且分了三层。

1.1 第一层：BaseModel 基础层

所有配置项的"祖宗"。把通用能力统一放在 BaseModel 里，子类继承即可：

from pydantic import BaseModel

class BaseConfig(BaseModel):
    """基础配置类，统一设置"""
    class Config:
        # 统一的 Pydantic 行为配置放在这里
        ...

为什么要抽这么一层？因为有些全局设置 -- 比如命名风格、序列化行为 -- 肯定不希望每个类都写一遍。配好一次，所有子类自动继承。后面要改全局行为，只需动这一处，所有下游类同步生效。

这其实就是 DRY 原则（Don't Repeat Yourself）在配置体系里的具体体现 -- 变化的东西分散到各业务类，不变的东西收敛到基类。

1.2 第二层：业务数据类层

按功能域拆分的具体配置类。比如 Agent 相关的、API 工具相关的，各自独立：

class AgentDefault(BaseConfig):
    """Agent 默认配置"""
    model: str = "gpt-4o"
    max_tokens: int = 8192
    temperature: float = 0.7

class ApiToolsDefault(BaseConfig):
    """API 工具默认配置"""
    api_base: str = "https://api.openai.com/v1"
    timeout: int = 30

注意这里用 BaseConfig 作父类而非直接继承 BaseModel。意思是 BaseConfig 里设好的规则（比如命名兼容策略），下游所有业务类天然就有，不用各自重复声明。

1.3 第三层：聚合根（Settings 类）

对外暴露的唯一入口。把上面所有的业务数据类"聚"到一起：

from pydantic import Field

class Settings(BaseConfig):
    """聚合根 -- 统一对外交互入口"""

    agent: AgentDefault = Field(default_factory=AgentDefault)
    api_tools: ApiToolsDefault = Field(default_factory=ApiToolsDefault)

这个设计的意图很明确：

• • 外部只需实例化 Settings 一个对象，就能取到所有配置
• • 取值方式是点号链式访问：settings.agent.default.model
• • 新增配置域只需加一个字段 + 对应的数据类，不动已有代码

三层的关系可以概括为：

BaseModel (第1层：统一行为)
    └── BaseConfig (封装全局设置)
            ├── AgentDefault (第2层：具体业务配置)
            ├── ApiToolsDefault
            └── ...
Settings (第3层：聚合根，组装所有业务类)

2，JSON 与类的映射关系

架构搭好了，下一个问题来了 -- JSON 文件里的层级结构，怎么和代码里的类一一对应上？

2.1 层级对齐

假设有这样一个 JSON 配置：

{
    "agent": {
        "default": {
            "model": "gpt-4o",
            "max_tokens": 8192
        }
    },
    "api_tools": {}
}

三级嵌套，和三层架构正好对应：

实例化之后，取值就是一句话的事：

settings = Settings()  # 从 JSON 自动解析
print(settings.agent.default.model)       # gpt-4o
print(settings.agent.default.max_tokens)  # 8192

有个细节值得注意：AgentDefault 用的是 Field(default_factory=...) 形式。JSON 里没写 agent 这段的话，它会用默认值实例填充，不会报错。传了就用你的，没传就用默认的 -- 兼容性拉满。

2.2 命名风格的兼容

还有一个容易踩坑的地方：命名风格不一致。

JSON 里一般用 snake_case（比如 api_base），但外部系统或前端传来的是 camelCase（比如 apiBase）。框架只认一种的话，另一边就会报字段找不到。

做法是 输入双兼容 + 输出统一为 camelCase：

class ApiTools(BaseConfig):
    api_base: str = "https://api.openai.com/v1"

    class Config:
        alias_generator = to_camel      # 输出时统一转 camelCase
        populate_by_name = True         # 输入时两种风格都接受

验证一下效果：

# 输入 snake_case
api = ApiTools(api_base="https://example.com")

# 输入 camelCase 也行
api = ApiTools(apiBase="https://example.com")

# 输出统一为 camelCase
print(api.model_dump(by_alias=True))
# {'apiBase': 'https://example.com'}

print(api.model_dump())  # by_alias=False 时保留原样
# {'api_base': 'https://example.com'}

populate_by_name=True 是关键 -- 它让 Pydantic 匹配字段名时同时检查原始名和别名。这对 FastAPI 场景特别有用：前端传什么格式都能接住。如果你做过前后端联调，应该踩过这个坑 -- 前端传 userName，后端字段叫 user_name，直接 422 报错。有了这层兼容，这类问题就不存在了。

3，敏感信息的环境变量注入

配置文件里最不想写的，就是 API Key 这类敏感信息。写进去怕提交代码库泄露；不写程序启动就报错。

解决方案是：环境变量兜底。

from pydantic import Field
import os

class AgentDefault(BaseConfig):
    model: str = "gpt-4o"
    api_key: Optional[str] = Field(default=None)

    def __init__(self, **data):
        super().__init__(**data)
        if self.api_key is None:
            self.api_key = os.getenv("API_KEY")

它的运行逻辑是这样的：

也就是说，JSON 配置优先于环境变量。本地开发时把 key 写在 JSON 方便调试，部署时删掉改成环境变量注入 -- 同一份代码，两套用法，零改动切换。

这套优先级设计的实际好处是：团队成员之间可以共享一份不含密钥的 JSON 配置（提交到代码库），每个人在自己的环境变量里填上自己的 Key，互不干扰，也不会有泄露风险。

实际项目中推荐用 pydantic-settings 库，它内置了这个能力，不用手写上面的 __init__ 逻辑。原理一致。

4，从 1 到 N：封装成 Skill 模板

前三部分解决了单个项目的配置问题。来了新项目怎么办？

改几个字段还行，十几个配置域、几十个参数就很折磨了。既然这套体系的结构是固定的（三层架构 + 映射规则 + 环境变量模式），能不能做成模板，让 AI 根据新的 JSON 直接生成全套代码？

这就是 Skill 的思路。

4.1 Skill 的工作流

给定一个新的项目 JSON 配置文件，Skill 会依次产出三样东西：

新项目 JSON 配置
       |
       v
  [Step 1] Schema 生成 -> 生成数据类（第二层的各 XXXDefault 类）
       |
       v
  [Step 2] 聚合根生成   -> Settings 聚合根 + load_config 加载函数
       |
       v
  [Step 3] Demo 输出    -> 示例（导入、实例化、取值）

最终拿到开箱即用的目录：

new_project_config/
├── config.json          <- 你填写的项目配置
├── schema.py             <- 自动生成的数据类
├── settings.py           <- 聚合根 + 加载逻辑
└── demo.py               <- 使用示例

4.2 两种加载方式

生成的代码支持两种初始化方式，效果完全一样：

方式 A：构造时传入字典

import json
with open("config.json") as f:
    data = json.load(f)
settings = Settings(**data)  # 自动解析为对象

方式 B：类方法加载

settings = Settings.from_json("config.json")

选哪种都行，看个人习惯。关键是换了项目，只需要准备一份新的 config.json，剩下的代码全部由 Skill 生成。从"手写配置代码"变成"填 JSON 就完事"，效率提升是明显的。

总结

回头看整个方案的四个环节：

实际开发中可以在这套基础上继续扩展：配置热更新（修改 JSON 后不重启即生效）、多环境切换（dev/test/prod 各一套配置文件）、配置校验钩子（启动时检查必填项是否完整）等等。

但底层思路不变：配置是数据，代码是结构，JSON 是桥梁，Skill 是放大器。 数据和结构分离后两边各自独立演化，通过 JSON 这个中间层对接 -- 这就是这套方案能跨项目复用的根本原因。

说到底，一个好的配置架构不在于它有多复杂，而在于它把"变的"和"不变的"分得有多清楚。JSON 会变（每个项目不同），Skill 生成的代码结构不变（模式固定），BaseConfig 里的规则基本不变（全局行为）。三层各司其职，这就是它的生命力所在。