Epics & Tasks¶

Epics and tasks form Pipelit's multi-agent delegation system. An epic is a high-level objective that gets decomposed into individual tasks, each of which can be executed by a separate workflow. This enables a main orchestrator agent to plan, delegate, track, and budget complex multi-step operations.

Overview¶

flowchart TB
    MainAgent["Main Agent\n(orchestrator)"] -->|creates| Epic
    MainAgent -->|decomposes into| T1[Task 1]
    MainAgent -->|decomposes into| T2[Task 2]
    MainAgent -->|decomposes into| T3[Task 3]
    T2 -->|depends_on| T1
    T3 -->|depends_on| T1

    T1 -->|spawn_and_await| W1["Child Workflow A"]
    T2 -->|spawn_and_await| W2["Child Workflow B"]
    T3 -->|spawn_and_await| W3["Child Workflow C"]

    W1 -->|result| T1
    W2 -->|result| T2
    W3 -->|result| T3

The pattern works as follows:

1. A main agent receives a complex objective
2. It creates an epic to represent the objective
3. It decomposes the epic into tasks with dependencies
4. Each task is executed by spawning a child workflow via spawn_and_await
5. Results flow back, costs are tracked, and the epic status updates automatically

Epics¶

An epic is a high-level objective that groups related tasks. It carries metadata for tracking progress, managing budgets, and recording outcomes.

Epic fields¶

Epic lifecycle¶

stateDiagram-v2
    [*] --> planning
    planning --> active : start work
    active --> paused : pause
    paused --> active : resume
    active --> completed : all tasks done
    active --> failed : unrecoverable error
    active --> cancelled : user cancels
    planning --> cancelled : user cancels
    paused --> cancelled : user cancels
    completed --> [*]
    failed --> [*]
    cancelled --> [*]

Cost tracking on epics¶

Epics track spending at two levels:

• Task-level costs (spent_tokens, spent_usd): Rolled up from the actual_tokens and actual_usd fields of all tasks in the epic.
• Agent overhead (agent_overhead_tokens, agent_overhead_usd): Tokens consumed by the orchestrator agent itself (planning, reasoning, tool calls) as distinct from child workflow execution.

Budget enforcement is checked before every node execution. See Cost Tracking for details.

Tasks¶

A task is an individual work item within an epic. Tasks have dependencies, lifecycle tracking, cost accounting, and can be linked to workflow executions.

Task fields¶

Task lifecycle¶

stateDiagram-v2
    [*] --> pending
    [*] --> blocked : has unfinished dependencies
    blocked --> pending : dependencies completed
    pending --> running : execution starts
    running --> completed : success
    running --> failed : error
    failed --> pending : retry
    pending --> cancelled : cancelled
    blocked --> cancelled : cancelled
    running --> cancelled : cancelled
    completed --> [*]
    cancelled --> [*]

Multi-agent delegation¶

The delegation pattern connects epic/task management with Pipelit's workflow execution engine through the spawn_and_await tool.

sequenceDiagram
    participant Main as Main Agent
    participant Epic as Epic Tools
    participant Task as Task Tools
    participant Spawn as spawn_and_await
    participant Child as Child Workflow

    Main->>Epic: create_epic(title, budget)
    Epic-->>Main: epic_id

    Main->>Task: create_task(epic_id, title, depends_on)
    Task-->>Main: task_id (status: pending)

    Main->>Task: update_task(task_id, status: running)
    Main->>Spawn: spawn_and_await(workflow_slug, task_id)

    Note over Main: Agent pauses (LangGraph interrupt)

    Spawn->>Child: Execute child workflow
    Child-->>Spawn: Result + cost data

    Note over Main: Agent resumes

    Spawn-->>Main: Child output (JSON)

    Note over Main: Orchestrator syncs costs to task and epic

    Main->>Task: update_task(task_id, status: completed, result_summary)
    Main->>Epic: update_epic(epic_id, status: completed)

spawn_and_await¶

The spawn_and_await tool is how an agent launches a child workflow and waits for its result:

1. The agent calls spawn_and_await(workflow_slug, input_text, task_id)
2. LangGraph's interrupt() pauses the agent at the tool-call boundary
3. The orchestrator spawns the child workflow execution
4. When the child completes, the orchestrator resumes the parent with the child's output
5. If the child fails, a ToolException is raised so the agent can handle the error

Cost synchronization¶

When a child execution completes, the orchestrator automatically:

1. Copies token counts and USD cost from the execution to the linked task
2. Recalculates the epic's spent_tokens and spent_usd by summing all task costs
3. Records llm_calls and tool_invocations on the task

This ensures the epic always reflects the true total cost across all child executions without double-counting.

Tool components¶

epic_tools¶

The epic_tools component provides four LangChain tools for agents:

task_tools¶

The task_tools component provides four LangChain tools for agents:

Connecting tools to an agent¶

On the workflow canvas, connect epic_tools and task_tools nodes to an agent via the tools handle (green diamond). You will typically also connect spawn_and_await so the agent can delegate tasks to child workflows.

flowchart LR
    Trigger[Chat Trigger] --> Agent
    Model[AI Model] -.->|model| Agent
    ET[epic_tools] -.->|tool| Agent
    TT[task_tools] -.->|tool| Agent
    SA[spawn_and_await] -.->|tool| Agent

WebSocket events¶

Epic and task mutations broadcast real-time events over the global WebSocket:

What's next?¶

• Understand how costs are tracked and budgets enforced: Cost Tracking
• Learn about agent capabilities: Agents
• See how workflows are scheduled: Scheduler