007: Agent/Variables

Variables build upon the Data system to enable dynamic data flows. They make structured information interactive by allowing Tool Calls to reference values that exist within the agent's context (such as an Input or State message) without needing to copy the data directly into their parameters.

Reading from Context

A parameter in a Tool Call can hold a Variable Reference—a special string that points to a value elsewhere in the context—instead of the value itself. This prevents the inefficient and error-prone process of having an LLM copy large data objects from its context into the parameters of a Tool Call. Using a reference is faster, cheaper, and more reliable, as it eliminates the risk of the LLM altering the data during reproduction.

The reference is a simple string syntax prefixed with a dagger (†). The syntax is †<kind>.<path>, where <kind> is the type of Data message (e.g., state, input) and <path> is the dot-notation path to the desired value

{
  "_tool": "greetUser",
  "userName": "†input.userName"
}

greetUser({
  userName: input.userName,
});

Interactions with other systems

• • 005: Agent/Data

  Data: Variables are the mechanism that makes Data messages interactive. Variable References read from Data messages (like Input or State), and Output Paths write back to them, creating a dynamic loop where data can be accessed and modified.

• • 006: Agent/Input

  Input: Variable References can target Input messages, allowing a workflow to be parameterized. This is essential for creating reproducible plans where the overall structure is defined, but the specific data it operates on is provided at runtime.

• • 009: Agent/State

  State: The State object is the primary scratchpad for variables in multi-step workflows. It's the most common target for Output Paths because it persists between the ticks of an agent's execution loop, allowing one step to leave a result that a future step can read.

• • 012: Agent/Plan

  Plan: Variables are the fundamental technology that powers the Plan system. A Plan message contains a graph of Tool Calls where the connections (edges) are formed by Variable References pointing to Output Paths. This allows an agent to define a complete, executable workflow as a single, declarative data structure.

From Ephemeral Connections to Persistent Memory

Variables provide the mechanism for wiring data to tools within a single, atomic request. However, to build complex agents that execute tasks over multiple steps, a more persistent form of memory is required—a "scratchpad" where results can be stored and accessed across multiple, independent requests in an execution loop.

008: Agent/Output describes the mechanics of how results are written to the context.