# Class LittleGhost::Swarm

Documentation version: Edge

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

Lets configured Agent members hand one request directly to one another.

A swarm is an Assembly for model-selected routing. One member is active at a
time. It either produces the final answer or uses a model-visible handoff tool
to choose one of the next members allowed by the application.

    class ProblemSolverSwarm < LittleGhost::Swarm
      member TriageAgent
      member BillingAgent
      member AccountAgent

      start TriageAgent
      handoff TriageAgent, to: [BillingAgent, AccountAgent]
      max_steps 12
    end

    run = ProblemSolverSwarm.ask("Why was I charged twice?")
    run.response

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

Swarm members are Agent definitions rather than arbitrary assemblies so a
handoff remains a direct model-to-model transition. Original conversation
history and application context stay isolated unless a member opts in with
`history: true` or `context: true`. Streams expose
coordination events and the final member response, but not intermediate model
text.

## Inheritance

`LittleGhost::Swarm < LittleGhost::Assembly`

## Class methods

<a id="method-c-handoff"></a>
### `.handoff`

```ruby
.handoff(from, to:)
```

Restricts one member to the declared handoff targets.

<a id="method-c-max_handoff_repeats"></a>
### `.max_handoff_repeats`

```ruby
.max_handoff_repeats(value = nil)
```

Reads or assigns how often the same directed handoff may repeat.

For example, a value of `2` allows the transition from triage to billing twice
during one Swarm run. `max_steps` still limits total member calls.

<a id="method-c-max_steps"></a>
### `.max_steps`

```ruby
.max_steps(value = nil)
```

Reads or assigns the maximum member executions.

<a id="method-c-member"></a>
### `.member`

```ruby
.member(agent, as: nil, timeout: nil, retries: 0, retry_on: nil, retry_delay: 0,
        history: false, context: false)
```

Declares one Agent member and its optional execution policy.

<a id="method-c-start"></a>
### `.start`

```ruby
.start(member = nil)
```

Reads or assigns the initial Agent member.

<a id="method-c-validate-21"></a>
### `.validate!`

```ruby
.validate!()
```

Validates the members and allowed handoff routes, then returns this class.

## Instance methods

<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, **_options)
```

Streams lifecycle events and only the final member's answer events.