References

References are typed handles to stored values. They let agents pass large, expensive, or sensitive payloads between tools, plans, executors, and host callbacks without copying the full value into every prompt.

Use define_reference(...) to declare the payload shape behind a reference. Customer code may also supply a glimpse callback that produces a small JSON summary stored alongside the reference, so the model can reason about what the handle points to before resolving the full value.

Reference schemas are normalized by normalize_schema(...), the same helper used by tools and plans.

For the full reference and glimpse model, see the References concept.

define_reference

define_reference(name: 'str', schema: 'Any', ttl_ms: 'int | None' = None, glimpse: 'Callable[[Any], Any] | None' = None) -> 'ReferenceSpec'

Parameter	Type	Default
name	str	required
schema	Any	required
ttl_ms	int | None	None
glimpse	Callable[[Any], Any] | None	None

Returns: ReferenceSpec

Create a validated Flow AI reference spec with optional customer glimpse code.

Args: name: Reference kind name used when creating and resolving references. schema: Schema of the referenced value: a JSON Schema mapping, a Pydantic model class, a simple type map, or any type hint Pydantic can export. ttl_ms: Optional time-to-live in milliseconds for stored values; must be non-negative when set. glimpse: Optional Python callback that derives the stored glimpse from the full value. It runs once before storing and is excluded from the Rust wire spec.

Returns: A frozen, validated ReferenceSpec.

Raises: TypeError: If the schema input cannot be normalized to JSON Schema. pydantic.ValidationError: If ttl_ms is negative.

ReferenceSpec

ReferenceSpec(*, name: str, schema: dict[str, typing.Any], ttlMs: Annotated[int | None, Ge(ge=0)] = None, glimpse: collections.abc.Callable[[typing.Any], typing.Any] | None = None) -> None

Parameter	Type	Default
name	str	required
schema	dict[str, Any]	required
ttlMs	int | None	None
glimpse	collections.abc.Callable[[Any], Any] | None	None

Returns: None

Named typed memory pointer declaration.

glimpse is a Python-only customer callback. It is excluded from the Rust wire spec; hosts call it before storing a reference and pass the resulting JSON glimpse to the runtime.