企业官网建设流程全解析

简介：Google Agent白皮书可运行源码包，面向关注AI代理技术从原型走向工程化落地的开发者与学习者。资源配套Google最新发布的《Agents Companion》白皮书，内容涵盖技术架构进阶、生态协同标准构建、企业级落地路径与未来趋势，填补了从概念普及到生产部署之间的知识缺口。压缩包仅9KB，共3个文件，包含inscode集成开发环境配置、HTML说明页面以及gitignore版本管理文件，结构精简，可直接解压后查看运行。目前已有136人学习下载，适合有一定AI基础、希望快速上手Agent工程化示例的中高级开发者。通过这套可运行材料，能够直观理解代理系统的组成与调用方式，结合白皮书中的案例分析，掌握在实际项目中设计、测试和优化Agent应用的具体方法，为后续自主开发提供可参考的起点。整体而言，该源码包是连接白皮书理论与工程实践的轻量入口，尤其适合在个人学习环境中做快速验证和原型探索。

1. Agent白皮书发布后，为什么拿到源码还是跑不出效果

Agent白皮书发布后，我第一件事就是把手里的配套源码拉下来，在本地跑通，还给身边几个团队做过同样的拆解。结果非常典型：照着源码改个模型名就能启动，但真让它连续处理几轮工具调用时，要么反复调同一个工具直到额度耗尽，要么给出一个看着完整、实际完全没用的答案。问题几乎不在模型，而在编排层。

这份白皮书真正值钱的地方，不是“Agent是什么”那部分概念，而是它把规划、工具调用、记忆管理、停止条件这四件事放进了一套可执行的结构里，并且真的附了可运行源码。对做工程的人来说，这是一份不用重复发明轮子的基线——它直接回答了一个比“Agent是什么”更实际的问题：怎么让Agent稳定地跑完一轮真实任务。

这篇文章我按复现这套思路的路径来写：先拆架构，再讲怎么把源码在本地跑通，然后给一组我自己常用的参数初值，最后列出五个最容易翻车的场景。新手可以跟着步骤走，熟手可以重点看参数边界和踩坑部分。

2. 白皮书的Agent不是“调大模型”，而是一套编排结构

2.1 规划器、工具注册表、记忆管理器、执行器：四个模块的分工

把白皮书里的架构图简化到能落地的程度，核心就是四个模块。规划器负责决定“下一步做什么”，它通常就是一次LLM调用，输入当前任务和观察结果，输出下一个动作；工具注册表是一张“名字到函数”的映射表，决定Agent能碰什么、不能碰什么；记忆管理器负责决定把哪些历史信息放进下一次LLM调用；执行器是真正调用工具函数的那一层，负责超时、重试、异常捕获和结果格式化。

很多团队跑不起来，就是把这四个模块混在了一个大循环里。规划器同时干执行器的活，Agent自己把工具调用结果塞进上下文，没有独立的超时控制。一旦某个工具函数抛了异常，整个循环就静默失败，模型拿着残缺信息继续编答案。

这四个模块落到最简实现时都不复杂。规划器就是一个带system提示的LLM请求，工具注册表就是一个dict，记忆管理器就是一个裁剪函数，执行器就是一层try/except。难的是把它们之间的接口约定清楚——下游拿到的结果必须是“模型看得懂的文本”，而不是Python对象。白皮书源码里最值得抄的，就是这套接口约定。

2.2 ReAct循环只是地基，白皮书把停止条件当成关键

ReAct的“思考→行动→观察”循环很多人已经写过一万遍了，白皮书并没有推翻它，但重点强调了循环必须有两个刹车：迭代上限和输出协议约束。没有迭代上限的Agent会在一条错误路径上越走越深，尤其是LLM发现自己做错了又不承认时，它会反复尝试同一个工具。

下面这个骨架是我在本地复现白皮书思路时用的最小版本，完整可运行，只依赖requests。它没有用各家厂商的原生tool_calls协议，而是用文本协议，原因后面讲。

