ExAgent.Compaction behaviour (ExAgent v2.1.0)

View Source

Behaviour for reducing the conversation context sent to a model.

A compactor takes the current request projection [Message.t()] and returns 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. It changes only request_messages: the authoritative history remains append-only and new_messages remains its real suffix. Compaction is opt-in and does not guarantee that pinned context fits a provider's context window.

Summary

Types

messages()
opts()

Callbacks

compact(messages, opts)

Functions

estimate_tokens(messages)

A rough context estimate using content bytes / 4 plus message/part overhead.

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 context estimate using content bytes / 4 plus message/part overhead.

Includes instructions, text, thinking/signatures, tool names, arguments, returns and retries. It can under- or over-estimate model tokens, especially for different tokenizers, languages and multimodal content; it is not a usage or billing counter. The built-in capability also includes advertised tool definitions when using this default estimate. Supply :token_counter for a model-specific estimate.