AI Agent基础设施搭建指南：从配置管理到可观测性的完整实践-代码聚汇网

AI Agent基础设施搭建指南：从配置管理到可观测性的完整实践

The Type·2026-09-09·阅读 22 GEO检测（免费）

AI Agent基础设施搭建配置管理

|难度：普通|阅读约 43 分钟

LCODER这个系列走到问数智能体搭建的第二篇，基础设施搭建这块我琢磨了挺久。很多同学聊AI Agent开发，上来就写Agent循环、调Prompt，结果项目跑两步就卡壳——不是模型返回格式不对，就是数据库连不上，要不就是配置写死、到处是硬编码。这篇把我的做法完整过一遍，把问数智能体的地基打牢实。

我先交代一下这个项目的背景：问数智能体，简单说就是用自然语言去查数据，用户问“上个月华东区销售额前五的产品有哪些”，Agent负责理解、拆解、生成SQL、执行查询、再组织成答案。整个链路看着不复杂，但正因为要走通“模型—工具—数据”三层，基础设施层一旦偷懒，后面全要返工。这篇文章适合正在学Agent搭建的、想从纯聊天机器人往业务场景走的人，也适合团队里准备落地问数能力的后端同学，跟着把依赖选型、配置管理、Agent骨架、日志排查这一套跑起来。

这篇会涉及完整的目录设计、关键代码片段、配置方式，以及我在实际搭建中踩过的一些坑。不是哪家的官方教程，是我个人在LCODER项目里沉淀下来的做法，你可以直接拿来用，也可以按自己团队的规范改。

1. 基础设施搭建的整体思路与架构选择

1.1 问数智能体到底需要哪些基础设施

先说个容易被忽视的事实：问数Agent不是一个“大模型API调用”就完事的东西。它本质上是一个系统，由模型调用、Agent调度、工具执行、数据访问、配置管理、日志监控这几层拼起来。

模型调用层：统一封装LLM的请求、超时、重试、参数管理。
Agent调度层：负责任务拆解、工具选择、循环决策，这是“智能”的核心。
工具层：问数场景里最典型的就是数据库查询工具，需要安全地执行SQL并返回结构化结果。
数据访问层：管理数据库连接、连接池、schema缓存。
配置管理：API密钥、模型名、数据库地址、超时等，全部集中管理。
日志与可观测：每轮思考、每次工具调用、每次模型返回都要有迹可循。

很多人一上来就写业务逻辑，最后卡在最基础的问题上：API密钥写死在代码里、换了模型要改十几个文件、数据库连接用一次关一次、Agent一旦循环就卡住超时。这些问题的根源都一样——基础设施层没有做充分的抽象和兜底。

我在LCODER里给自己定了几条原则：模型可以随时换、配置不碰代码、工具可插拔、每步留日志。这四条落实到代码上，就是下面要讲的内容。

1.2 技术选型：框架自研还是用现成的

这两年Agent框架层出不穷，LangChain、LangGraph、AutoGen、CrewAI，还有国内的一些平台级方案。我的选择是：核心不依赖重框架，自己写Agent调度层；工具和模型接入采用轻量封装，按需引入。

为什么这么做，主要三个原因。

第一，问数场景的决策链路相对固定：理解问题、抽取查询条件、生成SQL、执行、总结。用LangChain那套Chain的概念反而绕，自研一个几十行的循环就能跑通，出问题时好排查。

第二，框架的依赖传递太重。很多框架为了兼容各种场景，底层塞了一大堆可选依赖，光装包就能把环境搞乱。而在基础设施搭建这个阶段，依赖越少，越容易定位问题。

第三，从学习和面试的角度来说，自己把Agent循环写一遍，你才真正理解工具注册、上下文组织、终止条件这些东西的运作逻辑。很多“AI Agent面试题”问的就是这些机制的内部设计，框架用多了反而答不上来。

当然不是说框架不好，如果你有团队标准或者是要快速交付，用LangGraph这类工具也完全没问题。我的建议是看你的业务复杂度：链路固定、工具少、追求可控，自研足够；多智能体协作、需要人工介入、复杂状态管理，再上框架。LCODER的定位是实战教学和可控落地，所以我选了前者。

