Layered context struct separating ambient (read-only), working (mutable), and fork functions (applied at agent boundaries).
Nodes never receive this struct directly — they get a flat map from
to_flat_map/1, with ambient data under the reserved ambient_key/0 key.
Use to_clean_map/1 when the result must be serializable (JSON, OTel, or
returned to callers) — it returns only the working data without the tuple key.
Note: When the same scope key is used in multiple apply_result/3 calls
(e.g., an orchestrator calling the same tool twice), scalar values within
that scope are overwritten via deep merge. Tool authors who need to
accumulate results across invocations should read their prior output from
context and append explicitly.
Summary
Functions
Returns the key used to carry ambient data in flat context maps.
Returns working data as a plain map without the internal ambient tuple key.
Types
Functions
@spec ambient_key() :: {module(), :ambient}
Returns the key used to carry ambient data in flat context maps.
Returns working data as a plain map without the internal ambient tuple key.
Use this instead of to_flat_map/1 when the result will be returned to
callers, serialized to JSON, or used with OTel attributes — any context
where the {module, :ambient} tuple key would cause encoding failures.