# minimal_agent.py import os import requests # 工具注册表：名字 -> 函数。白皮书里最常见的形态就是这么一张dict def get_time(arg=""): from datetime import datetime return datetime.now().strftime("%Y-%m-%d %H:%M:%S") def add_two(arg): a, b = [int(x.strip()) for x in arg.split(",")] return str(a + b) TOOLS = { "get_time": get_time, "add_two": add_two, } def call_llm(messages): body = { "model": os.environ["LLM_MODEL"], "messages": messages, "temperature": 0, } resp = requests.post( os.environ["LLM_BASE_URL"] + "/chat/completions", headers={"Authorization": "Bearer " + os.environ["LLM_API_KEY"]}, json=body, timeout=60, ) resp.raise_for_status() return resp.json()["choices"][0]["message"]["content"] def run_agent(task, max_steps=5): messages = [ {"role": "system", "content": ( "你是一个Agent核心。每轮只输出两种内容之一：\n" "TOOL 工具名(参数)\n" "ANSWER 最终答案" )}, {"role": "user", "content": task}, ] for step in range(max_steps): # 第一道刹车：迭代上限 text = call_llm(messages) print(f"[step {step}] 模型输出: {text}") stripped = text.strip() if stripped.startswith("TOOL "): # 模型决定调用工具 spec = stripped[5:].strip() name, arg = spec.split("(", 1) arg = arg.rstrip(")") tool = TOOLS.get(name.strip()) result = tool(arg.strip()) if tool else f"工具 {name} 不存在" messages.append({"role": "assistant", "content": stripped}) messages.append({"role": "user", "content": f"工具返回: {result}"}) elif stripped.startswith("ANSWER "): # 模型给出最终答案 return stripped[7:].strip() else: # 输出不符合协议，记入历史但不执行 messages.append({"role": "assistant", "content": stripped}) return "迭代上限已到，未得到最终答案" if __name__ == "__main__": print(run_agent("今天的日期是什么？", max_steps=3))

这段代码里最关键的是“输出协议”。我刻意没有用各家模型服务商的原生tool_calls格式，而是让模型输出TOOL 工具名(参数)这样的纯文本。原因很现实：白皮书配套源码如果直接接厂商tool_calls，换一个模型服务就要改一遍请求体，而文本协议在任何一个提供chat/completions接口的模型上都能跑。

参数上，temperature设成0，因为Agent链路里随机性会让同一个任务两次跑出不同路径，排障时非常痛苦，先把随机性关掉。max_steps=3到5是白皮书反复强调的第一道刹车，没有上限的Agent会一直顺着错误路径挖下去。

2.3 可运行源码里通常会有的四类文件

白皮书配套的源码压缩包解开后，常见的文件结构不是一个大而全的框架，而是按模块拆开的几个文件。我按最常见的组织方式列一张表：

核心循环脚本是唯一需要读懂全部逻辑的文件，其余三个文件都可以按需替换。工具注册文件是后续迭代最频繁的，每接一个新业务系统，基本都是在这里加函数。记忆管理模块经常被忽略，但白皮书里其实花了不小篇幅讲上下文窗口，这部分我放到第4章展开。

这套结构最值得借鉴的地方是它把“一次LLM调用”和“一个Agent任务”严格区分开。一个Agent任务可能包含多次LLM调用，每次调用只负责产生一个动作；而动作的执行结果又会成为下一次调用的输入。想清楚这一层，就不会写出那种“用一次super prompt塞满所有工具用法”的巨型提示词了。

3. 把可运行源码在本地跑通：环境准备与最小启动

3.1 环境要求与依赖：一个venv就够

白皮书源码的依赖比我预想的少很多。按我复现的这套，只需要Python 3.10及以上版本，外加一个requests库，不需要LangChain这类重型框架。之所以只依赖requests，是因为它把LLM服务看作一个普通HTTP接口，任何支持chat/completions格式的模型服务都能接，降低了入门门槛。

# 建立虚拟环境，避免污染系统Python python3 -m venv .agent_venv source .agent_venv/bin/activate # 安装唯一的外部依赖 pip install requests # 配置运行所需环境变量 export LLM_BASE_URL="http://127.0.0.1:8080/v1" # 你的模型服务地址 export LLM_API_KEY="your-key-here" # 替换成你的密钥 export LLM_MODEL="your-model-name" # 替换成你的模型名

这里三个环境变量是整套代码能跑起来的前提。LLM_BASE_URL要指到带/v1的路径，因为chat/completions接口通常挂在版本号后面；LLM_API_KEY即使本地服务不校验也要随便填一个字符串，否则有的服务端会直接拒绝空密钥；LLM_MODEL必须和服务端部署的模型名完全一致，不一致时错误信息往往不直观，只会返回model_not_found。

