adk_agent_spec (erlang_adk v0.7.0)

View Source

Validated immutable configuration for LLM-agent request preparation.

This module deliberately owns no process and performs no persistence. A runner compiles a spec once, calls prepare/4 before a model request, and calls finalize/2 for a final model value. The returned state delta is meant to be attached to the same final event that stores the response, preserving the session service's existing atomic event/state commit.

Summary

Types

error_reason/0
spec/0

Functions

check_capabilities(Spec, Capabilities)

Verify every explicit/derived feature against provider discovery.

compile(Options)

Strictly compile a map containing only agent-spec options.

compile(Options, Capabilities)

Compile and immediately check provider capability discovery output.

finalize(Spec, Output)

Validate a final model value and produce an atomic state delta. No delta is returned when schema validation fails.

from_config(Config)

Narrow integration entry for the existing LLM config map. Only agent contract keys are copied; provider credentials and transport options are intentionally not retained in the immutable spec.

from_config(Config, Capabilities)
prepare(Spec, Input, History, Context)

Validate input, resolve instructions, and apply the immutable history policy. The returned map is provider-neutral.

required_capabilities(Spec)
validate_input(Spec, Input)
validate_output(Spec, Output)

Types

error_reason/0

-type error_reason() ::
          invalid_agent_spec | unsupported_agent_spec_options | invalid_history_policy |
          invalid_output_key | invalid_generation_config |
          {invalid_generation_option, atom()} |
          invalid_required_capabilities | invalid_capabilities |
          {missing_capabilities, [atom()]} |
          invalid_history |
          {input_schema_failed, term()} |
          {output_schema_failed, term()} |
          adk_agent_instruction:error_reason() |
          adk_json_schema:error_reason().

spec/0

-opaque spec()

Functions

check_capabilities(Spec, Capabilities)

-spec check_capabilities(spec(), map()) -> ok | {error, error_reason()}.

Verify every explicit/derived feature against provider discovery.

compile(Options)

-spec compile(map()) -> {ok, spec()} | {error, error_reason()}.

Strictly compile a map containing only agent-spec options.

compile(Options, Capabilities)

-spec compile(map(), map()) -> {ok, spec()} | {error, error_reason()}.

Compile and immediately check provider capability discovery output.

finalize(Spec, Output)

-spec finalize(spec(), term()) -> {ok, term(), map()} | {error, error_reason()}.

Validate a final model value and produce an atomic state delta. No delta is returned when schema validation fails.

from_config(Config)

-spec from_config(map()) -> {ok, spec()} | {error, error_reason()}.

Narrow integration entry for the existing LLM config map. Only agent contract keys are copied; provider credentials and transport options are intentionally not retained in the immutable spec.

from_config(Config, Capabilities)

-spec from_config(map(), map()) -> {ok, spec()} | {error, error_reason()}.

prepare(Spec, Input, History, Context)

-spec prepare(spec(), term(), list(), map()) -> {ok, map()} | {error, error_reason()}.

Validate input, resolve instructions, and apply the immutable history policy. The returned map is provider-neutral.

required_capabilities(Spec)

-spec required_capabilities(spec()) -> [atom()].

validate_input(Spec, Input)

-spec validate_input(spec(), term()) -> {ok, term()} | {error, error_reason()}.

validate_output(Spec, Output)

-spec validate_output(spec(), term()) -> {ok, term()} | {error, error_reason()}.