# Class LittleGhost::Workflow

Documentation version: Edge

Canonical HTML: https://littleghostai.org/docs/LittleGhost/Workflow.html

Coordinates Assembly participants with ordinary Ruby control flow.

A workflow is an Assembly whose `perform` method controls ordering, branching,
parallel work, and local variables. Each participant may be an Agent or
another coordinated Assembly. The workflow selects one participant result or
returns a value computed from intermediate answers.

A support workflow can guarantee that research happens before the responder
writes the caller-visible answer:

    class ResponseWorkflow < LittleGhost::Workflow
      private

      def perform
        evidence = invoke(ResearchAgent).output
        invoke CustomerSupportAgent, input: <<~PROMPT
          #{input.text}

          Research:
          #{evidence}
        PROMPT
      end
    end

    run = ResponseWorkflow.ask("Why is transfer 481 pending?")
    run.response
    # One possible response: Transfer 481 is waiting for the receiving bank.

Call a named Workflow with [ask](Assembly.md#method-c-ask) for its
final Run, or the streaming
[entrypoint](Assembly.md#method-c-stream_ask) for live events.

`invoke` returns a lazy Workflow::Invocation. Reading `result` runs the child
and returns its RunResult; `output` returns RunResult#output. Repeated reads
reuse the completed result. Return an invocation to select its conversation,
state, and structured result as the workflow answer, or return a String or
JSON-compatible value computed in Ruby. Every step contributes usage.

All participating Agents publish live `:agent_stream` progress to
the owning Run, regardless of how results are accessed. Selecting a result
does not replay its progress. Applications choose which sources to show the
caller; see Run for how to identify participants and choose which data to
share.

A child receives the Workflow input unless `invoke` supplies another one. It
also inherits history, settings, cancellation, deadline, template paths, and
the parent tracing relationship. JSON-like context is copied for each child,
preventing one intermediate Agent from mutating a sibling's state.
Non-JSON-like workflow context raises ArgumentError.

A Workflow instance streams once. Returning `nil`, an unsupported value, an
invocation owned by another workflow, or a failed invocation raises
ProtocolError. A composition error fails the owning top-level Run. Each child
Assembly closes after its attempt, and a cleanup failure raises from that
attempt.

## Inheritance

`LittleGhost::Workflow < LittleGhost::Assembly`

## Attributes

<a id="attribute-i-run"></a>
### `run` (R)

Run that owns this run-scoped Workflow.

<a id="attribute-i-runtime"></a>
### `runtime` (R)

Runtime used to resolve child Assemblies.

## Instance methods

<a id="method-i-close"></a>
### `#close`

```ruby
#close()
```

Closes all declared invocations in reverse order.

The operation is idempotent, attempts every close, and raises the first
cleanup failure.

<a id="method-i-prompt_locals"></a>
### `#prompt_locals`

```ruby
#prompt_locals()
```

Additional prompt locals shared by agents invoked from the workflow.
Subclasses may override this hook.

<a id="method-i-stream"></a>
### `#stream`

```ruby
#stream(input = nil,
      history: nil,
      context: nil,
      cancellation_token: Support::CancellationToken.new,
      deadline: nil,
      settings: nil,
      template_locals: nil,
      template_paths: nil,
      parent_operation_id: nil,
      checkpoint: nil)
```

Streams the workflow once as StreamEvent objects.

`perform` may return an invocation owned by this workflow, a String, or a
JSON-compatible value. The final `:invocation_stop` contains the
selected or computed result; it does not replay text events. A selected
invocation runs only if it has not started, and checkpoints its conversation
and state. Usage includes every workflow step. Cancellation and deadlines are
checked before child execution and final publication. The returned Enumerator
is lazy, but calling `stream` reserves the single-use instance before
enumeration starts.
