> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# リクエストコンテキスト

Agent、Tool、Workflow はいずれも `RequestContext` をパラメーターとして受け取ることができ、基盤となるプリミティブでリクエスト固有の値を利用できます。

## `RequestContext` を使用する場面

実行時の条件に応じてプリミティブの動作を変更する必要がある場合に、`RequestContext` を使用します。たとえば、ユーザー属性に基づいてモデルやストレージバックエンドを切り替えたり、言語に基づいて指示や Tool の選択を調整したりできます。

> **注記:** `RequestContext` は主に、特定のリクエストへデータを渡すために使用します。複数の呼び出しにわたる会話履歴と状態の永続化を処理する Agent Memory とは異なります。

## 値の設定

Agent、Network、Workflow、または Tool の呼び出しに `requestContext` を渡すと、実行中に基盤となるすべてのプリミティブで値を利用できます。呼び出しを行う前に `.set()` を使用して値を定義します。

`.set()` メソッドは 2 つの引数を取ります。

1. **キー**: 値を識別するために使用する名前。
2. **値**: そのキーに関連付けるデータ。

```typescript
import { RequestContext } from '@mastra/core/request-context'

export type UserTier = {
  'user-tier': 'enterprise' | 'pro'
}

const requestContext = new RequestContext<UserTier>()
requestContext.set('user-tier', 'enterprise')

const agent = mastra.getAgent('weatherAgent')
await agent.generate("What's the weather in London?", {
  requestContext,
})

const routingAgent = mastra.getAgent('routingAgent')
routingAgent.network("What's the weather in London?", {
  requestContext,
})

const run = await mastra.getWorkflow('weatherWorkflow').createRun()
await run.start({
  inputData: {
    location: 'London',
  },
  requestContext,
})
await run.resume({
  resumeData: {
    city: 'New York',
  },
  requestContext,
})

await weatherTool.execute({ location: 'London' }, { requestContext })
```

### リクエストヘッダーに基づく値の設定

ランタイムサーバーのミドルウェアでは、リクエストから情報を抽出して `requestContext` に値を設定できます。この例では、ユーザーのロケールに合ったレスポンスを返すため、Cloudflare の `CF-IPCountry` ヘッダーに基づいて `temperature-unit` を設定します。

```typescript
import { Mastra } from '@mastra/core'
import { RequestContext } from '@mastra/core/request-context'
import { testWeatherAgent } from './agents/test-weather-agent'

export const mastra = new Mastra({
  agents: { testWeatherAgent },
  server: {
    middleware: [
      async (context, next) => {
        const country = context.req.header('CF-IPCountry')
        const requestContext = context.get('requestContext')

        requestContext.set('temperature-unit', country === 'US' ? 'fahrenheit' : 'celsius')

        await next()
      },
    ],
  },
})
```

