ExAgent.Compaction behaviour (ExAgent v0.4.0)

Copy Markdown View Source

Behaviour for shrinking a conversation history when it grows too large, so a long-running session stays within a model's context window.

A compactor takes the current [Message.t()] and returns either a compacted list, {:no_change} (leave it alone), or an error. The built-in ExAgent.Compaction.Summary replaces older messages with an LLM-generated summary while keeping the most recent ones verbatim.

Compaction is wired into a run as a capability (see ExAgent.Compaction.Capability) that fires on the before_model_request hook. That keeps it opt-in and composable with other capabilities.

Summary

Types

messages()
opts()

Callbacks

compact(messages, opts)

Functions

estimate_tokens(messages)

A rough token estimate for a message history: total characters of all text content, divided by 4. Good enough to decide when to compact; it intentionally over-estimates slightly so compaction triggers a little early (safe side).

Types

messages()

@type messages() :: [ExAgent.Message.t()]

opts()

@type opts() :: keyword()

Callbacks

compact(messages, opts)

@callback compact(messages(), opts()) ::
  {:ok, messages()} | {:no_change} | {:error, term()}

Functions

estimate_tokens(messages)

@spec estimate_tokens(messages()) :: non_neg_integer()

A rough token estimate for a message history: total characters of all text content, divided by 4. Good enough to decide when to compact; it intentionally over-estimates slightly so compaction triggers a little early (safe side).