企业官网建设流程全解析

简介：本资源是O’Reilly Media出版的早期预发布电子书《Building Applications with AI Agents》，作者Michael Albada，面向AI工程实践者、系统架构师及进阶开发者，聚焦多智能体系统的设计与落地难题。书中以未编辑的原始内容形式抢先释放核心章节（如第3章Skills、第4章Orchestration），涵盖代理能力建模、任务编排机制、记忆设计原理等关键实践模块，助力读者在正式版上市前掌握AI Agent开发的核心范式与工程约束。资源为单文件PDF格式，共1个文件，大小558KB，轻量易读，适合作为技术预研与架构选型参考。目前已有441人学习下载，内容虽属Early Release版本，但已包含可直接复用的系统设计逻辑、生产级监控与防护思路提示，以及对开源许可与知识产权风险的明确说明，具备强实操引导性与法律合规提醒价值。

1. AI Agent 技能设计不是“加个工具就完事”：为什么90%的课设/毕设在第二章就卡死在“技能调不通”上？

你写完 prompt，跑通了单次 LLM 调用，兴冲冲接入一个 calculator 工具——结果 agent 死活不调用函数，或者调用了却传错参数、返回空值、甚至把{"x": "393", "y": "12.25"}当字符串直接扔进float()导致ValueError；你换了个 Wikipedia 工具，query 写成"Buzz Aldrin birth date"，API 却返回“Page not found”，而你翻遍文档才发现它只认"Buzz Aldrin"这种标准词条名；更常见的是：本地测试全绿，一上 Docker 就报ModuleNotFoundError: No module named 'langchain_community'，连环境都搭不齐……这不是玄学，是技能设计没过“三关”：语义对齐关、协议契约关、工程落地关。本方案不是教你抄几行 LangChain 代码，而是从某高校课程设计答辩现场真实翻车案例出发，拆解一套可交付、可答辩、可复现的 AI Agent 技能模块设计方案——覆盖手写技能（calculator / unit convert）、API 技能（stock / weather / internal KB）、混合技能（先查内部知识库再调计算服务），含完整模块划分、参数契约表、错误日志对照表、以及最关键的——如何让导师一眼看懂你不是在调包，而是在做系统设计。适合正在做“AI Agent 系统设计”类毕设、课设，或需快速交付可演示原型的工程师。

2. 技能模块化设计：三层结构与四个核心职责的硬性划分

AI Agent 的技能绝非“一堆 @tool 函数堆在一起”。真正能通过答辩、能上线、能维护的技能系统，必须有清晰的分层边界和职责契约。我带过的三个模拟项目X（含某跨平台智能工单系统、某实验室设备调度Agent、某企业级知识助手）全部采用统一的三层结构：接口层（Interface Layer）、执行层（Execution Layer）、适配层（Adaptation Layer）。这三层不是可选概念，而是解决“LLM乱调用”“参数类型错”“错误不可控”三大高频问题的物理隔离带。

2.1 接口层：定义技能的“法律合同”，而非函数签名

很多同学直接拿 Python 函数当技能接口，比如def add(x: float, y: float) -> float，这埋下巨大隐患：LLM 可能传入"12.3"字符串，也可能传入None，还可能漏传y。接口层要做的，是把函数签名升级为带校验、带默认、带语义约束的技能契约。

LangChain 的@tool装饰器只是起点，真正的接口层需额外封装一层验证逻辑。以加法技能为例：

from pydantic import BaseModel, Field, validator from typing import Optional class AddInput(BaseModel): x: float = Field(..., description="第一个操作数，必须为数字") y: float = Field(..., description="第二个操作数，必须为数字") @validator('x', 'y') def validate_numeric(cls, v): if not isinstance(v, (int, float)): raise ValueError(f"输入必须为数字，当前类型: {type(v).__name__}") if abs(v) > 1e12: raise ValueError("数值过大，超出安全计算范围") return float(v) @tool(args_schema=AddInput) def add(x: float, y: float) -> str: """执行两个浮点数相加，返回格式化字符串结果""" result = x + y return f"{x} + {y} = {result:.4f}"

提示：args_schema不是可选项。它强制 LLM 在生成 tool_call 时必须输出符合 Pydantic 模型的 JSON，否则invoke()直接抛ValidationError，而不是让错误流入执行层。这是拦截“类型错”的第一道防火墙。

关键设计说明：

• Field(..., description=...)的描述会进入 LLM 的 system prompt，直接影响其调用决策；
• @validator是运行时守门员，比try/except更早拦截非法输入；
• 返回值类型设为str而非float，是因为 LLM 需要文本上下文，直接返回数字反而增加解析负担。

