@callback after_model(Sagents.State.t(), middleware_config()) :: middleware_result()

Process state after receiving LLM response.

Receives the state after the LLM has responded and can modify the response, extract information, or update state.

Defaults to {:ok, state} if not implemented.

Parameters

• state - The current Sagents.State struct (with LLM response)
• config - The middleware configuration from init/1

Returns

• {:ok, updated_state} - Success with potentially modified state
• {:interrupt, state, interrupt_data} - Pause execution for human intervention
• {:error, reason} - Failure, halts execution

@callback before_model(Sagents.State.t(), middleware_config()) :: middleware_result()

Process state before it's sent to the LLM.

Receives the current agent state and can modify messages, add context, or perform validation before the LLM is invoked.

Defaults to {:ok, state} if not implemented.

Parameters

• state - The current Sagents.State struct
• config - The middleware configuration from init/1

Returns

• {:ok, updated_state} - Success with potentially modified state
• {:error, reason} - Failure, halts execution

@callback callbacks(middleware_config()) :: map()

Provide LangChain callback handlers for this middleware.

Receives the middleware configuration from init/1 and returns a callback handler map compatible with LangChain.Chains.LLMChain.add_callback/2. This allows middleware to observe LLM events such as token usage, tool execution, and message processing.

When multiple middleware declare callbacks, all handlers are collected and fire in fan-out fashion (every matching handler from every middleware fires).

Defaults to empty map (%{}) if not implemented. Return %{} for no callbacks.

Parameters

• config - The middleware configuration from init/1

Returns

• A map of callback keys to handler functions

Available Callback Keys

These are the LangChain-native keys supported by LLMChain. Use only these keys in your callback map (see LangChain.Chains.ChainCallbacks for full type signatures):

Model-level callbacks:

• :on_llm_new_delta - Streaming token/delta received
• :on_llm_new_message - Complete message from LLM
• :on_llm_ratelimit_info - Rate limit headers from provider
• :on_llm_token_usage - Token usage information
• :on_llm_response_headers - Raw response headers

Chain-level callbacks:

• :on_message_processed - Message fully processed by chain
• :on_message_processing_error - Error processing a message
• :on_error_message_created - Error message created
• :on_tool_call_identified - Tool call detected during streaming
• :on_tool_execution_started - Tool begins executing
• :on_tool_execution_completed - Tool finished successfully
• :on_tool_execution_failed - Tool execution errored
• :on_tool_response_created - Tool response message created
• :on_retries_exceeded - Max retries exhausted

Example

def callbacks(_config) do
  %{
    on_llm_token_usage: fn _chain, usage ->
      Logger.info("Token usage: #{inspect(usage)}")
    end,
    on_message_processed: fn _chain, message ->
      Logger.info("Message: #{inspect(message)}")
    end
  }
end

@callback debug_summary(middleware_config()) :: map() | String.t()

Optional. Returns a debugger-friendly representation of this middleware's runtime config, suitable for rendering in the live debugger's Middleware tab.

Use this when your config holds large structures (compiled agents, caches, big maps) that would dominate the inspect output and slow down the debugger UI. Keep the result small — this is for human reading.

Return either a map (rendered as a key/value config table) or a string (rendered verbatim in a code block). If not implemented, the debugger falls back to inspecting the raw config map with bounded limits.

@callback handle_message(message :: term(), Sagents.State.t(), middleware_config()) ::
  {:ok, Sagents.State.t()} | {:error, term()}

Handle messages sent to this middleware.

Messages are routed to a specific middleware by ID through the AgentServer's middleware registry. Any process can send a targeted message to a middleware using AgentServer.notify_middleware/3.

This enables two primary patterns:

1. External notifications

LiveViews, controllers, or other processes can send context updates to a running middleware. The middleware updates state metadata, which before_model/2 reads on the next LLM call.

# In a LiveView — user switched to editing a different blog post
AgentServer.notify_middleware(agent_id, MyApp.UserContext, {:post_changed, %{
  slug: "/blog/getting-started-with-elixir",
  title: "Getting Started with Elixir"
}})

# In the middleware
def handle_message({:post_changed, post_info}, state, _config) do
  {:ok, State.put_metadata(state, "current_post", post_info)}
end

2. Async task results

Middleware that spawns background tasks sends results back to itself for state updates.

