ReqManagedAgents.Handler behaviour (ReqManagedAgents v0.2.0)

Copy Markdown View Source

Behaviour a consumer implements to plug local tool execution and event handling into ReqManagedAgents.Session. This is the "tools stay local" seam: the managed loop runs on Anthropic's side and calls back into handle_tool_call/3 on your node.

handle_event/2 is observational and at-least-once: on reconnect (Claude) or a retried turn (Bedrock AgentCore), events from an aborted attempt may be delivered before the successful attempt's. When no attempt succeeds (retries exhausted), events live-delivered here were still observed even though the run returns an error; error frames surfaced by the transport (e.g. a "__stream_error__" envelope on Bedrock AgentCore) may also appear on this observational surface. The canonical exactly-once record is ReqManagedAgents.SessionResult.events.

Summary

Callbacks

handle_event(event, ctx)

Optional: react to non-tool events (assistant messages, status, errors).

handle_tool_call(name, input, ctx)

Run a custom tool locally. name and input come from the agent.custom_tool_use event; ctx is the :context passed at session start. Return {:ok, text} (sent as the tool result) or {:error, text} (sent with is_error: true).

Callbacks

handle_event(event, ctx)

(optional) 
@callback handle_event(event :: map(), ctx :: term()) :: :ok

Optional: react to non-tool events (assistant messages, status, errors).

handle_tool_call(name, input, ctx)

@callback handle_tool_call(name :: String.t(), input :: map(), ctx :: term()) ::
  {:ok, String.t()} | {:error, String.t()}

Run a custom tool locally. name and input come from the agent.custom_tool_use event; ctx is the :context passed at session start. Return {:ok, text} (sent as the tool result) or {:error, text} (sent with is_error: true).