# 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 consumes intermediate answers and
streams one final participant response.

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 `output` consumes an
intermediate invocation and returns RunResult#output; `perform` must return
its final invocation without consuming it so those events reach the caller.
Intermediate usage is added to the final result.

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 the wrong value, returning an
already consumed invocation, or consuming one twice 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` must return a final, unconsumed Workflow::Invocation. The returned
Enumerator is lazy, but calling `stream` reserves the single-use workflow
instance even when enumeration has not started yet.