@spec ask(name(), String.t(), timeout()) ::
  {:ok, GenAgent.Response.t()} | {:error, term()}

Send a synchronous prompt to an agent.

Blocks until the turn completes and returns {:ok, response} or {:error, reason}. If the agent is currently processing another prompt, the caller is queued transparently and unblocks when its queued turn finishes.

If admission to the pending prompt queue fails, returns {:error, {:overloaded, info}} immediately; no turn is accepted. info includes the queue, count or byte limit reached, current count and bytes, incoming bytes, and configured maxima.

An orderly agent stop replies to an active or queued ask with {:error, {:agent_terminated, reason}}. A call the agent has not yet handled, an abrupt agent death, or a forced kill can still exit the caller; catch :exit if the caller must survive those cases.

The default timeout is :infinity. The agent's own watchdog is the primary timeout mechanism -- callers generally should not need to set their own. Supplying a shorter timeout here will exit on expiry without affecting the agent. A queued ask is dropped if its calling process dies. If that ask is already active, it keeps running. A live caller's timeout leaves its ask queued or running. For cancellable queued work, use tell/3 or tell_with_completion/4 and cancel_request/3. Returns {:error, :not_found} if the agent name is not registered.

@spec cancel_request(name(), request_ref(), timeout()) ::
  {:ok, :cancelled} | {:error, :current | :already_finished | :not_found}

Cancel a queued tell/3 or tell_with_completion/4 request by exact ref.

Returns {:ok, :cancelled} when the queued request is removed, or when its cancellation result is still cached. The cancellation releases its queue count and bytes immediately. poll/3 then returns {:error, :cancelled}. A completion recipient receives exactly one {:gen_agent, :completion, name, ref, {:error, :cancelled}} message.

Returns {:error, :current} for an active tell turn; use interrupt_request/3 to interrupt it. Returns {:error, :already_finished} for a cached terminal result other than cancellation. Returns {:error, :not_found} for an unknown ref, a pruned result, or an internal ask or event ref. Cancellation results count toward the bounded max_tell_results cache. Once pruned, a cancelled ref also returns {:error, :not_found}.

A queued turn has not started, so cancellation does not call handle_response/3, handle_error/3, or post_turn/3. The agent processes cancellation and dispatch in order: if dispatch happened first, this returns {:error, :current} and leaves the turn alone. The default call timeout is :infinity. Returns {:error, :not_found} if the agent name is not registered.

@spec child_spec(module(), keyword()) :: Supervisor.child_spec()

Build a temporary agent child spec for a caller-owned supervisor.

Requires :name, :backend, and :task_supervisor. The selected Task.Supervisor must already be running; prompt tasks never fall back to GenAgent.TaskSupervisor. Other options have the same meaning as in start_agent/2.

Start the spec with DynamicSupervisor.start_child/2. The agent is registered in GenAgent.Registry, so the regular name-based APIs work. Names must be unique across both caller-owned and global agents. Use stop/2 with the owning supervisor to stop an individual agent.

Put the task supervisor before the agent supervisor in the caller's supervision tree so agents shut down before their prompt-task supervisor. Use :rest_for_one if loss of the task supervisor should also stop the agents. See the README for an example.

@spec interrupt(name()) :: :ok

Interrupt an in-flight turn.

Kills the prompt task and delivers {:error, :interrupted} to the waiting caller (if any). No-op if the agent is idle.

Asynchronous. Returns :ok immediately.

@spec interrupt_request(name(), request_ref(), timeout()) ::
  {:ok, :accepted} | {:error, :not_current | :idle | :not_found}

Interrupt the active turn only if its request reference matches ref.

Returns {:ok, :accepted} when the agent has cancelled that turn, {:error, :not_current} when another turn is active, or {:error, :idle} when no turn is active. A queued request is not interruptible through this API; use cancel_request/3 for a queued tell. Unlike interrupt/1, this operation is acknowledged by the agent and cannot cancel a successor turn after the observed request finishes. It is also safe against a replacement agent registered under the same name, because request references are unique.

The acknowledgement describes the agent's decision and BEAM task cancellation. It does not establish provider or OS process settlement. The default call timeout is :infinity. Returns {:error, :not_found} if the agent name is not registered.

@spec list() :: [name()]

Return an unordered list of registered agent names.

This is a point-in-time view of GenAgent.Registry; agents running without registration are excluded. Returned agents are not guaranteed to remain alive, and registry cleanup may briefly lag agent termination.

@spec notify(name(), term()) :: :ok

Push an external event into the agent.

The event is delivered to handle_event/2. If the callback returns {:prompt, text, state} the prompt is dispatched (or queued, if the agent is busy).

Asynchronous. Returns :ok immediately, including when the agent later rejects the event because its pending queue is full. Rejections emit [:gen_agent, :input, :rejected] telemetry. Use notify_ack/3 when the sender needs an in-memory admission result.

@spec notify_ack(name(), term(), timeout()) :: :ok | {:error, term()}

Send an event and wait for the agent to acknowledge admission.

