Workflows
Workflows are Anyy's parent records for grouped background work. A workflow job can own child agent or process jobs, collect completion status, and notify the parent session when the grouped work finishes.
This is not a visual workflow builder. In the current runtime, a workflow is a durable background-job record plus child-job metadata and notification delivery.
Workflow Jobs
A workflow job is stored as a background_jobs record with kind workflow.
It includes:
| Field | Meaning |
|---|---|
background_job_id | Durable parent job handle. |
workflow_job_id | Shared workflow key attached to child jobs. |
session_id / turn_id | Parent session and turn that started the workflow. |
channel_binding_id | Channel binding used for completion delivery when available. |
status | running, succeeded, failed, cancelled, or lost. |
title / summary | User-facing label and completion summary. |
Explicit workflow background turns are started when metadata sets
workflow_background: true or background_mode: workflow.
Background Execution
When a workflow starts, Anyy:
- Saves a durable parent workflow job.
- Spawns an internal child session for the requested task.
- Returns a foreground assistant message saying the workflow is running.
- Marks child work with the parent
workflow_job_id. - Completes the parent job when the child finishes.
Child jobs default to internal visibility so users see one workflow-level completion instead of duplicate child notifications.
References
Workflow background requests preserve context-reference metadata from the user
message. For example, a request containing @file:README.md can carry the
expanded reference metadata into the stored turn and workflow child context.
References remain subject to the same limits and safety checks documented in Context References.
Delivery
When a workflow reaches a terminal state, Anyy writes:
| Destination | Content |
|---|---|
| Session inbox | A pending background update for the parent session's next context build. |
| Job outbox | A channel delivery event when the workflow has a channel binding. |
Completion titles use the parent title plus completed, failed, or
cancelled.
The payload includes source: background_job, background_job_id, job_kind: workflow, job_status, and workflow_job_id.
Inspecting Workflow Jobs
Use the same job surfaces as other background work:
| Surface | Entry point |
|---|---|
| TUI | /jobs, /job <id> |
| RPC | jobs.list, jobs.status |
| Dashboard | Background/runtime views when available through the gateway. |
jobs.status returns child job information for workflow jobs.
Failure Handling
If cancellation happens after the parent job is saved but before child launch, the
parent workflow is marked failed with the cancellation error. If child launch
fails, the parent workflow is also marked failed.
Workflow jobs are session-scoped. If a workflow is not visible, confirm you are looking at the parent session that started it.