BeamAgent.Context (beam_agent v0.2.0)

Copy Markdown View Source

Owns the information sent to the model.

Older messages may be deterministically compressed, but the original goal and optional system prompt are always preserved.

Summary

Types

compression_metadata()
message()
t()

Functions

add_assistant_message(context, content)

Appends an assistant reply.

add_tool_call(context, tool_call)

Appends the assistant's tool-call message.

add_tool_result(context, call_id, result)

Appends a tool result, tagged with the call_id of the tool call it answers (see add_tool_call/2).

add_user_message(context, content)

Appends a user message.

compress(context, opts)

Deterministically compresses context if its rendered message count exceeds opts[:max_messages] (required): the oldest messages are folded into context.summary (capped at opts[:summary_char_limit], default

messages(context)

Renders context into the ordered list of messages sent to the model: optional system prompt, the goal as a user message, the compressed-history summary (if any) as a system message, then the accumulated messages (assistant replies, and tool-call/tool-result pairs correlated by call_id).

new(goal, opts \\ [])

Starts a fresh context for goal, optionally with a :system_prompt.

Types

compression_metadata()

@type compression_metadata() :: %{
  :compressed? => boolean(),
  :before_count => non_neg_integer(),
  :after_count => non_neg_integer(),
  :compressed_messages => non_neg_integer(),
  optional(:summary_chars) => non_neg_integer()
}

message()

@type message() :: %{
  :role => atom(),
  optional(:content) => term(),
  optional(:type) => :tool_call | :tool_result,
  optional(:call_id) => String.t(),
  optional(:name) => atom(),
  optional(:arguments) => map()
}

t()

@type t() :: %BeamAgent.Context{
  goal: String.t(),
  messages: [message()],
  summary: String.t() | nil,
  system_prompt: String.t() | nil
}

Functions

add_assistant_message(context, content)

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

Appends an assistant reply.

add_tool_call(context, tool_call)

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

Appends the assistant's tool-call message.

A real provider first emits a message announcing which tool call it wants (identified by tool_call.id); the matching add_tool_result/3 then carries the same id so the provider can correlate the result back to the request.

add_tool_result(context, call_id, result)

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

Appends a tool result, tagged with the call_id of the tool call it answers (see add_tool_call/2).

add_user_message(context, content)

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

Appends a user message.

compress(context, opts)

@spec compress(
  t(),
  keyword()
) ::
  {:ok, t(), compression_metadata()}
  | {:error, {:context_limit_too_small, map()}}

Deterministically compresses context if its rendered message count exceeds opts[:max_messages] (required): the oldest messages are folded into context.summary (capped at opts[:summary_char_limit], default

  1. and dropped from messages. Returns {:ok, context, metadata} (unchanged if under the limit, with metadata.compressed? == false), or {:error, {:context_limit_too_small, %{...}}} if :max_messages is too small to hold the goal + optional system prompt + at least one summary/message slot.

messages(context)

@spec messages(t()) :: [message()]

Renders context into the ordered list of messages sent to the model: optional system prompt, the goal as a user message, the compressed-history summary (if any) as a system message, then the accumulated messages (assistant replies, and tool-call/tool-result pairs correlated by call_id).

new(goal, opts \\ [])

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

Starts a fresh context for goal, optionally with a :system_prompt.