1.3 环境准备与依赖管理

这块我强烈建议别用裸pip + requirements.txt凑合了，试一下uv。uv是目前Python生态里非常顺手的包管理工具，底层用Rust写的，安装依赖的速度比pip快很多，而且自带虚拟环境管理、锁文件机制，一个工具解决大半环境问题。

安装uv只需要一行命令，官方脚本装好后，创建一个Python 3.10+的项目环境：

bash复制uv venv .venv --python 3.10
source .venv/bin/activate  # Windows下是 .venv\Scripts\activate
uv pip install ...

选Python 3.10以上，是因为新版类型语法（X | None、match）、Pydantic v2的特性，以及很多新库对旧版本支持不好。问数项目里我用的Python版本是3.11，稳定且生态兼容最好。

核心依赖我按功能拆分：

bash复制# AI核心
uv pip install openai pydantic pydantic-settings python-dotenv

# 工具与数据访问
uv pip install sqlalchemy pymysql pandas tabulate

# 日志与调试
uv pip install loguru

对照一下每类的作用：openai负责模型调用（目前大多数兼容OpenAI协议的模型都能用），pydantic-settings负责配置管理，sqlalchemy负责数据库连接池和ORM级操作，pandas用来处理查询结果，tabulate把结果格式化成文本给模型总结，loguru专门用来打日志。

这里我要单独说一句：依赖一定要按需要装，不是越多越好。你每多一个第三方库，就多一层版本冲突风险和接口适配成本。比如有些框架自带的查询引擎，最终还是要读写数据库，与其被它的抽象绕晕，不如直接用SQLAlchemy自己掌控。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 配置层与大模型接入

2.1 用pydantic-settings管好所有配置

问数Agent的配置项比普通应用要多：有大模型的API地址、模型名称、温度、超时；有数据库的地址、账号、连接池大小；有Agent的最大迭代次数、日志级别。如果全散在代码里，换环境就是一场灾难。

我用pydantic-settings把所有配置集中到一个地方。它比直接读环境变量好用的地方在于：有类型校验、有默认值、支持嵌套模型、能自动从.env文件和环境变量加载。

python复制# config/settings.py
from pydantic_settings import BaseSettings, SettingsConfigDict
from pydantic import Field

class LLMSettings(BaseSettings):
    model_config = SettingsConfigDict(env_prefix="LLM_")

    api_key: str = Field(..., description="API Key")
    base_url: str = Field("https://api.openai.com/v1", description="API Base URL")
    model: str = Field("gpt-4o-mini", description="模型名称")
    temperature: float = Field(0.1, ge=0.0, le=2.0)
    max_tokens: int = Field(2048)
    timeout: float = Field(30.0, description="请求超时时间(秒)")
    max_retries: int = Field(3, description="失败重试次数")

class DatabaseSettings(BaseSettings):
    model_config = SettingsConfigDict(env_prefix="DB_")

    host: str = Field("127.0.0.1")
    port: int = Field(3306)
    user: str = Field("root")
    password: str = Field("")
    database: str = Field("test")
    pool_size: int = Field(5)
    max_overflow: int = Field(10)
    charset: str = Field("utf8mb4")

class AgentSettings(BaseSettings):
    model_config = SettingsConfigDict(env_prefix="AGENT_")

    max_iterations: int = Field(5, description="最大执行轮数")
    sql_limit: int = Field(200, description="SQL查询最大返回行数")
    readonly: bool = Field(True, description="是否强制只读查询")

class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        extra="ignore",
    )
    llm: LLMSettings = LLMSettings()
    db: DatabaseSettings = DatabaseSettings()
    agent: AgentSettings = AgentSettings()

settings = Settings()

这套设计的好处是环境变量前缀直接对应分组：LLM_MODEL、DB_HOST、AGENT_MAX_ITERATIONS，一看就知道属于哪层。换环境的时候只改.env文件，代码不动分毫。

2.2 LLM客户端封装要点

