企业官网建设流程全解析

引言

很多初学者一上来就扎进LangChain、CrewAI、Dify这些框架的学习，结果越学越散，最后只记住了一堆名词，却没有真正理解Agent技术为什么会这样发展。Agent开发不是单纯的“调API”，它要求你同时具备工程能力、模型认知和概率性思维。Python异步编程是Agent开发的地基——Agent从开始运行就多数时间都在等大模型返回、等API响应、等工具跑完。如果按照同步思路编写，代码中每个调用都在等待，走一步卡三步。大模型本身不是100%可靠的，输出是文本而非结构化数据，Agent工程师的核心工作就是在这两个不确定之间搭建一座稳定的桥梁。

本文把Agent开发的前置基础拆解为四个模块，每个模块都列出了必须掌握的知识点、学习目标、代码示例和实践建议，适合零基础学习者按图索骥。

一、Python编程能力

Python是Agent开发的主流语言，占开发者份额72%。你不需要成为Python专家，但以下知识点必须熟练到“不用查资料就能写出来”的程度。

1.1 Python基础语法与面向对象

必须掌握的核心知识点：

变量与数据类型：Python是动态类型语言，但Agent开发中你需要对类型有清晰的认知。字符串、整数、浮点数、布尔值、None、列表、字典、元组、集合——这些是构建一切逻辑的基石。特别注意字典（dict），LLM返回的JSON数据解析后就是字典嵌套，你需要熟练地从中提取字段、处理缺失键（使用.get()方法）。

条件判断与循环：if/elif/else、for/while循环、break/continue。Agent中常见的是遍历工具列表、根据模型返回的action类型做分支判断。

函数定义与调用：位置参数、关键字参数、默认参数、*args和**kwargs。Agent开发中，你定义的每个工具都是一个函数，模型会根据函数签名来决定如何调用。

类与对象：理解__init__、self、实例属性、类属性、继承、多态。你会频繁定义工具类、记忆类、Agent类。例如，一个工具基类BaseTool可能定义name、description、run()方法，然后具体的SearchTool、CalculatorTool继承它。

模块与包：理解import机制，会创建自己的模块，会组织项目目录结构。Agent项目通常按tools/、memory/、agents/、config/来组织。

类型注解（Type Hints）：这是Agent开发中极其重要但常被忽视的技能。LLM需要根据函数的类型注解来生成正确的调用参数。没有类型注解，模型可能传入错误的类型。例如：

python

from typing import Optional, List from pydantic import BaseModel, Field class SearchInput(BaseModel): """搜索工具的参数定义""" query: str = Field(description="搜索关键词，不超过100字") max_results: Optional[int] = Field(default=5, description="返回结果数量上限") def search_web(input: SearchInput) -> str: """根据关键词搜索网络内容""" ...

学习建议：如果你完全没有编程基础，先花2-3周系统学习Python基础语法和面向对象编程。推荐资源包括廖雪峰Python教程（中文，体系完整）、Real Python（英文，示例丰富）、Codecademy的Python课程（交互式练习）。不要只看不写，每个知识点都要动手敲一遍。

1.2 异步编程（Asyncio）

这是Agent开发中最容易被忽视但极其关键的知识点。为什么异步如此重要？数据科学代码通常是CPU密集型的——加载数据框、转换、训练，一切按顺序运行。但AI工程代码是I/O密集型的——Agent调用模型、再调用工具、再调用另一个模型，大部分时间花在等待网络响应上，而不是在计算。同步写法下，每次等待都会阻塞下一步，即使这个等待并不要求阻塞。

必须掌握的知识点：

async def/await语法：async def定义协程函数，await暂停当前协程，让出控制权给事件循环去执行其他任务。

asyncio.run()启动协程：这是程序的入口，创建事件循环并运行顶层协程。

asyncio.gather()并发执行多个协程：这是Agent中最重要的并发工具。当你需要同时调用多个LLM或工具时，gather能让它们并发执行，总耗时等于最慢的那一个。

aiohttp或httpx发起异步HTTP请求：httpx是现代推荐，同时支持同步和异步接口。

一个对比示例，展示性能差距：

python

import asyncio import httpx # 同步写法：每个调用都堵住，一个接一个 def slow_agent_calls(queries): results = [] for query in queries: result = call_llm(query) # 堵死在这了 results.append(result) return results # 10 个查询 × 2秒 = 20秒 # 异步写法：全部同时打出去 async def fast_agent_calls(queries): async with httpx.AsyncClient() as client: tasks = [call_llm_async(client, q) for q in queries] results = await asyncio.gather(*tasks) return results # 10 个查询 × 2秒 ≈ 2秒搞定

