Skip to content

ADK 工具的限制

ADK 的某些内置工具存在特定的联用限制，这可能会影响你在智能体工作流中集成它们的方式。本页详细说明了这些局限性及其推荐的解决方法。

针对 ADK Python v1.15.0 及更低版本的搜索工具

下文所述的限制主要适用于 ADK Python v1.15.0 及更低版本在使用 Google 搜索和 Vertex AI 搜索工具时的场景。从 ADK Python v1.16.0 及更高版本开始，框架已提供内置机制消除了这些限制。

通常情况下，你可以在一个智能体中同时使用多个工具。但是，为了确保模型稳定性，在较低版本中，以下特定的内置工具不能在同一个智能体对象中与其他工具（无论是内置还是自定义）共存。它们必须单独使用：

错误示例

以下这种尝试在单个智能体中整合多个互斥工具的做法是不受支持的：

root_agent = Agent(
    name="RootAgent",
    model="gemini-2.5-flash",
    tools=[custom_function],
    code_executor=BuiltInCodeExecutor() # <-- 报错：不能与常规工具同时配置
)

LlmAgent searchAgent = LlmAgent.builder()
    .model(MODEL_ID)
    .name("SearchAgent")
    .tools(new GoogleSearchTool(), new YourCustomTool()) // <-- 不受支持
    .build();

解决方法 #1: 使用 AgentTool 模式

ADK 已支持PythonJava

解决此类限制的最有效方法是采用“智能体即工具”模式。你可以创建专门的子智能体来封装这些受限工具，然后将子智能体作为工具交给父智能体管理。

from google.adk.tools.agent_tool import AgentTool
from google.adk.agents import Agent
from google.adk.tools import google_search
from google.adk.code_executors import BuiltInCodeExecutor

# 专门负责搜索的智能体
search_agent = Agent(
    model='gemini-2.0-flash',
    name='SearchAgent',
    tools=[google_search],
)

# 专门负责代码执行的智能体
coding_agent = Agent(
    model='gemini-2.0-flash',
    name='CodeAgent',
    code_executor=BuiltInCodeExecutor(),
)

# 根智能体通过 AgentTool 统一调度
root_agent = Agent(
    name="RootAgent",
    model="gemini-2.0-flash",
    tools=[AgentTool(agent=search_agent), AgentTool(agent=coding_agent)],
)

// 定义核心逻辑
LlmAgent searchAgent = LlmAgent.builder()
    .name("SearchAgent")
    .tools(new GoogleSearchTool())
    .build();

LlmAgent codingAgent = LlmAgent.builder()
    .name("CodeAgent")
    .tools(new BuiltInCodeExecutionTool())
    .build();

// 在根智能体中使用 AgentTool.create() 包装
BaseAgent rootAgent = LlmAgent.builder()
    .name("RootAgent")
    .tools(
        AgentTool.create(searchAgent),
        AgentTool.create(codingAgent)
    )
    .build();

解决方法 #2: 开启 bypass_multi_tools_limit 标志

ADK 已支持PythonJava

在 ADK Python 中，对于 GoogleSearchTool 和 VertexAiSearchTool，你可以显式设置 bypass_multi_tools_limit=True 来绕过此限制。你可以参考 built_in_multi_tools 示例了解详细配置。

关于子智能体 (Sub-agent) 的局限性

请注意，内置工具通常不能在受控的“子智能体”中直接使用（除非是上述已通过解决方法处理的情况）。

以下场景在当前架构下是不受支持的：

# 错误：将使用了代码执行器的智能体直接放在 sub_agents 列表中
root_agent = Agent(
    name="RootAgent",
    sub_agents=[url_context_agent, coding_agent_with_executor] # <-- 不受支持
)

LlmAgent rootAgent = LlmAgent.builder()
    .name("RootAgent")
    .subAgents(searchAgent, codingAgent) // <-- 不受支持，因为子智能体包含了内置专用工具
    .build();