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

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

During an agent turn, a `Response` is built after the backend's terminal
`:result` event and delivered to `c:GenAgent.handle_response/3` when no
checkpoint error was recorded. A checkpoint error takes precedence over a
successful result, backend error, or task crash: its reason is dispatched
to `c:GenAgent.handle_error/3`, and any built `Response` is discarded.
A terminal `:error` event or a synchronous backend error also dispatches its
reason to `c:GenAgent.handle_error/3`; no `Response` is delivered on that path.
`from_events/2` can also build a response outside the agent lifecycle,
including from an event list containing an `:error` event. It carries:

  * `:prompt` -- the prompt actually sent to the backend after `pre_turn/2`
    rewriting. It is `nil` for responses built outside an agent turn.
  * `: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.
  * `:model` -- the model reported on the terminal event, if known.

# `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(),
  model: String.t() | nil,
  prompt: String.t() | nil,
  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.

## Examples

    iex> events = [
    ...>   GenAgent.Event.new(:text, %{text: "hello"}),
    ...>   GenAgent.Event.new(:result, %{text: "hello"})
    ...> ]
    iex> response = GenAgent.Response.from_events(events)
    iex> {response.text, response.final_message, response.event_coverage.mode}
    {"hello", "hello", :exact}

---

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