Dynamic agent delegation

Overview

Import path: from veadk.tools.builtin_tools.create_agent import CreateAgentToolset CreateAgentToolset is a built-in toolset that lets a main agent collect available resources at runtime, create one or more sub-agents on demand, and transfer control to a chosen sub-agent through the Google ADK transfer_to_agent event. The sub-agent continues in the same session context and produces the final answer. The toolset exposes two tools:

Tool	Purpose
`collect_resources`	Collects skills, knowledge bases, and VeADK built-in tools available to the current account, and searches the public Skill Hub using task keywords provided by the main agent. Returns a resource catalog and a `collection_id`.
`create_agents`	Creates sub-agents from the `collection_id` returned by `collect_resources` and blueprints designed by the main agent, registers them as sub-agents of the current agent, and transfers control to the agent named by `handoff_to`.

Resources returned by collect_resources are candidates only and are not mounted automatically. The main agent must explicitly include each resource ref it wants to use in the resources list of every LLM node; when relevant skills are present in the catalog, at least one must be bound.

When to use

Use this toolset when:

A main agent needs to assemble sub-agents with specific skills, knowledge bases, or tools on demand, rather than fixing the sub-agent structure at development time.
You need to hand off a task to a dynamically created sub-agent within the same session context, where the sub-agent produces the final answer directly.
You need to match resources from the public Skill Hub, account Skill Spaces, knowledge bases, and built-in tools against a task.

It is not suitable when you require a strict, fixed orchestration topology — in that case declare a static sub-agent tree at development time.

Prerequisites

Before use:

Configure the API key for the main agent’s reasoning model.
To collect account-level AgentKit Skill Center skills or knowledge bases, configure Volcengine AK / SK or an STS temporary credential (use BYTEPLUS_ACCESS_KEY and friends in BytePlus mode). Public Skill Hub search does not require credentials.
create_agents must run within an agent invocation driven by a Runner, otherwise it cannot register sub-agents and complete the handoff.

The public Skill Hub search is driven by keywords generated by the main agent from the task; no Space ID is required. Once AK/SK or STS credentials are configured, the AgentKit Skill Center automatically enumerates every Skill Space visible to the account. SKILL_SPACE_ID only narrows the search to a specific Space, with multiple IDs separated by commas. SKILL_HUB_SPACE_ID is retained for compatibility with legacy Skill Hub Spaces.

Environment variable	Default	Description
`MODEL_AGENT_API_KEY`	—	API key for the main agent’s reasoning model.
`VOLCENGINE_ACCESS_KEY`	—	Volcengine AccessKey, used to enumerate account skills and knowledge bases.
`VOLCENGINE_SECRET_KEY`	—	Volcengine SecretKey.
`VOLCENGINE_SESSION_TOKEN`	—	Volcengine STS temporary credential token, required when using STS.
`BYTEPLUS_ACCESS_KEY`	—	AccessKey in BytePlus mode.
`BYTEPLUS_SECRET_KEY`	—	SecretKey in BytePlus mode.
`BYTEPLUS_SESSION_TOKEN`	—	STS temporary credential token in BytePlus mode.
`CLOUD_PROVIDER`	`volcengine`	Cloud provider; set to `byteplus` to use BytePlus credentials and endpoints.
`SKILL_SPACE_ID`	—	Restricts AgentKit Skill Center search to the specified Space, comma-separated for multiple.
`SKILL_HUB_SPACE_ID`	—	Restricts search to legacy Skill Hub Spaces, comma-separated for multiple.
`AGENTKIT_TOOL_REGION`	Provider default region	Specifies the AgentKit control-plane region.
`VEADK_STUDIO_PROJECT`	—	Project used for knowledge-base enumeration; usually pre-set in the Studio environment.

Usage

Add a CreateAgentToolset() instance to the Agent tools list. Describe the resource-collection, blueprint-design, and handoff flow in the agent instruction; the model decides at runtime when to call the two tools.

dynamic_agent_coordinator.py

import asyncio

from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.create_agent import CreateAgentToolset

create_agent = CreateAgentToolset()

agent = Agent(
    name="dynamic_agent_coordinator",
    model_name="doubao-seed-2-1-pro-260628",
    description="A coordinator that assembles experts on demand and delegates execution.",
    instruction="""
You are a dynamic agent coordinator.

For greetings, introductions, or capability questions, answer directly without creating sub-agents.

For tasks that require retrieval, specialized skills, knowledge bases, tool calls, or authoring Python tools:
1. First call collect_resources, deriving 2 to 5 short Skill Hub search keywords from the user's task and passing them via skill_hub_keywords.
2. Design the minimum number of sub-agents from the returned resource catalog. Explicitly include each skill, knowledge base, and built-in tool ref you need in the resources list of the corresponding LLM node.
3. Call create_agents, specifying in handoff_to the agent that should actually complete the user's task.
4. create_agents transfers the task directly to that agent; do not repeat the answer yourself.
""",
    tools=[create_agent],
)

runner = Runner(agent=agent, short_term_memory=ShortTermMemory())


async def main():
    response = await runner.run("Search and summarize the latest public AgentKit materials, giving three conclusions and sources.")
    print(response)


if __name__ == "__main__":
    asyncio.run(main())

Resource collection and matching

By default collect_resources gathers resources from the following sources and unifies them into a candidate catalog with a ref:

