Runtime Context
Agents, tools, and workflows can all accept RuntimeContext as a parameter, making request-specific values available to the underlying primitives.
When to use RuntimeContext
Use RuntimeContext when a primitive’s behavior should change based on runtime conditions. For example, you might switch models or storage backends based on user attributes, or adjust instructions and tool selection based on language.
Setting values
Pass runtimeContext into an agent, workflow, or tool call to make values available to all underlying primitives during execution. Use .set() to define values before making the call.
The .set() method takes two arguments:
- key: The name used to identify the value.
- value: The data to associate with that key.
import { RuntimeContext } from "@mastra/core/runtime-context";
export type UserTier = {
"user-tier": "enterprise" | "pro";
};
const runtimeContext = new RuntimeContext<UserTier>();
runtimeContext.set("user-tier", "enterprise");
const agent = mastra.getAgent("weatherAgent");
await agent.generate("What's the weather in London?", {
runtimeContext
})
const run = await mastra.getWorkflow("weatherWorkflow").createRunAsync();
await run.start({
inputData: {
location: "London"
},
runtimeContext
});
await weatherTool.execute({
context: {
location: "London"
},
runtimeContext
});Accessing values with agents
You can access the runtimeContext argument from any supported configuration options in agents. These functions can be sync or async. Use the .get() method to read values from runtimeContext.
export type UserTier = {
"user-tier": "enterprise" | "pro";
};
export const weatherAgent = new Agent({
name: "weather-agent",
instructions: async ({ runtimeContext }) => {
const userTier = runtimeContext.get("user-tier") as UserTier["user-tier"];
if (userTier === "enterprise") {
// ...
}
// ...
},
model: ({ runtimeContext }) => {
// ...
},
tools: ({ runtimeContext }) => {
// ...
},
memory: ({ runtimeContext }) => {
// ...
},
});You can also use runtimeContext with other options like agents, workflows, scorers, inputProcessors, and outputProcessors.
See Agent for a full list of configuration options.
Accessing values from workflow steps
You can access the runtimeContext argument from a workflow step’s execute function. This function can be sync or async. Use the .get() method to read values from runtimeContext.
export type UserTier = {
"user-tier": "enterprise" | "pro";
};
const stepOne = createStep({
id: "step-one",
execute: async ({ runtimeContext }) => {
const userTier = runtimeContext.get("user-tier") as UserTier["user-tier"];
if (userTier === "enterprise") {
// ...
}
// ...
}
});See createStep() for a full list of configuration options.
Accessing values with tools
You can access the runtimeContext argument from a tool’s execute function. This function is async. Use the .get() method to read values from runtimeContext.
export type UserTier = {
"user-tier": "enterprise" | "pro";
};
export const weatherTool = createTool({
id: "weather-tool",
execute: async ({ runtimeContext }) => {
const userTier = runtimeContext.get("user-tier") as UserTier["user-tier"];
if (userTier === "enterprise") {
// ...
}
// ...
}
});See createTool() for a full list of configuration options.