很多初学者直接在业务代码里from openai import OpenAI，然后到处调用。我强烈不建议这么干。问数场景下，你需要统一处理几件事：超时、重试、token限制、日志埋点。把这些逻辑散落到每个调用处，后面排查问题会非常痛苦。

我封装了一个极简的LLM客户端，复用官方SDK的能力，但把Agent相关的控制面收拢起来：

python复制# core/llm.py
from openai import OpenAI
from config.settings import settings
from loguru import logger

class LLMClient:
    def __init__(self):
        self.client = OpenAI(
            api_key=settings.llm.api_key,
            base_url=settings.llm.base_url,
            timeout=settings.llm.timeout,
            max_retries=settings.llm.max_retries,
        )
        self.model = settings.llm.model
        self.temperature = settings.llm.temperature
        self.max_tokens = settings.llm.max_tokens

    def chat(self, messages: list[dict], **kwargs) -> str:
        """统一的聊天接口，每次都记录日志"""
        logger.debug(f"LLM请求 -> model={self.model}, messages_len={len(messages)}")
        resp = self.client.chat.completions.create(
            model=self.model,
            messages=messages,
            temperature=kwargs.get("temperature", self.temperature),
            max_tokens=kwargs.get("max_tokens", self.max_tokens),
        )
        content = resp.choices[0].message.content
        logger.debug(f"LLM响应 -> {content[:100]}")
        return content

为什么要单独设temperature=0.1？因为问数场景是确定性任务，你要求模型生成SQL和做逻辑判断，不需要它天马行空。温度越高，SQL语法错误的概率越大，字段名幻觉越多。实测中0.1和0.0差别不大，但稍微留点余地可以让它在生成自然语言解释时更灵活。

这里有个很重要的实践心得：在调试阶段，日志要打在“进入模型前”和“拿到模型后”两处，而不是只打最终结果。很多问题不是模型回答错，而是你的上下文本身就给错了。有了入口和出口的日志，一眼就能定位是“喂进去的问题错”还是“模型理解错”。

2.3 密钥与敏感信息管理

密钥管理这个事，说大不大，但出事就是大事。我在LCODER里明确了两条规矩：第一，密钥只放在.env，不进代码、不进git；第二，.env文件必须在.gitignore中，提交一个.env.example作为配置模板。

bash复制# .env.example —— 提交到仓库
LLM_API_KEY=sk-xxxxxxxxxx
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4o-mini
LLM_TEMPERATURE=0.1

DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_DATABASE=your_db

AGENT_MAX_ITERATIONS=5

gitignore复制# .gitignore
.env
.venv/
__pycache__/
*.pyc

很多团队出过这种事：开发把.env提交到公开仓库，API Key泄露，白白损失一笔费用。防这个只需要一条.gitignore规则。

另外说一句，如果你用的是企业级方案，可以把密钥放到KMS或Vault里。但本地开发和实战项目，.env + gitignore已经足够了，别为了“规范”过度设计。

3. Agent骨架与核心执行流程

3.1 项目目录结构设计

基础设施搭得好不好，看目录结构就能看出一大半。我最终的目录组织如下：

text复制lcoder_askdata/
├── .env
├── .env.example
├── .gitignore
├── pyproject.toml
├── config/
│   └── settings.py          # 配置集中管理
├── core/
│   ├── __init__.py
│   ├── llm.py               # LLM客户端封装
│   ├── agent.py             # Agent执行循环
│   └── schema.py            # 数据模型定义
├── tools/
│   ├── __init__.py
│   ├── registry.py          # 工具注册表
│   └── db_tools.py          # 数据库查询工具
├── prompts/
│   ├── __init__.py
│   └── askdata.py           # 提示词模板
├── logs/
│   └── app.log
├── main.py                  # 入口
└── requirements.txt

这个结构遵循一个原则：按“层”分包，不按“功能”分包。config放配置，core放Agent核心逻辑，tools放工具，prompts放提示词。后面加新的工具就在tools下加文件，加新的Agent能力就在core下扩展。如果按功能分包，就会出现“买票功能”和“查数功能”互相穿插，代码越写越乱。