Returns :ok when the event was handled immediately or retained for delivery after the current turn. Returns {:error, {:overloaded, info}} when the pending notification queue cannot hold it, or an event handled while halted generates a prompt that cannot be queued. This acknowledges in-memory handling or retention, not durable delivery or a guarantee that a callback-generated prompt will run. A deferred callback-generated prompt can be rejected later if the prompt queue is full; the agent's handle_error/3 receives that overload. The legacy notify/2 remains a best-effort asynchronous cast and always returns :ok. Returns {:error, :not_found} if the agent name is not registered.

@spec poll(name(), request_ref(), timeout()) ::
  {:ok, :pending} | {:ok, :completed, GenAgent.Response.t()} | {:error, term()}

Check the status of a previously-issued tell/2 request.

Returns:

• {:ok, :pending} if the request is queued or in-flight.
• {:ok, :completed, response} if the turn finished successfully.
• {:error, reason} if the turn failed, including {:error, :cancelled} for a cancelled queued request.
• {:error, :not_found} if the ref is unknown (never issued, or pruned from the bounded result cache).

Only refs returned from tell/2 are pollable. Refs from ask/2 are internal and reply directly to the caller. Returns {:error, :not_found} if the agent name is not registered.

@spec resume(name()) :: :ok

Resume a halted agent.

Clears the halted flag and re-drains the mailbox. No-op if the agent is not halted.

Asynchronous. Returns :ok immediately.

@spec runtime_snapshot(name(), timeout()) :: runtime_snapshot() | {:error, :not_found}

Read a bounded, metadata-only runtime snapshot of an agent.

pending_prompts counts the prompt mailbox; pending_notifications counts notifications buffered during a turn; self_chain_pending reports a separately held callback-generated follow-up prompt. current_request is nil when idle and otherwise contains the volatile request ref, its origin (:event and :self_chain are callback-origin turns), elapsed monotonic milliseconds since dispatch, and the configured watchdog duration. It excludes prompts, caller identities, callback state, backend sessions, events, and queued payloads. Elapsed time is an observation, not an exact countdown to the watchdog firing.

The snapshot is a point-in-time view of this BEAM coordinator, not durable application state, admission authority, or proof that external provider work has settled. The default call timeout is :infinity. Returns {:error, :not_found} if the agent name is not registered.

@spec start_agent(module(), keyword()) :: DynamicSupervisor.on_start_child()

Start an agent under the GenAgent supervision tree.

module is the implementation module (the one that use GenAgent). opts must include:

• :name -- the name the agent will register under in GenAgent.Registry.
• :backend -- the backend module implementing GenAgent.Backend.

Event evidence is bounded by :max_events_per_turn (default 1_000) and :max_event_bytes_per_turn (default 1_048_576), measured as the sum of :erlang.external_size/1 for retained GenAgent.Event values. Both limits must be positive integers. With the default event_retention: :compact, an oversized turn succeeds with a bounded prefix in Response.events and Response.event_coverage reports omissions. All normalized events still reach handle_stream_event/2, and the terminal result, full response text, and usage remain available separately. Use event_retention: :lossless to require a complete event list; an event that exceeds either limit then fails the turn with {:event_capture_overflow, diagnostics} before entering the callback.

Pending prompt and deferred notification queues have independent count and payload-byte limits: :max_pending_prompts and :max_pending_notifications (both default 1_000), and :max_pending_prompt_bytes and :max_pending_notification_bytes (both default 1_048_576). Limits are non-negative integers; zero disables that pending queue. Bytes are the sum of :erlang.external_size/1 of each queued prompt or notification payload, not the entire process memory. The active prompt and notifications handled immediately while idle are not pending. Self-chaining has one reserved slot outside the prompt count limit, but its payload must fit :max_pending_prompt_bytes.

:watchdog_ms is the per-turn deadline in milliseconds (default 600_000). It must be a positive integer or :infinity, which disables the watchdog. :max_tell_results is the number of completed tell/2 results kept for poll/2 (default 100). It must be a non-negative integer; the oldest results are evicted first and zero retains none.

:shutdown is the supervisor's graceful shutdown timeout in milliseconds (default 5_000), or :infinity. A callback still running when this timeout expires is killed and termination callbacks cannot run. Choose a value longer than any bounded callback or cleanup operation; :infinity can block the owning supervisor indefinitely. An explicit nil uses the default.

Invalid values for the watchdog and the capture and pending limits make start_agent/2 return {:error, {:init_failed, :error, ArgumentError}}. An invalid :shutdown raises ArgumentError while building the child spec. A missing :name or :backend raises KeyError in the caller. An explicit nil for a limit is treated as unset and uses the default.

The reserved keys :name, :backend, :watchdog_ms, :shutdown, :max_tell_results, :max_events_per_turn, :max_event_bytes_per_turn, :event_retention, :max_pending_prompts, :max_pending_prompt_bytes, :max_pending_notifications, and :max_pending_notification_bytes are consumed and not forwarded. Any other option, including :task_supervisor, is forwarded to init_agent/1. start_agent/2 always uses GenAgent.TaskSupervisor; use child_spec/2 to select a different task supervisor.