def handle_message({:title_generated, title}, state, _config) do
  {:ok, State.put_metadata(state, "conversation_title", title)}
end

Defaults to {:ok, state} if not implemented.

Parameters

• message - The message payload (any term — typically a tagged tuple)
• state - The current Sagents.State struct
• config - The middleware configuration from init/1

Returns

• {:ok, updated_state} - Success with potentially modified state
• {:error, reason} - Failure (logged but does not halt agent execution)

@callback handle_resume(
  Sagents.Agent.t(),
  Sagents.State.t(),
  resume_data :: term(),
  middleware_config(),
  opts :: keyword()
) ::
  {:ok, Sagents.State.t()}
  | {:cont, Sagents.State.t()}
  | {:interrupt, Sagents.State.t(), interrupt_data :: map()}
  | {:error, term()}

Handle a resume after an interrupt.

Called by Sagents.Agent.resume/3 to give each middleware a chance to claim and handle an interrupt. The middleware should pattern-match on state.interrupt_data to decide whether the interrupt belongs to it.

Return Values

• {:cont, state} - "Not mine, pass to next middleware." Default when not implemented.
• {:ok, updated_state} - "Handled. State is ready for re-execution." Halts the chain.
• {:interrupt, state, new_interrupt_data} - "Handled, but needs another round." Halts the chain.
• {:error, reason} - "Handled, but invalid." Halts the chain.

Parameters

• agent - The Sagents.Agent struct
• state - The current Sagents.State struct (with interrupt_data set)
• resume_data - The data provided by the caller to resume execution (polymorphic)
• config - The middleware configuration from init/1
• opts - Options from Sagents.Agent.resume/3 (includes :callbacks for LLMChain event handlers)

@callback init(config()) :: {:ok, middleware_config()} | {:error, term()}

Initialize middleware with configuration options.

Called once when the middleware is added to an agent. Returns configuration that will be passed to other callbacks.

Convention

• Input: opts as keyword list
• Output: config as map for efficient runtime access

Defaults to converting opts to a map if not implemented.

Example

def init(opts) do
  config = %{
    enabled: Keyword.get(opts, :enabled, true),
    max_retries: Keyword.get(opts, :max_retries, 3)
  }
  {:ok, config}
end

@callback on_server_start(Sagents.State.t(), middleware_config()) ::
  {:ok, Sagents.State.t()} | {:error, term()}

Called when the AgentServer starts or restarts.

This allows middleware to perform initialization actions that require the AgentServer to be running, such as broadcasting initial state to subscribers (e.g., TODOs for UI display).

Receives the current state and middleware config. Returns {:ok, state} (state is not typically modified here but could be).

Defaults to {:ok, state} if not implemented.

Parameters

• state - The current Sagents.State struct
• config - The middleware configuration from init/1

Returns

• {:ok, state} - Success (state typically unchanged)
• {:error, reason} - Failure (logged but does not halt agent)

Example

def on_server_start(state, _config) do
  # Broadcast initial todos when AgentServer starts
  broadcast_todos(state.agent_id, state.todos)
  {:ok, state}
end

@callback restorable_interrupt?(interrupt_data :: map()) :: boolean()

Return true if this middleware can resume an interrupted tool call from the given interrupt_data after a process restart (no in-memory context required), or false otherwise.

Called at state-load time for every LangChain.Message.ToolResult with is_interrupt: true. The framework asks each middleware in the agent's middleware list; if no middleware says true, the interrupt is converted to an error result and the LLM is told the prior call could not be resumed.

Default: false (every middleware must opt in).

Recommended pattern — pattern-match on the middleware's own :type value in interrupt_data and return true only for that type:

def restorable_interrupt?(%{type: :ask_user_question}), do: true
def restorable_interrupt?(_), do: false

See the "Restorable interrupts" section in the module documentation for the full guidance, including the data-only restriction and schema evolution caveats.

@callback state_schema() :: module() | nil

Provide the state schema module for this middleware.

If the middleware needs to add fields to the agent state, it should return a module that defines those fields.

Defaults to nil if not implemented.

@callback system_prompt(middleware_config()) :: String.t() | [String.t()]

Provide system prompt text for this middleware.

Can return a single string or list of strings that will be joined.

Defaults to empty string if not implemented.

@callback tools(middleware_config()) :: [LangChain.Function.t()]

Provide tools (Functions) that this middleware adds to the agent.

Defaults to empty list if not implemented.