Task Chains¶

Task chains orchestrate multi-step workflows where each step's output feeds into the next. Chains support configurable failure policies, delays between steps, and payload templating.

How It Works¶

flowchart LR
    A[Trigger Action] --> B[Step 1: Search]
    B -->|Output| C[Step 2: Summarize]
    C -->|Output| D[Step 3: Send Email]

    B -.->|Failure| E{Failure Policy}
    E -->|abort| F[Stop Chain]
    E -->|skip| C
    E -->|dlq| G[Dead Letter Queue]

1. An action matching a chain rule triggers the chain
2. The first step executes with the original action's context
3. Each subsequent step receives the previous step's output via template variables
4. On failure, the configured policy determines what happens

Configuration¶

Chain Definition in acteon.toml¶

[[chains]]
name = "search-summarize-email"
on_failure = "abort"
timeout_seconds = 604800        # 7 days

[[chains.steps]]
name = "search"
provider = "search-api"
action_type = "web_search"

[[chains.steps]]
name = "summarize"
provider = "llm"
action_type = "summarize"
delay_seconds = 2               # Wait 2s between steps

[[chains.steps]]
name = "send-email"
provider = "email"
action_type = "send_email"
on_failure = "dlq"              # Per-step failure policy

Rule That Activates the Chain¶

rules:
  - name: research-pipeline
    priority: 5
    condition:
      field: action.action_type
      eq: "research_request"
    action:
      type: chain
      chain_name: "search-summarize-email"

Chain Step Configuration¶

Payload Templates¶

Templates support variable substitution from the chain context:

Example Template¶

[[chains.steps]]
name = "send-email"
provider = "email"
action_type = "send_email"
payload_template = '''
{
  "to": "{{origin.payload.requester_email}}",
  "subject": "Research results for: {{origin.payload.query}}",
  "body": "{{steps.summarize.body.summary}}"
}
'''

Failure Policies¶

Chain-Level Policy¶

Step-Level Policy¶

Chain Lifecycle¶

stateDiagram-v2
    [*] --> Started: Chain triggered
    Started --> Step1: Execute first step
    Step1 --> Step2: Step 1 succeeded
    Step1 --> Failed: Step 1 failed (abort policy)
    Step2 --> Step3: Step 2 succeeded
    Step2 --> Step3: Step 2 failed (skip policy)
    Step3 --> Completed: Step 3 succeeded
    Step3 --> Failed: Step 3 failed (abort policy)
    Completed --> [*]
    Failed --> [*]

Background Execution¶

Chains execute asynchronously via the background processor:

1. The initial action triggers ChainStarted
2. The background processor monitors chain readiness
3. When a step completes (or its delay expires), the next step executes
4. The chain advances until all steps complete or a failure stops it

Response¶

{
  "outcome": "chain_started",
  "chain_id": "chn-abc123",
  "chain_name": "search-summarize-email",
  "total_steps": 3,
  "first_step": "search"
}

Sub-Chains¶

A chain step can invoke another chain by name instead of dispatching to a provider. This enables reusable workflow components — for example, a standard "escalate-and-notify" chain shared across multiple parent chains.

See Sub-Chains for full documentation.

Use Cases¶

Research Pipeline¶

Search → Summarize → Email results:

[[chains]]
name = "research"
[[chains.steps]]
name = "search"
provider = "search-api"
action_type = "search"
[[chains.steps]]
name = "summarize"
provider = "llm"
action_type = "summarize"
[[chains.steps]]
name = "notify"
provider = "email"
action_type = "send_email"

Deployment Pipeline¶

Build → Test → Deploy → Notify:

[[chains]]
name = "deploy"
on_failure = "abort"
[[chains.steps]]
name = "build"
provider = "ci"
action_type = "build"
[[chains.steps]]
name = "test"
provider = "ci"
action_type = "test"
[[chains.steps]]
name = "deploy"
provider = "k8s"
action_type = "deploy"
[[chains.steps]]
name = "notify"
provider = "slack"
action_type = "post_message"
on_failure = "skip"