Alloy.Middleware behaviour (alloy v0.13.0)

Copy Markdown View Source

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_tool completion
  • :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 as alloy_agent that 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

call_result()

@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()}

hook()

@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

tool_result()

@type tool_result() :: %{content: String.t(), data: map() | nil, is_error: boolean()}

Callbacks

call(hook, t)

@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

run(hook, state)

@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.

run_after_tool_call(state, call, result)

@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.

run_before_tool_call(state, tool_call)

@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.