Python ADK 示例代理Sample Agents全指南样本结构、本地运行、评估测试与部署实战【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples本指南以仓库中 python/agents/README.md 为纲系统讲解基于 Python Agent Development KitPython ADK构建的示例代理集合如何选择代理、配置环境、本地运行、评估测试以及代理目录的工程规范与源码结构。读完本文你将掌握从零上手任意 ADK 示例代理的完整流程并能读懂其多智能体架构的核心实现。一、Python ADK 示例代理集合是什么python/agents/目录是 Python ADK 的示例代理Sample Agents集合每个子目录对应一个完整的、可独立运行的代理示例。它们覆盖金融、零售、医疗、旅游、市场营销、数据分析等多个行业场景既有单代理Single Agent的对话式助手也有多代理Multi Agent协作的工作流还包含对自定义工具Custom tool、MCP、RAG、BigQuery 等能力的演示。这些示例的价值在于快速上手每个代理都带有独立的README.md、pyproject.toml、.env.example克隆仓库后即可安装运行架构参考示例覆盖了 ADK 中Agent、sub_agents、tools、回调callback等核心 API 的典型用法是学习多智能体编排的最佳范本端到端闭环多数示例同时提供eval/评估、tests/测试与deployment/部署目录示范了从开发到上线的完整链路。说明本仓库是该示例集合的一份快照python/agents/下收录的示例以子目录形式存在例如fomc-research、travel-concierge、youtube-analyst部分示例在本仓库中位于其他路径例如llm-auditor位于 contrib/python/llm-auditordeep-search位于 core/python/deep-search但工程结构与使用方式完全一致。二、快速开始Getting Started2.1 前提条件运行这些示例代理需要准备以下环境前提说明Python Agent Development Kit即google-adk包可参考 ADK 官方快速入门指南安装Python 3.9主 README 声明的最低版本要求注意部分新示例要求更高版本例如fomc-research的 pyproject.toml 要求3.11具体以各代理 README 为准Poetry 或 uv主 README 以 Poetry 作为依赖管理工具当前仓库中多数示例已改用 uv并带有uv.lock锁定文件Google Cloud / Gemini API Key取决于代理类型使用 Vertex AI 的代理需要 GCP 项目使用 Gemini API 的代理需要 API Key详见各代理 README2.2 运行一个示例代理的通用步骤进入目标代理目录例如cd python/agents/llm-auditor将.env.example复制为.env填写所需的环境变量API Key、项目 ID 等具体变量以该代理 README 为准安装依赖poetry install使用 uv 的示例则为uv sync --dev按该代理 README 的说明运行通常使用adk run .CLI或adk webWeb 界面。三、代理分类总览Agent Categories主 README 以一张总表列出了按类别组织的全部示例代理涵盖行业垂直领域Vertical、交互类型Interaction Type、复杂度Complexity、代理类型Agent Type与关键标签Tag。下表完整收录Agent NameUse CaseTagInteraction TypeComplexityAgent TypeVerticalAgent Skills TutorialDemonstrates 4 ADK skill patterns: inline, file-based, external, and meta (skill-creator). Uses SkillToolset for progressive disclosure of skill metadata, instructions, and resources.SkillToolset, Skills, Progressive disclosureConversationalEasySingle AgentHorizontalAcademic ResearchAssists researchers in identifying recent publications and discovering emerging research areas.Multi-agent, Custom tool, EvaluationWorkflowEasyMulti AgentAcademiaBrand Search OptimizationEnrich e-commerce product data by analyzing and comparing top search results. Useful for addressing issues like Null low recovery / Zero Results searches and identifies gaps in product data.Multi-agent, Custom tool, BigQuery connection, Evaluation, Computer useWorkflowEasyMulti AgentRetailCymbal Home Garden Customer Service AgentCustomer service, product selection, order management for home improvement, gardening, and related suppliesCustom tool, Async tool, External system calls, Live streaming, MultimodalConversationalAdvancedSingle AgentRetailCurrency AgentAgent for currency exchange rate lookups and conversions.Custom toolConversationalIntermediateSingle AgentFinancial ServicesData Engineering AgentData Engineering Agent designed for building sophisticated BigQuery and Dataform PipelinesBigQuery, Dataform, ELT Pipelines, Data Curation, Data Modelling, Data Preperation, Data Ingestion, Analytics Engineering, Data EngineeringConversationalAdvancedSingle AgentHorizontalData Science AgentA multi-agent system designed for sophisticated data analysisFunction tool (Python), Agent tool, NL2SQL, Structured data, DatabaseConversationalAdvancedMulti AgentHorizontalFinancial AdvisorAssists human financial advisors by providing educational content about topics related to finance and investments.Risk Analysis, Strategy Generation, Summarization, Report generationWorkflowEasyMulti AgentFinancial ServicesFOMC Research AgentMarket event analysisSummarization, Report generationWorkflowAdvancedMulti AgentFinancial ServicesDeep SearchA blueprint for building a sophisticated, fullstack research agent with Gemini. Demonstrates complex agentic workflows, modular agents, and Human-in-the-Loop (HITL) steps.Multi-agent, Function calling, Web search, React frontend, FastAPI backend, Human-in-the-LoopWorkflowAdvancedMulti AgentHorizontalGemma Food Tour GuideA food tour guide that uses Gemma 4 31B and Google Maps MCP to build personalized culinary tours from an image of a dish, location, and budget.Tool calling, Google Maps MCP, Multimodal input, Route planningLlmAgentIntermediateSingle AgentTravel and local discoveryLLM AuditorChatbot Response Verification, Content AuditingGemini with Google Search, Multi-agentWorkflowEasyMulti AgentHorizontalMarketing AgencyStreamlines new website and product launches. Identifies optimal DNS domains, generates entire websites, develops marketing strategies, and designs brand assets.Content generation, Website creation, Code generation, Strategy developmentWorkflowEasyMulti AgentHorizontalMedical Pre-AuthorizationAutomates the pre-authorization process by analyzing medical records and health policies to instantly determine coverage and eligibility.Custom tool, Document Analysis, Report GenerationConversationalIntermediateMulti AgentHealthcarePersonalized ShoppingProduct RecommendationsE-commerce, Personalized agent, Shopping assistant, Single-agent, Product recommendation, Product discovery, ChatbotConversationalEasySingle AgentE-commerceVertex AI Retrieval AgentRAG Powered Agent / Answering questions related to documents uploaded to Vertex AI RAG Engine, providing informative responses with citations to source materials.RAG engineWorkflowIntermediateSingle AgentHorizontalSafety Guardrail PluginsSafety filter plugins: Gemini as a judge, Model Armor as a filterPlugin, Security, Guardrail, Jailbreak, MultiagentConversational/WorkflowIntermediatePluginSafety SecurityShort Movie AgentsConstructs end to end videos based on the users intent.Multi-agent, Custom toolWorkflowIntermediateMulti AgentMediaSoftware Bug AssistantAssists in software bug resolution by querying internal ticketing systems and external knowledge sources (GitHub, StackOverflow, Google Search) to find similar issues and diagnostics.RAG, MCP, Bug Tracking, Google Search, IT Support, Database Integration, APIWorkflow/ConversationalIntermediateSingle AgentHorizontal / IT SupportSupply ChainA multi-agent system designed to analyze real-time market dynamics, weather conditions, internal operations, and demand forecasts to optimize the power energy supply chain.Function tool (Python), Custom tool, Agent tool, Google Search, BigQueryConversationalIntermediateMulti AgentPower Energy (Supply Chain)Travel ConciergeTravel Concierge, Digital Tasks AssistantFunction tool (Python), Custom tool, Agent tool, Input and output schema, Updatable context, Dynamic instructionsConversationalAdvancedMulti AgentTravelYouTube AnalystDeep insights into YouTube content, channel performance, and audience engagement using interactive Plotly charts.Multi-agent, YouTube API, Interactive chartsConversationalIntermediateMulti AgentMarketing / Media AnalyticsAuto Insurance AgentAuto Insurance Agent to manage members, claims, rewards and roadside assistance.Apigee, Apigee API hub, Agent ToolConversationalEasyMulti AgentFinancial ServicesImage ScoringImage scoring agent to generate images based on policies and score the generated images to measure policy compliance.Function tool (Python), Agent tool, Imagen, Loop AgentConversationalEasyMulti AgentHorizontalAntom PaymentIntegrates Ant Internationals Antom payment APIs to enable payment and refund operations via standardized MCP tools.MCP, Payment, Refund, External APIConversationalIntermediateSingle AgentFinancial Services / PaymentsIncident ManagementThis agent sample showcases the utilization of dynamic identity propagation with ServiceNow and Application Integration ConnectorsApplication Integration, Integration Connectors, Agent ToolConversationalEasySingle AgentCustomer SupportOrder ProcessingThis agent sample showcases how Application Integration Connectors can be leveraged to automate orders and include human in the loop for workflowsApplication Integration, Integration Connectors, Agent ToolConversationalEasySingle AgentOrder ManagementGoogle Trends AgentSurfaces top trending search trends from Google Trends using BigQuery dataset. Shows trending topics by region and time period.BigQuery, Trend analysis, Sequential agentConversationalMediumSequential AgentMarketing AnalyticsHierarchical Workflow AutomationThe Hierarchical Workflow Automation pattern is an automation process where multiple distinct tasks or transactions must be executed in a structured hierarchy across various systems to complete a full workflowMulti-agent, Custom tool, BigQuery, Agent ToolWorkflowAdvancedMulti Agent / Sequential AgentOrder Management / Customer SupportPlumber-Data-Engineering-AssistantA data engineering assistant agent capable of creating and deploy big data pipelines in Apache Spark, Apache Beam and dBT on GCP data stack via conversationsBig Data, Data Analytics, Streaming Analytics, Dataflow, Dataproc, BigqueryConversationalHardMulti AgentData AnalyticsGenMedia for CommerceFull-stack AI agent for commerce media generation: virtual try-on (image video), 360° product spinning, background changing, product fitting, and catalogue search. Includes MCP server, FastAPI backend, React frontend, and Terraform infra.MCP, Multimodal, Image generation, Video generation, Virtual try-on, Catalogue search, Agent RuntimeConversationalAdvancedSingle AgentRetailLive API Evals Audio AuditingA framework for real-time STT and TTS evaluations using Gemini Live and ADK. Additionally, It captures, archives, and audits bidirectional voice interactions.Gemini Live, Audio, Evaluation, STT, TTS, AuditWorkflowAdvancedSingle AgentHorizontalDynamic Workflow - Task ManagementCollects a list of tasks from the user, gains approval, and launches a dynamic workflow that schedules subagents to explain execution plans and mark tasks as done.ADK 2.0, Dynamic Workflows, Subagent Scheduling, NodeRunnerWorkflow / ConversationalIntermediateMulti Agent / WorkflowHorizontal从中可以归纳出几个规律帮助你快速定位感兴趣的示例交互类型Interaction TypeConversational表示对话式交互适合聊天场景Workflow表示以子代理编排为主的非对话式工作流如 FOMC Research、Financial Advisor 等自动生成报告的场景复杂度ComplexityEasy / Intermediate / Advanced / Hard 四档初学者建议从 Easy 的单代理示例入手代理类型Agent TypeSingle Agent、Multi Agent、Sequential Agent、Plugin 等反映编排模式标签Tag标注了该示例演示的 ADK 核心能力如 MCP、RAG、SkillToolset、BigQuery、Agent Tool可直接按能力关键词检索。四、使用本仓库代理的完整工作流主 README 强调虽然核心步骤相似但每个代理都有各自的专属要求与详细说明务必以其目录内独立的README.md为准例如 fomc-research/README.md。以下是通用流程4.1 选择并进入代理目录从仓库根目录进入所选代理的主目录cd python/agents/agent-name # 示例cd python/agents/fomc-research4.2 阅读代理 README最关键的一步打开该目录下的README.md其中会包含代理用途与架构的详细说明特定前提条件API Key、云服务、数据库配置等分步骤的安装与配置指引本地运行命令评估Evaluation运行方式如适用测试Test运行方式如适用部署Deployment步骤如适用。4.3 安装依赖与环境变量配置依赖安装在代理主目录中使用 Poetry 安装其专属 Python 依赖poetry install环境变量大多数代理需要通过环境变量配置。将代理目录内的.env.example复制为.env并填入实际值API Key、项目 ID 等。在 bash 中可将.env中的变量导出到当前 shellset -o allexport . .env set o allexport非 bash 环境请手动导出变量。4.4 本地运行代理代理通常可通过 ADK CLI 或 ADK Dev UI 在本地运行具体命令以各代理 README 为准。ADK CLI通常在代理的核心代码目录内执行例如fomc-research/fomc_research/# 示例以代理 README 为准 cd python/agents/fomc-research/fomc_research/ adk run .ADK Dev UI通常在代理的主目录执行# 示例 cd python/agents/fomc-research/ adk web然后在浏览器中打开输出的 URL从下拉菜单中选择代理即可交互。例如 fomc-research 的运行方式为adk run fomc_research启动后控制台会打印日志文件路径可用tail -F /tmp/agents_log/agent.latest.log实时跟踪。4.5 评估代理性能许多代理包含eval/目录存放评估脚本与数据例如python eval/test_eval.py用于验证代理在特定任务上的效果。运行方式以代理 README 为准。4.6 测试代理组件tests/目录通常包含单元测试或集成测试例如针对自定义工具确保各个代码组件功能正确通常使用pytest等框架运行。4.7 部署代理部分代理设计为可部署到 Agent RuntimeVertex AI Agent Engine。deployment/目录包含部署脚本如deploy.py与配置文件。部署通常需要特定的 Google Cloud 配置项目 ID、启用的 API、权限等具体步骤可参考代理 README 与deployment/目录内的脚本。以 fomc-research 为例其 deployment/deploy.py 负责创建 Agent Runtime 资源deployment/test_deployment.py 用于与已部署的远程代理交互验证。五、代理目录结构与工程规范每个示例代理都遵循统一的目录组织方式主 README 给出的标准结构如下本仓库中根目录对应python/agents/agent-name├── agent-name │ ├── agent_name/ # 核心代理代码 │ │ ├── shared_libraries/ # 多个子代理共享的辅助函数 │ │ ├── sub_agents/ # 每个子代理一个目录 │ │ │ │ ├── tools/ # 子代理专属工具 │ │ │ │ ├── agent.py # 子代理核心逻辑 │ │ │ │ └── prompt.py # 子代理提示词 │ │ │ └── ... # 更多子代理 │ │ ├── __init__.py # 初始化代理将 agent_name 标记为 Python 包 │ │ ├── tools/ # 路由代理主代理使用的工具代码 │ │ ├── agent.py # 主代理核心逻辑 │ │ ├── prompt.py # 主代理提示词 │ ├── deployment/ # 部署到 Agent Engine │ ├── eval/ # 评估方法与数据 │ ├── tests/ # 工具单元测试 │ ├── agent_pattern.webp # 代理模式架构图 │ ├── .env.example # 代理专属环境变量样例 │ ├── pyproject.toml # 项目配置 │ └── README.md # 代理总览5.1 各部分详解agent_name/核心代理代码包含代理的核心逻辑。shared_libraries/可选多个子代理共享的代码sub_agents/子代理的定义与逻辑。每个子代理拥有独立目录如 llm-auditor 中的critic/、reviser/其中tools/存放该子代理专属的自定义工具agent.py定义子代理行为模型、工具、指令prompt.py存放引导子代理行为的提示词__init__.py导入该文件夹中的agent.py将agent_name目录标记为 Python 包tools/主代理使用的自定义工具agent.py定义主代理行为子代理、模型、工具、指令prompt.py主代理的提示词。deployment/部署到 Agent Runtime 等平台所需的脚本与文件通常包含deploy.py。eval/评估数据与脚本典型文件为test_eval.py与测试数据如.test.json。tests/单元测试与集成测试如test_agents.py用于验证代理功能。agent_pattern.webp可视化架构图展示代理及其子代理的交互关系。.env.example运行代理所需环境变量的示例文件复制为.env后填写实际值。pyproject.toml项目元数据、依赖与构建系统配置由 Poetry或 uv/hatchling管理。README.md代理专属的详细文档包含用途、安装、使用示例与定制说明。5.2 命名约定连字符与下划线一个容易踩坑的细节外层目录名用连字符-连接单词而核心逻辑目录使用下划线_。例如外层目录是llm-auditor核心包是llm_auditorfomc-research对应fomc_research。这是 Poetry 项目结构约束所致导入包时请使用下划线形式。六、示例剖析llm-auditor与fomc-research6.1llm-auditor结构范本主 README 以llm-auditor为例说明目录结构的落地形态它包含核心目录llm_auditor/llm_auditor/sub_agents/下的子代理如critic/与reviser/deployment/部署脚本eval/评估数据与脚本tests/测试.env.example、pyproject.toml、README.md。在本仓库中该示例位于 contrib/python/llm-auditor其 README.md 与架构图 llm_auditor_architecture.webp 可直接对照查看。6.2fomc-research多智能体工作流实证主表格中的 FOMC Research Agent 是本仓库内结构最完整的示例之一用于分析美联储公开市场委员会FOMC会议并生成研究报告。它演示了与对话式交互不同的多阶段非对话式工作流大部分工作发生在子代理之间的来回协作中仅在必要时向用户索要关键信息如会议日期。其关键特征为交互类型 Workflow、复杂度 Advanced、代理类型 Multi Agent、组件包括 Tools / Multimodal / AgentTools、垂直领域为 Financial Services。代理Agents分层root_agent工作流入口协调其他代理的活动research_agent协调各研究组件的获取analysis_agent接收research_agent的输出并生成分析报告retrieve_meeting_data_agent从网页抓取 FOMC 会议数据extract_page_data_agent从 HTML 页面提取特定数据summarize_meeting_agent读取会议记录并生成摘要。工具Toolsfetch_page_tool封装 HTTP 请求获取网页、store_state_tool将信息存入 ToolContext、analyze_video_tool处理分析 YouTube 视频、compute_probability_tool依据 Fed Futures 定价计算利率变动概率、compare_statements比较当前与历史 FOMC 声明、fetch_transcript获取 FOMC 会议记录。回调Callbacksrate_limit_callback实现请求限流最小化429: Resource Exhausted错误。七、源码级深入读懂一个 ADK 多智能体代理以fomc-research为例深入其源码可以印证主 README 描述的工程规范。7.1 主代理定义agent.pypython/agents/fomc-research/fomc_research/agent.py 中root_agent通过 ADK 的Agent(...)声明式 API 组装而成root_agent Agent( modelMODEL, nameroot_agent, description( Use tools and other agents provided to generate an analysis report about the most recent FOMC meeting. ), instructionroot_agent_prompt.PROMPT, tools[store_state_tool], sub_agents[ RetrieveMeetingDataAgent, ResearchAgent, AnalysisAgent, ], before_model_callbackrate_limit_callback, )关键参数一一对应主 README 的目录规范name代理名称CLI 运行日志中显示为Running agent root_agentinstruction来自 root_agent_prompt.py 的提示词定义代理角色、索取会议日期的流程并指示通过store_state工具以user_requested_meeting_date键将日期存入 ToolContextISO 格式YYYY-MM-DDtools主代理直属工具此处仅store_state_toolsub_agents挂载的子代理列表即sub_agents/目录中定义的各 Agent 类before_model_callback在每次调用模型前执行的回调即shared_libraries/callbacks.py中的限流逻辑。7.2 子代理的编排与工具挂载research_agent.py 展示了子代理如何继续向下分层ResearchAgent自身又挂载了SummarizeMeetingAgent子代理并声明了compare_statements_tool、fetch_transcript_tool、compute_rate_move_probability_tool等研究工具。retrieve_meeting_data_agent.py 则演示了 ADK 的AgentTool用法——将ExtractPageDataAgent包装为工具暴露给上层代理调用tools[ fetch_page_tool, AgentTool(ExtractPageDataAgent), ],这印证了主 README 中子代理的tools/目录存放该子代理专属工具的说明tools/下的 fetch_page.py、compare_statements.py 等文件正是这些工具的实现。7.3 回调机制请求限流实现shared_libraries/callbacks.py 实现了rate_limit_callback通过CallbackContext.state维护timer_start与request_count当窗口内请求数超过RPM_QUOTA默认 1000时休眠RATE_LIMIT_SECS - elapsed_secs 1秒后重置计数。该回调被挂载到所有代理的before_model_callback从源码结构看这正是整个多代理工作流规避 Gemini API429 Resource Exhausted限流错误的核心机制。7.4 工程化细节从 Poetry 到 uv主 README 的Getting Started以 Poetry 为例但当前仓库中多数示例含 fomc-research/pyproject.toml已迁移至 uv hatchling 构建体系使用uv sync --dev安装依赖含google-adk及其eval扩展uv build --wheel --out-dirdeployment构建部署用 wheel 包。依赖声明中可见google-adk1.31.0、google-cloud-bigquery、google-genai、scikit-learn等与代理的 BigQuery 查询、概率计算等能力一一对应。因此实际运行前请以各代理目录内的 README 与pyproject.toml为准确认使用 Poetry 还是 uv。八、使用建议与注意事项以代理 README 为最终依据本指南给出的是通用流程每个示例的精确命令、必需变量与外部依赖数据库、第三方 API请以对应目录的README.md为准示例仅供学习这些示例旨在演示 ADK 能力作为开发自有代理的起点官方声明其未经严格生产级测试不包含生产环境所需的健壮错误处理、安全加固、可扩展性与完整日志等能力用于真实或关键系统前需自行评审、测试并实施适当防护按需选择复杂度首次上手建议选择 Easy 级别单代理示例如 agent-skills-tutorial熟悉目录结构与adk run/adk web流程后再挑战 Advanced 的多代理工作流如 fomc-research善用结构规律记住连字符目录名 下划线包名的约定以及agent.py/prompt.py/sub_agents//tools/的固定职责划分即可快速读懂任意示例的实现骨架。至此你已经掌握了 Python ADK 示例代理集合的完整使用路径——从选择代理、配置环境、本地运行到评估、测试、部署再到借助统一的目录规范与源码结构理解多智能体实现原理。以这份指南为地图逐一深入各示例的 README 与源码即可系统掌握 ADK 的核心开发模式。【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考