如果你用的是本地部署的模型服务，比如通过推理框架启动的，通常默认监听127.0.0.1:8080，保持默认就行。如果接的是云端API，把Base URL换成服务商文档里的地址，密钥换成你自己的，模型名换成服务商提供的模型标识。

3.2 最小闭环：从“TOOL”到“ANSWER”的完整链路

环境变量配好之后，直接运行上一章那个脚本就能看到完整的Agent闭环：

python minimal_agent.py

正常输出大致是这样：

[step 0] 模型输出: TOOL get_time() [step 1] 模型输出: ANSWER 2025-04-19 14:30:00 2025-04-19 14:30:00

第一轮模型决定调用工具，输出TOOL get_time()，代码解析出工具名后执行，把结果拼成工具返回: ...放回消息列表。第二轮模型拿到工具结果，输出ANSWER ...，整个任务在两步内结束。

这个最小闭环里，每一步都对应白皮书里“规划→执行→观察”的一个环节。TOOL那行是规划加执行，工具返回那行就是观察结果。如果模型在第二步仍然输出TOOL而不是ANSWER，说明system提示里的约束不够强，可以在提示里加一句“除非工具返回异常，否则你必须给出ANSWER”。

3.3 换模型接口的三种切法

跑通默认模型之后，下一步通常是换成自己业务里实际用的模型。常见做法有三种，按改动量从小到大排。

第一种是改环境变量，不碰代码。如果你的内部模型服务兼容chat/completions格式，只需要把LLM_BASE_URL和LLM_MODEL换成新服务的地址和模型名。我一般会在切换后先跑一次那个get_time用例，确认协议真的通了再继续。

第二种是加一层HTTP中转。团队里多个项目共用一套模型服务时，常有一个统一的网关，网关路径里会带/v1。这时LLM_BASE_URL指向网关地址就行，但要确认网关对Authorization头的透传规则，有些网关会改写密钥格式，导致401。

第三种是模型服务不支持chat/completions格式。这是最折腾的一种，需要自己写一个适配层，把模型的非标准输出转成标准消息格式。我接过的某跨平台系统用的是内部自研模型，输出格式完全自定义，最后是在代码里加了一个normalize_response函数做格式转换，核心循环不动。

# 以本地模型服务为例的最终启动方式 export LLM_BASE_URL="http://127.0.0.1:8080/v1" export LLM_API_KEY="local-test-key" export LLM_MODEL="local-model" python minimal_agent.py

切换接口之后，建议先做一次“工具不存在”测试：让Agent调用一个没有注册的工具，比如TOOL not_exist()。模型应当输出类似工具 not_exist 不存在的返回，如果模型开始编造这个工具的执行结果，说明你对工具返回信息的系统提示约束不够，需要加强。

提示：本地部署模型时，模型对文本协议的遵循程度差异很大。7B量级的小模型经常把TOOL和ANSWER混在一起输出，这时可以在system提示里加“只输出一行，不要解释”，必要时把max_steps调大一次，因为小模型可能需要更多轮才能学会协议。

4. 核心参数怎么调：迭代上限、工具超时与上下文裁剪

4.1 五个必调参数与推荐初值

源码跑通之后，真正的工程调优才刚开始。我整理了一张常用参数表，这些值是我在多个内部项目中反复试出来的初值，按你的场景在此基础上浮动：

max_steps是第一个要调的参数，它直接决定整个Agent的token消耗上限。如果你的任务需要调3个工具才能完成，max_steps=5就有一定余量；如果只有调1个工具就能答完的简单任务，max_steps=3更合适，因为步数太多时模型会“没事找事”，把已经完成的工具再调一遍。

temperature我从来不调大。Agent链路里每一步都是下一步的输入，一个随机的中间动作会把整个链路带偏，而且这种错误极难复现。有同事为了“让答案更自然”把temperature调到0.7，结果同一个查询两次跑出不同结论，这种不确定性在生产环境是不可接受的。

4.2 给工具调用加上超时与重试：三个函数串起来的防护链

白皮书源码里工具调用往往就是直接执行函数，没有超时和重试。这在本地Demo没问题，但真实业务里一个工具函数可能请求外部系统、读数据库、等网络响应，任何一环卡住都会让整个Agent挂起。我一般会套一层防护链：超时控制、重试、结果归一化。

