1. 入职第一件事拉代码库与架构冲击今天上午办完入职手续导师Tech Lead给我开通了 GitHub 权限让我把公司核心 Agent 项目的代码拉下来Clone。过去在学校做传统软件开发项目的目录结构一般很标准controllers/路由处理、services/业务逻辑、models/数据库表映射。只要逻辑确定数据顺着管道走就行。但当我打开这个 AI Agent 项目时目录结构完全颠覆了我的认知my-agent-system/ ├── config/ │ └── system_prompts.yaml # 1. 角色与人设定义 (System Prompts) ├── core/ │ ├── llm_client.py # 2. LLM 模型交互与 API 封装 │ ├── memory.py # 3. 记忆管理 (上下文窗口/向量检索) │ └── react_engine.py # 4. 思考推理引擎 (ReAct 循环) ├── tools/ # 5. 工具库 (Agent 的手和脚) │ ├── order_tools.py │ └── schema_definitions.py ├── schemas/ # 6. 数据约束与 Prompt 模版契约 └── main.py # 入口文件为了搞懂当用户发送一句“帮我查订单 ORD-12345678”时系统内部到底发生了什么我沿着入口main.py开启打点日志Print梳理出了整个系统的完整链路[用户输入] │ ▼ 1. main.py (入口) ── 接收用户字符串 帮我查订单 ORD-12345678 │ ├─ 2. config/system_prompts.yaml ── 加载 Agent 角色与规范约束 ├─ 3. tools/ ────────────────────── 读取注册的所有 Tool 及其 Schema 描述 │ ▼ 4. core/llm_client.py ── 将 [System Prompt 用户输入 Tools 列表] 发送给大模型 API │ ▼ 5. 大模型 (LLM) 推理决策 ── 返回结构化 JSON 响应: {tool_name: get_order_status, args: {order_id: ORD-12345678}} │ ▼ 6. core/react_engine.py ── 捕获大模型的调用请求解析参数分发给真正的函数 │ ▼ 7. tools/order_tools.py ── 执行 get_order_status()通过 SQL 查库获得数据结果 │ ▼ 8. core/llm_client.py ── 将工具执行结果 (Observation) 二次打包喂回给大模型 │ ▼ 9. 大模型 (LLM) ── 整理成人类能听懂的自然语言文本在 main.py 终端输出给用户传统软件与 AI Agent 开发的区别传统软件是A函数 - B函数 - C数据库的硬编码调用流程控制核心是确定性的代码。AI Agent 系统中core/react_engine.py充当了 CPU大模型充当了指令控制器tools/则是各种外设接口由概率模型自主决策执行路径。2. 今日补课搞懂三个关键概念在准备看tools/目录的代码前导师发现我眼神迷茫于是停下来给我补了三个关键概念(1) 什么是 Docstring给人看也是给 AI 看的注释在 Python 中Docstring 是紧跟在函数定义下方的多行字符串用包裹。传统开发中它只是给程序员看的方法说明但在 Agent 开发中Docstring 就是给大模型看的“工具使用说明书”。大模型会读取这段文字来判断什么时候该用这个函数、每个参数代表什么含义。(2) 什么是 JSON SchemaAI 调用的通信协议大模型本质上只输出文本。为了让大模型准确地调用后端的 API必须有一个标准的数据格式告诉模型“这个 API 需要哪些参数类型是什么必填项是哪个”。这个标准就是JSON Schema。它定义了结构的规范大模型决定调用时会严格按照这个规范生成 JSON 参数。(3) 什么是 Pydantic数据校验工具Python 是动态类型语言原生dict无法校验类型。如果模型传过来一个{order_id: 12345678}数字而非字符串直接传给数据库就会抛出 TypeError。Pydantic 是一个 Python 的数据校验库。它的强大之处在于不仅能自动帮我们校验数据类型是否合法还能直接一键导出符合 LLM 标准的 JSON Schema免去了手动编写 JSON 规范文件的麻烦。3. 真实数据库交互接入从 Mock 到 SQL在了解完上述概念后导师安排我在tools/order_tools.py中编写一个真实的订单查询工具。我没有使用伪造的字典数据而是写上了连接池与 PostgreSQL 的SQL 查询逻辑。import os import psycopg2 # PostgreSQL 数据库驱动 from psycopg2.extras import RealDictCursor from pydantic import BaseModel, Field # 1. 使用 Pydantic 定义数据约束契约 (Schema) class OrderQueryInput(BaseModel): order_id: str Field( ..., description用户的订单编号必须是 ORD- 开头加 8 位数字例如 ORD-12345678 ) # 2. 数据库连接配置 (从环境变量读取) DB_CONFIG { dbname: os.getenv(DB_NAME, company_db), user: os.getenv(DB_USER, postgres), password: os.getenv(DB_PASSWORD, secret), host: os.getenv(DB_HOST, localhost), port: os.getenv(DB_PORT, 5432) } def get_db_connection(): return psycopg2.connect(**DB_CONFIG) # 3. 供 Agent 调用的完整 Tool 函数 def get_order_status(order_id: str) - dict: 根据订单 ID 查询数据库中的真实订单状态与物流追踪信息。 当用户查询订单进度、物流单号、是否发货时调用此工具。 conn None try: conn get_db_connection() # 使用 RealDictCursor 让查询结果直接返回字典形式 with conn.cursor(cursor_factoryRealDictCursor) as cursor: # 安全参数化查询防止 SQL 注入 query SELECT order_id, status, carrier, tracking_number, updated_at FROM orders WHERE order_id %s; cursor.execute(query, (order_id,)) result cursor.fetchone() if not result: return {status: NotFound, message: f数据库中未找到编号为 {order_id} 的订单} return dict(result) except Exception as e: # 向 Agent 引擎抛出可读的错误信息便于 Agent 进行自我纠错或回退 return {status: Error, message: f数据库查询失败: {str(e)}} finally: if conn: conn.close()4. 今日复盘与收获认知转变Agent 开发的核心不只是“编写业务代码”更是“编写能让 LLM 正确理解并调用的接口与上下文Prompts Schemas”。链路闭环用户自然语言 $\rightarrow$ 大模型转化为结构化 JSON 参数Pydantic 校验参数格式 $\rightarrow$ Tool 提取参数拼装 SQL 查库数据库结果返回给大模型 $\rightarrow$ 大模型组织语言回答人类