Self-improving AI Employees for everyone
Task Trigger (taskTrigger)
| Field | Value |
|---|---|
| Category | workflow / trigger |
| Backend handler | Plugin server/nodes/trigger/task_trigger/__init__.py (TaskTriggerNode); dispatch via BaseNode.execute(). The base TriggerNode.execute runs the event wait; the @Operation("wait") body is a stub. |
| Tests | server/tests/nodes/test_workflow_triggers.py |
| Skill (if any) | none |
| Dual-purpose tool | no |
Purpose
Fires when a child agent dispatched from a durable Task Manager assignment completes or
errors. The Temporal agent.finish_delegation Activity in
server/services/temporal/agent_activities.py and the legacy coordinator in
server/services/handlers/tools.py persist the task outcome before calling
nodes.agent._events.broadcast_agent_task_completed or
broadcast_agent_task_failed. Both emit a CloudEvents WorkflowEvent
(type: com.opencompany.agent.task.completed, with the success/error
discriminator carried in data.status) via dispatch.emit. taskTrigger is
canary-registered. In controlled deployments its definition and accepted
Signals live in WorkflowControlWorkflow, which filters/queues the event and
starts a child graph per match. A separate TriggerListenerWorkflow remains
the legacy compatibility path. The assigning lead has already returned after
receiving queued. When
the detached runner submits or fails the task, this trigger starts the connected
lead's separate review invocation. The event preserves the owning execution,
so Task Manager reads the original durable task rather than the trigger run.
Inputs (handles)
| Handle | Connection type | Required | Purpose |
|---|---|---|---|
| (none) | - | - | Trigger nodes have no inputs. |
Parameters
| Name | Type | Default | Required | displayOptions.show | Description |
|---|---|---|---|---|---|
task_id |
string | "" |
no | - | If set, only match events with this exact task_id. |
agent_name |
string | "" |
no | - | Case-insensitive substring match against event.agent_name. |
status_filter |
options | all |
no | - | all / completed / error. |
parent_node_id |
string | "" |
no | - | If set, only match events with this exact parent_node_id. |
Outputs (handles)
| Handle | Shape | Description |
|---|---|---|
output-main |
object | The task_completed event payload. |
Output payload
Declared TaskTriggerOutput fields:
{
task_id?: string;
status?: 'completed' | 'error';
agent_name?: string;
result?: string; // Present when status='completed'
error?: string; // Present when status='error'
workflow_id?: string;
}
TaskTriggerOutput is model_config extra="allow", so the producer's extra
fields (agent_node_id, parent_node_id, team_id, execution_id,
root_execution_id, trace_id) pass through to downstream nodes at runtime
even though they are not declared on the model. Wrapped in the standard
envelope.
Logic Flow
flowchart TD
P[Persist terminal task outcome] --> Q[broadcast_agent_task_completed or failed<br/>dispatch.emit com.opencompany.agent.task.completed]
Q --> R[Controlled controller receives on_event Signal]
R --> S[TaskTriggerNode.build_filter<br/>task_id / status / agent_name / parent_node_id]
S -- match --> T[spawn child MachinaWorkflow<br/>trigger pre-executed with event payload]
S -- no match --> R
Decision Logic
TaskTriggerNode.build_filter applies all configured filters as AND:
- task_id: exact match if non-empty.
- agent_name:
agent_name_filter.lower() in event_agent.lower()- substring match, case-insensitive. - status_filter:
completed-> requiresevent.status == 'completed'error-> requiresevent.status == 'error'all(or anything else) -> no status restriction
- parent_node_id: exact match if non-empty.
If any filter rejects, the event is skipped and the waiter stays blocked.
Side Effects
- Database writes: none.
- Broadcasts: the producer emits a CloudEvents
WorkflowEventviadispatch.emit. The controller (or legacy listener) emits firing-pulse status viabroadcast_trigger_status_activityaround each child spawn. - External API calls: none.
- File I/O: none.
- Subprocess: none.
External Dependencies
- Credentials: none.
- Services:
services.deployment(canary listener),services.events.dispatch,services.status_broadcaster. - Upstream dispatchers:
services.temporal.agent_activities.finish_agent_delegationand the legacyservices.handlers.tools._execute_delegated_agentusenodes.agent._eventsafter persisting the outcome. A failed attempt that is requeued does not publish a terminal failure event. - Python packages: stdlib only.
- Environment variables: none.
Edge cases & known limits
agent_nameis a case-insensitive substring match, not an exact match. Two agents named"TwitterAgent"and"TwitterAgentV2"are both matched byagent_name="Twitter".status_filtervalues other thancompleted/errorare treated asall. There is no validation of unknown values.- Waiter has no timeout; if the child agent never dispatches a
task_completedevent (e.g. it is still running or died silently) the trigger blocks until cancelled. - Lead review requires a connected matching trigger path. External consumers may use the event without receiving authority to mutate another team.
- Terminal event IDs are stable (
terminal_event_idwhen supplied, otherwise task ID plus persisted terminal status), so Activity redelivery can use the controller's per-trigger deduplication. This does not fix same-label/type trigger Workflow-ID collisions or guarantee producer delivery before a Signal is accepted.
Related
Stop/Resume: new versioned generations retain accepted completion events while stopped and start the review graph after Resume. Detached delegation runners enroll as independent execution roots, so Stop controls them even after their assigning parent finishes. Safe Apply's producer-only review drain cannot reopen a whole-generation Stop. Signal acceptance is receipt, not completion; producer delivery remains best effort before acceptance. See Workflow control.
Skills using this as a tool: none.
Architecture docs: Event Waiter System, Agent Delegation
Sibling triggers:
chatTrigger,webhookTrigger