BeamAgent.State (beam_agent v0.2.0)

Holds the runtime state for a single agent execution.

Internal to a run's lifecycle inside BeamAgent.Runner — not the public result type (that's BeamAgent.Run, built from this via BeamAgent.Run.Builder once the run finishes or fails).

Summary

Types

status()

t()

Functions

add_assistant_message(state, reply)

Appends an assistant reply to the run's context.

add_tool_call(state, tool_call)

Appends the assistant's tool-call message to the run's context.

add_tool_result(state, call_id, result)

Appends a tool result to the run's context, tagged with its call_id.

elapsed_ms(state)

Milliseconds elapsed (monotonic clock) since the state was created.

fail(state, reason)

Marks the state :failed with the given reason.

finish(state, result)

Marks the state :finished with the given result (the model's final reply).

increment_iteration(state)

Increments the loop iteration counter by one.

increment_tool_calls(state)

Increments the tool-call counter by one.

new(goal)

Starts a fresh, :running state for goal.

put_context(state, context)

Replaces the run's context (used after compression).

trace(state, type, payload)

Appends one trace step of type with payload, tagged with the current iteration.

Types

status()

@type status() :: :running | :finished | :failed

t()

@type t() :: %BeamAgent.State{
  context: BeamAgent.Context.t(),
  goal: String.t(),
  iteration: non_neg_integer(),
  result: term() | nil,
  started_at: DateTime.t(),
  started_at_monotonic: integer(),
  status: status(),
  tool_calls: non_neg_integer(),
  trace: [BeamAgent.Trace.Step.t()]
}

Functions

add_assistant_message(state, reply)

@spec add_assistant_message(t(), String.t()) :: t()

Appends an assistant reply to the run's context.

add_tool_call(state, tool_call)

@spec add_tool_call(t(), BeamAgent.LLM.Client.tool_call()) :: t()

Appends the assistant's tool-call message to the run's context.

add_tool_result(state, call_id, result)

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

Appends a tool result to the run's context, tagged with its call_id.

elapsed_ms(state)

@spec elapsed_ms(t()) :: non_neg_integer()

Milliseconds elapsed (monotonic clock) since the state was created.

fail(state, reason)

@spec fail(t(), term()) :: t()

Marks the state :failed with the given reason.

finish(state, result)

@spec finish(t(), String.t()) :: t()

Marks the state :finished with the given result (the model's final reply).

increment_iteration(state)

@spec increment_iteration(t()) :: t()

Increments the loop iteration counter by one.

increment_tool_calls(state)

@spec increment_tool_calls(t()) :: t()

Increments the tool-call counter by one.

new(goal)

@spec new(String.t()) :: t()

Starts a fresh, :running state for goal.

put_context(state, context)

@spec put_context(t(), BeamAgent.Context.t()) :: t()

Replaces the run's context (used after compression).

trace(state, type, payload)

@spec trace(t(), atom(), map()) :: t()

Appends one trace step of type with payload, tagged with the current iteration.