3.2 Agent执行主循环实现

Agent的核心不是某个高深的算法，而是一个简单的循环：接收任务 -> 决定动作 -> 调用工具 -> 观察结果 -> 循环，直到可以回答或达到上限。我把这个循环实现成一个类，控制在100行以内，便于理解和调试。

python复制# core/agent.py
from loguru import logger
from config.settings import settings
from core.llm import LLMClient
from tools.registry import ToolRegistry

class Agent:
    def __init__(self):
        self.llm = LLMClient()
        self.registry = ToolRegistry()
        self.max_iterations = settings.agent.max_iterations

    def run(self, user_query: str) -> str:
        messages = self._build_system_messages()
        messages.append({"role": "user", "content": user_query})

        for step in range(1, self.max_iterations + 1):
            logger.info(f"Agent第{step}轮思考开始")

            response = self.llm.chat(messages)
            messages.append({"role": "assistant", "content": response})

            decision = self._parse_decision(response)
            if decision["type"] == "final":
                return decision["answer"]

            tool_name = decision["tool"]
            tool_args = decision["args"]
            logger.info(f"调用工具 {tool_name}, 参数: {tool_args}")

            result = self.registry.execute(tool_name, **tool_args)
            logger.info(f"工具返回: {str(result)[:200]}")

            messages.append({
                "role": "tool",
                "tool_call_id": tool_name,
                "content": str(result),
            })

        return "抱歉，任务超过最大处理轮数，请简化问题后重试。"

有几个关键设计点要说明。

第一，max_iterations是Agent的“刹车”。没有它，模型如果一直在“调用工具-观察结果”的圈子里出不来，请求会无限卡住。我的默认值是5，足够处理正常问数任务（通常是2-3轮），也不会让用户等太久。

第二，_parse_decision负责解析模型输出。我用的是“结构化输出”方案——要求模型返回JSON格式，指定动作类型（call_tool或final）、工具名、参数。解析出错时要兜底，格式化要求不严格，这部分在实战里最容易出问题，后面单讲。

第三，工具调用结果以tool角色回传给模型。这是走OpenAI兼容协议的标准方式。role=tool让模型知道这是工具执行的结果，不是用户的话，避免它混淆上下文。

3.3 核心工具：数据库查询与安全控制

问数Agent最重要的工具就是数据库查询。这个工具的设计直接决定Agent是“能用的demo”还是“可落地的系统”。我在实现时考虑了三个层面：连接管理、schema信息注入、安全执行。

连接管理用SQLAlchemy的create_engine，自动管理连接池，避免频繁建连和断连：

python复制# tools/db_tools.py
from sqlalchemy import create_engine, text
from config.settings import settings
from loguru import logger
import pandas as pd

engine = create_engine(
    f"mysql+pymysql://{settings.db.user}:{settings.db.password}@{settings.db.host}:{settings.db.port}/{settings.db.database}?charset={settings.db.charset}",
    pool_size=settings.db.pool_size,
    max_overflow=settings.db.max_overflow,
    pool_pre_ping=True,
)

pool_pre_ping=True值得单独说一句：它会在每次从连接池取连接前先ping一下，过期连接自动重建。数据库重启、网络闪断后，Agent不会因为拿到坏连接而报错。

schema信息是问数准确性的关键。模型生成SQL前必须知道有哪些表、每个表有哪些字段。我写了一个函数拉取当前库的表结构，并在Agent启动时注入系统提示词：

python复制def get_schema_info() -> str:
    """获取数据库schema信息，格式化成文本"""
    schema_sql = text("""
        SELECT TABLE_NAME, COLUMN_NAME, DATA_TYPE
        FROM information_schema.COLUMNS
        WHERE TABLE_SCHEMA = :db
        ORDER BY TABLE_NAME, ORDINAL_POSITION
    """)
    with engine.connect() as conn:
        rows = conn.execute(schema_sql, {"db": settings.db.database}).fetchall()

    schema_map = {}
    for row in rows:
        schema_map.setdefault(row[0], []).append(f"{row[1]}({row[2]})")
    return "\n".join(f"表 {table}: {', '.join(cols)}" for table, cols in schema_map.items())