2.2 执行层：纯逻辑、无副作用、可单元测试的原子块

执行层是技能的“心脏”，它只做一件事：给定合法输入，返回确定输出。绝不包含网络请求、文件读写、全局状态修改等副作用。所有外部依赖必须由上层注入。

以股票价格查询为例，原始代码中requests.get()硬编码在函数内，导致无法 mock 测试、无法切换 mock/staging/prod 环境：

# ❌ 错误示范：执行层污染 @tool def get_stock_price(ticker: str) -> float: api_url = f"https://api.example.com/stocks/{ticker}" response = requests.get(api_url) # 网络请求混入执行层！ if response.status_code == 200: return response.json()["price"] raise ValueError("API call failed")

正确做法是将 HTTP 客户端抽象为依赖项，执行层只处理数据转换：

# ✅ 正确示范：执行层纯净 from typing import Protocol class StockAPIClient(Protocol): def fetch_price(self, ticker: str) -> dict: ... class StockPriceExecutor: def __init__(self, client: StockAPIClient): self.client = client def execute(self, ticker: str) -> float: data = self.client.fetch_price(ticker) if "price" not in data: raise ValueError(f"Invalid API response: missing 'price' field, got {list(data.keys())}") return float(data["price"]) # 接口层绑定具体实现 @tool(args_schema=StockPriceInput) def get_stock_price(ticker: str) -> str: # 生产环境注入真实客户端 client = RealStockAPIClient(api_key=os.getenv("STOCK_API_KEY")) executor = StockPriceExecutor(client) price = executor.execute(ticker) return f"股票 {ticker} 当前价格: ¥{price:.2f}"

关键设计说明：

• StockPriceExecutor是纯函数式类，无状态、无 IO，100% 可单元测试；
• RealStockAPIClient实现StockAPIClient协议，便于替换为MockStockAPIClient；
• 接口层get_stock_price是胶水代码，只负责依赖注入和结果包装。

2023 年某高校毕设答辩真实案例：A同学的“智能会议纪要Agent”因未分离执行层，当导师要求“演示离线模式”时，他无法快速禁用所有网络调用，只能重写全部技能函数，最终超时答辩失败。

2.3 适配层：解决 LLM 与现实世界之间的“语义鸿沟”

LLM 说“查一下昨天上海的天气”，但你的天气 API 只接受{"city": "shanghai", "date": "2024-10-18"}。这个转换工作不能丢给 LLM 做（它可能把“昨天”算错），也不能写死在接口层（缺乏灵活性）。适配层就是干这个的：接收 LLM 的自然语言意图，输出 API 可消费的结构化参数。

我们设计一个通用适配器基类：

from datetime import datetime, timedelta import re class WeatherQueryAdapter: def __init__(self): self.city_mapping = { "上海": "shanghai", "北京": "beijing", "广州": "guangzhou" } def adapt(self, query: str) -> dict: # 提取城市（正则匹配中文城市名） city_match = re.search(r"(上海|北京|广州|深圳)", query) city = city_match.group(1) if city_match else "shanghai" # 解析日期（支持“今天”“明天”“昨天”“10月18日”） today = datetime.now().date() date = today if "今天" in query: date = today elif "明天" in query: date = today + timedelta(days=1) elif "昨天" in query: date = today - timedelta(days=1) else: # 尝试匹配 YYYY-MM-DD 或 MM-DD 格式 date_match = re.search(r"(\d{4}-\d{2}-\d{2})|(\d{1,2}-\d{1,2})", query) if date_match: if date_match.group(1): date = datetime.strptime(date_match.group(1), "%Y-%m-%d").date() else: # 补全年份 month_day = date_match.group(2) date = datetime.strptime(f"{today.year}-{month_day}", "%Y-%m-%d").date() return { "city": self.city_mapping.get(city, "shanghai"), "date": date.strftime("%Y-%m-%d") } # 在接口层使用 @tool(args_schema=WeatherQueryInput) def get_weather(city: str, date: str) -> str: adapter = WeatherQueryAdapter() params = adapter.adapt(f"查 {city} {date} 天气") # 实际应从LLM tool_call.args获取 # ... 调用执行层

关键设计说明：

• 适配逻辑与执行逻辑解耦，可独立测试（如adapter.adapt("查北京明天天气")应返回{"city":"beijing","date":"2024-10-19"}）；
• 城市映射、日期规则等业务知识集中管理，避免散落在各处；
• 当需求变更（如新增“杭州”支持），只需改city_mapping，无需动执行层。

3. 技能类型实战：手写技能、API技能、混合技能的三套落地方案

