Google ADK实战：用Python代码构建可控、可测试的AI智能体系统

1. 项目概述从代码出发构建可控的智能体如果你正在寻找一个能让你用写代码的方式从零开始构建、测试和部署复杂AI智能体的框架那么Google开源的Agent Development KitADKPython版绝对值得你花时间深入研究。它不是另一个简单的聊天机器人包装器而是一个真正面向开发者的、遵循软件工程最佳实践的智能体开发框架。简单来说ADK让你能像搭积木一样用Python代码定义智能体的行为逻辑、工具调用和多智能体协作流程最终得到一个可测试、可版本控制、可灵活部署的智能体应用。我花了些时间上手ADK发现它的核心吸引力在于“控制力”和“灵活性”。市面上很多智能体框架要么是黑盒要么绑定特定模型或云服务。ADK则不同它虽然是Google出品且对Gemini模型有优化但其设计是模型无关和部署无关的。这意味着你可以用Gemini也可以接入其他LLM可以部署在Google Cloud的Vertex AI Agent Engine上享受全托管服务也可以轻松地容器化后扔到任何支持Cloud Run或Kubernetes的地方。对于需要将智能体深度集成到现有业务系统或者对成本、数据隐私有严格要求的团队来说这种自由度至关重要。2. 核心设计理念软件工程思维注入智能体开发ADK的设计哲学非常明确将成熟的软件工程实践引入AI智能体开发。这听起来有点抽象但体现在具体功能上就非常实用了。2.1 代码优先Code-First范式这是ADK的基石。你的智能体逻辑、工具定义、工作流编排全部通过Python类、函数和配置来声明。这带来了几个直接好处可测试性你可以像测试普通Python函数一样为智能体的某个工具调用或决策逻辑编写单元测试和集成测试。版本控制整个智能体的定义就是代码可以完美地用Git管理清晰地追踪每一次功能迭代和逻辑变更。可维护性复杂的多智能体系统可以通过模块化的代码来组织比如将不同职责的智能体定义在不同的模块文件中通过清晰的接口进行交互避免了配置堆砌带来的混乱。注意ADK也提供了无代码的“Agent Config”功能允许通过YAML/JSON配置来定义简单智能体。但对于需要复杂逻辑、自定义工具或深度集成的场景代码优先模式是更强大和推荐的选择。2.2 模块化与组合性ADK将智能体系统视为由多个可复用的组件构成。一个智能体Agent的核心要素包括模型连接器、指令instruction、工具集tools以及可选的子智能体sub_agents。这种设计让你可以先构建一个个完成特定任务的“原子智能体”比如一个专精于数据库查询的DBAgent一个擅长调用外部API的APIAgent。再通过一个“协调者智能体”Coordinator将这些原子智能体组合起来形成层次化的多智能体系统。协调者负责理解用户意图并将子任务分派给最合适的子智能体执行。这种架构非常契合微服务的设计思想使得系统易于扩展。当需要新增能力时你只需要开发一个新的专用智能体并将其注册到协调者中即可无需重写核心逻辑。2.3 丰富的工具生态系统智能体的能力边界由其工具决定。ADK在工具生态上下了很大功夫预置工具开箱即用提供了如google_search网络搜索等与Google生态紧密集成的工具。自定义函数工具你可以将任何一个Python函数只要正确定义了输入输出和文档字符串包装成智能体可调用的工具。这是连接智能体与内部业务系统的桥梁。OpenAPI工具直接导入一个服务的OpenAPI规范文件ADK能自动生成对应的工具集让智能体可以操作该服务的所有API。MCP工具支持Model Context Protocol工具这是一种新兴的、标准化的工具描述和调用协议有助于工具在不同框架间的复用。工具确认流这是一个非常实用的安全特性。对于某些高风险或关键操作如发送邮件、修改数据库你可以启用工具确认HITL人机交互循环。当智能体尝试调用该工具时执行会暂停等待用户的明确批准甚至可以允许用户修改工具调用的参数然后再继续执行。这为生产环境部署增加了一道安全阀。3. 环境搭建与核心组件实操纸上得来终觉浅我们直接动手从安装到创建一个具备真实功能的智能体。3.1 安装与项目初始化首先强烈建议使用虚拟环境来管理依赖。这里我使用venv# 创建并激活虚拟环境 python -m venv adk-env source adk-env/bin/activate # Linux/macOS # 或 adk-env\Scripts\activate # Windows # 安装稳定版ADK pip install google-adk如果你想体验最新的功能比如刚提到的“会话回退”或新的代码执行器可以安装开发版但请注意稳定性风险pip install githttps://github.com/google/adk-python.gitmain安装完成后创建一个新的项目目录并准备好你的Gemini API密钥。你可以从Google AI Studio获取。通常的做法是将其设置为环境变量export GOOGLE_API_KEY你的API密钥3.2 构建你的第一个智能体天气查询助手我们来构建一个结合了网络搜索和自定义逻辑的天气助手。它需要做两件事1根据用户提供的城市名搜索天气2根据温度给出穿衣建议。首先定义我们的自定义工具——穿衣建议器。# weather_agent.py from google.adk.agents import Agent from google.adk.tools import google_search from google.adk.tools import tool from typing import Annotated # 1. 定义一个自定义工具穿衣建议 tool def get_dressing_advice( temperature_c: Annotated[float, 当前的摄氏温度] ) - Annotated[str, 穿衣建议]: 根据温度提供穿衣建议。 if temperature_c 25: return 天气炎热建议穿短袖、短裤注意防晒。 elif 18 temperature_c 25: return 天气舒适可以穿长袖T恤、薄外套或衬衫。 elif 10 temperature_c 18: return 天气较凉建议穿毛衣、夹克或风衣。 else: return 天气寒冷务必穿上厚外套、羽绒服注意保暖。 # 2. 创建主智能体并赋予它两个工具网络搜索和我们的穿衣建议器 weather_agent Agent( nameweather_expert, modelgemini-2.0-flash-exp, # 使用一个快速且免费的模型进行测试 instruction 你是一个天气助手。用户会告诉你一个城市名称。 你的工作流程是 1. 使用谷歌搜索工具查询该城市当前的天气情况特别是温度请确保获取的是摄氏温度。 2. 从搜索结果中提取出温度数值。 3. 调用get_dressing_advice工具将提取到的温度传递给它获得穿衣建议。 4. 将天气搜索结果和穿衣建议整合成一段友好、完整的回复给用户。 如果搜索不到该城市的天气请如实告知用户。 , description一个可以查询天气并提供穿衣建议的智能助手。, tools[google_search, get_dressing_advice] # 注入工具 ) # 3. 运行智能体进行测试 if __name__ __main__: from google.adk.sessions import Session from google import genai # 初始化客户端会自动读取GOOGLE_API_KEY环境变量 client genai.Client() # 创建一个会话 session Session(agentweather_agent, clientclient) # 用户提问 user_query 上海现在的天气怎么样 print(f用户: {user_query}) # 智能体响应 response session.run(user_query) print(f助手: {response.messages[-1].content})代码解析与实操要点tool装饰器这是将普通Python函数转化为ADK工具的关键。装饰器会自动解析函数的参数注释Annotated和文档字符串docstring生成工具的描述供LLM理解。Annotated[float, ...]这种写法同时定义了参数类型和描述非常重要。工具注入创建Agent实例时通过tools参数传入一个工具列表。智能体在思考时就能“看到”并学会使用这些工具。指令设计instruction是智能体的“人格”和“工作手册”。这里我们给出了非常明确的步骤式指令这对于确保智能体行为符合预期至关重要。好的指令应该清晰、无歧义并明确指导智能体何时及如何使用工具。会话SessionSession对象封装了一次与智能体的交互上下文。它记录了所有的对话历史、工具调用记录和状态。使用session.run()来驱动智能体处理输入并产生输出。运行这个脚本你会看到智能体自动执行了搜索、提取温度、调用穿衣建议工具并最终生成回复的全过程。在后台ADK引擎处理了与LLM的多次往返交互思考、决定调用工具、解析工具结果、继续思考。3.3 利用开发UI进行调试和展示ADK内置了一个基于Web的开发界面对于调试和演示来说极其方便。你不需要写任何前端代码。在上面的weather_agent.py文件中我们添加几行代码来启动这个UI# 在文件末尾添加 from google.adk.servers import development_server if __name__ __main__: # 原来的测试代码可以注释掉... # 启动开发服务器 development_server.run(agentweather_agent)然后在终端运行python weather_agent.py。它会启动一个本地服务器并输出一个URL通常是http://localhost:8080。用浏览器打开它你就能看到一个交互式界面。你可以直接在网页上输入问题实时看到智能体的完整思考链Chain-of-Thought、工具调用的请求和响应这对于理解智能体为何做出某个决策、工具调用是否准确至关重要。4. 构建多智能体协作系统单个智能体能力有限真正的威力在于让多个智能体协同工作。我们来模拟一个简单的客户服务场景一个接待员智能体负责问候和分类问题一个技术专家智能体负责解决技术问题一个协调员智能体负责总调度。# multi_agent_system.py from google.adk.agents import LlmAgent from google.adk.tools import tool from typing import Annotated # 1. 定义工具模拟查询知识库和创建工单 tool def query_knowledge_base(question: Annotated[str, 用户的技术问题]) - Annotated[str, 知识库中的答案或‘未找到’]: # 这里模拟一个简单的知识库 kb { 如何重置密码: 请访问官网登录页面点击‘忘记密码’按邮件指引操作。, 服务宕机了: 我们正在紧急排查请关注系统状态页。, 如何升级套餐: 登录后在‘账户设置’-‘订阅’中可以选择升级。 } return kb.get(question, 未找到相关解决方案。) tool def create_support_ticket(issue: Annotated[str, 问题描述], user: Annotated[str, 用户名]) - Annotated[str, 工单ID]: # 模拟创建工单返回一个ID import uuid ticket_id str(uuid.uuid4())[:8] print(f[系统日志] 已为用户 {user} 创建工单 #{ticket_id}问题{issue}) return f工单已创建编号为{ticket_id}客服将尽快联系您。 # 2. 创建两个专业子智能体 greeter_agent LlmAgent( name接待员, modelgemini-2.0-flash-exp, instruction你是一个友好的接待员。你的任务是热情问候用户并初步判断他们的问题类型。如果是简单的问候或非技术问题如‘你好’、‘你们公司地址在哪’直接友好回复。如果是技术问题如‘密码’、‘宕机’、‘升级’等关键词就明确告诉用户你将把问题转交给技术专家。, description负责初始问候和问题分类。 ) tech_expert_agent LlmAgent( name技术专家, modelgemini-2.0-flash-exp, instruction你是一个技术专家。你拥有查询知识库和创建工单的工具。当接到用户的技术问题时首先尝试使用query_knowledge_base工具在知识库中寻找答案。如果找到直接给出答案。如果没找到或者用户明确要求人工服务则使用create_support_ticket工具为用户创建工单并告知工单号。, description负责解决技术问题和创建工单。, tools[query_knowledge_base, create_support_ticket] # 技术专家有自己的工具 ) # 3. 创建协调员智能体并管理子智能体 coordinator_agent LlmAgent( name客户服务协调员, modelgemini-2.0-flash-exp, # 协调员可以使用能力更强的模型 instruction 你是客户服务系统的总协调员。你管理着两个下属接待员和技术专家。 你的工作流程是 1. 收到用户消息后首先让‘接待员’来处理。它会进行问候和初步分类。 2. 如果‘接待员’判断这是技术问题并请求转交或者用户的问题直接涉及技术细节那么你将任务移交给‘技术专家’。 3. 你负责汇总最终结果并回复用户。你不需要亲自使用工具而是指挥子智能体去使用他们的工具。 始终以清晰、专业的口吻与用户交流。 , description协调接待员和技术专家处理客户服务请求。, sub_agents[greeter_agent, tech_expert_agent] # 关键指定子智能体 ) # 4. 运行多智能体系统 if __name__ __main__: from google.adk.sessions import Session from google import genai client genai.Client() session Session(agentcoordinator_agent, clientclient) test_conversations [ 你好, 我的密码忘记了怎么办, 我想找人工客服服务用不了。 ] for query in test_conversations: print(f\n用户: {query}) response session.run(query) print(f协调员: {response.messages[-1].content}) # 可以查看会话历史了解内部是如何流转的 # for msg in session.history: # print(f - {msg.role}: {msg.content[:100]}...)多智能体协作的核心机制 当用户消息发给协调员后ADK引擎会驱动协调员进行思考。协调员根据其指令决定将任务派发给哪个子智能体sub_agent。被选中的子智能体在自己的上下文中运行调用自己的工具然后将结果返回给协调员。协调员再根据这些结果进行下一步决策或最终回复。这一切对用户来说是透明的他们只与协调员对话。这种架构的优势在于解耦和可维护性。你可以独立修改技术专家的知识库工具或者为接待员增加新的问题分类规则而不会影响其他部分。协调员的指令就是整个系统的业务流程控制器。5. 高级特性与生产化部署5.1 会话回退Rewind与错误处理智能体在长对话中可能会“跑偏”或做出错误决策。ADK新引入的“回退”功能允许你将会话状态重置到某次工具调用之前然后尝试不同的路径。这在进行复杂任务调试或提供用户“重试”选项时非常有用。在代码中你可以通过session对象记录关键节点并在需要时回退# 假设在某次运行后发现智能体做出了错误选择 checkpoint session.create_checkpoint() # 创建一个检查点 try: response session.run(执行一个可能有风险的操作...) if some_error_condition: session.restore(checkpoint) # 回退到检查点 # 尝试替代方案或者直接给用户一个安全回复 alternative_response session.run(我们换一种安全的方式来做...) except Exception as e: session.restore(checkpoint) print(f操作失败已回退。错误{e})5.2 使用Vertex AI代码沙箱执行器对于需要生成并执行代码的智能体比如数据分析、图形生成直接执行用户或AI生成的代码是极其危险的。ADK集成了Vertex AI Code Execution Sandbox API。这是一个安全的、隔离的代码执行环境。你可以这样配置你的智能体使用它from google.adk.tools.code_execution import AgentEngineSandboxCodeExecutor from google.adk.tools import code_interpreter_tool # 1. 创建安全的代码执行器 sandbox_executor AgentEngineSandboxCodeExecutor( projectyour-google-cloud-project-id, locationus-central1 # 或其他支持的区域 ) # 2. 创建代码解释器工具并绑定执行器 code_tool code_interpreter_tool(executorsandbox_executor) # 3. 将工具赋予智能体 coding_agent Agent( namedata_analyst, modelgemini-2.0-flash-exp, instruction你是一个数据分析助手可以编写和执行Python代码来分析用户提供的数据或解决问题。, tools[code_tool] )这样当智能体生成代码并调用code_interpreter_tool时代码会被发送到Google Cloud的沙箱环境中运行结果返回给智能体。这有效隔离了潜在的有害代码保护了主机的安全。5.3 评估你的智能体在将智能体投入生产前系统的评估至关重要。ADK提供了命令行工具adk eval允许你使用评估集来量化智能体的表现。你需要准备一个评估集文件例如my_agent.evalset.json它是一个JSON文件包含了多轮对话的测试用例、预期的工具调用或回复标准。[ { input: 北京的天气如何, expected_actions: [ { tool_name: google_search, args_contain: [北京, 天气] } ] }, { input: 帮我画一个正弦函数图, expected_actions: [ { tool_name: code_interpreter, args_contain: [matplotlib, plot, sin] } ] } ]然后运行评估adk eval path/to/your/agent/directory path/to/your/agent.evalset.json评估工具会运行所有测试用例并生成报告告诉你智能体在哪些用例上通过了预期的工具调用或回复匹配。这是CI/CD流程中自动化测试智能体的关键一步。5.4 部署选项ADK智能体本质上是一个Python应用因此部署方式非常灵活本地运行直接作为脚本或Web服务运行适用于开发和测试。容器化部署ADK应用可以轻松打包成Docker镜像。Google提供了示例的Dockerfile。然后你可以将镜像部署到Google Cloud Run无服务器容器平台按请求付费自动扩缩容是最简单的生产部署方式之一。Google Kubernetes Engine适合需要精细控制、服务网格集成的大型复杂应用。任何Kubernetes集群包括本地或其它云厂商的K8s服务。Vertex AI Agent Engine这是Google Cloud原生的全托管智能体服务平台。它提供了更高级的功能如内置的会话管理、可观测性、与Google生态的深度集成如Grounding with Google Search、以及可能更优的模型调用成本。部署到Agent Engine通常需要额外的配置和适配但能获得“开箱即用”的企业级能力。选择哪种部署方式取决于你的团队技术栈、运维能力和对云服务的依赖程度。对于初创项目或独立开发者从Cloud Run开始是一个低门槛、高性价比的选择。6. 常见问题与避坑指南在实际使用ADK的过程中我遇到并总结了一些典型问题和解决方案。6.1 工具调用失败或不符合预期问题智能体不调用工具或调用工具时参数错误。排查检查工具定义确保tool装饰器的函数有清晰的参数名、类型提示和描述。LLM严重依赖这些信息来理解如何调用。使用Annotated类型来提供描述是推荐做法。检查指令智能体的instruction是否明确指示了在什么情况下使用哪个工具指令需要足够具体。例如“如果用户问天气就使用搜索工具”比“你可以使用工具”要好得多。使用开发UI在开发UI中运行对话观察完整的“思考链”。你会看到LLM决定调用工具时的推理过程以及它生成的工具调用参数。这能最直观地定位问题出在指令理解、工具描述还是参数生成上。模型能力过于复杂或模糊的工具描述可能会超出轻量级模型如gemini-flash的理解能力。尝试简化工具描述或换用能力更强的模型如gemini-pro进行测试。6.2 多智能体协作效率低下或陷入循环问题协调员和子智能体之间来回传递信息却无法推进任务。解决明确角色与边界为每个子智能体设计极其明确的单一职责。技术专家不应该去处理问候接待员也不应该尝试解决技术问题。协调员的指令必须清晰定义任务派发逻辑。设定对话轮次限制在Session.run()中可以通过参数或自定义逻辑限制智能体内部的最大交互轮次防止无限循环。优化协调员指令协调员的指令应像一个项目经理不仅要派活还要能汇总和判断子任务的结果是否完整、是否需要进一步行动。例如“如果技术专家返回了‘未找到’则询问用户是否创建工单”。6.3 处理长上下文与记忆管理问题随着对话进行会话历史越来越长可能导致模型性能下降、成本增加甚至忘记早期信息。策略摘要记忆定期例如每10轮对话后让智能体自己对之前的对话历史生成一个简短的摘要然后用这个摘要替代冗长的原始历史作为新的上下文起点。这需要你在应用层实现逻辑。关键信息提取在工具调用或重要决策点将有价值的信息如用户偏好、任务目标、已确认的事实显式地存储在一个独立的“记忆存储”中并在后续对话中主动注入这些关键信息而不是依赖完整的原始历史。ADK的未来支持关注ADK的更新官方可能会引入更正式的记忆管理模块。6.4 成本控制与性能优化监控Token使用每次调用LLM都会消耗Token。在开发阶段务必在日志中输出或监控每次请求的输入/输出Token数量。这有助于你优化指令使其更简洁和设计工具让工具返回精炼的结果。选择合适的模型不是所有任务都需要最强大的模型。对于简单的分类、路由任务使用gemini-flash系列成本更低、速度更快。对于需要复杂推理的协调员或专家再使用gemini-pro系列。异步与流式处理对于需要同时处理多个用户请求或希望实现打字机效果的流式响应ADK支持异步会话和流式响应。这可以提升用户体验和系统吞吐量。我个人在将一个内部知识库问答系统迁移到ADK架构时最大的体会是“分而治之”带来的好处。我们将一个庞大的、指令混乱的单一智能体拆分为一个查询理解器、一个文档检索器和一个答案合成器。每个智能体都变得简单、易于测试和优化。协调员负责串联流程。当检索效果不佳时我们只需要调整文档检索器的工具和指令而不会影响其他部分。这种模块化带来的维护性提升在项目迭代中价值巨大。最后ADK的社区和文档正在快速成长遇到问题时除了查阅官方文档去GitHub的Discussions板块和Reddit的r/agentdevelopmentkit社区看看往往能找到灵感或直接的答案。这个框架的潜力在于它把构建智能体的复杂过程变成了一个可以用软件工程方法管理和迭代的工程项目。