ADK 工具的限制¶
ADK 的某些内置工具存在特定的联用限制，这可能会影响你在智能体工作流中集成它们的方式。本页详细说明了这些局限性及其推荐的解决方法。
针对 ADK Python v1.15.0 及更低版本的搜索工具
下文所述的限制主要适用于 ADK Python v1.15.0 及更低版本在使用 Google 搜索和 Vertex AI 搜索工具时的场景。从 ADK Python v1.16.0 及更高版本开始，框架已提供内置机制消除了这些限制。
此限制仅适用于在 ADK Python v1.15.0 及更低版本中使用 Google 搜索和 Agent Search 工具。ADK Python 版本 v1.16.0 及更高版本提供了内置的解决方法以消除此限制。
- 使用 Gemini API 的代码执行（注意：在 TypeScript 中，这需要 Gemini 2.0+，且不受此限制）
- 使用 Gemini API 的 Google 搜索（注意：限制仅适用于 TypeScript 中的 Gemini 1.x 模型）
- Agent Search（注意：目前在 TypeScript 中不可用）
以下这种尝试在单个智能体中整合多个互斥工具的做法是不受支持的：
import {Agent, BuiltInCodeExecutor} from '@google/adk';
const rootAgent = new Agent({
name: 'RootAgent',
model: 'gemini-flash-latest',
description: 'Code Agent',
tools: [myCustomTool], // Assume myCustomTool is defined
codeExecutor: new BuiltInCodeExecutor(), // <-- NOT supported when used with tools
});
解决方法 #1: 使用 AgentTool 模式¶
Supported in ADKPythonTypeScript (v0.6.1+)Java
解决此类限制的最有效方法是采用“智能体即工具”模式。你可以创建专门的子智能体来封装这些受限工具，然后将子智能体作为工具交给父智能体管理。
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-flash-latest',
name='SearchAgent',
tools=[google_search],
)
# 专门负责代码执行的智能体
coding_agent = Agent(
model='gemini-flash-latest',
name='CodeAgent',
code_executor=BuiltInCodeExecutor(),
)
# 根智能体通过 AgentTool 统一调度
root_agent = Agent(
name="RootAgent",
model="gemini-flash-latest",
description="Root Agent",
tools=[AgentTool(agent=search_agent), AgentTool(agent=coding_agent)],
)
import {Agent, AgentTool, BuiltInCodeExecutor, GOOGLE_SEARCH} from '@google/adk';
const searchAgent = new Agent({
model: 'gemini-flash-latest',
name: 'SearchAgent',
instruction: "You're a specialist in Google Search",
tools: [GOOGLE_SEARCH],
});
const codingAgent = new Agent({
model: 'gemini-flash-latest', // Built-in code execution requires Gemini 2.0+ in ADK JS
name: 'CodeAgent',
instruction: "You're a specialist in Code Execution",
codeExecutor: new BuiltInCodeExecutor(),
});
const rootAgent = new Agent({
name: 'RootAgent',
model: 'gemini-flash-latest',
description: 'Root Agent',
tools: [new AgentTool({agent: searchAgent}), new AgentTool({agent: codingAgent})],
});
// 定义核心逻辑
LlmAgent searchAgent = LlmAgent.builder()
.name("SearchAgent")
.tools(new GoogleSearchTool())
.build();
LlmAgent codingAgent = LlmAgent.builder()
.name("CodeAgent")
.tools(new BuiltInCodeExecutionTool())
.build();
private static final String MODEL_ID = "gemini-flash-latest";
public static void main(String[] args) {
// Define the SearchAgent
LlmAgent searchAgent =
LlmAgent.builder()
.model(MODEL_ID)
.name("SearchAgent")
.instruction("You're a specialist in Google Search")
.tools(new GoogleSearchTool()) // Instantiate GoogleSearchTool
.build();
// Define the CodingAgent
LlmAgent codingAgent =
LlmAgent.builder()
.model(MODEL_ID)
.name("CodeAgent")
.instruction("You're a specialist in Code Execution")
.tools(new BuiltInCodeExecutionTool()) // Instantiate BuiltInCodeExecutionTool
.build();
// Define the RootAgent, which uses AgentTool.create() to wrap SearchAgent and CodingAgent
BaseAgent rootAgent =
LlmAgent.builder()
.name("RootAgent")
.model(MODEL_ID)
.description("Root Agent")
.tools(
AgentTool.create(searchAgent), // Use create method
AgentTool.create(codingAgent) // Use create method
)
.build();
// Note: This sample only demonstrates the agent definitions.
// To run these agents, you'd need to integrate them with a Runner and SessionService,
// similar to the previous examples.
System.out.println("Agents defined successfully:");
System.out.println(" Root Agent: " + rootAgent.name());
System.out.println(" Search Agent (nested): " + searchAgent.name());
System.out.println(" Code Agent (nested): " + codingAgent.name());
}
}
解决方法 #2: 开启 bypass_multi_tools_limit 标志¶
ADK 已支持PythonJava
在 ADK Python 中，对于 GoogleSearchTool 和 VertexAiSearchTool，你可以显式设置 bypass_multi_tools_limit=True 来绕过此限制。你可以参考 built_in_multi_tools 示例了解详细配置。
关于子智能体 (Sub-agent) 的局限性
请注意，内置工具通常不能在受控的“子智能体”中直接使用（除非是上述已通过解决方法处理的情况）。
以下场景在当前架构下是不受支持的：
url_context_agent = Agent(
model='gemini-flash-latest',
name='UrlContextAgent',
instruction="""
You're a specialist in URL Context
""",
tools=[url_context],
)
coding_agent = Agent(
model='gemini-flash-latest',
name='CodeAgent',
instruction="""
You're a specialist in Code Execution
""",
code_executor=BuiltInCodeExecutor(),
)
root_agent = Agent(
name="RootAgent",
model="gemini-flash-latest",
description="Root Agent",
sub_agents=[
url_context_agent,
coding_agent
],
)
import {Agent, BuiltInCodeExecutor} from '@google/adk';
const urlContextAgent = new Agent({
model: 'gemini-flash-latest',
name: 'UrlContextAgent',
instruction: "You're a specialist in URL Context",
tools: [myCustomTool], // Assume myCustomTool is defined
});
const codingAgent = new Agent({
model: 'gemini-flash-latest',
name: 'CodeAgent',
instruction: "You're a specialist in Code Execution",
codeExecutor: new BuiltInCodeExecutor(),
});
const rootAgent = new Agent({
name: 'RootAgent',
model: 'gemini-flash-latest',
description: 'Root Agent',
subAgents: [urlContextAgent, codingAgent], // NOT supported when sub-agents use built-in tools
});
LlmAgent searchAgent =
LlmAgent.builder()
.model("gemini-flash-latest")
.name("SearchAgent")
.instruction("You're a specialist in Google Search")
.tools(new GoogleSearchTool())
.build();
LlmAgent codingAgent =
LlmAgent.builder()
.model("gemini-flash-latest")
.name("CodeAgent")
.instruction("You're a specialist in Code Execution")
.tools(new BuiltInCodeExecutionTool())
.build();
LlmAgent rootAgent =
LlmAgent.builder()
.name("RootAgent")
.model("gemini-flash-latest")
.description("Root Agent")
.subAgents(searchAgent, codingAgent) // Not supported, as the sub agents use built in tools.
.build();