サーバーミドルウェアの使用方法については、[ミドルウェア](https://mastra.zisheng.pro/ja/docs/server/middleware)を参照してください。

## Studio

ローカルでの開発時には、JSON ファイルでプリセットを定義し、[`--request-context-presets`](https://mastra.zisheng.pro/ja/reference/cli/mastra) CLI フラグを使用して [Studio](https://mastra.zisheng.pro/ja/docs/studio/overview) に読み込めます。これにより Studio のリクエストコンテキストエディターにドロップダウンが追加され、毎回 JSON を手動で編集せずに設定をすばやく切り替えられます。

```bash
mastra dev --request-context-presets ./presets.json
```

```json
{
  "development": { "userId": "dev-user", "env": "development" },
  "production": { "userId": "prod-user", "env": "production" }
}
```

ドロップダウンからプリセットを選択すると、JSON エディターにそのプリセットの値が入力されます。JSON を手動で編集すると、ドロップダウンは **「Custom」** に戻ります。

## Agent での値へのアクセス

Agent でサポートされている任意の設定オプションから `requestContext` 引数にアクセスできます。これらの関数は同期または `async` にできます。`requestContext` から値を読み取るには `.get()` メソッドを使用します。

```typescript
export type UserTier = {
  'user-tier': 'enterprise' | 'pro'
}

export const weatherAgent = new Agent({
  id: 'weather-agent',
  name: 'Weather Agent',
  instructions: async ({ requestContext }) => {
    const userTier = requestContext.get('user-tier') as UserTier['user-tier']

    if (userTier === 'enterprise') {
    }
  },
  model: ({ requestContext }) => {},
  tools: ({ requestContext }) => {},
  memory: ({ requestContext }) => {},
})
```

`agents`、`workflows`、`scorers`、`inputProcessors`、`outputProcessors` などのほかのオプションでも `requestContext` を使用できます。

### 動的な指示

Agent の指示は非同期関数として指定できるため、実行時にプロンプトを解決できます。`requestContext` と組み合わせることで、次のようなパターンを実現できます。

- **パーソナライズ**: ユーザーの属性、設定、またはティアに基づいて指示を調整する
- **ローカライズ**: ロケールに基づいて口調、言語、または動作を調整する
- **A/B テスト**: 実験のために異なるプロンプトのバリエーションを提供する
- **外部プロンプト管理**: 再デプロイせずにレジストリサービスからプロンプトを取得する

```typescript
import { Agent } from '@mastra/core/agent'

export const dynamicAgent = new Agent({
  id: 'dynamic-agent',
  name: 'Dynamic Agent',
  instructions: async ({ requestContext }) => {
    const userTier = requestContext?.get('user-tier')
    const locale = requestContext?.get('locale')

    // Personalize based on user tier
    const basePrompt =
      userTier === 'enterprise'
        ? 'You are a premium support agent. Provide detailed, thorough responses with technical depth.'
        : 'You are a helpful assistant. Be concise and friendly.'

    // Localize behavior
    const localeInstructions = locale === 'ja' ? 'Respond in Japanese using formal keigo.' : ''

    return `${basePrompt} ${localeInstructions}`.trim()
  },
  model: 'openai/gpt-5.6-sol',
})
```

#### プロンプトレジストリからの取得

組織でプロンプトを一元管理するためにプロンプトレジストリサービスを使用している場合は、実行時に指示を取得できます。再デプロイせずにプロンプトを更新し、バリエーションを使った実験を実行できるほか、Agent 全体でのプロンプト使用状況を追跡できます。

```typescript
import { Agent } from '@mastra/core/agent'

// Your prompt registry client
import { promptRegistry } from '../lib/prompt-registry'

export const registryAgent = new Agent({
  id: 'registry-agent',
  name: 'Registry Agent',
  instructions: async ({ requestContext }) => {
    const prompt = await promptRegistry.getPrompt({
      promptId: 'customer-support-agent',
      // Pass context for variant selection or tracking
      variant: requestContext?.get('experiment-variant'),
      userId: requestContext?.get('user-id'),
    })

    return prompt.content
  },
  model: 'openai/gpt-5.6-sol',
})
```

設定オプションの全一覧については、[Agent](https://mastra.zisheng.pro/ja/reference/agents/agent)を参照してください。

## Workflow ステップでの値へのアクセス

Workflow ステップの `execute` 関数から `requestContext` 引数にアクセスできます。この関数は同期または非同期にできます。`requestContext` から値を読み取るには `.get()` メソッドを使用します。

```typescript
export type UserTier = {
  'user-tier': 'enterprise' | 'pro'
}

const stepOne = createStep({
  id: 'step-one',
  execute: async ({ requestContext }) => {
    const userTier = requestContext.get('user-tier') as UserTier['user-tier']

    if (userTier === 'enterprise') {
    }
  },
})
```

設定オプションの全一覧については、[createStep()](https://mastra.zisheng.pro/ja/reference/workflows/step)を参照してください。

## Tool での値へのアクセス

Tool の `execute` 関数から `requestContext` 引数にアクセスできます。この関数は `async` です。`requestContext` から値を読み取るには `.get()` メソッドを使用します。

```typescript
export type UserTier = {
  'user-tier': 'enterprise' | 'pro'
}

export const weatherTool = createTool({
  id: 'weather-tool',
  execute: async (inputData, context) => {
    const userTier = context?.requestContext?.get('user-tier') as UserTier['user-tier'] | undefined

    if (userTier === 'enterprise') {
    }
  },
})
```

設定オプションの全一覧については、[createTool()](https://mastra.zisheng.pro/ja/reference/tools/create-tool)を参照してください。

## 予約済みキー

Mastra はセキュリティのために特別なコンテキストキーを予約しています。これらのキーが設定されている場合、クライアントが指定した値より優先されます。サーバーは所有権を自動的に検証し、ユーザーが所有していないリソースへアクセスしようとすると 403 エラーを返します。

`MASTRA_RESOURCE_ID_KEY` を設定する最も簡単な方法は、認証設定で `mapUserToResourceId` コールバックを使用することです。

```typescript
auth: {
  authenticateToken: async token => verifyToken(token),
  mapUserToResourceId: user => user.id,
}
```

この方法でリソース ID を導出すると、クライアントは Agent の generate および stream リクエストボディから `memory.resource` を省略でき、代わりにサーバーが導出した値が使用されます（クライアントが指定した値より常に優先されます）。リクエストが Memory を使用しており、ボディにもリクエストコンテキストにもリソース ID が指定されていない場合、サーバーは 400 エラーを返します。

ミドルウェアでこれらのキーを手動で設定することもできます。

```typescript
import { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY } from '@mastra/core/request-context'

// In middleware: force memory operations to use authenticated user's ID
requestContext.set(MASTRA_RESOURCE_ID_KEY, user.id)

// In middleware: set validated thread ID
requestContext.set(MASTRA_THREAD_ID_KEY, threadId)
```

| キー                       | 目的                                                                                          |
| ------------------------ | ------------------------------------------------------------------------------------------- |
| `MASTRA_RESOURCE_ID_KEY` | すべての Memory 操作でこのリソース ID を強制的に使用します。サーバーは、アクセスされたスレッドがこのリソースに属することを検証し、属していない場合は 403 を返します。 |
| `MASTRA_THREAD_ID_KEY`   | クライアントが指定した値を上書きし、スレッド操作でこのスレッド ID を強制的に使用します。                                              |

これらのキーは、マルチテナントアプリケーションでユーザーを分離するために使用します。使用例については、[認可ミドルウェア](https://mastra.zisheng.pro/ja/docs/server/middleware)を参照してください。

## TypeScript サポート

`RequestContext` に型パラメーターを指定すると、すべてのメソッドに完全な型が付与されます。

```typescript
import { RequestContext } from '@mastra/core/request-context'

type MyContext = {
  userId: string
  maxTokens: number
  isPremium: boolean
}

const ctx = new RequestContext<MyContext>()

// set() enforces correct value types
ctx.set('userId', 'user-123') // ✓ valid
ctx.set('maxTokens', 4096) // ✓ valid
ctx.set('maxTokens', 'wrong') // ✗ TypeScript error: expected number

// get() returns the correct type automatically
const tokens = ctx.get('maxTokens') // inferred as number
const id = ctx.get('userId') // inferred as string

// keys() returns typed keys
for (const key of ctx.keys()) {
  // key is "userId" | "maxTokens" | "isPremium"
}

// entries() supports type narrowing
for (const [key, value] of ctx.entries()) {
  if (key === 'maxTokens') {
    // TypeScript knows value is number here
    console.log(value.toFixed(2))
  }
  if (key === 'userId') {
    // TypeScript knows value is string here
    console.log(value.toUpperCase())
  }
}
```

## スキーマ検証

`requestContextSchema` を使用して、実行時にリクエストコンテキストの値を検証する [Standard JSON Schema](https://standardschema.dev/json-schema)（[Zod](https://zod.dev/)、[Valibot](https://valibot.dev/)、[ArkType](https://arktype.io/) など）を定義します。これにより、欠落または無効なコンテキスト値を早期に検出して明確なエラーメッセージを提供できるほか、コンポーネント内で型推論を利用できます。

### Agent のスキーマ検証

Agent に `requestContextSchema` を定義すると、`generate()` または `stream()` の開始時にコンテキストが検証されます。検証に失敗した場合、LLM が呼び出される前に Agent が `MastraError` をスローします。

```typescript
import { Agent } from '@mastra/core/agent'
import { z } from 'zod'

export const validatedAgent = new Agent({
  id: 'validated-agent',
  name: 'Validated Agent',
  requestContextSchema: z.object({
    userId: z.string(),
    apiKey: z.string(),
  }),
  instructions: ({ requestContext }) => {
    // Access all values as a typed object
    const { userId, apiKey } = requestContext.all
    // { userId: string; apiKey: string }

    // Or retrieve individual values with .get()
    const id = requestContext.get('userId')
    // string

    return `You are helping user ${userId}`
  },
  model: 'openai/gpt-5.6-sol',
})
```

検証に失敗すると、エラーには Agent ID と、失敗したフィールドの詳細が含まれます。

```text
Request context validation failed for agent 'validated-agent':
- apiKey: Required
```

### Tool のスキーマ検証

Tool に `requestContextSchema` を定義すると、`execute()` の実行前にコンテキストが検証されます。Agent とは異なり、Tool は例外をスローせず、検証エラーオブジェクトを返します。

```typescript
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const validatedTool = createTool({
  id: 'validated-tool',
  description: 'A tool that requires authenticated context',
  inputSchema: z.object({
    query: z.string(),
  }),
  requestContextSchema: z.object({
    userId: z.string(),
  }),
  execute: async (inputData, context) => {
    // Access all values as a typed object
    const { userId } = context.requestContext?.all ?? {}
    // { userId: string }

    // Or retrieve individual values with .get()
    const id = context.requestContext?.get('userId')
    // string | undefined

    return { result: `Processed for ${userId}` }
  },
})
```

検証に失敗すると、Tool は例外をスローせず、エラーオブジェクトを返します。

```json
{
  "error": true,
  "message": "Request context validation failed for validated-tool. Please fix the following errors and try again:\n- userId: Required\n\nProvided context: {}"
}
```

### Workflow のスキーマ検証

Workflow に `requestContextSchema` を定義すると、`run.start()` の開始時にコンテキストが検証されます。検証に失敗した場合、いずれかのステップが実行される前に Workflow がエラーをスローします。

```typescript
import { createWorkflow, createStep } from '@mastra/core/workflows'
import { z } from 'zod'

// Define schema once and share between workflow and steps
const workflowContextSchema = z.object({
  tenantId: z.string(),
})

const step1 = createStep({
  id: 'step-1',
  inputSchema: z.object({ message: z.string() }),
  outputSchema: z.object({ result: z.string() }),
  // Add schema to step for type inference
  requestContextSchema: workflowContextSchema,
  execute: async ({ inputData, requestContext }) => {
    // Access all values as a typed object
    const { tenantId } = requestContext.all
    // { tenantId: string }

    // Or retrieve individual values with .get()
    const id = requestContext.get('tenantId')
    // string

    return { result: `Processed for tenant ${tenantId}` }
  },
})

export const validatedWorkflow = createWorkflow({
  id: 'validated-workflow',
  inputSchema: z.object({ message: z.string() }),
  outputSchema: z.object({ result: z.string() }),
  requestContextSchema: workflowContextSchema,
})
  .then(step1)
  .commit()
```

検証に失敗すると、Workflow はエラーをスローします。

```text
Request context validation failed for workflow 'validated-workflow':
- tenantId: Required
```

ステップに独自の `requestContextSchema` を定義して、ステップ単位で検証することもできます。ステップの検証は、そのステップの `execute()` 関数が実行される前に行われます。

### 検証の動作

| コンポーネント  | プロパティ                  | 検証のタイミング                       | 失敗時の動作             |
| -------- | ---------------------- | ------------------------------ | ------------------ |
| Agent    | `requestContextSchema` | `generate()` / `stream()` の開始時 | `MastraError` をスロー |
| Tool     | `requestContextSchema` | `execute()` の実行前               | エラーオブジェクトを返す       |
| Workflow | `requestContextSchema` | `run.start()` の開始時             | `Error` をスロー       |
| Step     | `requestContextSchema` | ステップの `execute()` の実行前         | エラーによりステップが失敗      |

### ベストプラクティス

**ミドルウェアと一致させる**: ミドルウェアで設定する必須フィールドと同じフィールドをスキーマに定義します。これにより、ミドルウェアとコンポーネント間の契約が明示され、検証されます。

```typescript
// Middleware sets these fields
requestContext.set('userId', user.id)
requestContext.set('tenantId', tenant.id)

// Schema validates they exist
requestContextSchema: z.object({
  userId: z.string(),
  tenantId: z.string(),
})
```

**条件付きコンテキストにはオプションフィールドを使用する**: 常に存在するとは限らない値には `.optional()` を使用します。

```typescript
requestContextSchema: z.object({
  userId: z.string(), // Always required
  experimentVariant: z.string().optional(), // May not be set
})
```

**Tool の検証エラーを処理する**: Tool は例外をスローせずにエラーオブジェクトを返すため、Tool の実行が重要な場合は Agent または Workflow のロジックでエラーを確認してください。

## 関連情報

- [Agent の Request Context](https://mastra.zisheng.pro/ja/docs/memory/overview)
- [Workflow の Request Context](https://mastra.zisheng.pro/ja/docs/workflows/overview)
- [サーバーミドルウェア](https://mastra.zisheng.pro/ja/docs/server/middleware)
- [認可ミドルウェア](https://mastra.zisheng.pro/ja/docs/server/middleware)