异步方式和同步执行的任务是一样的，但是快了10倍。

事件循环（Event Loop）的基本概念：事件循环是一个无限循环，不断检查是否有任务需要执行。理解它的调度机制，有助于你写出不会阻塞的异步代码。

常见坑：在异步函数中调用同步阻塞代码会卡死整个事件循环。Agent开发中如果需要调用同步库（如某些数据库驱动），要用asyncio.to_thread()包装：

python

import asyncio from some_sync_db import sync_query async def query_db(): # 把同步阻塞调用放到单独的线程中，不阻塞事件循环 result = await asyncio.to_thread(sync_query, "SELECT * FROM users") return result

另一个常见坑是：在异步函数中直接调用requests.get()会导致整个事件循环卡死，因为requests是同步阻塞的。必须使用httpx的异步客户端或aiohttp。

超时与重试：

python

import asyncio import httpx from tenacity import retry, stop_after_attempt, wait_exponential @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, max=10)) async def call_llm_with_retry(client: httpx.AsyncClient, prompt: str) -> str: """带超时和重试的LLM调用""" try: resp = await client.post( "https://api.example.com/v1/chat/completions", json={"messages": [{"role": "user", "content": prompt}]}, timeout=30.0 ) resp.raise_for_status() return resp.json()["choices"][0]["message"]["content"] except httpx.TimeoutException: raise # tenacity 会重试 except httpx.HTTPStatusError as e: if e.response.status_code == 429: # 限流 await asyncio.sleep(5) raise raise

实践任务：搭一个FastAPI服务，同时跑10个LLM调用，一个都不卡；写一套重试逻辑，API挂了的时候不乱崩；做错误处理，某个工具挂了，别让整个Agent跟着陪葬。

异步任务的状态机：在Agent开发中，一个复杂的任务可能需要跟踪多个异步子任务的状态。Python标准库的asyncio.Task提供了任务状态机，可以监控任务的pending、done、cancelled等状态。

1.3 HTTP请求与API调用

Agent需要与各种外部服务通信：LLM API、搜索API、数据库API、企业内部系统。

必须掌握的知识点：

使用httpx（推荐）和requests（同步）：httpx同时支持同步和异步接口，是现代Agent开发的首选。requests虽然简单，但在异步环境中会阻塞事件循环。

设置请求头：LLM API通常需要Authorization: Bearer sk-xxx认证头，Content-Type: application/json声明数据格式。

python

import httpx async def call_deepseek(prompt: str) -> str: async with httpx.AsyncClient() as client: resp = await client.post( "https://api.deepseek.com/v1/chat/completions", headers={ "Authorization": f"Bearer {api_key}", "Content-Type": "application/json" }, json={ "model": "deepseek-chat", "messages": [{"role": "user", "content": prompt}], "temperature": 0.1, "max_tokens": 2048 }, timeout=60.0 ) return resp.json()

处理超时和重试：LLM调用耗时可能从几秒到几分钟不等。必须设置合理的超时时间，并配合tenacity等库实现指数退避重试。

理解HTTP状态码：

• 200：成功

• 400：请求格式错误（通常是你发的JSON字段不对）

• 401：认证失败（API Key 错误或过期）

• 429：请求过多（限流，需要等待后重试）

• 500：服务器内部错误（上游服务问题，通常可以重试）

处理流式响应（Streaming）：LLM API常以SSE（Server-Sent Events）流式返回，你需要在客户端逐块接收并拼接：

python

async def stream_llm(prompt: str): async with httpx.AsyncClient() as client: async with client.stream( "POST", "https://api.example.com/v1/chat/completions", json={"messages": [...], "stream": True} ) as response: async for chunk in response.aiter_lines(): if chunk.startswith("data: "): data = chunk[6:] if data == "[DONE]": break yield json.loads(data)["choices"][0]["delta"].get("content", "")

1.4 JSON序列化与反序列化

JSON是LLM与外部工具之间交换数据的标准格式。

必须掌握的知识点：

json.dumps()/json.loads()：基础序列化和反序列化。

处理嵌套JSON：LLM返回的JSON可能有多层嵌套，你需要递归地提取字段。