不是所有技能都该走同一套流程。根据稳定性、实时性、数据源可信度，我将技能分为三类，并为每类提供经过答辩验证的最小可行实现（MVP）模板。某实验室设备调度Agent 就严格按此分类设计，最终通过导师“随机断网+篡改输入+并发压测”三重考验。

3.1 手写技能：数学运算与单位转换——用确定性对抗LLM的不确定性

手写技能的核心价值是兜底：当 LLM 在复杂计算上出错（如大数乘法溢出、浮点精度丢失），或需要强一致性（如财务结算）时，手写技能是唯一可靠选择。它必须满足：零依赖、零IO、毫秒级响应、100% 可预测。

我们以“温度单位转换”为例，实现摄氏（C）、华氏（F）、开尔文（K）三者互转：

from enum import Enum from pydantic import BaseModel, Field class TemperatureUnit(str, Enum): CELSIUS = "celsius" FAHRENHEIT = "fahrenheit" KELVIN = "kelvin" class TempConvertInput(BaseModel): value: float = Field(..., ge=-273.15, le=1e6, description="温度值，摄氏度范围[-273.15, ∞)") from_unit: TemperatureUnit = Field(..., description="源单位") to_unit: TemperatureUnit = Field(..., description="目标单位") @tool(args_schema=TempConvertInput) def convert_temperature(value: float, from_unit: str, to_unit: str) -> str: """ 温度单位转换工具 支持 C<->F, C<->K, F<->K 任意组合 """ # 统一转为摄氏度作为中间态 if from_unit == "celsius": celsius = value elif from_unit == "fahrenheit": celsius = (value - 32) * 5/9 elif from_unit == "kelvin": celsius = value - 273.15 else: raise ValueError(f"不支持的源单位: {from_unit}") # 从摄氏度转目标单位 if to_unit == "celsius": result = celsius elif to_unit == "fahrenheit": result = celsius * 9/5 + 32 elif to_unit == "kelvin": result = celsius + 273.15 else: raise ValueError(f"不支持的目标单位: {to_unit}") return f"{value} {from_unit[:1].upper()} = {result:.4f} {to_unit[:1].upper()}"

注意：ge=-273.15是热力学绝对零度，Pydantic 自动校验输入合法性，比if value < -273.15: raise...更简洁可靠。

参数契约表（答辩必交文档）：

3.2 API技能：对接外部服务——用契约驱动开发，而非“能跑就行”

API技能最大的坑是“本地能跑，线上崩”。根源在于未定义API契约：请求方法、路径、Header、Query参数、Body Schema、成功/失败响应体结构。我要求所有 API 技能必须附带一份api_contract.yaml，内容如下（以模拟天气API为例）：

# api_contract.yaml weather_api: method: GET base_url: "https://api.example.com/v1" path: "/weather" headers: Authorization: "Bearer ${API_KEY}" query_params: city: string # 必填，城市英文代码 date: string # 必填，YYYY-MM-DD格式 success_response: status_code: 200 body_schema: temperature: number condition: string humidity: integer error_responses: - status_code: 400 reason: "参数缺失或格式错误" - status_code: 404 reason: "城市不存在" - status_code: 500 reason: "服务端内部错误"

基于此契约，自动生成客户端和测试用例：

# 自动生成的客户端（简化版） import requests import os class WeatherAPIClient: def __init__(self, api_key: str): self.api_key = api_key self.base_url = "https://api.example.com/v1" def fetch_weather(self, city: str, date: str) -> dict: url = f"{self.base_url}/weather" headers = {"Authorization": f"Bearer {self.api_key}"} params = {"city": city, "date": date} try: response = requests.get(url, headers=headers, params=params, timeout=5) response.raise_for_status() # 触发4xx/5xx异常 data = response.json() # 契约校验：检查必要字段 if not all(k in data for k in ["temperature", "condition", "humidity"]): raise ValueError(f"API响应缺少必要字段，实际字段: {list(data.keys())}") return data except requests.exceptions.Timeout: raise TimeoutError("天气API请求超时，请检查网络") except requests.exceptions.RequestException as e: raise ConnectionError(f"天气API连接失败: {e}") # 对应的单元测试（pytest） def test_weather_api_client(): client = WeatherAPIClient("test_key") # Mock requests.get with patch("requests.get") as mock_get: mock_get.return_value.status_code = 200 mock_get.return_value.json.return_value = { "temperature": 22.5, "condition": "sunny", "humidity": 65 } result = client.fetch_weather("shanghai", "2024-10-18") assert result["temperature"] == 22.5 assert "condition" in result

关键设计说明：

