# Class LittleGhost::Assembly

Documentation version: Edge

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

Gives one agent or a coordinated group the same callable entrypoint.

An assembly is anything callers can invoke like one Agent. An Agent is the
smallest assembly because it owns one model loop. Workflow, Swarm, and Graph
subclasses coordinate several participants while preserving the same `ask`,
`stream_ask`, `call`, and `stream` interface.

    agent_run = CustomerSupportAgent.ask("Why is my transfer pending?")
    graph_run = SupportFlowGraph.ask("Why is my transfer pending?")

    agent_run.response
    graph_run.response

Applications normally subclass Agent, Workflow, Swarm, or Graph rather than
Assembly directly. Each standalone call returns a top-level Run. Participants
called inside another Assembly return a RunResult to their parent.

## Advanced construction

Named subclasses are the usual form. `to_builder` creates a mutable definition
for applications that discover participants at runtime. `definition` returns
the fixed snapshot used by one execution. Composite results record their steps
in RunResult#trajectory.

## Return values

`CustomerSupportAgent.ask(...)`
:   A named class creates and returns a top-level Run.

`CustomerSupportAgent.new(runtime: runtime).ask(...)`
:   A standalone instance also creates and returns a top-level Run.

`runtime.build_assembly(..., run: run).call(...)`
:   A participant already bound to a Run returns its child RunResult.

`stream_ask(...).each { |event| ... }`
:   A standalone stream returns its top-level Run after enumeration. A
    run-scoped stream ends with an `invocation_stop` event carrying RunResult.

## Inheritance

`LittleGhost::Assembly < Object`

## Attributes

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

The owning Run, or `nil` for a standalone entrypoint.

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

Runtime used to resolve participants and build Runs.

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

Sandbox supplied to this Assembly, when present.

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

Workspace supplied to this Assembly, when present.

## Class methods

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

```ruby
.ask(message, **options)
```

Executes `message` through a fresh standalone assembly and returns its Run.

`options` become Invocation fields. Common values include `history`,
`context`, `settings`, `metadata`, `session_id`, `actor_id`, and
`deadline_at`.

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

```ruby
assembly_id() -> String
assembly_id(value) -> String
```

The stable identifier used for tools and telemetry. Named subclasses derive it
from their underscored class name without their type suffix.

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

```ruby
.assembly_kind()
```

Returns `:agent`, `:workflow`, `:swarm`,
`:graph`, or `:assembly`.

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

```ruby
.definition()
```

Returns an immutable definition for this class.

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

```ruby
description() -> String
description(value) -> String
```

The human-readable description used when exposing the assembly as a tool.

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

```ruby
.stream_ask(message, **options)
```

Lazily streams `message` through a fresh standalone assembly.

Enumeration yields StreamEvent objects and returns the terminal Run. The same
Invocation fields accepted by .ask may be supplied as `options`. Composite
assemblies also emit an `:agent_stream` event for every normalized
event from every Agent in the run, including intermediate and nested
participants. Set `include_agent_events: false` to keep only the
ordinary public stream. A standalone Agent retains its ordinary stream by
default and accepts `true` to opt in.

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

```ruby
.to_builder()
```

Returns a mutable dynamic builder seeded by this class.

## Instance methods

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

```ruby
#as_tool(name: self.class.assembly_id, description: self.class.description, preserve_context: false)
```

Exposes this assembly as a Tool instance.

By default, calls do not remember earlier conversation history. Set
`preserve_context: true` to carry that history from one tool call
to the next. This option does not control working state: every call receives
the invoking Tool's current RunContext#state, which may include current
request values or values restored from a Session. Nested tools must still
authorize privileged work with current, application-established values.

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

```ruby
#ask(message, **options)
```

Runs `message` to completion.

A standalone instance returns its owning Run. A run-scoped instance returns
the child RunResult.

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

```ruby
#call(input = nil, **options)
```

Runs `input` to completion.

A standalone assembly returns a Run. A run-scoped assembly returns its
RunResult.

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

```ruby
#close()
```

Closes resources owned directly by this assembly.

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

```ruby
#interject(message, **options)
```

Adds an interjection to the single active leaf Agent.

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

```ruby
#prompt_locals()
```

Additional prompt locals made available to child agents.

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

```ruby
#start_execution(payload, &event_consumer)
```

Starts `payload` in the background and returns an Execution. Composite
assemblies include contextual `:agent_stream` events in the
consumer by default. Set `include_agent_events` to `false` in `payload` to
keep only the ordinary public stream.

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

```ruby
#stream_ask(message, **options)
```

Lazily streams `message` through the standalone or run-scoped assembly.

A standalone stream returns its terminal Run after enumeration. A run-scoped
stream finishes with an `invocation_stop` event containing its RunResult. A
standalone composite Assembly receives contextual `:agent_stream`
events from every Agent in the Run by default and may set
`include_agent_events: false` to omit them. A standalone Agent may
set the option to `true` to include its contextual wrapper.