处理中文：默认json.dumps()会把中文转成Unicode转义，使用ensure_ascii=False保持中文可读。

从LLM返回的文本中提取JSON：模型经常在JSON前后添加解释文字，或者用Markdown代码块包裹：

python

import json import re def extract_json(text: str) -> dict: """从LLM输出中提取JSON，处理各种常见格式问题""" # 尝试直接解析 try: return json.loads(text) except json.JSONDecodeError: pass # 尝试去除Markdown代码块包裹 match = re.search(r'```(?:json)?\s*\n?(.*?)\n?```', text, re.DOTALL) if match: try: return json.loads(match.group(1)) except json.JSONDecodeError: pass # 尝试找到第一个完整的 {} 结构 match = re.search(r'\{.*\}', text, re.DOTALL) if match: try: return json.loads(match.group(0)) except json.JSONDecodeError: pass raise ValueError(f"无法从输出中提取JSON: {text[:200]}")

1.5 Pydantic：Agent开发中最关键的数据校验工具

Pydantic v2 是Agent开发的核心依赖。它不仅仅是一个数据校验库，更是LLM输出与下游代码之间的“合同层”。Pydantic v2 严格模式（strict mode）不做类型强制转换——如果模型传入了字符串 “500” 而你的函数期望整数 500，Pydantic会直接拒绝，而不是悄悄转换。Agent-Airlock等工具正是利用这一点，在模型调用工具之前拦截类型错误、剥离“幽灵参数”（模型编造的不存在的参数），并返回带有修复提示的结构化错误，让模型可以自我修正后重试。

基础模型定义：

python

from pydantic import BaseModel, Field, field_validator from typing import List, Optional class ToolCall(BaseModel): """模型请求调用工具的结构""" tool_name: str = Field(description="要调用的工具名称") arguments: dict = Field(description="工具的参数") @field_validator("tool_name") @classmethod def tool_name_must_be_valid(cls, v: str) -> str: allowed = {"search", "calculator", "weather"} if v not in allowed: raise ValueError(f"未知工具: {v}，可用工具: {allowed}") return v class AgentOutput(BaseModel): """Agent最终输出的结构""" answer: str = Field(description="对用户问题的回答") sources: Optional[List[str]] = Field(default=None, description="引用来源") confidence: float = Field(ge=0.0, le=1.0, description="置信度")

extra='forbid'防止静默类型转换：在Pydantic v2中，默认的Union类型可能产生静默的类型强制转换问题。例如，一个包含任意键的字典可能被错误地转换为特定模型，导致数据被静默丢弃。使用extra='forbid'可以防止这种问题。

自愈重试机制：当Pydantic校验失败时，Agent-Airlock会返回一个带有fix_hints的结构化错误，模型可以据此修正参数后重试。这意味着你不需要在提示词中反复强调“请输出正确的JSON格式”，校验层会自动兜底。

实践任务：写一个Python脚本，用httpx异步调用一个公开API（如天气API），解析JSON，处理超时和异常，打印日志。然后为你的工具函数定义Pydantic输入模型，确保模型传入的参数被严格校验。

1.6 日志记录与可观测性

Agent的行为需要可追踪、可评估、可控制。日志是第一步。

python

