Google GenAI SDK `Tool` 类型全解：12 类工具 JSON 结构与 Phoenix 落地实践

• 可观测性
• AI 评测
• LLMOps
• AI 应用
• 人工智能

本文以google-genaiPython SDK 中Tool及其嵌套工具类型的 JSON/dict 形状为骨架，逐一拆解function_declarations、google_search、google_maps、url_context、file_search、code_execution、computer_use、mcp_servers等全部顶层键的实用负载结构，并结合本仓库 Phoenix 的 playground 客户端转换逻辑与集成测试，说明这些工具定义如何在 AI Observability 平台中被规范化、保真回放与执行。读完本文，你将能按 Gemini API / Vertex AI 双面区分正确构造GenerateContentConfig.tools，并理解 Phoenix 中"函数工具（可移植）与原始工具（供应商专属透传）"的双模型设计。

背景：一个Tool对象承载多种可选能力

与 OpenAI 的ToolParam或 Anthropic 的ToolUnionParam不同，Google GenAI SDK 中tools列表的每个元素都是一个Tool对象，其内部包含大量可选键——你只需启用当前场景所需的能力，例如只填function_declarations，或只填google_search。这些工具定义会喂给GenerateContentConfig.tools/tools参数（models.generate_content及其相关 API），在客户端归一化之后随请求发出。

两个关键的类型事实（见 google-genai-tools-illustration.md）：

• 模型与字典一致：请求负载与Tool/ToolDict对齐，即 Pydantic 模型与 TypedDict 共享同一组键。
• ToolListUnion：tools列表的每个元素可以是一个Tool、一个callable（会被包装为函数声明），或在 MCP 扩展可导入时使用 MCP 客户端类型。
• Gemini API 与 Vertex AI 的字段差异：SDK 的字段 docstring 会对每个字段标注支持面（例如"not supported in Gemini API"或"not supported in Vertex AI"）。这是最快的兼容性过滤手段——若某个键标注不支持 Gemini API，就不要把依赖它的功能规划为可移植特性。多个键在同一个Tool中组合在 JSON 语法上合法，但在特定面（surface）上运行时可能失败。

注意：SDK 类型定义随版本演进，行号会移动；升级google-genai后应以你本地安装的google/genai/types.py为准重新核对字段。

Tool顶层键速查表

1.function_declarations— 用户定义函数

FunctionDeclaration是 OpenAPI 风格的函数声明。其中parameters（SDKSchema）与parameters_json_schema互斥；同理response与response_json_schema互斥。

使用 SDK 风格Schema字典的示例（type取值为OBJECT、STRING、INTEGER等枚举风格大写值）：

{ "function_declarations": [ { "name": "get_weather", "description": "Get the current weather for a location.", "parameters": { "type": "OBJECT", "properties": { "city": { "type": "STRING", "description": "City name" }, "unit": { "type": "STRING", "enum": ["celsius", "fahrenheit"] } }, "required": ["city"] } } ] }

使用单对象JSON Schema参数的替代写法（与parameters互斥）：

{ "function_declarations": [ { "name": "register_user", "description": "Register a user.", "parameters_json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" } }, "additionalProperties": false, "required": ["name", "age"], "propertyOrdering": ["name", "age"] } } ] }

可选字段：response/response_json_schema声明输出 schema；behavior（Bidi 场景，按 SDK docstring 可能仅 Vertex 支持）。

实践要点：parameters（枚举风格Schema）与parameters_json_schema二选一，二者 API 无法合并；输出 schema（response*）用于让下游解析器直接获得类型化工具输出，无需第二次模型调用。

Phoenix 侧印证：在 playground_clients.py 的_google_prepare_generate_content中，Phoenix 把规范化函数工具转换为types.FunctionDeclaration，且优先使用parameters_json_schema传递参数 JSON Schema，与本文上述第二种写法完全一致；转换后的声明被聚合进单个types.Tool(function_declarations=...)追加到工具列表。

2.google_search— 模型内 Google 搜索

