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

Send a synchronous prompt to an agent.

Blocks until the logical request completes and returns {:ok, response} or {:error, reason} (error_reason/0). A handle_error/3 retry keeps the caller waiting and returns only the final attempt's outcome. If the agent is processing another prompt, the caller is queued transparently and unblocks when its queued turn finishes.

If the agent is halted, the ask is queued until resume/1 is called; the watchdog does not bound this idle wait. Use status/2 or runtime_snapshot/2 to check whether the agent is halted. A caller timeout does not cancel a live caller's queued ask; it can still run after resume/1 without that caller receiving the result.

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, or place {MyAgent, opts} in a static Supervisor child list when MyAgent uses GenAgent. The tuple calls the module's overridable child_spec/1, which delegates here. 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. Static children retain restart: :temporary: once stopped or crashed, they are removed from the supervisor and must be started explicitly again.

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 current_name() :: name() | nil

Return the registered name from an agent callback, or nil elsewhere.

Available in init_agent/1, turn and lifecycle callbacks, and handle_stream_event/2, which runs in the prompt task. The name is scoped to those processes; tasks spawned by application callbacks do not inherit it. This avoids duplicating :name in backend options or agent state just to identify the current agent.

@spec drain(name(), timeout()) ::
  :ok | {:error, :not_found | :timeout | {:agent_down, term()}}

Stop an agent after its active turn finishes.

Drain immediately refuses new asks, tells, and acknowledged notifications with {:error, :draining}. Already queued asks receive that error and queued tell_with_completion/4 recipients receive a completion with the same error. Queued notifications and callback-generated follow-up prompts are discarded. The active turn runs through its decision and post_turn/3 callbacks, then the agent terminates its backend session and exits. Plain notify/2 casts sent during drain remain best effort and are ignored.

Returns :ok only after the agent process has exited normally, or {:error, :not_found} if it is absent at lookup. If it exits abnormally, returns {:error, {:agent_down, reason}}. The timeout covers both the admission call and the wait for process exit; a caller-side timeout does not cancel the drain. As with other synchronous APIs, a timeout or a concurrent agent death during the admission call can exit the caller. The default timeout is :infinity.

@spec halt(name()) :: :ok

Halt an agent from outside its callback module.

When idle, the agent enters the halted state and runs post_run/1. An active turn is allowed to finish its callbacks first; the halt is pending until then. Queued prompts remain paused until resume/1. resume/1 during the active turn cancels a pending external halt. Calling halt/1 again is idempotent. Asynchronous, like resume/1; returns :ok immediately. status/2 and runtime_snapshot/2 expose :halt_pending while the active turn is finishing.

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

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

Returns:

• {:ok, :pending} if the request is queued, in-flight, or between caller-owned retry attempts. This also includes work queued while halted until resume/1; use status/2 or runtime_snapshot/2 to distinguish a halted queue from an active turn.
• {: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).

Refs returned from tell/2 and tell_with_completion/4 are pollable until evicted by the count or byte limit. Refs from ask/2 are internal and reply directly to the caller. Returns {:error, :not_found} if the agent name is not registered.

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

Reset an agent's backend conversation context without restarting the agent.

The backend must implement GenAgent.Backend.reset_session/1. This call is accepted only while the agent is idle; an active turn returns {:error, :busy} so its session cannot be replaced under it. A draining agent returns {:error, :draining}. Callback state and queued prompts are preserved. A backend without the callback returns {:error, :unsupported}. Returns {:error, :not_found} if the agent is not registered. The default call timeout is :infinity.

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

Resume a halted agent.

Clears the halted flag and re-drains the mailbox, or cancels a pending external halt if an active turn is still running. No-op otherwise.

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 and ordinary OTP messages buffered during a turn; self_chain_pending reports a separately held callback-generated follow-up prompt. halt_pending means an external halt was requested while a turn was active and will take effect after that turn finishes. draining is true after drain/2 has stopped accepting work and before the agent exits. current_request is nil when idle and otherwise contains the volatile request ref, its origin (:event and :self_chain are callback-origin turns), 1-based attempt number, 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 (including ordinary OTP messages deferred for handle_info/2), 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). :max_tell_result_bytes bounds their combined serialized size (default 8_388_608, or 8 MiB), measured with :erlang.external_size/1 for each ref and result pair. Both limits must be non-negative integers; the oldest results are evicted first when either limit is exceeded. Zero retains none. A single result larger than the byte limit is immediately evicted. Results sent by tell_with_completion/4 remain pollable until evicted and count against both limits. This measures cached payloads, not total process memory.

: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_tell_result_bytes, :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(),
    halt_pending: boolean(),
    draining: 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. The legacy keys :state and :queued correspond to :phase and :pending_prompts in runtime_snapshot/2, respectively. Returns {:error, :not_found} if the agent name is not registered.

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

Stop an agent.

Terminates the agent process via its owning supervisor. Pass the supervisor as the second argument for an agent started with child_spec/2 or a {MyAgent, opts} tuple; the default is GenAgent.AgentSupervisor. For a static Supervisor, the child ID is the agent's registered name. 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. Most callbacks run inside the agent process and can delay shutdown. If one 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 supervisor during stop/2.

Do not call stop/1 or stop/2 for the same agent from one of its callbacks, including handle_stream_event/2 in the linked prompt task. The supervisor waits for the agent process to exit, so a synchronous self-stop would block until the child shutdown timeout and skip cleanup. Such a call returns {:error, :self_stop} immediately. To retain final state, return {:halt, state} from a decision callback, let an external owner inspect it, then have that owner call stop/1 or stop/2. If immediate teardown is intended and final state and cached results are not needed, post_run/1 can spawn a separate process to call stop/1 as the halt completes.

Returns :ok, {:error, :not_found}, or {:error, :self_stop}.

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

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: a tell accepted while halted remains pending until resume/1. poll/3 reports {:ok, :pending} during that wait; inspect status/2 or runtime_snapshot/2 to tell why it is pending. 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, error_reason()}

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. Requests accepted while halted remain queued until resume/1 unless the five-argument form opts into on_halt: :fail. The ref stays {:ok, :pending} from poll/3 during the halted wait. Inspect status/2 or runtime_snapshot/2 to distinguish a halted queue from an active turn. 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 :pre_turn_skipped, :pre_turn_halted and :pre_turn_invalid without starting a turn. A hook crash also delivers :pre_turn_skipped. Successful and failed turns deliver after their decision and post_turn/3 callbacks. Interruptions deliver an error immediately. A watchdog timeout or backend failure may be retried by handle_error/3; the recipient receives only the final success or error under the original ref. 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. Caller-owned retries relay each attempt's events under the same request ref, so an intermediate :error event can precede later successful events and the single final completion message.

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.