用 ADK Data Agent 工具集成 Gemini Conversational Analytics自然语言数据查询、Agent 生命周期管理与图表生成实战【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python导读本文基于 ADK 官方示例 contributing/samples/integrations/data_agent 及其配套源码讲解如何在 ADK 智能体中接入 Google Cloud 的Data Agent数据代理能力通过google.adk.tools.data_agent模块提供的第一方工具让 Agent 能够用自然语言列出、查看、对话乃至创建、修改、删除 Data Agent并借助有状态会话实现多轮追问。读完本文你将掌握 DataAgentToolset 的完整配置方法、六种工具的调用契约、三种凭据接入方式以及如何结合图表生成工具构建一个开箱即用的数据问答 Agent。一、Data Agent 工具能做什么Data Agent 是 Google Cloud 提供的对话式数据分析能力Conversational Analytics它指向你的 BigQuery 表或其他数据源接受自然语言问题并返回 SQL、检索结果与最终回答。ADK 的google.adk.tools.data_agent模块把这些能力封装成标准工具让 ADK Agent 可以直接调度它们列出你有权限访问的 Data Agent查看某个 Data Agent 的详细信息数据源引用、系统指令等对话用自然语言向指定 Data Agent 提问创建 / 删除 / 更新Data Agent 资源实验性需显式开启。一个关键特性是有状态会话在同一个 session 内可以连续追问如上季度我的前 3 名客户是谁→那再前一个季度呢Agent 会维持上下文无需反复交代背景。模块的公开 API 入口见 src/google/adk/tools/data_agent/init.py导出了三个核心类DataAgentCredentialsConfig、DataAgentToolConfig、DataAgentToolset。二、架构与调用链从 Agent 到 Gemini Data Analytics API从源码结构看Data Agent 工具的调用链分为四层Agent 层示例 Agent 定义 将DataAgentToolset实例直接放入tools列表同时混入generate_chart和load_artifacts等自定义工具Toolset 层data_agent_toolset.py 的DataAgentToolset.get_tools()按配置装配工具——默认装配 3 个只读工具仅当enable_data_agent_modificationTrue时才追加 3 个写工具每个工具都被包装为GoogleToolgoogle_tool.py从而复用 ADK 的 Google API 凭据机制工具函数层data_agent_tool.py 定义 6 个工具函数负责参数校验、构造请求、调用 Gemini Data Analytics REST API端点默认geminidataanalytics.googleapis.com/v1流式处理层ask_data_agent通过_gda_stream_util.get_stream以流式方式消费会话回复并用DataAgentToolConfig.max_query_result_rows限制返回行数。每个工具函数返回统一的字典结构{status: SUCCESS|ERROR, response: ...}或{status: ERROR, error_details: ...}方便 Agent 在指令中约定根据 status 判断成败。三、前置条件运行该示例前需要准备一个已启用的 Google Cloud 项目需要开启 BigQuery 和 Gemini API官方指引中同时要求启用 Conversational Analytics 相关 API 并按文档配置 IAM 权限与数据源认证本文不再展开外部文档细节。配置 Application Default CredentialsADCgcloud auth application-default login至少一个已创建的 Data Agent可以通过 Conversational Analytics API、其 Python SDK或直接在 BigQuery Studio 中创建。这些 Agent 在 Google Cloud 控制台配置指向你的 BigQuery 表或其他数据源。按官方 Setup 指南完成 API 启用与 IAM 权限配置确保数据源可被 Data Agent 访问。四、六种工具详解原文档列出的 6 个工具在 data_agent_tool.py 中实现签名与要点如下工具类型关键参数说明list_accessible_data_agents只读project_id,location?列出项目下你有权限访问的 Data Agent返回 name、displayName、description、createTime、updateTime 及dataAnalyticsAgent上下文get_data_agent_info只读data_agent_name按资源全名查询单个 Data Agent 详情ask_data_agent只读data_agent_name,query用自然语言向指定 Agent 提问流式返回思考过程、生成的 SQL、检索数据与最终回答create_data_agent写实验性project_id,data_agent_id,agent_config(JSON),location?创建新 Agent需开启修改开关等待 LRO 完成update_data_agent写实验性data_agent_name,agent_config(JSON),update_mask按字段掩码更新 Agent需开启修改开关等待 LRO 完成delete_data_agent写实验性data_agent_name删除 Agent需开启修改开关等待 LRO 完成4.1 资源命名与参数校验所有 Agent 均使用资源全名定位格式为projects/{project}/locations/{location}/dataAgents/{agent}例如示例提示词中的projects/my-project/locations/global/dataAgents/sales-agent-123。工具内部用正则_DATA_AGENT_NAME_RE校验该格式project、location、agent 三个路径段只允许字母数字以及-、_、.见 data_agent_tool.py 中的_validate_path_segment。格式错误会直接返回{status: ERROR, error_details: ...}。4.2 查询返回结构ask_data_agent的返回是一个步骤列表steps每个步骤是包含不同键的字典典型流程如下源码 docstring 示例{ status: SUCCESS, response: [ {text: {parts: [Analyzing context, Retrieved context for 1 table.], textType: THOUGHT}}, {data: {generatedSql: SELECT AVG(SAFE_CAST(street_trees.dbh AS FLOAT64)) AS average_height FROM bigquery-public-data.san_francisco.street_trees AS street_trees;}}, {Data Retrieved: {headers: [average_height], rows: [[10.073475670972512]], summary: Showing all 1 rows.}}, {text: {parts: [### Summary\nBased on the street tree data for San Francisco, the average height ... is approximately 10.07.], textType: FINAL_RESPONSE}} ] }可见返回中既包含模型的思考textType: THOUGHT、生成的 SQLgeneratedSql、检索到的数据表格也有最终回答textType: FINAL_RESPONSE。有状态会话的底层实现是ask_data_agent先调用_get_data_agent_info拿到 Agent 信息再向{resource_parent}:chat端点发起带clientIdEnumGOOGLE_ADK的流式请求见 data_agent_tool.py同一 ADK session 内的连续提问即构成上下文延续。4.3 写操作与长任务轮询create/update/delete三个写工具都会发起一个长期运行操作LRO并在data_agent_modification_timeout_seconds默认 60 秒内以data_agent_modification_poll_interval_seconds默认 2 秒为间隔轮询GET /operations/{name}直到done为止可重试的 HTTP 状态码429/500/502/503/504会自动重试。注意轮询超时并不代表操作失败——操作可能仍在后台执行超时响应中会附带operation_name供后续查询源码注释明确提示不要重试该操作。update_data_agent有一个防误删保护update_mask中列出的每个字段必须同时出现在agent_config中否则返回错误避免因遗漏字段导致 API 清空未提及的属性见_mask_field_present逻辑。五、DataAgentToolConfig 配置详解工具行为通过DataAgentToolConfigconfig.py控制这是一个 pydantic 模型extraforbid表示不认识的字段会直接报错字段默认值说明max_query_result_rows50单次查询最多返回的行数上限locationNoneGCP location如eu、us、global未指定时优先从资源名解析否则回退到globalapi_endpointNone自定义 Gemini Data Analytics API 端点覆盖默认或按 location 推导的端点data_agent_modification_timeout_seconds60写操作create/update/delete等待 LRO 的总超时须 0data_agent_modification_poll_interval_seconds2写操作轮询间隔须 0enable_data_agent_modificationFalse是否允许工具集修改 Agent 资源创建/更新/删除默认关闭保证只读工具集永远只读六、凭据接入三种认证方式DataAgentCredentialsConfigcredentials.py封装凭据配置默认 OAuth scope 为https://www.googleapis.com/auth/bigquery并使用data_agent_token_cache作为令牌缓存键。示例 agent.py 通过CREDENTIALS_TYPE变量演示了三种接入方式CREDENTIALS_TYPE None # 默认使用 ADC if CREDENTIALS_TYPE AuthCredentialTypes.OAUTH2: # 交互式 OAuth2需设置 OAUTH_CLIENT_ID / OAUTH_CLIENT_SECRET 环境变量 credentials_config DataAgentCredentialsConfig( client_idos.getenv(OAUTH_CLIENT_ID), client_secretos.getenv(OAUTH_CLIENT_SECRET), ) elif CREDENTIALS_TYPE AuthCredentialTypes.SERVICE_ACCOUNT: # 服务账号密钥文件需替换为你的 key 文件路径 creds, _ google.auth.load_credentials_from_file( service_account_key.json, scopes[https://www.googleapis.com/auth/cloud-platform], ) creds.refresh(google.auth.transport.requests.Request()) credentials_config DataAgentCredentialsConfig(credentialscreds) else: # Application Default Credentials推荐本地开发 application_default_credentials, _ google.auth.default() if not application_default_credentials.valid: application_default_credentials.refresh( google.auth.transport.requests.Request() ) credentials_config DataAgentCredentialsConfig( credentialsapplication_default_credentials )ADC默认本地开发最省事配合gcloud auth application-default login即可OAuth2适合需要交互式授权页面的场景Service Account适合 CI/服务器等无交互环境。七、组合 Toolset 与图表生成示例 Agent 全解示例 Agent 将 Data Agent 工具集与自定义工具组合形成一个完整的查询 可视化智能体完整代码见 agent.pytool_config DataAgentToolConfig( max_query_result_rows100, # 每查询最多返回 100 行 enable_data_agent_modificationTrue, # 允许创建/更新/删除 ) da_toolset DataAgentToolset( credentials_configcredentials_config, data_agent_tool_configtool_config, tool_filter[ list_accessible_data_agents, get_data_agent_info, ask_data_agent, create_data_agent, delete_data_agent, update_data_agent, ], ) root_agent Agent( namedata_agent, descriptionAgent to answer user questions using Data Agents and generate charts., instruction( ## Persona\nYou are a helpful assistant that uses Data Agents to answer user questions about their data.\n\n ## Tools\n- You can list available data agents using list_accessible_data_agents.\n - You can get information about a specific data agent using get_data_agent_info.\n - You can chat with a specific data agent using ask_data_agent.\n - You can create/delete/update data agents using the corresponding tools.\n - generate_chart renders professional charts from a chart_spec (Vega-Lite JSON).\n - You can load artifacts using load_artifacts.\n ), tools[da_toolset, generate_chart, load_artifacts], )几点值得注意的实现细节tool_filter语义与基类BaseToolset不同DataAgentToolset在tool_filter为空列表时不会装配任何工具见 data_agent_toolset.py且即使过滤列表里写了写工具只要enable_data_agent_modificationFalse这些工具依然不会被创建见get_tools的装配逻辑以及 test_data_agent_toolset.py 中test_data_agent_toolset_tools_selective_modification_disabled的验证。图表工具generate_chart接收 Vega-Lite JSON 规格通过 Altair vl-convert渲染成 PNG 并调用tool_context.save_artifact(chart.png, ...)保存为 artifact。需要额外安装pip install altair vl-convert-python。Agent 指令要求需要可视化时使用它不要向用户展示原始 JSON。工具装配的默认行为get_tools()默认只创建 3 个只读工具开启修改开关后共 6 个工具——这一点被测试test_data_agent_toolset_tools_default3 个与test_data_agent_toolset_tools_with_mutation_enabled6 个精确断言。八、运行方式与示例提示词进入 ADK 仓库根目录使用 ADK CLI 运行示例adk run contributing/samples/integrations/data_agentCLI 进入交互模式后即可提问。原文档给出的四组示例提示词覆盖了查列表 → 查详情 → 有状态追问 → 创建资源的完整链路List accessible data agents.—— 列出可访问的 Data AgentUsing agent projects/my-project/locations/global/dataAgents/sales-agent-123, who were my top 3 customers last quarter?—— 指定 Agent 做具体分析How does that compare to the quarter before?——无需重复指定 Agent直接追问上一季度对比有状态会话的体现Create a new data agent named my-new-agent.—— 触发create_data_agent写操作需已开启修改开关。九、测试验证行为契约有据可依仓库在 tests/unittests/tools/data_agent/ 提供了两层测试Toolset 层test_data_agent_toolset.py断言默认装配 3 个只读工具、开启修改后装配 6 个、tool_filter白名单过滤、未知工具名被忽略、修改未开启时写工具即使列入 filter 也不出现工具函数层test_data_agent_tool.pymockget_gda_session/get_gda_endpoint验证list_accessible_data_agents的请求 URL/v1/projects/{project}/locations/{location}/dataAgents:listAccessible、请求头X-Goog-API-Client: GOOGLE_ADK以及异常路径返回ERROR字典等行为。这些测试同时是学习工具契约参数、返回结构、错误格式的绝佳参考。十、小结google.adk.tools.data_agent将 Gemini Conversational Analytics 的 Data Agent 能力封装为 6 个第一方工具通过DataAgentToolset统一装配并复用 ADK 的 Google 凭据体系默认只读安全只有显式设置enable_data_agent_modificationTrue才会暴露创建/更新/删除能力ask_data_agent天然支持有状态多轮追问返回结构包含思考、SQL、数据与最终回答配合max_query_result_rows控制数据量结合自定义generate_chartAltair vl-convert可将查询结果直接渲染为图表 artifact形成自然语言提问 → 数据分析 → 可视化的完整闭环上述所有行为均有源码与测试佐证可放心在此基础上扩展你的数据问答 Agent。【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 用 ADK Data Agent 工具集成 Gemini Conversational Analytics：自然语言数据查询、Agent 生命周期管理与图表生成实战
用 ADK Data Agent 工具集成 Gemini Conversational Analytics自然语言数据查询、Agent 生命周期管理与图表生成实战【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python导读本文基于 ADK 官方示例 contributing/samples/integrations/data_agent 及其配套源码讲解如何在 ADK 智能体中接入 Google Cloud 的Data Agent数据代理能力通过google.adk.tools.data_agent模块提供的第一方工具让 Agent 能够用自然语言列出、查看、对话乃至创建、修改、删除 Data Agent并借助有状态会话实现多轮追问。读完本文你将掌握 DataAgentToolset 的完整配置方法、六种工具的调用契约、三种凭据接入方式以及如何结合图表生成工具构建一个开箱即用的数据问答 Agent。一、Data Agent 工具能做什么Data Agent 是 Google Cloud 提供的对话式数据分析能力Conversational Analytics它指向你的 BigQuery 表或其他数据源接受自然语言问题并返回 SQL、检索结果与最终回答。ADK 的google.adk.tools.data_agent模块把这些能力封装成标准工具让 ADK Agent 可以直接调度它们列出你有权限访问的 Data Agent查看某个 Data Agent 的详细信息数据源引用、系统指令等对话用自然语言向指定 Data Agent 提问创建 / 删除 / 更新Data Agent 资源实验性需显式开启。一个关键特性是有状态会话在同一个 session 内可以连续追问如上季度我的前 3 名客户是谁→那再前一个季度呢Agent 会维持上下文无需反复交代背景。模块的公开 API 入口见 src/google/adk/tools/data_agent/init.py导出了三个核心类DataAgentCredentialsConfig、DataAgentToolConfig、DataAgentToolset。二、架构与调用链从 Agent 到 Gemini Data Analytics API从源码结构看Data Agent 工具的调用链分为四层Agent 层示例 Agent 定义 将DataAgentToolset实例直接放入tools列表同时混入generate_chart和load_artifacts等自定义工具Toolset 层data_agent_toolset.py 的DataAgentToolset.get_tools()按配置装配工具——默认装配 3 个只读工具仅当enable_data_agent_modificationTrue时才追加 3 个写工具每个工具都被包装为GoogleToolgoogle_tool.py从而复用 ADK 的 Google API 凭据机制工具函数层data_agent_tool.py 定义 6 个工具函数负责参数校验、构造请求、调用 Gemini Data Analytics REST API端点默认geminidataanalytics.googleapis.com/v1流式处理层ask_data_agent通过_gda_stream_util.get_stream以流式方式消费会话回复并用DataAgentToolConfig.max_query_result_rows限制返回行数。每个工具函数返回统一的字典结构{status: SUCCESS|ERROR, response: ...}或{status: ERROR, error_details: ...}方便 Agent 在指令中约定根据 status 判断成败。三、前置条件运行该示例前需要准备一个已启用的 Google Cloud 项目需要开启 BigQuery 和 Gemini API官方指引中同时要求启用 Conversational Analytics 相关 API 并按文档配置 IAM 权限与数据源认证本文不再展开外部文档细节。配置 Application Default CredentialsADCgcloud auth application-default login至少一个已创建的 Data Agent可以通过 Conversational Analytics API、其 Python SDK或直接在 BigQuery Studio 中创建。这些 Agent 在 Google Cloud 控制台配置指向你的 BigQuery 表或其他数据源。按官方 Setup 指南完成 API 启用与 IAM 权限配置确保数据源可被 Data Agent 访问。四、六种工具详解原文档列出的 6 个工具在 data_agent_tool.py 中实现签名与要点如下工具类型关键参数说明list_accessible_data_agents只读project_id,location?列出项目下你有权限访问的 Data Agent返回 name、displayName、description、createTime、updateTime 及dataAnalyticsAgent上下文get_data_agent_info只读data_agent_name按资源全名查询单个 Data Agent 详情ask_data_agent只读data_agent_name,query用自然语言向指定 Agent 提问流式返回思考过程、生成的 SQL、检索数据与最终回答create_data_agent写实验性project_id,data_agent_id,agent_config(JSON),location?创建新 Agent需开启修改开关等待 LRO 完成update_data_agent写实验性data_agent_name,agent_config(JSON),update_mask按字段掩码更新 Agent需开启修改开关等待 LRO 完成delete_data_agent写实验性data_agent_name删除 Agent需开启修改开关等待 LRO 完成4.1 资源命名与参数校验所有 Agent 均使用资源全名定位格式为projects/{project}/locations/{location}/dataAgents/{agent}例如示例提示词中的projects/my-project/locations/global/dataAgents/sales-agent-123。工具内部用正则_DATA_AGENT_NAME_RE校验该格式project、location、agent 三个路径段只允许字母数字以及-、_、.见 data_agent_tool.py 中的_validate_path_segment。格式错误会直接返回{status: ERROR, error_details: ...}。4.2 查询返回结构ask_data_agent的返回是一个步骤列表steps每个步骤是包含不同键的字典典型流程如下源码 docstring 示例{ status: SUCCESS, response: [ {text: {parts: [Analyzing context, Retrieved context for 1 table.], textType: THOUGHT}}, {data: {generatedSql: SELECT AVG(SAFE_CAST(street_trees.dbh AS FLOAT64)) AS average_height FROM bigquery-public-data.san_francisco.street_trees AS street_trees;}}, {Data Retrieved: {headers: [average_height], rows: [[10.073475670972512]], summary: Showing all 1 rows.}}, {text: {parts: [### Summary\nBased on the street tree data for San Francisco, the average height ... is approximately 10.07.], textType: FINAL_RESPONSE}} ] }可见返回中既包含模型的思考textType: THOUGHT、生成的 SQLgeneratedSql、检索到的数据表格也有最终回答textType: FINAL_RESPONSE。有状态会话的底层实现是ask_data_agent先调用_get_data_agent_info拿到 Agent 信息再向{resource_parent}:chat端点发起带clientIdEnumGOOGLE_ADK的流式请求见 data_agent_tool.py同一 ADK session 内的连续提问即构成上下文延续。4.3 写操作与长任务轮询create/update/delete三个写工具都会发起一个长期运行操作LRO并在data_agent_modification_timeout_seconds默认 60 秒内以data_agent_modification_poll_interval_seconds默认 2 秒为间隔轮询GET /operations/{name}直到done为止可重试的 HTTP 状态码429/500/502/503/504会自动重试。注意轮询超时并不代表操作失败——操作可能仍在后台执行超时响应中会附带operation_name供后续查询源码注释明确提示不要重试该操作。update_data_agent有一个防误删保护update_mask中列出的每个字段必须同时出现在agent_config中否则返回错误避免因遗漏字段导致 API 清空未提及的属性见_mask_field_present逻辑。五、DataAgentToolConfig 配置详解工具行为通过DataAgentToolConfigconfig.py控制这是一个 pydantic 模型extraforbid表示不认识的字段会直接报错字段默认值说明max_query_result_rows50单次查询最多返回的行数上限locationNoneGCP location如eu、us、global未指定时优先从资源名解析否则回退到globalapi_endpointNone自定义 Gemini Data Analytics API 端点覆盖默认或按 location 推导的端点data_agent_modification_timeout_seconds60写操作create/update/delete等待 LRO 的总超时须 0data_agent_modification_poll_interval_seconds2写操作轮询间隔须 0enable_data_agent_modificationFalse是否允许工具集修改 Agent 资源创建/更新/删除默认关闭保证只读工具集永远只读六、凭据接入三种认证方式DataAgentCredentialsConfigcredentials.py封装凭据配置默认 OAuth scope 为https://www.googleapis.com/auth/bigquery并使用data_agent_token_cache作为令牌缓存键。示例 agent.py 通过CREDENTIALS_TYPE变量演示了三种接入方式CREDENTIALS_TYPE None # 默认使用 ADC if CREDENTIALS_TYPE AuthCredentialTypes.OAUTH2: # 交互式 OAuth2需设置 OAUTH_CLIENT_ID / OAUTH_CLIENT_SECRET 环境变量 credentials_config DataAgentCredentialsConfig( client_idos.getenv(OAUTH_CLIENT_ID), client_secretos.getenv(OAUTH_CLIENT_SECRET), ) elif CREDENTIALS_TYPE AuthCredentialTypes.SERVICE_ACCOUNT: # 服务账号密钥文件需替换为你的 key 文件路径 creds, _ google.auth.load_credentials_from_file( service_account_key.json, scopes[https://www.googleapis.com/auth/cloud-platform], ) creds.refresh(google.auth.transport.requests.Request()) credentials_config DataAgentCredentialsConfig(credentialscreds) else: # Application Default Credentials推荐本地开发 application_default_credentials, _ google.auth.default() if not application_default_credentials.valid: application_default_credentials.refresh( google.auth.transport.requests.Request() ) credentials_config DataAgentCredentialsConfig( credentialsapplication_default_credentials )ADC默认本地开发最省事配合gcloud auth application-default login即可OAuth2适合需要交互式授权页面的场景Service Account适合 CI/服务器等无交互环境。七、组合 Toolset 与图表生成示例 Agent 全解示例 Agent 将 Data Agent 工具集与自定义工具组合形成一个完整的查询 可视化智能体完整代码见 agent.pytool_config DataAgentToolConfig( max_query_result_rows100, # 每查询最多返回 100 行 enable_data_agent_modificationTrue, # 允许创建/更新/删除 ) da_toolset DataAgentToolset( credentials_configcredentials_config, data_agent_tool_configtool_config, tool_filter[ list_accessible_data_agents, get_data_agent_info, ask_data_agent, create_data_agent, delete_data_agent, update_data_agent, ], ) root_agent Agent( namedata_agent, descriptionAgent to answer user questions using Data Agents and generate charts., instruction( ## Persona\nYou are a helpful assistant that uses Data Agents to answer user questions about their data.\n\n ## Tools\n- You can list available data agents using list_accessible_data_agents.\n - You can get information about a specific data agent using get_data_agent_info.\n - You can chat with a specific data agent using ask_data_agent.\n - You can create/delete/update data agents using the corresponding tools.\n - generate_chart renders professional charts from a chart_spec (Vega-Lite JSON).\n - You can load artifacts using load_artifacts.\n ), tools[da_toolset, generate_chart, load_artifacts], )几点值得注意的实现细节tool_filter语义与基类BaseToolset不同DataAgentToolset在tool_filter为空列表时不会装配任何工具见 data_agent_toolset.py且即使过滤列表里写了写工具只要enable_data_agent_modificationFalse这些工具依然不会被创建见get_tools的装配逻辑以及 test_data_agent_toolset.py 中test_data_agent_toolset_tools_selective_modification_disabled的验证。图表工具generate_chart接收 Vega-Lite JSON 规格通过 Altair vl-convert渲染成 PNG 并调用tool_context.save_artifact(chart.png, ...)保存为 artifact。需要额外安装pip install altair vl-convert-python。Agent 指令要求需要可视化时使用它不要向用户展示原始 JSON。工具装配的默认行为get_tools()默认只创建 3 个只读工具开启修改开关后共 6 个工具——这一点被测试test_data_agent_toolset_tools_default3 个与test_data_agent_toolset_tools_with_mutation_enabled6 个精确断言。八、运行方式与示例提示词进入 ADK 仓库根目录使用 ADK CLI 运行示例adk run contributing/samples/integrations/data_agentCLI 进入交互模式后即可提问。原文档给出的四组示例提示词覆盖了查列表 → 查详情 → 有状态追问 → 创建资源的完整链路List accessible data agents.—— 列出可访问的 Data AgentUsing agent projects/my-project/locations/global/dataAgents/sales-agent-123, who were my top 3 customers last quarter?—— 指定 Agent 做具体分析How does that compare to the quarter before?——无需重复指定 Agent直接追问上一季度对比有状态会话的体现Create a new data agent named my-new-agent.—— 触发create_data_agent写操作需已开启修改开关。九、测试验证行为契约有据可依仓库在 tests/unittests/tools/data_agent/ 提供了两层测试Toolset 层test_data_agent_toolset.py断言默认装配 3 个只读工具、开启修改后装配 6 个、tool_filter白名单过滤、未知工具名被忽略、修改未开启时写工具即使列入 filter 也不出现工具函数层test_data_agent_tool.pymockget_gda_session/get_gda_endpoint验证list_accessible_data_agents的请求 URL/v1/projects/{project}/locations/{location}/dataAgents:listAccessible、请求头X-Goog-API-Client: GOOGLE_ADK以及异常路径返回ERROR字典等行为。这些测试同时是学习工具契约参数、返回结构、错误格式的绝佳参考。十、小结google.adk.tools.data_agent将 Gemini Conversational Analytics 的 Data Agent 能力封装为 6 个第一方工具通过DataAgentToolset统一装配并复用 ADK 的 Google 凭据体系默认只读安全只有显式设置enable_data_agent_modificationTrue才会暴露创建/更新/删除能力ask_data_agent天然支持有状态多轮追问返回结构包含思考、SQL、数据与最终回答配合max_query_result_rows控制数据量结合自定义generate_chartAltair vl-convert可将查询结果直接渲染为图表 artifact形成自然语言提问 → 数据分析 → 可视化的完整闭环上述所有行为均有源码与测试佐证可放心在此基础上扩展你的数据问答 Agent。【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考