AgentTool 子调用工具泄露问题分析

[Flash-LHR]

现象

主 agent 注册了若干外部工具，子 agent 只注册了一个普通工具。

主 agent 通过 AgentTool 调子 agent 时，子 agent 明明只配置了自己的工具，却在模型请求上下文里看到了主 agent 的外部工具。

根因

AgentTool 创建子 invocation 时使用了：

parentInv.Clone(...)

而 Invocation.Clone 会复制父 invocation 的：

RunOptions

父 run 中由 AG-UI 注入的外部工具会进入：

RunOptions.ExternalTools

子 invocation 继承后，LLM flow 又会把这些外部工具追加到子 agent 的模型请求里：

AG-UI input.Tools
  -> RunOptions.ExternalTools
  -> AgentTool parentInv.Clone(...)
  -> child invocation.RunOptions.ExternalTools
  -> LLM flow append tools
  -> 子 agent 看到外部工具

影响范围

父 agent 静态注册工具不受影响，子 invocation 切到子 agent 后，基础工具面来自子 agent 自己的 Tools()。问题范围集中在父 invocation RunOptions 继承下来的工具字段。

受影响字段如下。

字段	影响
ExternalTools	外部工具会进入子 invocation，是本次问题的主链路
AdditionalTools	run 级别追加的外部工具也会进入子 invocation
ExternalToolNames	外部工具的派生状态会进入子 invocation
ToolFilter	父工具过滤器会进入子 invocation，并在子流程工具过滤阶段被使用

源码确认的路径如下。

路径	行为
普通 AgentTool	会继承父 RunOptions，当前没有清理外部工具字段，是本次问题触发点
DynamicTool	会通过 Clone 派生子 invocation，随后清理 AdditionalTools、ExternalTools、ExternalToolNames、ToolFilter
Explorer	会继承父 invocation，随后清理 ExternalTools、ExternalToolNames、ToolFilter，保留 AdditionalTools
Graph AgentNode	会继承父 ExternalTools，测试明确要求 parent external tools 先于 node-scoped external tools 出现在子 invocation
Team	会通过 Clone 派生成员 invocation，继承父 RunOptions
ChainAgent / CycleAgent / ParallelAgent	会通过 Clone 派生子 agent invocation，继承父 RunOptions
transfer_to_agent	会通过 Clone 派生目标 agent invocation，继承父 RunOptions

结论

普通 AgentTool 子调用 clone 了父 invocation 的 RunOptions，但没有清理外部工具面，导致父 run 注入的外部工具暴露给子 agent。

修复建议

方案一 修改默认行为

普通 AgentTool 创建子 invocation 时默认清理父 invocation 继承下来的外部工具字段。

RunOptions.AdditionalTools = nil
RunOptions.ExternalTools = nil
RunOptions.ExternalToolNames = nil
RunOptions.ToolFilter = nil

这个方案可以直接修复所有普通 AgentTool 调用场景，更符合语义直觉。语义上把子 agent 作为独立工具边界，子 agent 默认只看到自己定义的工具。

方案二 新增 option

保持当前默认行为，新增一个 AgentTool option 显式控制外部工具隔离，形式类似已有的 WithPinModel(true)。

示例命名如下。

WithPinExternalTools(true)

开启后清理父 invocation 继承下来的外部工具字段。

RunOptions.AdditionalTools = nil
RunOptions.ExternalTools = nil
RunOptions.ExternalToolNames = nil
RunOptions.ToolFilter = nil

这个方案兼容性更稳，调用方可以逐个 AgentTool 启用隔离。

回归测试

至少补三类测试：

1. 父 invocation 有 ExternalTools，子 agent 模型请求不应看到。
2. 父 invocation 有 AdditionalTools，子 agent 模型请求不应看到。
3. 父 invocation 有 ToolFilter，不应误过滤子 agent 自身工具。

[Flash-LHR]

本质问题是一次 Run 传入的 RunOption 的作用范围没有定义清楚。

RunOption 进入 AgentTool、transfer_to_agent、Graph node、Team、Swarm 时，哪些配置继续生效需要定义清楚。

本次问题暴露在工具面字段上。当前行为下，Invocation.Clone 会复制整份 RunOptions，相关字段会随之进入新的执行上下文。

