Interaction Layer and Active Tasks Playbook

Languages: English · 中文

When an agent task takes time, users do not only need the final answer. They need to know what is happening, why the system is waiting, and what they can do next. When the system starts work proactively, the trigger also needs its own owner.

Separate Three Event Types

Event type	Used by	Should contain
Product event	UI, IM, customer-facing service	Stable business status, stage, summary, artifact refs
TriggerFlow signal	Workflow control	Internal event names and payloads that affect flow
RuntimeEvent	Observability / DevTools / logs	Diagnostic facts about request, action, environment, flow

Do not make frontend code depend on raw parser paths, chunk names, or RuntimeEvent payloads. Map runtime facts into product events first.

Minimal Output Layer

AgentExecution / TriggerFlow
  -> runtime stream item
  -> service projection
  -> product event
  -> SSE / WebSocket / IM / notification

The service projection is where internal fields become stable UI contracts.

Product Event Shape

Field	Purpose
event_type	Frontend or IM gateway chooses rendering
task_id	Business task ownership
execution_id	Current run ownership for recovery and debugging
stage	User-readable stage
status	running, waiting, ready, failed, etc.
summary	Short text the user can understand
artifact_ref	Workspace report, screenshot, form, or log reference

Channel Selection

Channel	Fits	Notes
HTTP POST	Short task, final result only	Return structured data or close snapshot
SSE	One-way process stream, report generation, ticket progress, long response	Server owns stream close; clients ignore unknown events
WebSocket	Multi-turn chat or repeated inputs in one connection	Needs session ownership and disconnect recovery
IM gateway	Enterprise chat, email, notification systems	IM is interaction layer, not workflow owner
Worker / Queue	Proactive tasks, batch jobs, async long work	Application persists task, idempotency, and scheduling state

Active Task Boundary

A proactive trigger belongs outside the HTTP request lifecycle:

scheduler / webhook / queue
  -> create business task record
  -> start Agently execution
  -> stream product events
  -> persist final state

The scheduler should not hide prompt logic, and the Agently execution should not own the timer.

Scheduled Daily Report Example

1. Scheduler creates a daily_report task with topic, tenant, and due time.
2. Worker starts a TriggerFlow execution.
3. Flow emits product events: outline_ready, source_selected, section_ready, report_ready.
4. Search/browse/source summaries are stored as Workspace records.
5. Final Markdown/PDF artifact ref is persisted to the business task.
6. IM or email sends a link to the artifact.

Waiting and Resume

When human approval is required:

• TriggerFlow uses pause_for(...).
• Product event exposes approval_required.
• UI/IM shows artifact summary and approval actions.
• Resume endpoint validates user permission and idempotency.
• Execution continues with the resume payload.

Avoid

Misuse	Better shape
Long tasks only show the final result	Emit stage-level product events through runtime stream
Frontend binds to instant parser paths as a long-term protocol	Map them into stable service/product events
Event Center drives product UI	Event Center is observation; UI consumes product events
Scheduler lives inside HTTP request handler	Scheduler / queue / worker owns proactive triggers
No task_id / execution_id / trace_id	The task cannot be recovered or debugged
IM bot decides workflow path by itself	IM is interaction layer; workflow is driven by Agently execution and app state

Launch Check

Check	Passing standard
Process events	Users can see key stages, waits, and failures
Final state	Durable state comes from data / snapshot / Workspace artifact, not temporary patches
Channel separation	UI stream, TriggerFlow signal, and Event Center are not mixed
Proactive trigger	Scheduler / webhook / queue is separate from API request handling
Resume entry	Interrupt id, execution id, resume payload, and idempotency key are traceable
Notification strategy	The task can recover after IM/WebSocket/SSE disconnect
Observability	RuntimeEvent / DevTools / trace can locate model, Action, flow, or environment problems

Continue Reading

• FastAPI Service Exposure
• TriggerFlow Events and Streams
• Pause and Resume
• Long-Running Agent State