Source	Resource type	ref form	Credential
Public Skill Hub search	skill	`skill_hub:<slug>`	None
Account Skill Spaces	skill	`<space_id>:<skill_id>`	AK/SK or STS
AgentKit knowledge bases	knowledge base	`agentkit_kb:<knowledge_id>`	AK/SK or STS
VeADK built-in tools	tool	`veadk_tool:<tool_name>`	None

The collection_id returned after collection must be passed unchanged to the subsequent create_agents call to associate the resource snapshot.

Agent blueprints

The agents argument of create_agents is a list of blueprints, each describing one independently constructed root agent:

Field	Type	Required	Description
`name`	`str`	Yes	Agent name, matching `[A-Za-z_][A-Za-z0-9_]*`, unique within the batch.
`task`	`str`	Yes	Description of the task the agent must complete.
`root_node`	`str`	Yes	The node id used as the entry point.
`nodes`	`list[node]`	Yes	Node list, at least one; node ids are unique within a blueprint.

Nodes inside a blueprint support the following types, with availability depending on the installed Google ADK version:

Node type	Description	Key fields
`llm`	Model-driven leaf node carrying skills, knowledge bases, and tools	`instruction`, `resources`, `python_tools`, `model_name`
`sequential`	Runs children in sequence	`children`
`parallel`	Runs children in parallel	`children`
`loop`	Runs children in a loop	`children`, `max_iterations` (default 3)
`workflow`	DAG-based workflow orchestration	`edges`, `max_concurrency`

The workflow node is available only on Google ADK 2.0.0 and above. On lower versions, the capability catalog returned by collect_resources indicates the supported node types, and create_agents omits workflow nodes.

LLM node

The LLM node is the most common leaf node. Its fields are:

Field	Type	Default	Description
`id`	`str`	—	Node id, matching `[A-Za-z_][A-Za-z0-9_]*`, unique within the blueprint.
`type`	`"llm"`	—	Fixed to `llm`.
`description`	`str`	`""`	Node description.
`instruction`	`str`	—	System instruction for the node; should include a clear goal, output format, and completion criteria.
`model_name`	`str \| list[str] \| None`	`None`	Model used by the node; inherits the main agent’s model when empty.
`model_provider`	`str \| None`	`None`	Model provider.
`model_api_base`	`str \| None`	`None`	Model API base URL.
`resources`	`list[str]`	`[]`	Resource refs to mount; must come from the `collect_resources` return value.
`python_tools`	`list[PythonToolSpec]`	`[]`	Trusted Python tools authored by the main agent, separate from built-in tools in `resources`.

Ad-hoc Python tools

The main agent can provide complete Python source in the python_tools of an LLM node, exposed as tools callable by the sub-agent:

Field	Type	Default	Description
`name`	`str`	—	Tool name, matching `[A-Za-z_][A-Za-z0-9_]*`.
`description`	`str`	—	Tool description, used by the model to decide when to call it.
`code`	`str`	—	Complete Python source defining the callable.
`entrypoint`	`str \| None`	`None`	Callable to expose; defaults to `name` when omitted.
`dependencies`	`list[str]`	`[]`	Python requirements to verify, e.g. `pandas>=2`; missing packages are reported and never installed.

Code in python_tools runs as the main agent in the current process without sandboxing. Only accept code from trusted sources, and avoid letting untrusted input become executable source directly.

Parameters

Constructor parameters of CreateAgentToolset:

Parameter	Type	Default	Description
`skill_source_ids`	`str \| Sequence[str] \| None`	`None`	Narrows skill search to the specified Spaces. ids starting with `sp-` are treated as Skill Hub Spaces and the rest as AgentKit Skill Spaces; when empty, `SKILL_HUB_SPACE_ID` and `SKILL_SPACE_ID` are read.
`resource_sources`	`Sequence[ResourceSource] \| None`	Default sources	Custom resource source list; when omitted, the four default sources for skills, knowledge bases, and built-in tools are used.
`capabilities`	`AgentCapabilities \| None`	Auto-detected	Specifies runtime capabilities; when omitted, supported node types are detected from the installed Google ADK version.
`resource_store`	`ResourceStore \| None`	New instance	Custom resource snapshot store; when omitted, an in-process store keeps only the latest snapshot per session.
`skill_cache_dir`	`Path \| None`	`None`	Skill materialization cache directory.
`leaf_factory`	`Callable \| None`	Default factory	Custom LLM-node builder to replace the default leaf-agent creation logic.
`knowledge_factory`	`Callable \| None`	Default factory	Custom knowledge-base mounter to replace the default VikingDB knowledge-base construction logic.

Limitations

create_agents must run within an active agent invocation driven by a Runner, otherwise it cannot register sub-agents and complete the handoff.
Within a session, each collect_resources call overwrites the previous resource snapshot, and create_agents consumes the matching snapshot, after which it is no longer valid.
Dynamically created sub-agents are registered in the agent tree of the current session and are not retained after the session ends.
python_tools run in the current process without sandbox isolation.

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

Deployment

Overview

When to use

Prerequisites

Usage

Resource collection and matching

Agent blueprints

LLM node

Ad-hoc Python tools

Parameters

Limitations

​Overview

​When to use

​Prerequisites

​Usage

​Resource collection and matching

​Agent blueprints

​LLM node

​Ad-hoc Python tools

​Parameters

​Limitations

Overview

When to use

Prerequisites

Usage

Resource collection and matching

Agent blueprints

LLM node

Ad-hoc Python tools

Parameters

Limitations