启用搜索能力；省略search_types时默认走网页搜索。嵌套的web_search/image_search是空标记对象（模型定义中为pass）。

{ "google_search": { "search_types": { "web_search": {}, "image_search": {} } } }

默认写法（隐含网页搜索）：

{ "google_search": {} }

可选嵌套字段（并非所有面都支持每个字段，需以 SDK docstring 与 Google 官方文档为准）：blocking_confidence、exclude_domains、time_range_filter（start_time/end_time，ISO 时间格式）。

实践要点：响应会携带groundingMetadata（查询词、网页片段、引用 span），应在 UX 中呈现以增强可信度与可调试性。image_search会切换多模态搜索的成本与延迟；仅需网页搜索默认行为时省略search_types即可。

Phoenix 侧印证：集成测试 test_prompts.py 中的google-genai-built-in-tool用例以genai_types.Tool(google_search=genai_types.GoogleSearch())构造负载，验证了这种"空标记启用"形状在 prompt 版本 round-trip 中完整保真。

3.google_maps— Maps 接地

{ "google_maps": { "enable_widget": true } }

可选auth_config（按 SDK docstring：Gemini API 不支持）。

实践要点：Maps 接地最适合查询中含位置信息的任务（营业时间、导航、"附近"）；enable_widget用于支持交互式地图 UI 的产品。Gemini API 无auth_config时，可假定只能访问公开地图数据。

4.url_context— URL 上下文检索

空负载，出现即启用：

{ "url_context": {} }

实践要点：检查响应的url_context_metadata可确认实际检索了哪些 URL（以及命中缓存还是实时抓取）。与google_search搭配效果佳：模型先发现链接，再对其中少数做深度读取。

5.file_search— 托管 RAG / 文件搜索存储

{ "file_search": { "file_search_store_names": [ "fileSearchStores/my-file-search-store-123" ], "top_k": 8, "metadata_filter": "optional-filter-expression" } }

实践要点：File Search 是托管式 RAG——把分块/嵌入的管道复杂度换成存储与导入的配置成本。metadata_filter用于实现租户或文档类型粒度的范围隔离，无需为每个客户单独建存储。

6.code_execution— 模型代码执行

类型定义中为空对象：

{ "code_execution": {} }

按 SDK docstring：Gemini API 不支持。

实践要点：该字段面向Vertex / AI Studio类面。若你的应用走消费级 Gemini API，应省略code_execution或在运行时探测能力——发送该字段可能导致请求报错。

7.enterprise_web_search— 企业级网页搜索

{ "enterprise_web_search": { "exclude_domains": ["example.com"], "blocking_confidence": "BLOCK_HIGH_AND_ABOVE" } }

按 SDK docstring：Gemini API 不支持。blocking_confidence在 SDK 中使用PhishBlockThreshold。

实践要点：这是 Vertex 上的企业 / Sec4 网页搜索路径，合规与计费模式均不同于消费级 Gemini。exclude_domains是对已知恶意或品牌外域名做滥用控制的简单杠杆。

8.retrieval— Vertex 检索（三分支）

定义 Vertex 风格检索，需从vertex_ai_search、vertex_rag_store、external_api中选择其一（每种在types.py中都有各自嵌套形状）。

最小占位写法：

{ "retrieval": { "vertex_ai_search": {} } }

按 SDK docstring：Gemini API 不支持。

实践要点：vertex_ai_search、vertex_rag_store、external_api是三种不同架构——只选一个分支，并按该路径建模鉴权与延迟预期（不要"三个全填"指望 API 合并）。

9.google_search_retrieval— 动态检索接地

{ "google_search_retrieval": { "dynamic_retrieval_config": { "mode": "MODE_DYNAMIC", "dynamic_threshold": 0.3 } } }

（mode在 SDK 中为DynamicRetrievalConfigMode。）

实践要点：动态检索即"按需搜索"——若模型对琐碎问题过度接地，调高dynamic_threshold；若模型在需要新鲜度的事实性查询上跳过搜索，则调低该阈值。

10.parallel_ai_search— Parallel.ai 搜索