The child uses restart: :temporary. If it exits, call start_agent/2 explicitly to create another agent; its previous state is not restored. An agent also exits if its Registry partition is lost, so it cannot remain alive but unreachable by name after a Registry restart. The returned pid is for monitoring or supervision. Pass the registered :name to the public client functions, including stop/1.

@spec status(name(), timeout()) ::
  %{
    state: :idle | :processing,
    name: term(),
    queued: non_neg_integer(),
    current_request: request_ref() | nil,
    halted: boolean(),
    agent_state: term()
  }
  | {:error, :not_found}

Read an agent's current status.

This compatibility API includes the full callback-maintained agent_state. While a turn is processing, that value is the server's latest retained state, not a live read of state inside the prompt task. Use runtime_snapshot/2 for a bounded metadata-only view. Returns {:error, :not_found} if the agent name is not registered.

@spec stop(name(), GenServer.server()) :: :ok | {:error, :not_found}

Stop an agent.

Terminates the agent process via its owning DynamicSupervisor. Pass the supervisor as the second argument for an agent started with child_spec/2; the default is GenAgent.AgentSupervisor. Active and queued ask/3 callers receive an :agent_terminated error when the agent processes the orderly shutdown. Accepted tell_with_completion/4 requests do not receive a synthetic completion; recipients should monitor the agent to detect that uncertainty. A callback runs inside the agent process and can delay shutdown. If it exceeds the child spec's :shutdown timeout (default 5_000 ms), the supervisor kills the agent and terminate_agent/2 and backend terminate_session/1 cannot run. Configure :shutdown when starting an agent whose callbacks or cleanup can take longer. A blocked callback can also delay unrelated operations on the same DynamicSupervisor during stop/2. Returns :ok or {:error, :not_found}.

@spec tell(name(), String.t(), timeout()) :: {:ok, request_ref()} | {:error, term()}

Send an asynchronous prompt to an agent.

Returns {:ok, ref} when the agent accepts the prompt. A pre_turn/2 callback runs before acceptance for an idle agent, so this call waits for that callback even though it does not wait for the backend result. Use poll/2 to check on the result. The same queueing semantics as ask/2 apply. When a pending queue limit is reached, returns {:error, {:overloaded, info}} without an accepted ref. Returns {:error, :not_found} if the agent name is not registered.

@spec tell_with_completion(name(), String.t(), pid(), timeout()) ::
  {:ok, request_ref()} | {:error, term()}

Submit an asynchronous prompt and opt into one completion message.

recipient is a pid (defaults to the calling process). On an accepted request this returns {:ok, ref} and sends the recipient {:gen_agent, :completion, name, ref, {:ok, response}} or {:gen_agent, :completion, name, ref, {:error, reason}} when the logical request finishes. The recipient is registered within the same agent call that accepts the request, so even an immediate pre_turn/2 skip or fast backend response can be delivered before this function returns. Match on the returned ref to correlate the message.

Admission failure returns {:error, {:overloaded, info}} with no ref or completion message. Accepted queued requests deliver after their turn completes, unless cancelled with cancel_request/3. A cancelled queued request delivers {:gen_agent, :completion, name, ref, {:error, :cancelled}} without running turn lifecycle callbacks. pre_turn/2 skip, halt and invalid results deliver their corresponding error without starting a turn. Successful and failed turns deliver after their decision and post_turn/3 callbacks. An interrupt, watchdog timeout or backend failure delivers an error. A crashing handle_response/3 callback stops the agent before completion; monitor the agent when its death matters.

Delivery is a single BEAM message sent at most once per accepted request. It is independent of the bounded poll/3 result cache. A dead recipient does not receive the message, and any agent exit, including an orderly stop, can leave accepted requests without a completion message; a monitor reports that uncertainty. This does not prove that an external provider process has settled. The request ref remains suitable for interrupt_request/3 while active or cancel_request/3 while queued. A new agent under the same name never reuses it.

The five-argument form accepts on_halt: :fail. It rejects a new request with {:error, :halted} when the agent is already halted, and completes an opted-in queued request with {:error, :halted} if the agent halts before dispatch. The default preserves the ordinary queue-until-resume behavior. This is useful for callers, such as ensembles, that cannot resume a halted agent themselves.

The five-argument form also accepts stream_to: pid. The process receives {:gen_agent, :event, name, ref, %GenAgent.Event{}} for each event the backend streams during that request's turn, in stream order. Events are relayed through the agent after handle_stream_event/2 runs, so for one ref they arrive before the completion message when stream_to and recipient are the same process. Separate processes have no shared arrival order. Streaming is off by default and independent of event_retention: compact mode relays events that the retained history omits, and lossless mode does not relay the event it rejects for exceeding the capture limits.

Delivery has no backpressure and is best effort. A dead stream_to process is ignored. An interrupt or watchdog timeout can drop events that were generated but not yet relayed; nothing is relayed for a ref after its request has finished. A request that never starts a turn (cancelled, rejected by pre_turn/2, halted or failed dispatch) produces no events. Returns {:error, :not_found} if the agent name is not registered.

@spec whereis(name()) :: pid() | nil

Look up the pid of a registered agent, or nil if not found. Pass the name, not this pid, to public client functions.