Self-improving AI Employees for everyone
Agent-to-Agent Delegation (Nested Agents)
Team-lead contract: Orchestrator and AI Employee models do not call
delegate_to_*directly. They create durable work through the intrinsictask_manager(assign_task)interface described in agent_teams.md. Delegate names below are internal dispatch identities or legacy/non-team-lead compatibility mechanics.
How memory, parameters, and execution context flow when one AI agent delegates work to another agent connected as a tool.
Related docs: tool_building_pipeline.md for the underlying
_build_tool_from_node+execute_toolpipeline that backsdelegate_to_*(delegation tools use the same provider-neutralAgentToolSpec/ToolDefconstruction path as other AI tools — what makes them special is the fire-and-forget background task and the{"status": "delegated"}lifecycle opt-out documented there).
Overview
AI Agents can delegate tasks to other agents connected to their input-tools handle. The parent agent's LLM decides when to call the child agent by invoking a delegate_to_<agent> tool.
Two execution paths depending on whether the parent is running under Temporal F4.B:
- F4.B (default,
TEMPORAL_AGENT_WORKFLOW_ENABLED=true): Task Manager assignment persists first, thenAgentWorkflowstarts a detachedDelegatedTaskWorkflowwithParentClosePolicy.ABANDONand immediately returnsqueuedto the lead. The runner owns the root-wide permit, task claim, childAgentWorkflow, compact result/usage persistence,taskTrigger, and permit release. The LLM's{task, context}args travel aschild_context["invocation"];prepare_agent_payloadapplies them after stored config resolution, so saved defaults cannot override the mission. Parent identity still travels inparent_node_idfor status mirroring. Completion starts a separately scoped lead review instead of blocking the assigning invocation — see TEMPORAL_ARCHITECTURE.md §F4.B. - Legacy / F4.A-only: the rest of this doc.
_execute_delegated_agentspawns the child as an independentasyncio.Taskand the parent continues working immediately — the fire-and-forget pattern. Applies the same task/context semantics by overwritingchild_paramsAFTER loading them from the DB. Still the path forrlm_agent/claude_code_agent(excluded fromAGENT_WORKFLOW_TYPES) and any deployment with F4.B disabled.
In both paths the parent passes only a task string and optional context string — per-invocation input that always wins over stored configuration. Everything else -- the child's provider, model, memory, skills, and tools -- comes from the child's own configuration and workflow connections.
Generation Stop/Resume ownership
The F4.B path has two lifetimes. Direct non-team delegation starts an attached
AgentWorkflow child and collects its result through the existing child
handle. Task Manager assignment starts a detached DelegatedTaskWorkflow
runner with ParentClosePolicy.ABANDON; the runner can outlive the assigning
lead and owns its attached agent child, permit, and terminal bookkeeping.
Native parent discovery alone cannot find the runner after the lead closes.
For new execution_control_version=1 generations, every detached runner
enrolls with the existing generation controller through an acknowledged Update
before admitting business work. The maintenance Activity/client bridge returns
current pause/revision/hold posture so a late runner cannot bypass Stop.
Attached agent children inherit the scope and require no separate registration.
The controller's independent-root map and membership epoch survive rollover;
control checks the execution chain while addressing the current Workflow ID.
Stop closes admission throughout the discovered topology before waiting for admitted Activities and result bookkeeping to drain. A child-start gate counts only until start acknowledgement, enabling reliable native enumeration. A parent waiting for child completion or a runner waiting for a subagent permit does not hold the local drain count; its child is acknowledged separately. Stopped children therefore do not deadlock a parent's checkpoint. Completion persistence and permit cleanup for work already completed still run normally. No task is cancelled or re-queued merely because its generation is stopped.
Resume publishes a newer revision with producers held, releases descendants and registered roots, reconciles membership, and releases controller/local/schedule producers. It uses existing handles and pending continuations rather than creating replacement runners or repeating completed tools. Pending task events remain queued for later processing. Agent continuation carries prepared configuration and bindings; rollover is deferred while child handles or Task Manager tasks remain live.
The stronger guarantee is limited to version 1 Temporal generations. It does
not turn process-local asyncio.Task delegation inside an opaque node into
independent Temporal roots. Claude Code and RLM nodes remain
whole-Activity boundaries; their internal calls may continue until that
Activity settles. Unlimited LLM retries can delay complete Stop acknowledgement,
and ambiguous external effects remain subject to tool retries/idempotency.
See Temporal workflow control and
Agent continuation.
Architecture
Parent Agent (chatAgent / aiAgent / specialized)
|
| LLM calls: delegate_to_ai_agent(task="...", context="...")
|
v
tool_executor callback (closure in ai.py)
| Injects: ai_service, database, nodes, edges, workflow_id,
| parent_node_id, execution_id
|
v
execute_tool() dispatcher (handlers/tools.py)
| Routes node_type in AI_AGENT_TYPES to _execute_delegated_agent()
|
v
_execute_delegated_agent() (handlers/tools.py)
| 1. Fetches child_params from DATABASE
| 2. Injects API key + default model from credential store
| 3. task -> system_message (directive),
| context-or-task -> prompt
| 4. Builds child_context with all nodes/edges
| 5. Spawns asyncio.create_task()
| 6. Returns immediately: {status: "delegated", task_id: "..."}
|
v v
Parent continues reasoning Child runs independently
(non-blocking) |
v
plugin_cls().execute(child_node_id, child_params, child_ctx)
| (BaseNode.execute -> the agent plugin's
| @Operation method in nodes/agent/<plugin>/)
|
collect_agent_connections(child_node_id)
| (services/plugin/edge_walker.py)
| Filters edges by child's ID
| Finds child's own memory/skills/tools/task
|
AIService.execute_agent() / execute_chat_agent()
| Uses child's provider/model
| Uses child's memory (isolated session)
| Uses child's skills + tools
| system_message = delegated task,
| prompt = delegated context
|
Result broadcast via WebSocket
(NOT returned to parent LLM)
The Delegation Chain (7 Steps)
Step 1: Parent Builds Tool from Child Agent Node
File: server/services/ai.py, _build_tool_from_node()
When the parent agent starts executing and finds a child agent connected to its input-tools handle, _build_tool_from_node() is called during tool setup:
for tool_info in tool_data:
tool, config = await self._build_tool_from_node(tool_info)
tools.append(tool)
tool_configs[tool.name] = config
For agent node types, the method:
Resolves the tool name via
_resolve_default_tool_name_description(node_type)— a closure inside_build_tool_from_node()that reads the plugin class'stool_nameClassVar (each agent plugin declarestool_name = "delegate_to_<x>"). There is no centralDEFAULT_TOOL_NAMESdict; the name comes from the plugin class viaservices.node_registry.get_node_class. The delegation branch is gated by_get_tool_schema()'s_AGENT_DELEGATION_TYPEStuple inservices/ai.py, which mirrors the authoritativeAI_AGENT_TYPESfrozenset inserver/constants.py. Thetool_name = f"delegate_to_{cls.type}"default is stamped byBaseNode.__init_subclass__inservices/plugin/base.py;aiAgentandchatAgentdeclare their names explicitly.Creates a
DelegateToAgentSchemaPydantic model in_get_tool_schema()with two fields (task-> the child's mission directive / system message,context-> the child's input data / prompt):class DelegateToAgentSchema(BaseModel): task: str = Field( description=f"The mission directive for '{agent_label}'. ..." ) context: Optional[str] = Field( default=None, description="Input data or specific details the agent needs to work with, ..." )Returns a config dict:
config = { 'node_type': node_type, # e.g., 'aiAgent' 'node_id': node_id, # child's node ID 'parameters': node_params, # child's stored params (from tool_info) 'label': node_label, 'connected_services': [] }
The LLM sees a tool like delegate_to_ai_agent(task="...", context="..."). It does NOT see or fill the child's actual configuration (provider, model, temperature, etc.).
Step 2: Tool Executor Callback Injects Services
File: server/services/ai.py, tool_executor / chat_tool_executor closures
Both execute_agent() and execute_chat_agent() define nearly identical tool executor callbacks as closures. When the parent's LLM decides to call the delegation tool, the callback fires.
The callback captures from outer scope:
| Variable | Source | Purpose |
|---|---|---|
tool_configs |
Built in step 1 | Maps tool name to config dict |
self |
AIService instance | Provides .database, .auth |
broadcaster |
Function parameter | WebSocket status broadcasts |
workflow_id |
Function parameter | Scopes broadcasts to workflow |
context |
Function parameter | Contains nodes and edges arrays |
Before calling execute_tool(), the callback injects the service + graph fields into the config:
config["workflow_id"] = workflow_id
config["ai_service"] = self # AIService instance (shared)
config["database"] = self.database # Database instance (shared)
config["parent_node_id"] = node_id # parent's node id (duplicate tracking)
if context:
config["nodes"] = context.get("nodes", []) # ALL workflow nodes
config["edges"] = context.get("edges", []) # ALL workflow edges
config["workspace_dir"] = context.get("workspace_dir", "")
config["execution_id"] = context.get("execution_id") # stable per-run id
These injected fields are what enable the child agent to discover its own connections and execute independently. Without them, the child would have no access to the workflow graph or services.
Step 3: Dispatch to Delegation Handler
File: server/services/handlers/tools.py, execute_tool()
The dispatcher checks node_type against the AI_AGENT_TYPES frozenset (server/constants.py) and routes every agent type to _execute_delegated_agent():
from constants import AI_AGENT_TYPES
if node_type == "_builtin_check_delegated_tasks":
return await _execute_check_delegated_tasks(tool_args, config)
if node_type in AI_AGENT_TYPES:
return await _execute_delegated_agent(tool_args, config)
AI_AGENT_TYPES in server/constants.py is the single source of truth for standard delegatable agents and the CLI/REPL agents that bypass the standard loop.
Step 4: Delegated Agent Execution (Fire-and-Forget)
File: server/services/handlers/tools.py, _execute_delegated_agent()
This is where the actual parameter assembly happens.
4a. Extract injected services from config:
ai_service = config.get("ai_service")
database = config.get("database")
nodes = config.get("nodes", [])
edges = config.get("edges", [])
workflow_id = config.get("workflow_id")
A (parent_node_id, node_id, task_hash) duplicate guard (_active_delegations) short-circuits with status: "ALREADY_DELEGATED" if the LLM calls the same delegation twice. A per-child counter (_active_delegated_nodes) keeps the child's canvas glow alive past the parent run's end (the background task outlives the delegate_to_<x> tool return).
4b. Fetch child's OWN parameters from database:
child_params = await database.get_node_parameters(node_id) or {}
The child's stored parameters (provider, model, temperature, etc.) come from the database -- whatever the user configured in the child node's parameter panel. They are NOT inherited from the parent. The stored system_message and prompt are loaded here too, but step 4e overwrites both with the delegated task / context.
4c. Inject API key if missing:
if not child_params.get("api_key"):
provider = detect_ai_provider(node_type, child_params)
key = await ai_service.auth.get_api_key(provider, "default")
if key:
child_params["api_key"] = key
The child gets its API key from the credential store based on its own provider setting. If the child is configured for Anthropic and the parent uses OpenAI, the child gets the Anthropic key.
4d. Inject default model if not set:
if not child_params.get("model"):
provider = detect_ai_provider(node_type, child_params)
models = await ai_service.auth.get_stored_models(provider, "default")
if models:
child_params["model"] = models[0]
4e. Map the delegated task/context onto the child's params:
# task -> mission directive (system message), context -> input data (prompt)
child_params["system_message"] = task_description
child_params.pop("systemMessage", None) # drop pre-migration camelCase mirror
child_params["prompt"] = task_context if task_context else task_description
These two strings are the only inputs the parent passes to the child. task becomes the child's system_message (its mission directive); context becomes its prompt (its input data), falling back to the task text when no context is given. Everything else comes from the child's own stored configuration.
4f. Build child execution context:
child_context = {
"nodes": nodes, # ALL workflow nodes (not just child's)
"edges": edges, # ALL workflow edges (not just child's)
"workflow_id": workflow_id, # Parent's workflow ID (for status scoping)
"outputs": {}, # Empty -- child starts fresh
"parent_task_id": task_id, # Link back to parent's delegation task
"execution_id": config.get("execution_id"), # shared per-run id (session-keyed tools)
}
4g. Spawn as background task and return immediately:
task = asyncio.create_task(run_child_agent())
_delegated_tasks[task_id] = task
return {
"success": True,
"status": "delegated",
"task_id": task_id,
"agent_node_id": node_id,
"agent_name": agent_label,
"message": f"Task delegated to '{agent_label}'. Agent is now working independently...",
}
Inside run_child_agent(), the child executes through its own plugin class (Wave 11.E.3 — the legacy handle_ai_agent / handle_chat_agent imports are gone). Every agent type owns an @Operation method that wraps prepare_agent_call + AIService dispatch, so delegation just goes through BaseNode.execute:
from services.node_registry import get_node_class
from services.plugin import NodeContext
plugin_cls = get_node_class(node_type)
instance = plugin_cls()
child_ctx = NodeContext.from_legacy(
node_id=node_id, node_type=node_type, context=child_context,
)
result = await instance.execute(node_id, child_params, child_ctx)
Step 5: Child Handler Collects Its Own Connections
File: server/nodes/agent/_inline.py, prepare_agent_call() (called by every agent plugin's @Operation)
The spawned child's execute() runs prepare_agent_call(), which calls collect_agent_connections() (from server/services/plugin/edge_walker.py) with its own node_id. The function returns a 5-tuple — (context_data, skill_data, tool_data, input_data, task_data) (edge_walker.py:181-199; the first element is the Context descriptor, or the legacy Memory descriptor on input-memory graphs):
context_data, skill_data, tool_data, input_data, task_data = await collect_agent_connections(
node_id, # CHILD's node ID
child_context, # Contains ALL nodes/edges
database,
log_prefix="[AI Agent]",
)
Step 6: Connection Filtering by Node ID
File: server/services/plugin/edge_walker.py, collect_agent_connections()
This function receives ALL nodes/edges but filters by the child's node_id:
for edge in edges:
if edge.get("target") != node_id: # Only edges pointing TO this child
continue
target_handle = edge.get("targetHandle")
source_node_id = edge.get("source")
For each matching edge, it checks the target handle:
| Handle | Action |
|---|---|
input-context |
Resolves the child's Context thread (RFC-0002). Memory is now an ordinary tool on input-tools. |
input-skill |
Loads skill instructions; expands masterSkill into individual enabled skills |
input-tools |
Discovers directly connected tool nodes, including Android services |
input-main / input-chat |
Reads upstream node output for auto-prompt fallback |
input-task |
Collects taskTrigger output for the conversational task-report pattern |
The child only gets connections that are physically wired to it in the workflow graph. If the child has no Context node connected, context_data is None (and it runs without stored conversation history). If the child has its own tools — including a simpleMemory tool node — it gets those tools -- and can delegate further.
Step 7: Child Executes with Its Own Resources
File: server/services/ai.py, execute_agent() / execute_chat_agent()
The child now executes with:
| Resource | Source |
|---|---|
| Prompt | Delegated context from parent's LLM (falls back to task) |
| System message | Delegated task from parent's LLM (replaces the child's stored system message) |
| Provider / model | Child's own (from its DB params) |
| API key | Injected from credential store based on child's provider |
| Temperature / max tokens | Child's own (from its DB params) |
| Memory | Child's own connected simpleMemory node (if any) |
| Skills | Child's own connected skill nodes (if any) |
| Tools | Child's own connected tool nodes (if any) |
The child's result is broadcast to the UI via WebSocket but is NOT fed back into the parent's reasoning loop.
Memory Isolation
Parent and child agents have completely separate memory systems. On current
(V2) graphs the child's conversation is its own RFC-0002 Context store row,
keyed by (workflow_id, generation, <child agent_node_id>), and simpleMemory
is an explicit tool the child calls on its own input-tools; the table below
describes the legacy markdown model, which survives only for graphs recorded
with an input-memory edge:
| Aspect | Parent Agent | Child Agent |
|---|---|---|
| Memory source | Parent's connected simpleMemory | Child's connected simpleMemory |
| Session ID | From parent's memory node params | From child's memory node params |
| Memory content | Parent's conversation markdown | Child's conversation markdown |
| Vector store | _memory_vector_stores[parent_session] |
_memory_vector_stores[child_session] |
| Memory updates | Parent appends its own exchanges | Child appends its own exchanges |
| Shared? | No -- completely isolated | No -- completely isolated |
If the child has no memory node connected, it has no conversation history and executes statelessly with just the delegated task prompt.
Parameter Flow Summary
What the parent passes to the child
| Parameter | How it arrives |
|---|---|
task (string) |
Parent's LLM generates it via DelegateToAgentSchema tool call; becomes the child's system_message |
context (optional string) |
Parent's LLM generates it via DelegateToAgentSchema tool call; becomes the child's prompt (falls back to task) |
workflow_id |
Injected by tool_executor callback from parent's execution context |
nodes / edges |
Injected by tool_executor callback -- ALL workflow nodes and edges |
ai_service / database |
Injected by tool_executor callback -- shared instances (by reference) |
What the child gets from its own config
| Parameter | Source |
|---|---|
provider |
Child's DB params (e.g., 'openai', 'anthropic') |
model |
Child's DB params (e.g., 'gpt-4o'), or first stored model as fallback |
temperature |
Child's DB params |
max_tokens / maxTokens |
Child's DB params |
thinkingEnabled / thinkingBudget |
Child's DB params |
api_key |
Credential store, resolved by child's own provider |
| Memory | Child's own connected simpleMemory node |
| Skills | Child's own connected skill nodes |
| Tools | Child's own connected tool nodes |
What the parent does NOT pass
- Provider, model, temperature, max tokens
- The parent's own system message (the child's stored one is replaced by the delegated
taskinstead) - Memory or conversation history
- Skills or skill instructions
- Tool configurations
- API keys
What the Parent Receives Back
Immediate Response (Fire-and-Forget)
The parent LLM receives this immediate response from the tool call:
{
"success": true,
"status": "delegated",
"task_id": "delegated_node123_a1b2c3d4",
"agent_node_id": "child_agent_node_123",
"agent_name": "Research Agent",
"message": "Task delegated to 'Research Agent'. Agent is now working independently..."
}
The parent does NOT wait for the child's result. The child's output is broadcast to the UI via WebSocket (broadcaster.update_node_status).
Optional Blocking Delegation (delegation_wait_seconds)
Callers may opt into a bounded wait for a delegated child result:
- The caller sets
config["delegation_wait_seconds"]on the dispatch config for agent-type tools. _execute_delegated_agentthen awaits the spawned child viawait_for_delegation(asyncio.wait_for(asyncio.shield(task))— a timeout cancels the WAITER, never the child) and returns the child's REAL result as the function result, shaped by_delegation_result_reply.- The reply carries
delegation_lifecycle: True;execute_toolpops it and skips its terminalsuccessbroadcast (the child'srun_child_agentalready owns the terminal status — an awaitederrorresult must not be stomped by asuccessglow). - On timeout the child keeps running in the background and the parent receives the standard
status: "delegated"ack. The parent can retrieve the result throughcheck_delegated_taskson a later turn. An identical re-call after a timeout hits the_active_delegationsdedupe and awaits the existing in-flight task instead of duplicating work. - Absent
delegation_wait_seconds(all native agents), behavior is byte-identical fire-and-forget.
Contract locked by TestDelegationWait (tests/nodes/test_ai_tools.py).
Result Retrieval (check_delegated_tasks Tool)
When a parent agent has delegation tools, a check_delegated_tasks tool is automatically injected. The parent LLM can call this tool to check on child status and retrieve results:
# LLM calls:
check_delegated_tasks(task_ids=["delegated_abc123"])
# Returns:
{
"total_tasks": 1,
"completed": 1,
"running": 0,
"errors": 0,
"tasks": [{
"task_id": "delegated_abc123",
"status": "completed",
"agent_name": "Research Agent",
"result": "The research findings show..."
}]
}
3-Layer Result Storage (Celery AsyncResult / Ray ObjectRef Pattern)
Results are stored in a 3-layer hierarchy for fast access and durability:
| Layer | Storage | Survives Restart | Access Speed |
|---|---|---|---|
| 1 | asyncio.Task in _delegated_tasks |
No | O(1), task.result() |
| 2 | _delegation_results dict |
No | O(1), dict lookup |
| 3 | NodeOutput SQLite table |
Yes | DB query |
Layer 1: Live tasks are tracked in _delegated_tasks. When a task completes, task.result() extracts the return value.
Layer 2: Results are cached in _delegation_results dict immediately after child completion/error. This survives the task cleanup in the finally block.
Layer 3: Results are persisted to the existing NodeOutput table with session_id="delegation_{task_id}". This survives server restarts indefinitely.
# On child completion:
_delegation_results[task_id] = {
"task_id": task_id,
"status": "completed",
"agent_name": agent_label,
"result": result.get('result', {}).get('response', ...),
}
# Persist to NodeOutput table
await database.save_node_output(
node_id=node_id,
session_id=f"delegation_{task_id}",
output_name="delegation_result",
data={...}
)
Auto-Injection Logic
The check_delegated_tasks tool is only injected when the parent has delegation tools:
# In execute_agent() and execute_chat_agent():
if any(name.startswith('delegate_to_') for name in tool_configs):
check_info = {
'node_type': '_builtin_check_delegated_tasks',
'node_id': f'{node_id}_check_tasks',
'parameters': {},
'label': 'Check Delegated Tasks',
}
check_tool, check_config = await self._build_tool_from_node(check_info)
if check_tool:
tools.append(check_tool)
tool_configs[check_tool.name] = check_config
Recursive Delegation
If the child agent has other agents connected to its own input-tools handle, it can delegate further. Each level follows the same pattern:
- Child's
_build_tool_from_node()creates aDelegateToAgentSchematool for the grandchild - Child's
tool_executorcallback injects services and the samenodes/edgesgraph - Grandchild spawns as its own
asyncio.create_task() - Grandchild collects its own connections by filtering edges with its own
node_id
There is no hard recursion limit. Each agent in the chain is memory-isolated and independently configured.
Status Broadcasting
Every delegated agent broadcasts status at key phases via WebSocket:
| Phase | When | Broadcast to |
|---|---|---|
delegated_task |
Child starts executing | Child's node ID |
initializing |
Creating LLM model | Child's node ID |
loading_memory |
Parsing markdown history (legacy input-memory graphs only; not emitted when a Context node resolves) |
Child's node ID |
building_tools |
Converting tool nodes to AgentToolSpec values |
Child's node ID |
invoking_llm |
Calling model | Child's node ID |
executing_tool |
Running a tool called by child's LLM | Tool node ID |
delegated_complete |
Child finishes successfully | Child's node ID |
delegated_error |
Child fails | Child's node ID |
All broadcasts include workflow_id for UI scoping. The frontend uses these to show real-time execution animations on the child agent node.
Key Files
| File | Role |
|---|---|
server/services/ai.py |
_build_tool_from_node(), _get_tool_schema() (incl. _AGENT_DELEGATION_TYPES + DelegateToAgentSchema), _resolve_default_tool_name_description(), tool_executor / chat_tool_executor closures, execute_agent() / execute_chat_agent() |
server/services/plugin/edge_walker.py |
collect_agent_connections() (5-tuple: context / skill / tool / input / task) |
server/nodes/agent/_inline.py |
prepare_agent_call() — the 3-step pre-dispatch flow (connection collection + param prep) every agent plugin's @Operation runs |
server/nodes/agent/<plugin>/__init__.py |
Per-agent plugin classes (ai_agent, chat_agent, the specialized agents) with their delegation tool_name ClassVar + @Operation execute method |
server/services/handlers/tools.py |
execute_tool() dispatcher, _execute_delegated_agent(), _execute_check_delegated_tasks(), _delegated_tasks / _delegation_results / _active_delegations tracking |
server/constants.py |
AI_AGENT_TYPES frozenset, detect_ai_provider() |
client/src/components/AIAgentNode.tsx |
Frontend rendering of execution phase animations |
Key Findings
Only task/context strings flow from parent to child. No other parameters (model, temperature, memory, skills) are inherited.
Child configuration comes from its own database params. Whatever the user set in the child's parameter panel is what the child uses.
Memory is fully isolated. Parent and child have separate simpleMemory nodes with separate session IDs and separate vector stores.
The child sees the full workflow graph via
nodes/edges, butcollect_agent_connections()filters by the child's ownnode_id, so it only gets resources physically connected to it.Services are shared, not duplicated.
ai_serviceanddatabaseare passed by reference. They share the same credential store and DB connection.Delegation is non-blocking.
asyncio.create_task()spawns the child; the parent continues immediately. The child's result is NOT returned to the parent's LLM.Recursive delegation is supported. If the child has agents connected to its own
input-tools, it can delegate further with no hard depth limit.Task Trigger enables workflow-based result handling. The
taskTriggernode fires when delegated tasks complete, allowing workflows to process child agent results.
Event-Driven Task Completion (taskTrigger)
In addition to the check_delegated_tasks tool (LLM-driven result checking), the system provides an event-driven approach via the taskTrigger workflow node. This enables parent workflows to react to child completion without polling.
Architecture
Child Agent completes (success or error)
↓
tools.py: _execute_delegated_agent.run_child_agent()
↓
broadcaster.send_custom_event('task_completed', event_data)
↓
event_waiter dispatch ('task_completed', event_data)
↓
Matching taskTrigger nodes resolve their Futures
↓
Downstream workflow nodes execute with delegation result
Note (Wave 12/13):
taskTriggeris one of the canary-registered trigger types. Under the canary path the producer's CloudEvents envelope routes viadispatch.emit; the legacyevent_waiter.register/send_custom_eventpath is retained for the in-process fallback. See event_framework.md and the trigger-architecture notes in CLAUDE.md.
Event Data Schema
The task_completed event carries:
{
'task_id': str, # e.g., "delegated_abc123_xyz"
'status': str, # 'completed' or 'error'
'agent_name': str, # Label of child agent
'agent_node_id': str, # Node ID of child agent
'parent_node_id': str, # Node ID of parent that delegated
'result': str, # Response text (if completed)
'error': str, # Error message (if error)
'workflow_id': str, # For scoping
}
Filter Options
The taskTrigger node supports filtering to match specific delegation events:
| Filter | Description |
|---|---|
task_id |
Exact match on specific task ID |
agent_name |
Partial match on child agent name |
status_filter |
all, completed, or error |
parent_node_id |
Only trigger for delegations from specific parent |
Usage Example
[Parent Agent] --delegates--> [Research Agent]
↓ (completes)
[task_completed event]
↓
[Task Trigger]
(filters: agent_name="Research")
↓
[Process Results Node]
(uses {{taskTrigger.result}})
Key Files
| File | Changes |
|---|---|
server/services/event_waiter.py |
TriggerConfig, filter builder, FILTER_BUILDERS entry |
server/services/handlers/tools.py |
send_custom_event() calls (success + error paths) |
server/constants.py |
taskTrigger in EVENT_TRIGGER_TYPES, WORKFLOW_TRIGGER_TYPES |
client/src/components/parameterPanel/InputSection.tsx |
Output schema for draggable variables |
LLM-Driven vs Event-Driven vs Agent-Handled
| Approach | Tool/Handle | When to Use |
|---|---|---|
| LLM-Driven | check_delegated_tasks |
Parent LLM decides when to check results and how to process them |
| Event-Driven | taskTrigger |
Workflow automatically reacts to completion, processes via downstream nodes |
| Agent-Handled | input-task handle |
Parent agent receives task result and reports to user conversationally |
All approaches can coexist. The LLM-driven approach is better for dynamic reasoning about results; the event-driven approach is better for deterministic post-processing workflows; the agent-handled approach is best when you want the parent agent to interpret and communicate results naturally.
Agent Task Input Handle (input-task)
All AI agents (aiAgent, chatAgent, and the specialized agents — live count via glob server/nodes/agent/*/__init__.py) have an input-task handle on the left side that can receive task completion events from taskTrigger nodes. This enables a conversational pattern where the parent agent reports delegated task results to the user.
Architecture
[Child Agent] completes
↓
[taskTrigger] fires (filters by agent_name/status)
↓
[Parent Agent] (input-task handle)
↓
Agent generates conversational response about completed task
How It Works
- Backend Detection:
collect_agent_connections()inserver/services/plugin/edge_walker.pydetects nodes connected to theinput-taskhandle and returns the collectedtask_data(5th element of the tuple) - Task Data Collection: Collects output from the connected
taskTriggernode - Context Injection:
prepare_agent_call(server/nodes/agent/_inline.py) callsformat_task_context()(fromedge_walker.py) to rendertask_dataas prompt context - Prompt Prepending: Task context is prepended to the agent's prompt before execution
Task Context Format
When a task completes successfully:
A delegated task has completed:
- Agent: Research Agent
- Task ID: delegated_abc123_xyz
- Status: Completed Successfully
- Result: [child agent's response]
Please report this result to the user in a conversational way.
When a task fails:
A delegated task has failed:
- Agent: Research Agent
- Task ID: delegated_abc123_xyz
- Status: Error
- Error: [error message]
Please report this error to the user and suggest next steps if appropriate.
Key Files
| File | Changes |
|---|---|
client/src/components/AIAgentNode.tsx |
Spec-driven; renders the input-task handle from the backend NodeSpec (no per-agent config map) |
server/services/plugin/edge_walker.py |
task_data collection via collect_agent_connections(), format_task_context() |
server/nodes/agent/_inline.py |
prepare_agent_call() injects the formatted task context into the prompt |
Usage Example
[Parent Agent] ──delegates──> [Research Agent]
↓ (completes)
[Task Trigger]
(filters: agent_name="Research")
↓
[Chat Agent]
(input-task handle)
↓
Generates response:
"The research task has completed!
Here's what was found: ..."
Shared Input/Output Handles (backend SSOT)
Post-Wave-11 the frontend specializedAgentNodes.ts definition file no longer exists — handle topology is declared on the backend plugin classes and the frontend renders it from each NodeSpec via useNodeSpec(type). Every specialized agent subclasses SpecializedAgentBase (server/nodes/agent/_specialized.py), which provides the standard handle set through std_agent_handles() (declared in server/nodes/agent/_handles.py):
- Left:
input-main(Input),input-context(Context),input-task(Task) - Bottom:
input-skill(Skill),input-tools(Tool) - Right:
output-main(Output) - Top:
output-top(Output)
Team-lead agents (orchestrator_agent, ai_employee) add an extra input-teammates handle for delegation. AIAgentNode.tsx is type-agnostic — it reads handles / icon / color / displayName / uiHints straight from the spec, with no AGENT_CONFIGS map.