GenAgent.Response (GenAgent v0.8.0)

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

During an agent turn, a Response is built after the backend's terminal :result event and delivered to 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 GenAgent.handle_error/3, and any built Response is discarded. A terminal :error event or a synchronous backend error also dispatches its reason to 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.

Summary

Types

t()

Functions

from_events(events, opts \\ [])

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

Types

t()

@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
}

Functions

from_events(events, opts \\ [])

@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}