Behaviour for middleware that wraps the agent loop.
Middleware runs at defined hook points:
:before_completion- Prepare request inputs before the provider call; list preparation before compaction:after_completion- Finalize a normal answer or successful:stop_after_toolcompletion:after_compaction- After context compaction occurs (only fires when messages changed):after_tool_request- After provider response with :tool_use (gates tool execution):after_tool_execution- After tools have been executed:before_tool_call- Compose argument edits and policy checks before execution:after_tool_call- Replace each result's content/data before publication:on_context_overflow- Shrink messages after the provider rejects the context; retry once:on_error- When an error occurs:session_start,:session_end- Not fired by the loop; reserved for runtimes such asalloy_agentthat wrap it in a process
Middleware runs in list order and should return the state unchanged for
hooks it does not handle (def call(_hook, state), do: state), since
new hooks may be added.
Compaction
Alloy.Context.Compactor is middleware: it compacts on
:before_completion when the history nears the context budget, and
forces compaction on :on_context_overflow. Alloy.run/2 puts it last
so it budgets the prepared inputs, unless you pass compaction: false
or list it yourself to choose its position.
Summary
Callbacks
Called at the specified hook point. Returns modified state,
{:block, reason} for :before_tool_call to prevent execution,
or {:halt, reason} to stop the entire agent loop immediately.
Functions
Runs all middleware for a given hook point.
Runs :after_tool_call before publishing each tool outcome.
Runs :before_tool_call middleware for a single tool call.
Types
@type call_result() :: Alloy.Agent.State.t() | {:block, String.t()} | {:halt, String.t()} | {:halt, String.t(), Alloy.Agent.State.t()} | {:edit, map()} | {:result, tool_result()}
@type hook() ::
:before_completion
| :after_completion
| :after_compaction
| :after_tool_request
| :after_tool_execution
| :on_context_overflow
| :on_error
| :before_tool_call
| :after_tool_call
| :session_start
| :session_end
Callbacks
@callback call(hook(), Alloy.Agent.State.t()) :: call_result()
Called at the specified hook point. Returns modified state,
{:block, reason} for :before_tool_call to prevent execution,
or {:halt, reason} to stop the entire agent loop immediately.
A halted run keeps the changes earlier middleware made to the state in
that hook (for example, compaction and the usage of its summary
request). Return {:halt, reason, state} to halt with changes of your
own. :before_tool_call is the exception: it decides about one tool
call and never changes the loop's state, so a halt there keeps the
state as it was before the hook.
Functions
@spec run(hook(), Alloy.Agent.State.t()) :: Alloy.Agent.State.t() | {:halted, String.t()}
Runs all middleware for a given hook point.
Middleware can return {:halt, reason} to stop processing immediately
and mark the agent as halted. Returns either the final state or
{:halted, reason} tuple.
@spec run_after_tool_call(Alloy.Agent.State.t(), map(), tool_result()) :: tool_result()
Runs :after_tool_call before publishing each tool outcome.
Context contains :current_tool_call and :current_tool_result with
:content, :data, and :is_error. Return {:result, result} to replace
content and structured data, or the state unchanged. Replacements compose;
they must retain :is_error. State changes are not applied to the loop.
Hook failures abort execution rather than publishing an unredacted result.
@spec run_before_tool_call(Alloy.Agent.State.t(), map()) :: :ok | {:block, String.t()} | {:edit, map()} | {:halted, String.t()}
Runs :before_tool_call middleware for a single tool call.
Injects the tool call into state.config.context[:current_tool_call]
before running middleware. Returns :ok, {:block, reason},
{:edit, modified_call}, or {:halted, reason}.
The {:edit, modified_call} return lets middleware rewrite tool arguments
before execution. The modified call must keep the same :id and :name.
Edits pass the modified call to subsequent middleware. Block and halt stop the chain. State returned from this hook does not alter loop state.