字段	含义
ExternalTools	调用方代执行的工具
AdditionalTools	本次运行追加的工具
ToolFilter	本次运行使用的工具过滤器

下面几个片段能说明需要定义的语义边界。

AgentTool

child := llmagent.New(childName)
parent := llmagent.New(
	parentName,
	llmagent.WithTools([]tool.Tool{agenttool.NewTool(child)}),
)
r := runner.NewRunner(appName, parent)

r.Run(ctx, userID, sessionID, input,
	agent.WithExternalTools([]tool.Tool{requestTool}),
)

当前行为，AgentTool 创建子 agent 执行上下文时会 clone 父 RunOptions。requestTool 会进入 child 的模型请求，ToolFilter 也会继续影响 child 的工具面。

transfer_to_agent

target := llmagent.New(targetName)
source := llmagent.New(
	sourceName,
	llmagent.WithSubAgents([]agent.Agent{target}),
)
r := runner.NewRunner(appName, source)

r.Run(ctx, userID, sessionID, input,
	agent.WithExternalTools([]tool.Tool{requestTool}),
)

当前行为，transfer_to_agent 创建 target 执行上下文时会 clone source RunOptions。requestTool 会继续出现在 target 的模型请求里。

Graph node

sg.AddAgentNode(
	childName,
	graph.WithAgentNodeRunOptions(
		agent.WithExternalTools([]tool.Tool{nodeTool}),
	),
)

r.Run(ctx, userID, sessionID, input,
	agent.WithExternalTools([]tool.Tool{requestTool}),
)

当前行为，AgentNode 会从父 RunOptions 起步，再叠加 WithAgentNodeRunOptions。requestTool 和 nodeTool 都会进入子 agent 执行上下文。

递归 AgentNode

childGraph.AddAgentNode(
	leafName,
	graph.WithAgentNodeRunOptions(
		agent.WithExternalTools([]tool.Tool{leafNodeTool}),
	),
)

rootGraph.AddAgentNode(
	childGraphName,
	graph.WithAgentNodeRunOptions(
		agent.WithExternalTools([]tool.Tool{rootNodeTool}),
	),
)

r.Run(ctx, userID, sessionID, input,
	agent.WithExternalTools([]tool.Tool{requestTool}),
)

当前行为，rootGraph 的 AgentNode 会把顶层 requestTool 带入 childGraph，再叠加 rootNodeTool。childGraph 内部的 AgentNode 继续基于父 RunOptions 构造 leaf 执行上下文，因此 requestTool、rootNodeTool、leafNodeTool 都会进入 leaf 侧的工具面。

Team

coordinator := llmagent.New(coordinatorName)
member := llmagent.New(memberName)
tm, _ := team.New(coordinator, []agent.Agent{member})
r := runner.NewRunner(appName, tm)

r.Run(ctx, userID, sessionID, input,
	agent.WithExternalTools([]tool.Tool{requestTool}),
)

当前行为，requestTool 会进入 coordinator 的模型请求。coordinator 调用 member 时，member 通过 AgentTool 运行，也会继承这组 run-scoped 工具字段。

Swarm

entry := llmagent.New(entryName)
next := llmagent.New(nextName)
swarm, _ := team.NewSwarm(
	teamName,
	entryName,
	[]agent.Agent{entry, next},
)
r := runner.NewRunner(appName, swarm)

r.Run(ctx, userID, sessionID, input,
	agent.WithExternalTools([]tool.Tool{requestToolA}),
)

当前行为，首轮 start member 继承本次 Run 的 requestToolA。发生 handoff 时，target member 通过 transfer_to_agent 继续继承 requestToolA。

讨论点

上面的例子可以拆成下面几个讨论点。

场景	讨论点
AgentTool	requestTool 是否进入 child
transfer_to_agent	requestTool 是否进入 target
Graph node	child 在看到 nodeTool 的同时，是否继续看到 requestTool
递归 AgentNode	leaf 在看到 leafNodeTool 的同时，是否继续看到上层的 requestTool 和 rootNodeTool
Team	requestTool 是否从 coordinator 继续进入 member
Swarm	requestToolA 是否从 start member 继续进入 handoff target

[Flash-LHR]

#2220 只修复普通 AgentTool