Skip to main content
The agent runtime is a per-request mutable store used to share data between your application code and the tools executed by the model. It replaces ad-hoc experimental_context usage and keeps sensitive paths out of prompts.

Initialise a runtime

  • RuntimeStore<T> accepts typed values; get, set, require, delete work like a Map.
  • onCleanup registers a function executed at the end of the request (including streaming).
  • The runtime is cloned per call to avoid state leaks.

Runtime-aware tools

createRuntimeTool injects the current runtime into execute. If no runtime is provided (caller forgets runtime), execution fails immediately.

Declarative resources

registerRuntimeResource centralises encoding/decoding logic and guarantees consistent cleanup. runtime.load calls the loader, stores the value, and schedules the disposer after the response.

Best practices

  • Async isolation – every generate/stream call runs inside an AsyncLocalStorage scope. Tools can retrieve the active runtime without extra parameters.
  • Streaming aware – the runtime stays alive until the stream finishes; cleanup handlers run on success or error.
  • Multiple runtimes – instantiate several RuntimeStores to isolate functional domains (files, users, …).
  • Strong typing – parameterise RuntimeStore<{ ... }> and createRuntimeTool<INPUT, OUTPUT, RuntimeState> to keep types aligned end-to-end.