# `GenAgent.Response`
[🔗](https://github.com/genagent/gen_agent/blob/v0.7.0/lib/gen_agent/response.ex#L1)

The result of a completed prompt turn, delivered to `c:GenAgent.handle_response/3`.

A `Response` is built by the state machine after a terminal event
(`:result` or `:error`) arrives from the backend. It carries:

  * `:text` -- the full assembled assistant text for the turn.
  * `:final_message` -- the terminal text when provided, otherwise the
    last boundary-marked assistant message (or all text if no boundary
    was marked). This remains available when compact retention omits
    the text events. Manually constructed responses leave it `nil`.
  * `:events` -- retained normalized events in arrival order. Check
    `:event_coverage` before treating this as a complete log.
  * `:terminal` -- the original terminal result event, even if compact
    retention omitted it from `:events`.
  * `:event_coverage` -- counts and the first omission reason for the
    retained log. `mode: :exact` means no event was omitted.
  * `:usage` -- token usage if the backend reported any, otherwise `nil`.
  * `:duration_ms` -- wall-clock time from prompt dispatch to terminal event.
  * `:metadata` -- additive application or orchestration results, defaulting to `%{}`.
  * `:session_id` -- the backend's session identifier, if any.

# `t`

```elixir
@type t() :: %GenAgent.Response{
  duration_ms: non_neg_integer(),
  event_coverage: map(),
  events: [GenAgent.Event.t()],
  final_message: String.t() | nil,
  metadata: map(),
  session_id: String.t() | nil,
  terminal: GenAgent.Event.t() | nil,
  text: String.t(),
  usage: map() | nil
}
```

# `from_events`

```elixir
@spec from_events([GenAgent.Event.t()], keyword()) :: t()
```

Build a `Response` from a completed turn's event list and wall-clock duration.

The `events` list must include exactly one terminal event (`:result` or
`:error`). Text is taken from the `:result` event's `:text` field if
present, otherwise assembled from any `:text` deltas. Deltas concatenate
directly; a text event with `message_boundary: true` starts a separate
assistant message after a blank line. `:final_message` selects the terminal
text when present, otherwise the last boundary-marked message. Usage is
taken from the most recent `:usage` event, if any.

---

*Consult [api-reference.md](api-reference.md) for complete listing*