# tool_guard.py import functools import time from concurrent.futures import ThreadPoolExecutor, TimeoutError class ToolFailure(Exception): pass def with_timeout(seconds): """给工具函数加超时限制""" def deco(fn): @functools.wraps(fn) def wrapper(*args, **kwargs): with ThreadPoolExecutor(max_workers=1) as pool: future = pool.submit(fn, *args, **kwargs) try: return future.result(timeout=seconds) except TimeoutError: raise ToolFailure(f"{fn.__name__} 执行超过 {seconds}s") return wrapper return deco def safe_tool_call(tool, arg, retry=2, timeout=10): """带重试的工具调用入口，所有异常都被捕获并转成文本""" last_err = None for i in range(retry + 1): try: guarded = with_timeout(timeout)(tool) return guarded(arg) except Exception as e: last_err = e time.sleep(0.5) # 重试前稍微等一会，避免打爆下游系统 return f"TOOL_ERROR: {last_err}"

这段代码在原有工具函数外面包了两层。with_timeout把任何工具函数变成带超时的版本，超时统一抛ToolFailure，而不是让线程还在后台跑；safe_tool_call负责重试，retry=2表示最多执行3次，每次失败后等0.5秒。

注意最后返回的是一个字符串TOOL_ERROR: ...，而不是让异常继续往外抛。原因很简单：Agent的输入必须是文本。异常一旦抛到核心循环里，整个任务就可能中断；而转成文本之后，模型看到TOOL_ERROR，至少还有机会调整策略。这个归一化处理是白皮书源码里没有的，我强烈建议加上。

4.3 上下文裁剪：Agent忘事不是记忆问题，是窗口问题

Agent跑长链路任务时最大的问题是上下文窗口被撑爆，模型开始“忘事”。这不是模型没有记忆能力，而是历史消息太多，超出有效注意力范围。白皮书里提到的记忆管理，落地时核心就是裁剪策略。

# memory.py def estimate_tokens(text: str) -> int: """不接分词器的粗估：中文字符约1.7个算1个token，英文约4个字符算1个""" zh = sum(1 for ch in text if '\u4e00' <= ch <= '\u9fff') en = len(text) - zh return int(zh / 1.7 + en / 4) def trim_messages(messages, keep=8, max_tokens=1200): """保留系统提示和最近keep轮，轮数太多时从最早的用户消息开始删除""" sys_msg = messages[0] recent = messages[-keep:] while estimate_tokens(str(recent)) > max_tokens and len(recent) > 2: recent = recent[2:] return [sys_msg] + recent

这个裁剪策略的核心思路是“两头保中间丢”：系统提示包含Agent的行为约束，必须完整保留；最近几轮包含当前正在推进的任务状态，也必须保留；空中最早的历史对话轮被丢弃。

keep=8这个值是我常用的事务型任务初值。如果任务是类似“先查A再查B再汇总”的三段式流程，8轮足够覆盖全部过程；如果任务需要跨很多步骤，比如数据分析类的多轮推理，可以调到12到15，但要同时增大max_tokens限制，否则还是会被截断。

注意：不要用“把所有历史浓缩成一段摘要”这种方案。很多团队试过，效果很差，因为摘要丢失的是工具返回的具体数字和字段名，而这恰恰是后续步骤最需要的信息。保留原始消息比生成摘要可靠得多。

5. Agent实战避坑：五个常见翻车现象与排查

5.1 现象：Agent在同一工具上反复打转直到耗尽额度

模型连续五轮输出TOOL get_time()，每次拿到结果后又调一次，就是不肯往下走。原因有两层：一是迭代上限没设，二是系统提示里没有告诉模型“拿到结果后必须继续下一步”。只靠模型自觉是不行的。

解决方法是硬约束加提示双管齐下。硬约束就是max_steps必须小于等于5，让错误路径最多消耗五次额度；同时修改system提示，明确写“如果工具返回了正常结果，下一轮必须输出ANSWER”。如果模型还是打转，就在提示里加一句物极必反式的话：“你已经拿到足够信息，重复调用同一个工具是错误的。”

5.2 现象：工具返回了合法结果，模型却视而不见