安全执行是问数项目的高压线。我用一个执行函数强制加了几层保护：

python复制def execute_query(sql: str) -> str:
    """安全执行查询SQL并返回结果"""
    # 只读保护
    forbidden = {"insert", "update", "delete", "drop", "alter", "truncate", "create", "replace", "grant"}
    first_word = sql.strip().split()[0].lower()
    if first_word in forbidden:
        return "错误：仅允许SELECT查询"

    # 强制加LIMIT
    if "limit" not in sql.lower():
        sql = sql.rstrip().rstrip(";") + f" LIMIT {settings.agent.sql_limit}"

    logger.info(f"执行SQL -> {sql}")
    try:
        with engine.connect() as conn:
            df = pd.read_sql_query(sql, conn)
        if df.empty:
            return "查询结果为空"
        return df.to_markdown(index=False)
    except Exception as e:
        logger.error(f"SQL执行失败: {e}")
        return f"SQL执行错误: {e}"

这里用pd.read_sql_query纯读库，在SQLAlchemy连接上执行，配合前面在Agent层的工具注册，组成完整链路。

要注意的一个细节：LIMIT保护。用户一句“把全表数据都查出来”，如果没有LIMIT，几百万行数据直接打到Agent上下文里，token爆掉。我的做法是SQL里没有LIMIT就自动追加一个上限，并且上限值也可以通过环境变量AGENT_SQL_LIMIT动态调整。

4. 日志、异常与可观测性

4.1 用loguru搭一套分层日志

Agent系统的日志比普通业务系统更重要，因为它的“状态”是动态的——你不知道模型下一步会做什么。所以要记录的内容包括：每轮思考的输入、工具调用参数、工具返回结果、模型输出。我统一用loguru，配置一次，终端和文件同时输出：

python复制# core/logger.py
import sys
from loguru import logger

logger.remove()
logger.add(
    sys.stderr,
    level="DEBUG",
    format="<green>{time:HH:mm:ss}</green> | <level>{level: <5}</level> | <cyan>{name}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>",
)
logger.add(
    "logs/app.log",
    level="INFO",
    rotation="5 MB",
    retention="7 days",
)

rotation=5 MB和retention=7 days这两个参数很重要：日志文件按大小自动滚动、按天自动保留，不会无限占磁盘。

实际排查问题时，我会直接在代码关键路径打上这些日志：

收到用户问题
调用LLM前（记录上下文长度）
模型返回后（记录决策类型）
执行工具前（记录函数名和参数）
工具返回后（记录结果前200字符）
Agent结束时（记录总轮数）

有了这套日志，可以做到“回放式”排查：出问题时打开日志，每一步都清清楚楚，不需要用户复述操作过程。

4.2 基础设施层常踩的坑

这里把我在问数项目里真实遇到过的坑列出来，都是基础设施层面的，提前避开能省很多时间。

坑一：LLM请求超时不设，用户挂起半小时。 第一次测试时，模型服务如果响应慢或网络抖动，没有timeout的请求会一直卡着，用户等得心态炸了。在LLMClient里我显式设置了30秒超时，并配置了重试3次。Agent层面再兜一个整体超时时间，超过直接返回友好提示。

坑二：环境变量加载顺序不对，配置全是None。 pydantic-settings本身的加载顺序是“环境变量 > .env文件 > 默认值”。但如果你在.env里写了LLM_API_KEY，而系统环境变量里也恰巧有一个旧的同名变量，那系统环境变量优先。调试时发现API Key总是“莫名的值”，先echo $LLM_API_KEY看一下。

坑三：数据库连接不释放，连接池被耗尽。 SQLAlchemy的engine.connect()拿到连接后一定要用上下文管理器或finally关掉。用with engine.connect() as conn:这种写法最稳妥，异常也会自动归还连接。不要手写conn = engine.connect()然后忘了close。

