adk_event (erlang_adk v0.7.0)

Immutable, versioned events for the ADK event system.

Events are the fundamental unit of communication in the Runner architecture. encode/1 and decode/1 are the checked persistence/JSON boundary. They deliberately accept only JSON values in generic fields; Erlang terms are not rendered with ~p because that loses type information and can leak internal values into an external protocol.

Summary

Types

codec_error/0

event/0

json_path/0

Functions

codec_version()

The schema version emitted by encode/1 and to_map/1.

decode(Map)

Decode either a canonical event map or a map persisted by v0.2.x. Maps without schema_version use the legacy decoder. New, unknown versions are rejected so that a future schema is never misinterpreted as version 1.

decode_content(EncodedContent)

Decode canonical version-1 content produced by encode_content/1.

encode(Adk_event)

Encode an event to the canonical JSON-safe map representation.

encode_content(Content)

Encode one event content value without constructing an event. This is useful for durable continuations which embed tool calls but must use exactly the same canonical representation as externally visible events.

from_map(Map)

Strict compatibility wrapper around decode/1. Prefer decode/1 when reading untrusted data.

is_final_response(Event)

Check whether this is the terminal event in an invocation.

new(Author, Content)

Create a new immutable event with an auto-generated ID and timestamp. Author is the name of the agent or the binary string <<"user">>. Content can be text, tool calls, or a tool response.

new(Author, Content, Opts)

Create a new immutable event with options. Options can include partial, is_final, actions, and invocation_id.

to_map(Event)

Strict compatibility wrapper around encode/1. Prefer encode/1 at external boundaries where a typed error can be handled.

with_state_delta(Event, Delta)

Attach a state delta map to an existing event.

Types

codec_error/0

-type codec_error() ::
          {invalid_event, json_path(), term()} |
          {invalid_content, json_path(), term()} |
          {invalid_json_value, json_path(), term()} |
          {unsupported_schema_version, term()}.

event/0

-type event() ::
          #adk_event{id :: binary(),
                     invocation_id :: binary(),
                     author :: binary(),
                     content :: term(),
                     actions :: map(),
                     timestamp :: integer(),
                     partial :: boolean(),
                     is_final :: boolean()}.

json_path/0

-type json_path() :: [binary() | non_neg_integer()].

Functions

codec_version()

-spec codec_version() -> pos_integer().

The schema version emitted by encode/1 and to_map/1.

decode(Map)

-spec decode(map()) -> {ok, event()} | {error, codec_error()}.

Decode either a canonical event map or a map persisted by v0.2.x. Maps without schema_version use the legacy decoder. New, unknown versions are rejected so that a future schema is never misinterpreted as version 1.

decode_content(EncodedContent)

-spec decode_content(term()) -> {ok, term()} | {error, codec_error()}.

Decode canonical version-1 content produced by encode_content/1.

encode(Adk_event)

-spec encode(event()) -> {ok, map()} | {error, codec_error()}.

Encode an event to the canonical JSON-safe map representation.

Tool-call tuples are represented as maps. A three-field call always has a thought_signature key and a four-field call always has both optional keys; JSON null represents Erlang undefined. This makes tuple arity survive a JSON encode/decode round trip.

encode_content(Content)

-spec encode_content(term()) -> {ok, map()} | {error, codec_error()}.

Encode one event content value without constructing an event. This is useful for durable continuations which embed tool calls but must use exactly the same canonical representation as externally visible events.

from_map(Map)

-spec from_map(map()) -> event().

Strict compatibility wrapper around decode/1. Prefer decode/1 when reading untrusted data.

is_final_response(Event)

-spec is_final_response(Event :: event()) -> boolean().

Check whether this is the terminal event in an invocation.

new(Author, Content)

-spec new(Author :: binary(), Content :: term()) -> event().

Create a new immutable event with an auto-generated ID and timestamp. Author is the name of the agent or the binary string <<"user">>. Content can be text, tool calls, or a tool response.

new(Author, Content, Opts)

-spec new(Author :: binary(), Content :: term(), Opts :: map()) -> event().

Create a new immutable event with options. Options can include partial, is_final, actions, and invocation_id.

to_map(Event)

-spec to_map(event()) -> map().

Strict compatibility wrapper around encode/1. Prefer encode/1 at external boundaries where a typed error can be handled.

with_state_delta(Event, Delta)

-spec with_state_delta(Event :: event(), Delta :: map()) -> event().

Attach a state delta map to an existing event.