エージェントのランタイムコンテキスト
Mastra は RuntimeContext を提供します。これは、実行時の変数でエージェントを設定できる依存性注入システムです。似たタスクを行うエージェントを複数作成している場合、ランタイムコンテキストを使うことで、それらをより柔軟な単一のエージェントにまとめられます。
概要
依存性注入システムを使うと、次のことが可能になります：
- 型安全な
runtimeContextを通じて、実行時の設定変数をエージェントに渡す - ツールの実行コンテキスト内でこれらの変数にアクセスする
- 基盤のコードを変更せずにエージェントの振る舞いを調整する
- 同一のエージェント内で複数のツール間で設定を共有する
エージェントでの runtimeContext の使用
エージェントは instructions パラメータ経由で runtimeContext にアクセスし、runtimeContext.get() を使って変数を取得できます。これにより、基盤となる実装を変更せずに、ユーザー入力や外部設定に応じてエージェントの挙動を動的に適応させられます。
src/mastra/agents/test-weather-agent.ts
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { testWeatherTool } from "../tools/test-weather-tool";
export const testWeatherAgent = new Agent({
name: "test-weather-agent",
instructions: async ({ runtimeContext }) => {
const temperatureUnit = runtimeContext.get("temperature-unit");
return `You are a weather assistant that provides current weather information for any city.
When a user asks for weather:
- Extract the city name from their request
- Respond with: temperature, feels-like temperature, humidity, wind speed, and conditions
- Use ${temperatureUnit} for all temperature values
- If no city is mentioned, ask for a city name
`;
},
model: openai("gpt-4o-mini"),
tools: { testWeatherTool }
});ツールの例
このツールは WeatherRuntimeContext 型をエクスポートします。これは、RuntimeContext を使用する任意の場所で、実行時の設定へ型安全にアクセスするために利用できます。
src/mastra/tools/test-weather-tool.ts
import { createTool } from "@mastra/core/tools";
import { z } from "zod";
export type WeatherRuntimeContext = {
"temperature-unit": "celsius" | "fahrenheit";
};
export const testWeatherTool = createTool({
id: "test-weather-tool",
description: "指定した場所の天気を取得します",
inputSchema: z.object({
location: z.string()
}),
outputSchema: z.object({
metric: z.string(),
temperature: z.number(),
weather: z.string()
}),
execute: async ({ context, runtimeContext }) => {
const { location } = context;
const unit = runtimeContext.get("temperature-unit") as WeatherRuntimeContext["temperature-unit"];
const temperature = 30;
const weather = "Sunny";
return {
metric: unit === "celsius" ? "°C" : "°F",
temperature,
weather
};
}
});使用例
この例では、runtimeContext.set() を使用して temperature-unit を celsius または fahrenheit に設定し、エージェントが適切な単位で気温を返すようにします。
src/test-weather-agent.ts
import { mastra } from "./mastra";
import { RuntimeContext } from "@mastra/core/runtime-context";
import { WeatherRuntimeContext } from "./mastra/tools/test-weather-tool";
const agent = mastra.getAgent("testWeatherAgent");
const runtimeContext = new RuntimeContext<WeatherRuntimeContext>();
runtimeContext.set("temperature-unit", "fahrenheit");
const response = await agent.generate("What's the weather in London?", {
runtimeContext
});
console.log(response.text);サーバー・ミドルウェアでの runtimeContext へのアクセス
リクエストから情報を抽出して、サーバー・ミドルウェア内で動的に runtimeContext を設定できます。次の例では、Cloudflare の CF-IPCountry ヘッダーに基づいて temperature-unit を設定し、ユーザーのロケールに合ったレスポンスになるようにしています。
src/mastra/index.ts
import { Mastra } from "@mastra/core/mastra";
import { RuntimeContext } from "@mastra/core/runtime-context";
import { testWeatherAgent } from "./agents/test-weather-agent";
import { WeatherRuntimeContext } from "./mastra/tools/test-weather-tool";
export const mastra = new Mastra({
agents: { testWeatherAgent },
server: {
middleware: [
async (context, next) => {
const country = context.req.header("CF-IPCountry");
const runtimeContext = context.get("runtimeContext") as RuntimeContext<WeatherRuntimeContext>;
runtimeContext.set("temperature-unit", country === "US" ? "fahrenheit" : "celsius");
await next();
}
]
}
});