坑四：模型返回的JSON解析崩了。 模型不是机器，偶尔会返回带解释文字的一堆东西，比如“根据您的请求，我的答案是：{...}”。我用一个容错解析函数，先提取大括号部分再json.loads，实在解析不了就返回“请重新表达”给模型，让它重新生成。千万不要让json.loads直接抛异常中止整个Agent。

4.3 排查思路记录

日志系统搭好之后，排查问题的思路就清晰了。我一般按下面四层定位：

配置层：先看启动日志里的配置信息，确认识别到正确的环境、数据库、模型地址。
LLM接入层：用一个固定测试问题，看模型是否能正常返回。如果返回空或超时，检查API Key、Base URL、网络连通性。
工具执行层：看Agent日志里的SQL语句，复制到数据库客户端手动执行，确认是SQL问题还是连接问题。
Agent调度层：看模型每次返回的JSON决策是否符合预期，看是否陷入循环。

举个例子，有个真实问题：用户问“近7天订单量”，Agent返回“找不到字段order_id”。我打开日志看两步：第一步，schema信息里确实没有order_id，表里叫order_number；第二步，模型根据schema生成SQL正确。这问题根因是建表时的字段命名和业务口语不一致，不是Agent的错。解决方式是优化schema描述，在表结构信息里补上一行注释“订单号字段为order_number，业务上常称为order_id”。这个思路对任何“模型找不到字段”的问题都适用：喂给模型的信息不够，模型就会猜。

5. 实操复盘与后续扩展思路

5.1 从零到一的最小验证

基础设施搭完，第一件事不是急着写复杂功能，而是跑一个最小冒烟测试，验证“配置 — 模型 — 日志”这条链路是否通畅：

python复制# smoke_test.py
from core.llm import LLMClient
from loguru import logger

def test_llm():
    client = LLMClient()
    reply = client.chat([
        {"role": "system", "content": "你是一个数据查询助手，请用中文回答。"},
        {"role": "user", "content": "你好，能正常工作吗？"},
    ])
    assert len(reply) > 0
    logger.info(f"冒烟测试通过，模型回复: {reply}")

if __name__ == "__main__":
    test_llm()

这一步过了，再测数据库工具、Agent循环。好处是一条链路一条链路验证，出问题能精确知道是哪一层。

5.2 基础设施后续扩展方向

第一版跑通之后，我列了几个后续要做的扩展，你可以按需取舍：

多模型路由：简单问题用小模型省钱，复杂SQL生成用大模型保证准确率，基于配置层扩展很容易做。
向量记忆库：用户经常问的“上个月销量”“同比环比”这类查询，把历史查询结果缓存成向量，下次直接给答案，节省大量token。
多Agent协作：把“理解用户意图”和“生成SQL”拆成两个Agent，各司其职。前提是基础设施层的工具注册和日志机制已经稳定，可以把单个Agent的能力复制给其他Agent使用。
数据权限控制：企业真实落地时，不同用户只能查询自己角色范围内的数据，这个可以在工具执行层加统一拦截。

这些扩展都在当前基础设施的框架内做，不会推翻重建。这也是为什么我坚持把配置、日志、工具注册这些“地基层”做好——后面的所有功能都站在它上面。

5.3 挖个小细节：一个简单却救命的“重试”技巧

最后分享一个我在基础设施调试中特别常用的技巧：拿到模型返回的内容后，永远先打印后截取，别直接处理。

python复制response = self.llm.chat(messages)
logger.debug(f"原始响应全文: {response}")  # 先打全文

在调试阶段，打全文能让你看见模型的真实输出格式，包括它带的解释、多余的换行、甚至Markdown符号。等你确认稳定了再改成截取前100字符。别嫌日志啰嗦，出问题的时候，这行“原始响应全文”比任何调试器都管用。

我个人在实际搭建中的体会是：AI Agent项目的复杂度，很大一部分不在“智能”本身，而在基础设施的完备度上。把配置管好、日志打好、工具封稳、安全守住，Agent的智能部分才有发挥空间。LCODER系列后面还会继续深入问数项目的具体业务逻辑实现，基础设施这关过了，下一步就能专注在Agent的推理链路和调优上了。