Skip to main content

功能说明

导入路径:from veadk.tools.builtin_tools.create_agent import CreateAgentToolset CreateAgentToolset 是一个内置工具集,让主智能体在运行时收集可用资源、按任务需要创建一个或多个子智能体,并通过 Google ADK 的 transfer_to_agent 把当前任务移交给指定子智能体。子智能体在同一会话上下文中继续执行并直接给出最终回答。 该工具集对外暴露两个工具:
collect_resources 返回的资源是候选清单,不会自动挂载到子智能体。主智能体必须在每个 LLM 节点的 resources 中显式写入需要使用的每个资源 ref;当清单中存在与任务相关的技能时,至少绑定一个技能。

何时使用

适合以下场景:
  • 主智能体需要根据用户任务临时组建具备特定技能、知识库或工具的专家子智能体,而不在开发期固定子智能体结构。
  • 需要在同一会话上下文中把任务移交给动态创建的子智能体,由子智能体直接向用户输出最终结果。
  • 需要从公共 Skill Hub 或账号下的 Skill Space、知识库与内置工具中按任务匹配资源。
不适合需要严格可控、固定编排拓扑的场景——这类场景应直接在开发期声明静态子智能体树。
在 Studio 对话中,如果当前会话已挂载 AIO Sandbox 执行环境,挂载环境的优先级高于动态子智能体创建。智能体应优先使用挂载环境(通过 list_envs、execute_in_sandbox 等工具)完成任务,除非用户明确要求创建或委派新智能体。详见会话沙箱环境。

依赖与前提

使用前请确认:
  1. 主智能体使用的推理模型已配置 API Key。
  2. 如需收集账号下的 AgentKit 技能中心技能或知识库,需配置火山引擎 AK / SK 或 STS 临时凭证(BytePlus 模式使用 BYTEPLUS_ACCESS_KEY 等)。公共 Skill Hub 检索不需要凭证。
  3. create_agents 必须在由 Runner 驱动的智能体调用链中执行,否则无法注册子智能体并完成移交。
公共 Skill Hub 检索由主智能体根据任务生成关键词完成,无需配置 Space ID。配置 AK/SK 或 STS 后,AgentKit 技能中心会自动检索当前账号可访问的全部 Skill Space。SKILL_SPACE_ID 仅用于将检索范围限制到指定 Space,多个 Space ID 用逗号分隔;兼容旧版 Skill Hub Space 时仍可使用 SKILL_HUB_SPACE_ID。

使用方法

把 CreateAgentToolset() 实例加入 Agent 的 tools 列表即可。主智能体在指令中描述资源收集、蓝图设计与移交的流程,运行时由模型自主决定何时调用两个工具。
dynamic_agent_coordinator.py

资源收集与匹配

collect_resources 默认从以下来源收集资源,并将其统一为带 ref 的候选清单: 收集完成后返回的 collection_id 需要在随后调用 create_agents 时原样传入,用于关联本次收集的资源快照。

离线模式

当用户明确禁止检索外部资源但允许模型服务调用时,主智能体可以跳过 collect_resources,直接调用 create_agents 并传入空字符串作为 collection_id。此时每个 LLM 节点的 resources 必须为空列表,子智能体仅使用自身模型能力完成当前任务。离线模式下不会发起 Skill Hub 关键词检索或其他资源源调用。

智能体蓝图

create_agents 的 agents 参数是一个蓝图列表,每个蓝图描述一个独立构建的根智能体: 蓝图内的节点支持以下类型,具体可用类型取决于已安装的 Google ADK 版本:
workflow 节点仅在 Google ADK 2.0.0 及以上版本可用;低版本下 collect_resources 返回的能力清单会标明当前支持的节点类型,create_agents 也会忽略 workflow 节点。

可复用身份与任务分离

蓝图中的 name、节点 id、description 和 instruction 字段应描述可跨请求复用的稳定能力域,而 task 字段是当前一次性任务具体信息的唯一载体。具体而言:
  • name 和 id 使用简洁的 snake_case 能力名,例如 video_creation_agent、document_translation_agent、investment_analysis_agent,不要按本次交付物或研究对象命名。
  • description 和 instruction 描述通用操作,如「调研用户指定的主题」「比较用户指定的候选项」,不硬编码本次任务中的品牌、平台、行业、语言或题材。
  • task 完整保留当前用户的具体目标、对象、输入和交付要求,包括具体的研究对象、行业信息、源语言或目标语言等请求特有内容。
运行时,task 中的任务上下文会自动附加到每个 LLM 节点的指令末尾,子智能体可据此完成当前一次性任务,而无需在 instruction 中重复请求特定的实体。

LLM 节点

LLM 节点是最常用的叶节点,其字段如下:

临时 Python 工具

主智能体可以在 LLM 节点的 python_tools 中提供完整 Python 源码,作为子智能体可调用的工具:
python_tools 中的代码以主智能体身份在当前进程内执行,不经过沙箱隔离。仅应接受受信任源提供的代码,并避免让不可信的输入直接成为可执行源码。小规模、可直接枚举或心算验证的问题优先由子智能体直接推理,不需要创建临时 Python 工具。

参数

CreateAgentToolset 的构造参数:

限制

  • create_agents 必须在由 Runner 驱动的活跃智能体调用中执行,否则无法注册子智能体并完成移交。
  • 每次 collect_resources 的结果只需调用一次 create_agents,并在同一次调用中包含全部所需子智能体;调用完成或设置 handoff_to 后不应再次调用。
  • 同一会话内多次调用 collect_resources 会覆盖同一会话的资源快照;资源快照存储在进程内有界缓存中(最多 128 份),create_agents 读取快照后不会使其失效,同一快照可被具有相同请求指纹的后续调用复用。
  • 动态创建的子智能体不是持久化部署。应用退出时调用 await create_agent.close() 释放资源;同一会话重新收集资源会清理此前注册的子智能体,不应假定关闭聊天页面就已经释放服务连接
  • python_tools 在当前进程内执行,不做沙箱隔离。

调用参数与完成检查

“离线模式”仅指跳过资源收集,不会把云端模型改成本地模型;模型推理仍可能访问网络。严格禁止任何网络访问时,需要另行配置可离线运行的模型与运行环境 每次收集后将所需蓝图一次性提交是推荐调用流程,重复请求的去重行为不意味着只能使用快照一次。新一轮收集会替换当前会话的资源快照;不要保存旧 collection_id 作为长期资源引用 创建结果可能包含部分失败项。检查 results 中各项状态以及是否返回 handoff_to,没有有效移交目标时不能视为任务已开始执行。使用自定义 resource_sources、leaf_factory 或 knowledge_factory 时,其接口需与当前版本相匹配;普通集成保持默认值即可
最后修改于 2026年9月19日