• api_contract.yaml是技能设计文档，也是测试依据，答辩时导师可据此抽查你是否理解 API 行为；
• 客户端强制timeout=5，避免 LLM 等待挂起；
• raise_for_status()+ 显式异常类型，确保错误可被捕获、可分类、可记录。

3.3 混合技能：先查知识库，再执行计算——用编排逻辑替代LLM幻觉

当任务需要多步协同（如“计算某型号CPU的功耗并对比竞品”），单一技能无法胜任。混合技能 =多个原子技能 + 明确编排逻辑。它不是让 LLM 自己决定步骤（易出错），而是由开发者预设流程。

以“设备功耗分析”为例，流程为：

1. 从内部知识库查 CPU 型号的 TDP（热设计功耗）参数；
2. 从知识库查竞品型号的 TDP；
3. 调用计算器技能计算差值与百分比。

from langchain_core.tools import Tool from typing import Dict, Any # 原子技能（已定义） # knowledge_tool: 查询知识库，返回JSON字符串 # calc_tool: 计算器技能，支持 add/sub/multiply class PowerAnalysisSkill: def __init__(self, knowledge_tool: Tool, calc_tool: Tool): self.knowledge_tool = knowledge_tool self.calc_tool = calc_tool def execute(self, target_cpu: str, competitor_cpu: str) -> str: # Step 1: 查目标CPU TDP target_res = self.knowledge_tool.invoke(f"TDP of {target_cpu}") target_tdp = self._parse_tdp_from_json(target_res) # Step 2: 查竞品CPU TDP comp_res = self.knowledge_tool.invoke(f"TDP of {competitor_cpu}") comp_tdp = self._parse_tdp_from_json(comp_res) # Step 3: 计算差值与百分比 diff = self.calc_tool.invoke(f"subtract {target_tdp} {comp_tdp}") percent = self.calc_tool.invoke(f"divide {diff} {comp_tdp} multiply 100") return ( f"{target_cpu} TDP: {target_tdp}W\n" f"{competitor_cpu} TDP: {comp_tdp}W\n" f"差值: {diff}W ({percent:.1f}% 相对竞品)" ) def _parse_tdp_from_json(self, json_str: str) -> float: try: data = json.loads(json_str) return float(data.get("tdp_watts", 0)) except (json.JSONDecodeError, ValueError, TypeError): raise ValueError(f"知识库返回无效TDP数据: {json_str}") # 接口层注册为单个技能 @tool def analyze_cpu_power(target_cpu: str, competitor_cpu: str) -> str: """分析两款CPU的功耗对比，需提供准确型号名""" # 注入依赖 knowledge_tool = KnowledgeBaseTool() # 假设已定义 calc_tool = CalculatorTool() # 假设已定义 analyzer = PowerAnalysisSkill(knowledge_tool, calc_tool) return analyzer.execute(target_cpu, competitor_cpu)

关键设计说明：

• 编排逻辑在PowerAnalysisSkill.execute()中显式编写，LLM 只需调用一次analyze_cpu_power；
• _parse_tdp_from_json封装容错解析，避免 JSON 格式变化导致整个技能崩溃；
• 所有原子技能（knowledge_tool/calc_tool）保持独立可测试，混合技能只负责 glue logic。

4. 技能集成与调试：LLM调用失败的五大避坑指南

技能写完了，但 LLM 就是不调用？调用了却传错参？返回结果 LLM 看不懂？别怀疑人生，这是 95% 的初学者必经阶段。以下是我在三个项目中总结的最常翻车的五类问题，按“现象→原因→解决”给出可立即执行的排查路径。

4.1 现象：LLM 完全不调用任何工具，只返回文字回答

原因：LLM 判断“无需工具即可回答”，通常因 prompt 中未明确声明工具能力，或工具描述（description）过于简略、缺乏触发关键词。
解决：

• 检查@tool的description字段，必须包含动词+对象+约束，例如"""计算两个数字的乘积，仅当用户明确要求'乘'、'times'、'*'时调用。"""，而非"""Multiply two numbers."""；
• 在 LLM system prompt 中追加一句：You MUST use one of the provided tools if the user's request involves calculation, data lookup, or external information retrieval.；
• 用固定测试用例验证：query = "393 * 12.25"，若仍不调用，检查llm.bind_tools([tools])是否漏掉tools列表。

4.2 现象：tool_call 中参数为字符串而非数字，如{"x": "393", "y": "12.25"}

原因：LLM 输出 JSON 时未遵循args_schema的类型定义，或args_schema未启用（如忘记传args_schema=AddInput）。
解决：

