adk_runner (erlang_adk v0.7.0)
View Sourceadk_runner - Event and session execution orchestrator.
The Runner manages the event loop for an agent, handling session retrieval, event recording, tool execution, and streaming responses back to the caller.
Summary
Functions
Request cancellation of an asynchronous run. Cancellation is delivered as {adk_error, StreamPid, {cancelled, Reason}} to the run's original caller.
Type-safe boundary check for services that accept an opaque Runner. Callers must not inspect the record tuple directly.
Create a new Runner with required services.
Create a new Runner with optional services and run_timeout.
Resume a paused workflow with a human-provided result. The original invocation ID, tool name, and thought signature are retained.
Resume one specific paused invocation. The continuation reference is the invocation_id exposed by the pause event. Unlike resume/4 this API stays deterministic when several invocations are paused in the same session.
Execute the agent synchronously, returning only after a terminal message.
Execute the agent asynchronously. The worker emits adk_event messages and exactly one terminal adk_done, adk_paused, or adk_error message.
Append a correlated non-terminal update for a suspended long-running tool. The continuation remains available. Built-in session backends perform one atomic compare-and-append, so a racing terminal resume is ordered wholly before or after this update and can never consume the wrong operation.
Validate a continuation response without claiming it. Stable run/API layers use this fail-fast check before allocating a linked resumed run; the actual resume validates again after its atomic single-use claim.
Types
-type runner() :: #runner{agent :: pid() | module(), app_name :: binary(), session_svc :: module(), memory_svc :: adk_service_ref:service_ref() | undefined, artifact_svc :: adk_service_ref:service_ref() | undefined, credential_store :: undefined | {module(), term()}, memory_retrieval :: disabled | map(), memory_ingestion :: disabled | on_success | map(), context_policy :: disabled | map(), context_compaction :: disabled | map(), context_cache :: disabled | map(), service_timeout :: pos_integer(), run_timeout :: timeout(), max_llm_calls :: pos_integer() | infinity, max_tool_rounds :: pos_integer() | infinity, tool_execution :: serial | map(), streaming_mode :: none | text | content, max_stream_output_bytes :: pos_integer(), admission_control :: disabled | map(), runtime_policy :: disabled | adk_runtime_policy:policy(), plugin_pipeline :: disabled | adk_plugin_pipeline:pipeline(), observability :: disabled | map()}.
Functions
-spec cancel(StreamPid :: pid()) -> ok.
Request cancellation of an asynchronous run. Cancellation is delivered as {adk_error, StreamPid, {cancelled, Reason}} to the run's original caller.
Type-safe boundary check for services that accept an opaque Runner. Callers must not inspect the record tuple directly.
Create a new Runner with required services.
-spec new(Agent :: pid() | module(), AppName :: binary(), SessionSvc :: module(), Opts :: map()) -> runner().
Create a new Runner with optional services and run_timeout.
-spec resume(Runner :: runner(), UserId :: binary(), SessionId :: binary(), ToolResponse :: term()) -> {ok, pid()} | {error, term()}.
Resume a paused workflow with a human-provided result. The original invocation ID, tool name, and thought signature are retained.
-spec resume(Runner :: runner(), UserId :: binary(), SessionId :: binary(), InvocationId :: binary(), ToolResponse :: term()) -> {ok, pid()} | {error, term()}.
Resume one specific paused invocation. The continuation reference is the invocation_id exposed by the pause event. Unlike resume/4 this API stays deterministic when several invocations are paused in the same session.
-spec run(Runner :: runner(), UserId :: binary(), SessionId :: binary(), Message :: term()) -> {ok, binary() | adk_content:content()} | {paused, adk_event:event()} | {error, term()}.
Execute the agent synchronously, returning only after a terminal message.
-spec run_async(Runner :: runner(), UserId :: binary(), SessionId :: binary(), Message :: term()) -> {ok, pid()}.
Execute the agent asynchronously. The worker emits adk_event messages and exactly one terminal adk_done, adk_paused, or adk_error message.
-spec update_long_running(runner(), binary(), binary(), binary(), binary(), map()) -> {ok, adk_event:event()} | {error, term()}.
Append a correlated non-terminal update for a suspended long-running tool. The continuation remains available. Built-in session backends perform one atomic compare-and-append, so a racing terminal resume is ordered wholly before or after this update and can never consume the wrong operation.
Validate a continuation response without claiming it. Stable run/API layers use this fail-fast check before allocating a linked resumed run; the actual resume validates again after its atomic single-use claim.