import logging import time logging.basicConfig( level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s' ) logger = logging.getLogger("agent") async def traced_llm_call(prompt: str) -> str: """带追踪的LLM调用""" start = time.time() try: result = await call_llm(prompt) elapsed = time.time() - start logger.info(f"LLM调用成功 | 耗时={elapsed:.2f}s | 输入长度={len(prompt)} | 输出长度={len(result)}") return result except Exception as e: elapsed = time.time() - start logger.error(f"LLM调用失败 | 耗时={elapsed:.2f}s | 错误={type(e).__name__}: {e}") raise

二、大模型基础概念

你不必会训练模型，但必须理解模型的行为特征，否则无法设计稳定的Agent系统。

2.1 Token机制

什么是Token：模型处理文本的最小单位。英文中一个Token约等于0.75个单词（即1000个Token约等于750个单词），中文中一个Token约等于1-2个汉字。Token不是字符也不是单词，而是模型分词器（Tokenizer）根据训练数据学到的子词单元。

Token计数：输入Token + 输出Token = 总消耗。API计费按Token数量计算，输入和输出可能单价不同。使用tiktoken库（OpenAI提供）可以精确计算Token数：

python

import tiktoken enc = tiktoken.encoding_for_model("gpt-4o") tokens = enc.encode("你好，世界！Hello, world!") print(f"Token数量: {len(tokens)}") # 输出: 13

Token限制的实际影响：每个模型有最大上下文长度（如128K、200K）。超出会报错或截断。但更重要的是：即使没有超出硬限制，当上下文变得很长时，模型对中间部分内容的注意力会下降——这就是所谓的“迷失在中间”（Lost in the Middle）现象。因此，Agent设计时不仅要考虑“能不能塞进去”，还要考虑“塞进去后模型还能不能有效推理”。

Token成本估算：

2.2 上下文窗口限制

上下文窗口：模型一次能“看到”的最大Token数。GPT-4o为128K Token（约9万6千字），Claude 3.5为200K Token（约15万字）。Agent执行任务时间长后，很快就会填满这个窗口，必须从动手开始就想好对策。

上下文压缩策略的详细对比：

方案一：滑动窗口截断。最简单的方式，保留最近N条消息。优点是实现简单，缺点是可能丢失关键的历史信息。

方案二：摘要压缩（Compaction）。当历史接近窗口限制时，暂停Agent，把对话记录交给LLM生成摘要，用摘要替换原始历史。这是当前多个Agent框架的默认做法，但存在四个已知问题：摘要的损失不可预测（哪些信息被保留取决于摘要模型当时的判断）、因果结构被破坏（工具调用→输出→决策的链式关系被压扁成散文）、压缩本身是一次完整的LLM调用（增加延迟和成本，而且发生在Agent正在执行任务的中途）、压缩可能引入新的幻觉。

方案三：结构化上下文逐出（Context Window Lifecycle, CWL）。这是2026年提出的更先进的方案。Agent将自身的轨迹标注为带有依赖关系的“剧集”（episodes），当Token预算超出时，一个确定性的、不调用LLM的策略按优先级顺序逐出内容。它保留用户轮次和Agent正在推理的探索性上下文，而积极地丢弃那些效果已经持久化到环境中的动作剧集。与摘要压缩相比，CWL避免了不可预测的损失、因果结构破坏、阻塞性的模型成本和压缩引入的幻觉。实验显示，一个Agent会话在8000万Token中完成了89个连续任务，任务准确率相比孤立会话没有可测量的下降。

Agent中的实际挑战：多轮工具调用会快速消耗上下文。一个搜索工具返回的长文档可能就占用了数千Token。你必须设计记忆管理机制：哪些信息需要保留在上下文中，哪些应该存入向量数据库按需检索。

2.3 模型路由：根据任务复杂度选择模型

任务有难有易，根据难易程度使用不同价格（也对应聪明程度）的大模型，能帮你省一大笔钱。

python

def route_to_model(task_type: str) -> str: """根据任务类型路由到不同模型""" routing = { # 简单任务 → 便宜快的模型 "classify": "deepseek-chat", # 分类 "summarize": "deepseek-chat", # 摘要 "extract": "deepseek-chat", # 信息提取 # 中等任务 → 均衡模型 "draft": "claude-sonnet-4-6", # 草拟 "analyze": "claude-sonnet-4-6", # 分析 # 复杂任务 → 最强模型 "plan": "claude-opus-4-8", # 规划 "debug": "claude-opus-4-8", # 调试 } return routing.get(task_type, "deepseek-chat")

模型路由的核心原则是：让便宜模型做便宜的事，把贵模型的额度留给真正需要深度推理的任务。

2.4 生成控制参数

Temperature：控制随机性。0最确定（模型每次都选概率最高的Token），1最随机（按概率分布采样）。Agent中通常用0-0.3保证稳定。但注意：Temperature=0并不意味着100%确定，因为浮点数运算和GPU非确定性仍可能导致微小差异。

Top-p：核采样。与Temperature二选一调节。当Top-p=0.9时，模型只从累积概率达到90%的Token集合中采样。

Max Tokens：限制单次输出长度。Agent中需要为工具调用预留足够的输出空间（通常2048-4096 Token）。

Frequency Penalty / Presence Penalty：减少重复。Frequency Penalty根据Token出现频率惩罚，Presence Penalty根据Token是否出现过惩罚。

Stop Sequences：指定停止生成的标记。Agent中常用"\nObservation:"作为停止标记，让模型在调用工具后停下来等待结果。

2.5 模型幻觉的成因与工程兜底

幻觉成因：模型在缺乏知识时“编造”看似合理的内容。这不是模型的“错误”，而是概率生成机制的自然结果——模型本质上是在预测“下一个最可能出现的Token”，而不是在“查找真相”。

工程兜底策略的详细方案：

RAG（检索增强生成）：先检索真实文档，再让模型基于文档回答。这是最有效的幻觉治理手段。检索质量决定了回答质量。

强制引用：要求模型在输出中附带来源。例如：“回答时必须引用知识库中的原文，格式为 [来源: 文档名, 第X页]”。

LLM-as-Judge评估：用第二个模型判断回答是否可靠。默认置信度阈值为0.70，低于阈值的结果被标记为“Ambiguous”（歧义），进入人工审核或降级处理。但需要注意，LLM-as-Judge本身也有失败模式——例如当Agent执行了无害的中间步骤但拒绝了操作指令时，Judge可能错误地判定为“合规”。

置信度阈值与熔断器：如果端点流量出现500%的激增（可能是bot攻击）或连续HTTP 402/429错误，立即触发熔断器，路由到低成本降级方案，并通知人工介入。

降级回复：当模型不确定时，回复“我无法确认，请咨询人工”。这比编造一个看似合理的错误答案要好得多。

实践任务：用同一个问题，分别设置Temperature=0和Temperature=1，观察输出差异。用tiktoken计算一段文本的Token数。设计一个简单的模型路由函数，根据任务类型选择不同的模型。

三、提示词工程基础

提示词是Agent的“指令集”。Prompt工程已经不再只是“问得好”的技巧，而是构建可靠AI应用的核心能力。输入的质量直接决定了输出的上限。

3.1 零样本与少样本提示

零样本（Zero-shot）提示：只给指令，不给示例。大模型因预训练知识能直接完成任务。优点是简洁，缺点是当任务小众、领域性强或输出格式有特殊要求时容易产生偏差。

少样本（Few-shot）提示：在Prompt中提供2-5个示例，让模型学会“照猫画虎”。少样本提示是很多复杂Prompt的基础，特别是在需要严格格式或风格迁移时。

python

# 少样本提示示例 prompt = """ 请将用户评论分类为：正面、负面、中性。 示例1： 评论："这个产品太好用了，物流也很快！" 分类：正面 示例2： 评论："质量一般，用了两天就坏了。" 分类：负面 示例3： 评论："收到了，还没开始用。" 分类：中性 现在请分类： 评论："外观漂亮，但功能有点少。" 分类： """

3.2 思维链（Chain-of-Thought, CoT）

对于需要推理、计算或多步逻辑的任务，CoT提示能显著提升准确率。核心思想是在Prompt中引导模型展示中间推理过程。

零样本CoT：只需在Prompt末尾加上一句“Let‘s think step by step”或“请一步一步思考”，就能激发模型生成推理链。

少样本CoT：提供包含推理步骤的示例，让模型模仿。

CoT在Agent中的变体就是ReAct——模型交替进行“推理”和“行动”，推理过程本身就是CoT的一种形式。

3.3 ReAct范式

ReAct = Reasoning + Acting。模型交替进行“思考”（Thought）和“行动”（Action），观察行动结果（Observation），然后继续思考，直到得出最终答案。

完整的ReAct循环：

text

Thought: 用户想知道北京今天的天气。我需要调用天气查询工具。 Action: get_weather Action Input: {"city": "北京", "date": "2026-10-10"} Observation: 北京今天晴，气温18-25°C，西北风3级。 Thought: 我已经获得了天气信息，可以回答用户了。 Final Answer: 北京今天天气晴朗，气温18到25摄氏度，西北风3级，适合外出。

ReAct的失败模式——需要深入理解：

失败模式一：无限Agent循环（Infinite Agentic Loops, IALs）。Agent可能在没有有效终止条件的情况下反复触发LLM调用、工具调用或工作流转换。这不是普通的编程循环，而是由Agent逻辑、框架语义、运行时观察和终止机制之间的交互产生的结构性失败。例如：Agent反复调用同一个工具而不改变参数，因为模型没有意识到上一次调用已经完成了；或者多个Agent之间的交接形成了循环——Agent A交给B，B又交回给A。

一项针对6549个LLM Agent仓库的研究中，IAL-Scan检测出了74个潜在问题，人工审查确认了47个项目中的68个无限循环失败，精确率达到91.9%。

失败模式二：上下文爆炸。每一轮Thought-Action-Observation都会增加上下文长度。如果工具返回的内容很长（如搜索结果、文件内容），上下文会迅速膨胀。当窗口填满时，模型开始“遗忘”早期内容，导致推理质量急剧下降。

失败模式三：工具选择错误。模型可能选择了不合适的工具，或者为工具传入了错误的参数。更糟糕的是，模型可能反复尝试同一个失败的工具调用，因为它在上下文中看到了之前的失败尝试，而这反过来“引导”它继续尝试同样的方式。

失败模式四：注意力锁定（Attention Latch）。在仅解码器自回归Transformer模型中，存在一种系统性的失败模式——当推理链需要超过3跳合成时，ReAct基线的成功率会崩溃到0.1%。

3.4 JSON Mode结构化输出

为什么需要：Agent需要程序化解析模型输出，自然语言无法直接处理。结构化输出让模型以可预测的格式返回结果。

实现方式：

方式一：OpenAI的response_format参数：

python

response = client.chat.completions.create( model="gpt-4o", messages=[...], response_format={"type": "json_object"} # 强制JSON输出 )

方式二：提示词中明确要求：“只输出JSON，不要其他任何文字。JSON格式如下：{...}”。

方式三：使用Pydantic定义Schema并校验：将Pydantic模型转换为JSON Schema传给模型，然后用Pydantic校验返回结果。

常见问题与解决方案：模型可能在JSON前后添加解释文字。解决方法包括：使用正则表达式提取{}或[]之间的内容、使用json.loads()并捕获异常后重试、要求模型“只输出JSON”。

3.5 上下文压缩技巧

除了前面2.2节讨论的滑动窗口、摘要压缩和结构化逐出之外，还有以下实用技巧：

关键信息提取：只保留实体、意图、约束，丢弃修饰性内容。

向量检索替代全文：把历史存入向量数据库，按需检索相关片段，而不是把全部历史塞进上下文。

稀疏语义补丁记忆（SSPM）：一种更精细的压缩方法，平均减少48.7%的Token，同时保留100%的显式约束和决策。

实践任务：写一个提示词，让模型从一段用户评论中提取“情感倾向、主要问题、是否要求退款”，输出严格的JSON格式。然后为你的Agent设计一个ReAct循环，测试它在多少次迭代后会出现上下文爆炸问题。

四、认知校准：从“确定性编程”到“概率性工程”

这是零基础学习者最容易忽视但最重要的一点。传统软件追求100%正确，而Agent工程的核心是在不确定性中构建可接受的确定性。

4.1 两种思维模式的对比

4.2 构建可接受的确定性

评估体系（Evaluation）：

LLM-as-Judge是当前主流的自动评估方法。用第二个模型对第一个模型的输出打分。但需要注意，LLM-as-Judge本身也有偏差——它可能对某些格式的回答有偏好，或者被回答中的自信语气所影响。

一个完整的评估体系应该包含：结果质量（回答是否准确、完整）、轨迹质量（Agent的推理过程是否合理、工具调用是否恰当）、成本效率（每任务的Token消耗和延迟）。上线前必须通过Golden Dataset（基准数据集）的回归测试。

安全护栏（Guardrails）：

输入检测：过滤恶意输入、注入攻击、越狱尝试。

输出过滤：检测敏感信息泄露、有害内容、PII（个人身份信息）。

工具调用权限控制：白名单机制——只有经过授权的工具才能被调用。危险工具（如文件删除、数据库写入）需要多级确认。

PII处理与秘密遮蔽：在工具调用的输出中自动遮蔽个人身份信息和密钥。

降级策略：

熔断器模式：当某个API端点连续失败或流量异常时，自动切断该端点，路由到备用方案。

多供应商路由：按历史性能（速度、成本、准确率）对供应商排序，优先使用最优的，失败时自动切换。

规则引擎回退：模型失败时回退到基于规则的确定性逻辑。

缓存结果：对于重复查询，直接返回缓存结果，减少模型调用。

重试机制：

python

from tenacity import retry, stop_after_attempt, wait_exponential import httpx @retry( stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=2, max=30), retry=retry_if_exception_type((httpx.TimeoutException, httpx.HTTPStatusError)) ) async def robust_llm_call(prompt: str) -> str: """健壮的LLM调用，带指数退避重试""" async with httpx.AsyncClient() as client: resp = await client.post( "https://api.example.com/v1/chat/completions", json={"messages": [{"role": "user", "content": prompt}]}, timeout=60.0 ) if resp.status_code == 429: # 限流，等待后重试 raise httpx.HTTPStatusError("Rate limited", request=resp.request, response=resp) resp.raise_for_status() return resp.json()["choices"][0]["message"]["content"]

超时控制：每个LLM调用和工具调用都必须设置超时。Agent不能无限等待。超时后应该触发降级策略——使用缓存结果、返回部分答案、或提示用户稍后重试。

4.3 工程化思维

可观测性：记录每一步的输入、输出、耗时、Token消耗。这是Agent开发中最重要的工程实践之一。没有可观测性，你无法知道Agent为什么失败。

版本管理：提示词、模型版本、工具定义都要版本化。当一个提示词修改后，需要能够追踪“哪个版本的提示词产生了什么结果”。

灰度发布：新提示词先小流量测试（如5%流量），再全量。这就是“影子测试”——将实验模型的输出与生产模型对比，但不影响用户。

成本控制：监控Token消耗，设置预算上限。每个外部请求必须有严格的超时、重试上限和指定的更便宜的降级方案。禁止实现无上限的重试循环或无边界的API调用。

实践任务：为你写的问答脚本添加日志记录（输入、输出、耗时、Token数），并设置一个简单的重试机制。设计一个评估方案：用LLM-as-Judge对Agent的回答打分，统计准确率。

五、综合实践任务

完成以上四个模块的学习后，用以下任务检验自己：

1. 注册API：注册OpenAI或DeepSeek的API，获取Key。

2. 写一个问答脚本：用Python写一个脚本，接收用户输入，调用LLM API，返回回答。

3. 添加异步支持：用httpx异步调用，支持同时处理多个问题。

4. 添加异常处理：处理超时、网络错误、API限流。

5. 添加日志：记录每次调用的输入、输出、耗时、Token消耗。

6. 添加JSON输出：让模型对用户问题进行分类，输出JSON格式。

7. 添加Pydantic校验：为JSON输出定义Pydantic模型，校验模型返回的数据。

8. 添加重试机制：用tenacity实现指数退避重试。

9. 添加评估：用LLM-as-Judge对回答质量打分。

这个脚本虽然简单，但涵盖了前置基础的所有核心知识点。完成后，你就可以自信地进入框架学习阶段。

六、学习建议与资源

时间安排

推荐资源

Python：廖雪峰Python教程（中文，体系完整）、Real Python（英文，示例丰富）、Python官方文档（最权威）。

异步编程：asyncio官方文档（包含大量示例）、Real Python的Async IO教程。

Pydantic：Pydantic官方文档（v2版本）、Pydantic AI文档。

大模型基础：OpenAI Cookbook（实用示例）、DeepSeek API文档（中文）、Anthropic的Prompt Engineering指南。

提示词工程：吴恩达《ChatGPT Prompt Engineering for Developers》、Anthropic的Prompt Library。

Agent思维：ReAct论文（原始论文，必读）、LangChain官方博客、Agent-Airlock文档（了解工具调用安全实践）。

核心原则

动手优先：看十遍不如写一遍。每个知识点都要有对应的代码练习。

先跑通再优化：不要一开始就追求完美架构。先让代码能跑起来，再逐步添加异常处理、重试、评估。

拥抱不确定性：接受模型会犯错，学会用工程手段兜底。不要试图通过“更好的提示词”解决所有问题——有些问题需要代码层面的护栏。

持续迭代：提示词和评估体系需要反复打磨。记录每次修改的效果，建立自己的最佳实践库。

七、总结

Agent开发的前置基础可以概括为四句话：

1. Python要够用：异步编程是地基，HTTP/JSON是日常，Pydantic是工具调用的合同层，异常处理和日志是可观测性的起点。

2. 模型要理解：Token决定成本，上下文窗口决定能装多少，Temperature决定随机性，幻觉是概率生成的自然结果而非bug。

3. 提示词要精准：结构化、CoT、ReAct、JSON Mode、上下文压缩——每个技巧解决一类特定问题。

4. 思维要转变：从确定性编程转向概率性工程，用评估、护栏、降级、熔断构建稳定系统。

把这四个模块打牢，你后续学习LangChain、LangGraph、多智能体协作时，才不会“知其然不知其所以然”。基础越扎实，上层建筑越稳固。