Agent开发前置基础知识点全总结：零基础入门必读

引言很多初学者一上来就扎进LangChain、CrewAI、Dify这些框架的学习结果越学越散最后只记住了一堆名词却没有真正理解Agent技术为什么会这样发展。Agent开发不是单纯的“调API”它要求你同时具备工程能力、模型认知和概率性思维。Python异步编程是Agent开发的地基——Agent从开始运行就多数时间都在等大模型返回、等API响应、等工具跑完。如果按照同步思路编写代码中每个调用都在等待走一步卡三步。大模型本身不是100%可靠的输出是文本而非结构化数据Agent工程师的核心工作就是在这两个不确定之间搭建一座稳定的桥梁。本文把Agent开发的前置基础拆解为四个模块每个模块都列出了必须掌握的知识点、学习目标、代码示例和实践建议适合零基础学习者按图索骥。一、Python编程能力Python是Agent开发的主流语言占开发者份额72%。你不需要成为Python专家但以下知识点必须熟练到“不用查资料就能写出来”的程度。1.1 Python基础语法与面向对象必须掌握的核心知识点变量与数据类型Python是动态类型语言但Agent开发中你需要对类型有清晰的认知。字符串、整数、浮点数、布尔值、None、列表、字典、元组、集合——这些是构建一切逻辑的基石。特别注意字典dictLLM返回的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需要根据函数的类型注解来生成正确的调用参数。没有类型注解模型可能传入错误的类型。例如pythonfrom typing import Optional, List from pydantic import BaseModel, Field class SearchInput(BaseModel): 搜索工具的参数定义 query: str Field(description搜索关键词不超过100字) max_results: Optional[int] Field(default5, 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是现代推荐同时支持同步和异步接口。一个对比示例展示性能差距pythonimport 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()包装pythonimport 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。超时与重试pythonimport asyncio import httpx from tenacity import retry, stop_after_attempt, wait_exponential retry(stopstop_after_attempt(3), waitwait_exponential(multiplier1, max10)) 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}]}, timeout30.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声明数据格式。pythonimport 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: fBearer {api_key}, Content-Type: application/json }, json{ model: deepseek-chat, messages: [{role: user, content: prompt}], temperature: 0.1, max_tokens: 2048 }, timeout60.0 ) return resp.json()处理超时和重试LLM调用耗时可能从几秒到几分钟不等。必须设置合理的超时时间并配合tenacity等库实现指数退避重试。理解HTTP状态码200成功400请求格式错误通常是你发的JSON字段不对401认证失败API Key 错误或过期429请求过多限流需要等待后重试500服务器内部错误上游服务问题通常可以重试处理流式响应StreamingLLM API常以SSEServer-Sent Events流式返回你需要在客户端逐块接收并拼接pythonasync 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()基础序列化和反序列化。处理嵌套JSONLLM返回的JSON可能有多层嵌套你需要递归地提取字段。处理中文默认json.dumps()会把中文转成Unicode转义使用ensure_asciiFalse保持中文可读。从LLM返回的文本中提取JSON模型经常在JSON前后添加解释文字或者用Markdown代码块包裹pythonimport 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 PydanticAgent开发中最关键的数据校验工具Pydantic v2 是Agent开发的核心依赖。它不仅仅是一个数据校验库更是LLM输出与下游代码之间的“合同层”。Pydantic v2 严格模式strict mode不做类型强制转换——如果模型传入了字符串 “500” 而你的函数期望整数 500Pydantic会直接拒绝而不是悄悄转换。Agent-Airlock等工具正是利用这一点在模型调用工具之前拦截类型错误、剥离“幽灵参数”模型编造的不存在的参数并返回带有修复提示的结构化错误让模型可以自我修正后重试。基础模型定义pythonfrom 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(defaultNone, description引用来源) confidence: float Field(ge0.0, le1.0, description置信度)extraforbid防止静默类型转换在Pydantic v2中默认的Union类型可能产生静默的类型强制转换问题。例如一个包含任意键的字典可能被错误地转换为特定模型导致数据被静默丢弃。使用extraforbid可以防止这种问题。自愈重试机制当Pydantic校验失败时Agent-Airlock会返回一个带有fix_hints的结构化错误模型可以据此修正参数后重试。这意味着你不需要在提示词中反复强调“请输出正确的JSON格式”校验层会自动兜底。实践任务写一个Python脚本用httpx异步调用一个公开API如天气API解析JSON处理超时和异常打印日志。然后为你的工具函数定义Pydantic输入模型确保模型传入的参数被严格校验。1.6 日志记录与可观测性Agent的行为需要可追踪、可评估、可控制。日志是第一步。pythonimport logging import time logging.basicConfig( levellogging.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(fLLM调用成功 | 耗时{elapsed:.2f}s | 输入长度{len(prompt)} | 输出长度{len(result)}) return result except Exception as e: elapsed time.time() - start logger.error(fLLM调用失败 | 耗时{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数pythonimport tiktoken enc tiktoken.encoding_for_model(gpt-4o) tokens enc.encode(你好世界Hello, world!) print(fToken数量: {len(tokens)}) # 输出: 13Token限制的实际影响每个模型有最大上下文长度如128K、200K。超出会报错或截断。但更重要的是即使没有超出硬限制当上下文变得很长时模型对中间部分内容的注意力会下降——这就是所谓的“迷失在中间”Lost in the Middle现象。因此Agent设计时不仅要考虑“能不能塞进去”还要考虑“塞进去后模型还能不能有效推理”。Token成本估算模型输入价格每百万Token输出价格每百万TokenGPT-4o$2.50$10.00Claude Sonnet$3.00$15.00DeepSeek Chat¥2.00¥8.002.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 模型路由根据任务复杂度选择模型任务有难有易根据难易程度使用不同价格也对应聪明程度的大模型能帮你省一大笔钱。pythondef 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最确定模型每次都选概率最高的Token1最随机按概率分布采样。Agent中通常用0-0.3保证稳定。但注意Temperature0并不意味着100%确定因为浮点数运算和GPU非确定性仍可能导致微小差异。Top-p核采样。与Temperature二选一调节。当Top-p0.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错误立即触发熔断器路由到低成本降级方案并通知人工介入。降级回复当模型不确定时回复“我无法确认请咨询人工”。这比编造一个看似合理的错误答案要好得多。实践任务用同一个问题分别设置Temperature0和Temperature1观察输出差异。用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循环textThought: 用户想知道北京今天的天气。我需要调用天气查询工具。 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交给BB又交回给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参数pythonresponse client.chat.completions.create( modelgpt-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 两种思维模式的对比维度传统编程Agent工程输入确定类型、格式、范围明确自然语言模糊多义输出确定相同输入→相同输出概率性相同输入可能不同输出错误可复现同样的输入必然触发同样的错误偶发难以复现可能是模型内部的随机性测试单元测试断言相等评估体系LLM-as-Judge、人工评分、规则校验调试断点、日志追踪推理链、工具调用记录、Token消耗分析发布一次部署稳定运行持续监控、迭代提示词、A/B测试4.2 构建可接受的确定性评估体系EvaluationLLM-as-Judge是当前主流的自动评估方法。用第二个模型对第一个模型的输出打分。但需要注意LLM-as-Judge本身也有偏差——它可能对某些格式的回答有偏好或者被回答中的自信语气所影响。一个完整的评估体系应该包含结果质量回答是否准确、完整、轨迹质量Agent的推理过程是否合理、工具调用是否恰当、成本效率每任务的Token消耗和延迟。上线前必须通过Golden Dataset基准数据集的回归测试。安全护栏Guardrails输入检测过滤恶意输入、注入攻击、越狱尝试。输出过滤检测敏感信息泄露、有害内容、PII个人身份信息。工具调用权限控制白名单机制——只有经过授权的工具才能被调用。危险工具如文件删除、数据库写入需要多级确认。PII处理与秘密遮蔽在工具调用的输出中自动遮蔽个人身份信息和密钥。降级策略熔断器模式当某个API端点连续失败或流量异常时自动切断该端点路由到备用方案。多供应商路由按历史性能速度、成本、准确率对供应商排序优先使用最优的失败时自动切换。规则引擎回退模型失败时回退到基于规则的确定性逻辑。缓存结果对于重复查询直接返回缓存结果减少模型调用。重试机制pythonfrom tenacity import retry, stop_after_attempt, wait_exponential import httpx retry( stopstop_after_attempt(3), waitwait_exponential(multiplier1, min2, max30), retryretry_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}]}, timeout60.0 ) if resp.status_code 429: # 限流等待后重试 raise httpx.HTTPStatusError(Rate limited, requestresp.request, responseresp) 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的回答打分统计准确率。五、综合实践任务完成以上四个模块的学习后用以下任务检验自己注册API注册OpenAI或DeepSeek的API获取Key。写一个问答脚本用Python写一个脚本接收用户输入调用LLM API返回回答。添加异步支持用httpx异步调用支持同时处理多个问题。添加异常处理处理超时、网络错误、API限流。添加日志记录每次调用的输入、输出、耗时、Token消耗。添加JSON输出让模型对用户问题进行分类输出JSON格式。添加Pydantic校验为JSON输出定义Pydantic模型校验模型返回的数据。添加重试机制用tenacity实现指数退避重试。添加评估用LLM-as-Judge对回答质量打分。这个脚本虽然简单但涵盖了前置基础的所有核心知识点。完成后你就可以自信地进入框架学习阶段。六、学习建议与资源时间安排模块建议时间核心产出Python基础无编程经验2-3周能写面向对象的Python程序Python进阶异步、HTTP、JSON1周能写异步API调用带重试和日志Pydantic与数据校验3天能为工具函数定义Schema并校验大模型基础概念3-5天理解Token、上下文、温度参数提示词工程1周能写结构化的CoT和JSON Mode提示词认知校准与工程思维持续体会理解概率性工程与确定性编程的差异推荐资源Python廖雪峰Python教程中文体系完整、Real Python英文示例丰富、Python官方文档最权威。异步编程asyncio官方文档包含大量示例、Real Python的Async IO教程。PydanticPydantic官方文档v2版本、Pydantic AI文档。大模型基础OpenAI Cookbook实用示例、DeepSeek API文档中文、Anthropic的Prompt Engineering指南。提示词工程吴恩达《ChatGPT Prompt Engineering for Developers》、Anthropic的Prompt Library。Agent思维ReAct论文原始论文必读、LangChain官方博客、Agent-Airlock文档了解工具调用安全实践。核心原则动手优先看十遍不如写一遍。每个知识点都要有对应的代码练习。先跑通再优化不要一开始就追求完美架构。先让代码能跑起来再逐步添加异常处理、重试、评估。拥抱不确定性接受模型会犯错学会用工程手段兜底。不要试图通过“更好的提示词”解决所有问题——有些问题需要代码层面的护栏。持续迭代提示词和评估体系需要反复打磨。记录每次修改的效果建立自己的最佳实践库。七、总结Agent开发的前置基础可以概括为四句话Python要够用异步编程是地基HTTP/JSON是日常Pydantic是工具调用的合同层异常处理和日志是可观测性的起点。模型要理解Token决定成本上下文窗口决定能装多少Temperature决定随机性幻觉是概率生成的自然结果而非bug。提示词要精准结构化、CoT、ReAct、JSON Mode、上下文压缩——每个技巧解决一类特定问题。思维要转变从确定性编程转向概率性工程用评估、护栏、降级、熔断构建稳定系统。把这四个模块打牢你后续学习LangChain、LangGraph、多智能体协作时才不会“知其然不知其所以然”。基础越扎实上层建筑越稳固。