{ "parallel_ai_search": { "api_key": "optional-parallel-ai-key", "custom_configs": { "source_policy": { "include_domains": ["google.com", "wikipedia.org"], "exclude_domains": ["example.com"] }, "fetch_policy": { "max_age_seconds": 3600 } } } }

按 SDK docstring：Gemini API 不支持。

实践要点：需要Parallel.ai凭据与 Vertex 启用，应视为可选的企业集成，而非google_search的默认替代。fetch_policy.max_age_seconds在新鲜度与缓存命中率之间权衡。

11.computer_use— 计算机使用

environment使用Environment枚举（例如ENVIRONMENT_BROWSER）。

{ "computer_use": { "environment": "ENVIRONMENT_BROWSER", "excluded_predefined_functions": ["some_predefined_action"] } }

实践要点：启用computer_use会同时注入预定义的 UI 操作函数声明——你的客户端必须实现真正的自动化循环（截图 → 模型 → 动作）。excluded_predefined_functions可从声明面中移除高风险动作（例如支付类）。

12.mcp_servers— 基于 HTTP Streamable 的 MCP

按 SDK docstring：Vertex AI 不支持。

{ "mcp_servers": [ { "name": "my-mcp-server", "streamable_http_transport": { "url": "https://api.example.com/mcp", "headers": { "Authorization": "Bearer token" }, "timeout": "30s", "sse_read_timeout": "60s", "terminate_on_close": true } } ] }

实践要点：Gemini API 上的 MCP 使用HTTP streamable传输——你的服务端必须可靠实现 MCP 协议，超时过短会表现为模型侧工具调用停滞。由于 Vertex AI 在上述 SDK 类型中不支持该键，若同时面向 Gemini API 与 Vertex，必须对Tool负载做分支。

附录 A：ToolType— 服务端工具调用判别枚举

枚举ToolType映射服务端工具种类，例如：

• GOOGLE_SEARCH_WEB/GOOGLE_SEARCH_IMAGE→Tool.google_search
• URL_CONTEXT→Tool.url_context
• GOOGLE_MAPS→Tool.google_maps
• FILE_SEARCH→Tool.file_search

它用于ToolCall/ToolResponse（响应的工具调用判别），而非请求端Tool定义本身。

实践要点：排查"调错工具"时，对比请求Tool键与响应ToolType——服务端执行的工具会以专用枚举值出现，而不是你的function_declarations名称。

附录 B：ToolConfig— 请求级共享配置

ToolConfig/ToolConfigDict的完整形状：

{ "function_calling_config": { "mode": "AUTO", "allowed_function_names": ["get_weather"], "stream_function_call_arguments": false }, "retrieval_config": { "lat_lng": { "latitude": 37.7749, "longitude": -122.4194 }, "language_code": "en-US" }, "include_server_side_tool_invocations": true }

mode为FunctionCallingConfigMode；按 SDK docstring，部分嵌套字段仅 Vertex 支持。

实践要点：function_calling_config作用于请求中的全部工具——allowed_function_names是 demo 与生产 canary 的廉价安全护栏；include_server_side_tool_invocations让你能在响应Content中记录Google 托管的工具步骤，用于审计。

工具选择配置（ToolConfig/function_calling_config）

在 Gemini API 中，函数式工具的选择策略位于tool_config（REST）/ToolConfig（SDK），重点是function_calling_config。它与tools列表互补：tools描述声明，function_calling_config.mode（及相关字段）决定该请求中模型是否可以省略调用、必须调用或遵循其他调用规则。

FunctionCallingConfigMode枚举包含AUTO、ANY、NONE、VALIDATED等取值。

实践要点：模式对整个请求是全局的——若需按工具差异化行为，请拆分为多次generate_content调用或收窄allowed_function_names。托管工具（google_search、url_context等）仍会以工具调用形式出现在响应中；将include_server_side_tool_invocations与你的可观测性方案配合使用。