我见过一个案例，某开发者自己写了一个查询函数，正常返回{"status": "success", "data": [...]}这样的JSON字符串，模型却完全不引用里面的数据，自顾自编了个答案。排查后发现，原因是模型训练语料里JSON格式出现的频率低，当JSON字符串夹在对话历史里时，模型对它的注意力权重偏低。

解决方法是把工具返回格式对齐到自然语言。我常用的做法是让执行器在返回前加一层格式化，把{"status": "success", "data": [1, 2, 3]}转成“查询成功，结果是数字1、2、3”。这一步看起来多此一举，实际对中小尺寸模型的效果提升非常明显。

5.3 现象：本地启动报错，提示Python语法版本不兼容

源码里用了str | None这种新式类型注解，或者list[str]，在Python 3.8环境下直接SyntaxError。很多人第一反应是装依赖，其实问题是解释器版本太老。

解决方法是把虚拟环境的Python版本升到3.10及以上。如果系统自带版本太低，装个3.10版本的Python再重建虚拟环境，比改代码里的类型注解靠谱得多。白皮书源码是按新版本语法写的，不建议为了迁就旧环境改动语法结构。

5.4 现象：加了记忆窗口后反而答非所问

按第4章的裁剪思路加了上下文管理，结果Agent开始答非所问，反馈说“系统提示丢了”。排查后确认是裁剪逻辑的起始位置错了：messages[0]被当成了系统提示，但实际消息列表里第一条可能是用户消息，或者有多个system消息叠加。

解决方法是把系统提示单独存成一个变量，不进消息列表，每次组请求时手动拼接。裁剪操作只作用于中间的用户消息和助手消息，系统提示永远原样带上。这个改动很小，但能避免一类极其隐蔽的“越裁越傻”问题。

5.5 现象：工具函数报错被吞掉，Agent一本正经地胡说

工具函数内部抛了异常，执行器没有catch，导致整个Agent循环崩溃；或者catch了但只返回ERROR两个字，模型不知道发生了什么，开始编理由圆场。

解决方法是按第4章的归一化思路，把异常转成包含错误类型的文本。比如TOOL_ERROR: 数据库连接超时(TimeoutError)，模型看到“数据库连接超时”这几个字，至少能判断出是外部依赖问题，而不是功能逻辑问题。我一般还会在返回文本里加一句“此时请告知用户系统暂时不可用，不要继续重试”，防止模型傻乎乎地再调一次。

6. 进阶：把白皮书的编排思想收成你自己的轻量Agent

6.1 三态工具调用：正常、降级、人工接管

把白皮书思路落进自己业务时，我最后沉淀下来的是一套三态工具调用器：正常执行返回结果，失败后尝试降级方案，降级也不行就把控制权交回人类。这套逻辑比单纯的try/except多覆盖了一个真实场景——工具挂了但任务不能直接失败。

# three_state_tool.py def call_with_states(tool_name, arg, ctx): # 第一态：正常执行，失败后自动重试 result = safe_tool_call(ctx["tools"][tool_name], arg, retry=2, timeout=10) if not result.startswith("TOOL_ERROR"): return {"status": "ok", "data": result} # 第二态：降级，尝试同义工具或简化实现 for alias in ctx.get("fallbacks", {}).get(tool_name, []): alias_result = safe_tool_call(ctx["tools"][alias], arg, retry=1, timeout=5) if not alias_result.startswith("TOOL_ERROR"): return {"status": "degraded", "data": alias_result, "from": alias} # 第三态：人工接管，把错误原样带出 return {"status": "need_human", "data": result, "message": f"{tool_name} 连续失败"}

ctx里挂的是工具表和一个可选的fallbacks映射表，比如“查天气”工具挂了就降级为“查天气-备用接口”。人工接管是生产环境必不可少的出口，宁可让真人处理，也不要让Agent硬着头皮编答案。

6.2 用一个注定失败的工具验证边界行为

验证这套三态逻辑，我一般注册一个必定抛异常的工具，然后观察Agent的最终输出。如果状态是need_human，说明降级和接管逻辑正确；如果状态是degraded，说明fallback配置生效了。

我最早跑这套源码时，总想往里塞更多规则，后来发现编排稳定比功能扩展更值得投入。工具越多、链路越长，越需要把刹车和出口设计在前面。希望这篇文章能帮你少踩几个我踩过的坑，把白皮书里那套编排思想真正变成你自己业务里的稳定基石，希望帮到你。

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