• 立即打印ai_msg.tool_calls原始内容，确认是否为字符串；
• 检查@tool装饰器是否传入args_schema，且该 schema 的字段类型为float/int而非str；
• 强制开启 LangChain 的严格模式：llm.bind_tools(tools, strict=True)（LangChain >= 0.1.16）。

4.3 现象：工具执行成功，但 LLM 在 final_response 中忽略 tool_msg.content

原因：messages.append(tool_msg)后，未将tool_msg的content字段正确注入 message history；或tool_msg类型错误（应为ToolMessage，而非AIMessage）。
解决：

• 确保tool_msg是langchain_core.messages.ToolMessage实例，创建方式为：

  from langchain_core.messages import ToolMessage tool_msg = ToolMessage( content=str(result), # 必须是字符串！ name=tool_call["name"], tool_call_id=tool_call["id"] )

• 检查messages列表顺序：必须是[HumanMessage, AIMessage(with tool_calls), ToolMessage, ...]，不能颠倒；
• 在llm_with_tools.invoke(messages)前，打印messages[-1].content确认 tool 结果已写入。

4.4 现象：本地运行正常，Docker 容器中报ModuleNotFoundError

原因：requirements.txt未锁定 LangChain 生态版本，或镜像中缺少langchain-community等子包。
解决：

• 生成精确依赖：pip freeze | grep "langchain" > requirements.txt，确保包含langchain-core==0.1.16,langchain-openai==0.1.5,langchain-community==0.0.36；
• Dockerfile 中显式安装：

  RUN pip install --no-cache-dir \ langchain-core==0.1.16 \ langchain-openai==0.1.5 \ langchain-community==0.0.36 \ openai==1.35.0

• 在容器内执行python -c "import langchain_community.tools; print('OK')"验证。

4.5 现象：API技能调用返回 401，但 API_KEY 环境变量已设置

原因：.env文件未被加载，或环境变量在 Docker run 时未传递，或os.getenv("API_KEY")在模块顶层执行（此时.env尚未加载）。
解决：

• 将load_dotenv()移至技能函数内部，或主程序入口处：

  from dotenv import load_dotenv load_dotenv() # 必须在任何 os.getenv() 调用之前

• Docker run 时显式传入：docker run -e API_KEY=xxx my-agent；
• 在技能函数开头添加诊断日志：print(f"[DEBUG] API_KEY length: {len(os.getenv('API_KEY', ''))}")，确认是否为空。

5. 方案验收与答辩：用三张表让导师当场认可你的工程能力

答辩不是讲 PPT，是现场验证。我要求所有学生在答辩前，必须准备好三张表：技能清单表、调用链路表、错误对照表。这三张表加起来不到一页 A4，但能让导师瞬间判断你是否真做过、是否理解系统、是否具备工程素养。某高校去年毕设答辩中，B同学凭这三张表，在 8 分钟内完成演示并获得“优秀”评价。

5.1 技能清单表：证明你不是调包，而是设计

这张表列明每个技能的设计意图、输入输出契约、测试用例、状态。答辩时导师可随机挑一行，让你现场演示。

提示：状态栏用 ✅/⚠️/❌，❌ 表示未完成，⚠️ 表示有已知限制（如“仅支持美股”），绝不要写“已完成”。

5.2 调用链路表：暴露你的系统思维深度

LLM 不是黑匣子，它的决策路径必须可追溯。这张表展示一次典型请求的完整消息流，从 HumanMessage 到 final_response，每一步的 role、content、tool_calls 都要列清。导师可据此判断你是否理解 LangChain 的消息机制。

以query = "393 * 12.25"为例：

关键点：

• 步骤2的args必须是float（非字符串），证明args_schema生效；
• 步骤3的content必须是字符串，且包含可读结果，证明ToolMessage构造正确；
• 步骤4的content必须引用步骤3的结果，证明消息链路完整。

5.3 错误对照表：展现你的鲁棒性设计能力

导师最爱问：“如果用户输错参数，系统怎么反应？” 这张表直接给出答案，按错误类型、触发方式、系统响应、日志示例四列组织。

注意：所有错误响应必须是用户可理解的中文，而非 Python traceback。在try/except中统一处理，返回ToolMessage(content="错误：...", name="error_handler", tool_call_id=...)。

从那以后我每次带学生做 AI Agent 项目，都强制他们在git commit前，必须用这三张表自查：技能清单表是否覆盖所有功能点？调用链路表能否复现一次完整交互？错误对照表是否穷尽 Top 5 失败场景？没有这三张表，代码写得再漂亮，我也不会让它进入答辩环节。希望帮到你。

本文还有配套的精品资源，点击获取