Phoenix 侧印证：在 google.py 中，Phoenix 将规范化的工具选择映射为 Google 的ToolConfig：none → {"mode": "none"}、zero_or_more → {"mode": "auto"}、one_or_more → {"mode": "any"}、specific_function → {"mode": "any", "allowed_function_names": [name]}；反向解析时会把 mode 归一化为小写（Google API 大小写不敏感），且当前仅支持单个allowed_function_names（只能配合any模式使用）。

Phoenix 中的落地：从双模型工具存储到 Google 负载

本文档所述的工具形状在本仓库 Phoenix 中有直接落地，可作深入参考：

双模型：函数工具 vs 原始工具

internal_docs/specs/vendor-specific-tools.md 定义了 Phoenix 的工具数据模型：单个有序列表中混排两类变体——函数工具（归一化、跨供应商可移植的name/description/parameters/strict）与原始工具（供应商专属 JSON 透传值）。其核心原则与本文一致：

• Phoenix 不试图理解每个供应商的 schema；无法无损归一化的工具定义以原始 JSON 保真存储与回放。
• 原始工具不可移植：切换供应商或供应商 API 类型（如 OpenAI Responses → Chat Completions）时会被丢弃，而函数工具保留。
• 原始工具可能含供应商配置，但不应作为凭据存储使用。

运行时转换：_google_prepare_generate_content

在 playground_clients.py 的_google_prepare_generate_content中可以看到完整的转换路径：

• 原始工具：types.Tool.model_validate(tool.raw)直接透传——正是"原始工具不转换、原样发送"的规范实现。
• 函数工具：提取name、description、parameters，以parameters_json_schema构造types.FunctionDeclaration，再聚合为一个types.Tool(function_declarations=...)。
• 关键约束（源码注释明确）：function_calling_config仅当存在function_declarations时才设置——Google 会拒绝将其用于google_search等内置工具。这与本文"function_calling_config作用于函数式工具"的说明互相印证。
• 工具选择映射与 google.py 完全一致：none→NONE、zero_or_more→AUTO、one_or_more→ANY、specific_function→ANY + allowed_function_names。
• 转换完成后，每个FunctionDeclaration会以llm.tools.<idx>.tool.json_schema属性写入 OpenInference span（见同一函数 playground_clients.py），使工具定义对可观测性链路可见。

集成测试验证

tests/integration/client/test_prompts.py 提供了一组 round-trip 参数化用例，直接对应本文形状：

• google-genai-tools-and-config：FunctionDeclaration(name="get_weather", parameters_json_schema={...})+ToolConfig(function_calling_config=FunctionCallingConfig(mode=ANY))+response_mime_type="application/json"+response_json_schema。
• google-genai-tool-choice-none：mode=NONE的"不要调用任何工具"场景。
• google-genai-built-in-tool：Tool(google_search=GoogleSearch())内置工具保真。

测试通过PromptVersion.from_google_genai导入再经 GraphQL / client API round-trip，并用DeepDiff断言负载完全一致，验证了上述所有工具形状在 Phoenix prompt 版本中的无损往返。

小结

• 一个Tool对象、多个可选键——只组合你的 API 面支持的键。
• 用户定义工具→function_declarations（FunctionDeclaration+Schema或parameters_json_schema）。
• 内置工具→google_search、google_maps、url_context、file_search、code_execution等，如上文逐一所述。
• 服务端判别→ 响应中的ToolType枚举；请求级策略→ToolConfig.function_calling_config（全局模式 +allowed_function_names白名单）。
• 兼容性真相源→ 安装包内的google/genai/types.py（docstring 标注 Gemini API / Vertex AI 支持面）；版本升级后需重新核对行号与字段。

推荐实践：当需要不同缓存或计费语义时（例如一个工具 dict 放google_search、另一个放function_declarations），优先使用独立的Tool列表条目，而非难以按面（surface）推理的单一大 dict。在 Phoenix 中，这正对应"函数工具可移植、原始工具按供应商透传、切换供应商时原始工具被丢弃"的既有行为，可结合 vendor-specific-tools.md 与上述源码路径进一步研读。

• 可观测性
• AI 评测
• LLMOps
• AI 应用
• 人工智能