Nous.PubSub.Approval (nous v0.13.3)

View Source

Async HITL approval via PubSub.

Provides a handler function compatible with Nous.Plugins.HumanInTheLoop that broadcasts approval requests and waits for responses via PubSub. This enables LiveView or other external processes to approve/reject tool calls asynchronously.

Usage

# In your agent setup:
deps = %{
  hitl_config: %{
    tools: ["send_email"],
    handler: Nous.PubSub.Approval.handler(
      pubsub: MyApp.PubSub,
      session_id: session_id,
      timeout: :timer.minutes(5)
    )
  }
}

# In your LiveView:
def handle_info({:approval_required, approval}, socket) do
  {:noreply, assign(socket, pending_approval: approval)}
end

def handle_event("approve", _params, socket) do
  approval = socket.assigns.pending_approval
  Nous.PubSub.Approval.respond(
    MyApp.PubSub, approval.session_id, approval.tool_call_id, :approve
  )
  {:noreply, socket}
end

Summary

Functions

handler(opts)

Build an approval handler function for use with Nous.Plugins.HumanInTheLoop.

respond(pubsub, session_id, tool_call_id, decision)

Send an approval response for a pending tool call.

Functions

handler(opts)

@spec handler(keyword()) :: (map() -> :approve | :reject | {:edit, map()})

Build an approval handler function for use with Nous.Plugins.HumanInTheLoop.

The returned function:

  1. Broadcasts {:approval_required, info} on the agent topic
  2. Subscribes to the approval topic and blocks via receive
  3. Returns the decision when received, or :reject on timeout

Options

  • :pubsub - PubSub module (falls back to Nous.PubSub.configured_pubsub/0)
  • :session_id - Session ID for topic routing (required)
  • :timeout - How long to wait for a response (default: 5 minutes)

respond(pubsub, session_id, tool_call_id, decision)

@spec respond(module(), String.t(), String.t(), :approve | :reject | {:edit, map()}) ::
  :ok | {:error, term()}

Send an approval response for a pending tool call.

Broadcasts {:approval_response, tool_call_id, decision} on the approval topic for the given session.

Parameters

  • pubsub - PubSub module
  • session_id - Session ID
  • tool_call_id - The tool call ID to respond to
  • decision - :approve, :reject, or {:edit, new_args}