BeamAgent.Run (beam_agent v0.1.0)

Copy Markdown View Source

Represents a completed outcome of a single agent execution.

This is the struct BeamAgent.API.run/2 hands back on every path — a normal finish, a failed guardrail, a hard timeout, or a runner crash — so callers always get one consistent shape with a full trace to inspect, rather than needing to handle each failure mode differently.

Summary

Types

t()

:execution_status reflects whether the runner itself finished (:finished) or not (:failed); :verification_status reflects the separate, subsequent check of whether the result actually satisfied the goal (:passed, :failed, or :not_run when execution never finished).

Functions

crash(goal, reason)

Builds the Run returned when the runner process itself crashed (e.g. a tool raised) rather than reaching a normal finish or failure. error is {:runner_crashed, reason}, where reason is the process exit reason.

timeout(goal, timeout_ms)

Builds the Run returned when BeamAgent.API.run/2's own hard timeout fires — the runner never replied within timeout_ms and was force -terminated. error is {:execution_timeout, timeout_ms}.

Types

t()

@type t() :: %BeamAgent.Run{
  answer: term() | nil,
  duration_ms: non_neg_integer() | nil,
  error: term() | nil,
  execution_status: :finished | :failed,
  finished_at: DateTime.t(),
  goal: String.t(),
  iterations: non_neg_integer() | nil,
  started_at: DateTime.t() | nil,
  tool_calls: non_neg_integer() | nil,
  trace: [BeamAgent.Trace.Step.t()],
  verification_error: term() | nil,
  verification_status: :passed | :failed | :not_run
}

:execution_status reflects whether the runner itself finished (:finished) or not (:failed); :verification_status reflects the separate, subsequent check of whether the result actually satisfied the goal (:passed, :failed, or :not_run when execution never finished).

Functions

crash(goal, reason)

@spec crash(String.t(), term()) :: t()

Builds the Run returned when the runner process itself crashed (e.g. a tool raised) rather than reaching a normal finish or failure. error is {:runner_crashed, reason}, where reason is the process exit reason.

timeout(goal, timeout_ms)

@spec timeout(String.t(), non_neg_integer()) :: t()

Builds the Run returned when BeamAgent.API.run/2's own hard timeout fires — the runner never replied within timeout_ms and was force -terminated. error is {:execution_timeout, timeout_ms}.