Wire request context through dataset experiments (#17597)

Co-authored-by: Mastra Code (anthropic/claude-opus-4-8)
Co-authored-by: YJ <yj@example.com>
Co-authored-by: Mastra Code (anthropic/claude-opus-4-8) <noreply@mastra.ai>

Author: 3 people

.changeset/heavy-flowers-count.md

@@ -0,0 +1,14 @@
+---
+'@mastra/core': patch
+---
+
+Fixed per-item request context being dropped for inline experiment data. When running an experiment with inline `data`, each item's `requestContext` is now passed to the agent or workflow and merged over the global request context (per-item values win on key collisions), matching the behavior of storage-backed datasets.
+
+```ts
+await dataset.startExperiment({
+  data: [{ input: { prompt: 'Hello' }, requestContext: { clinicId: 'clinic-1' } }],
+  targetType: 'agent',
+  targetId: 'support-agent',
+});
+// Tools can now read clinicId from requestContext during inline experiments
+```

.changeset/silver-trees-attend.md

@@ -0,0 +1,32 @@
+---
+'@internal/playground': patch
+---
+
+Wire request context into dataset experiments in Studio.
+
+You can now define a dataset's `requestContextSchema` when creating or editing a dataset. You can set per-item `requestContext` values on dataset items. You can also provide run-level request context when triggering an experiment.
+
+The run dialog renders a schema-driven form when the dataset declares a `requestContextSchema`, and falls back to a raw JSON editor otherwise. This lets values like `clinicId` flow from Studio through to agent/workflow experiment runs.
+
+```ts
+// 1. Dataset declares the request context it expects
+const dataset = await client.createDataset({
+  name: 'patients',
+  requestContextSchema: { type: 'object', properties: { clinicId: { type: 'string' } } },
+});
+
+// 2. A dataset item provides per-item request context
+await client.addDatasetItem({
+  datasetId: dataset.id,
+  input: { patientId: 'p-123' },
+  requestContext: { clinicId: 'clinic-a' },
+});
+
+// 3. Triggering an experiment can supply run-level request context
+await client.triggerDatasetExperiment({
+  datasetId: dataset.id,
+  targetType: 'agent',
+  targetId: 'clinicDirectAgent',
+  requestContext: { clinicId: 'clinic-a' },
+});
+```

examples/agent/request-context-presets.json

@@ -39,5 +39,15 @@
       "advancedTools": false,
       "analytics": false
     }
+  },
+  "clinic-a": {
+    "clinicId": "clinic-a",
+    "environment": "production",
+    "userId": "clinician-001"
+  },
+  "clinic-b": {
+    "clinicId": "clinic-b",
+    "environment": "production",
+    "userId": "clinician-002"
   }
 }

examples/agent/src/mastra/agents/clinic-context-agents.ts

@@ -0,0 +1,53 @@
+import { Agent } from '@mastra/core/agent';
+import { clinicLookupTool } from '../tools/clinic-tools';
+
+/**
+ * Clinic Context Agents
+ *
+ * Test agents for verifying requestContext propagation through dataset
+ * experiments in multi-tenant clinic scenarios.
+ *
+ * - clinicDirectAgent: calls clinicLookupTool directly
+ * - clinicSupervisorAgent: delegates to clinicSpecialistAgent, which calls clinicLookupTool
+ *
+ * The tool throws if clinicId is missing from requestContext, so experiment
+ * items fail visibly instead of hanging silently.
+ */
+
+export const clinicDirectAgent = new Agent({
+  id: 'clinic-direct-agent',
+  name: 'Clinic Direct Agent',
+  description: 'Looks up patient records directly. Requires clinicId in requestContext.',
+  instructions: `You are a clinic assistant that looks up patient records.
+Always use the clinic-lookup tool to retrieve patient information.
+Include the clinicId and patientId in your response so the caller can verify tenant isolation.`,
+  model: 'openai/gpt-5.4-mini',
+  tools: {
+    clinicLookupTool,
+  },
+});
+
+export const clinicSpecialistAgent = new Agent({
+  id: 'clinic-specialist-agent',
+  name: 'Clinic Specialist Agent',
+  description: 'Specialist sub-agent that looks up patient records. Requires clinicId in requestContext.',
+  instructions: `You are a clinical specialist. When asked to look up patient data, use the clinic-lookup tool.
+Always include the clinicId and patientId in your response.`,
+  model: 'openai/gpt-5.4-mini',
+  tools: {
+    clinicLookupTool,
+  },
+});
+
+export const clinicSupervisorAgent = new Agent({
+  id: 'clinic-supervisor-agent',
+  name: 'Clinic Supervisor Agent',
+  description: 'Supervisor agent that delegates patient lookups to the specialist sub-agent. Tests requestContext propagation through agent delegation.',
+  instructions: `You are a clinic supervisor. When a user asks you to look up patient data, delegate the task to the clinic-specialist-agent.
+Do not look up records yourself — always hand off to the specialist.
+Report back the specialist's response, including the clinicId they used.`,
+  model: 'openai/gpt-5.4-mini',
+  agents: {
+    clinicSpecialistAgent,
+  },
+});

examples/agent/src/mastra/index.ts

@@ -88,6 +88,7 @@ import {
 } from './processors/index';
 import { gatewayAgent } from './agents/gateway';
 import { codeModeAgent } from './agents/code-mode-agent';
+import { clinicDirectAgent, clinicSpecialistAgent, clinicSupervisorAgent } from './agents/clinic-context-agents';
 
 const libsqlStore = new LibSQLStore({
   id: 'mastra-storage',
@@ -132,6 +133,9 @@ export const mastra = new Mastra({
     cryptoResearchAgent,
     slackDemoAgent,
     codeModeAgent,
+    clinicDirectAgent,
+    clinicSpecialistAgent,
+    clinicSupervisorAgent,
   },
   processors: {
     moderationProcessor,

examples/agent/src/mastra/tools/clinic-tools.ts

@@ -0,0 +1,42 @@
+import { createTool } from '@mastra/core/tools';
+import { z } from 'zod';
+
+/**
+ * Clinic-aware patient lookup tool.
+ *
+ * Requires `clinicId` in requestContext — the tool throws if the value is
+ * absent so that missing-tenant failures surface immediately instead of
+ * silently hanging during dataset experiment runs.
+ */
+export const clinicLookupTool = createTool({
+  id: 'clinic-lookup',
+  description: 'Looks up patient records for the current clinic tenant. Requires a clinicId in requestContext.',
+  inputSchema: z.object({
+    patientId: z.string().describe('The patient ID to look up'),
+  }),
+  requestContextSchema: z.object({
+    clinicId: z.string(),
+  }),
+  execute: async ({ patientId }, { requestContext }) => {
+    const clinicId = requestContext?.get('clinicId') as string | undefined;
+
+    if (!clinicId) {
+      throw new Error(
+        'clinicId is missing from requestContext. The tool cannot execute without tenant isolation.',
+      );
+    }
+
+    return {
+      clinicId,
+      patientId,
+      tenant: clinicId,
+      status: 'success',
+      record: {
+        patientId,
+        clinicId,
+        lastVisit: '2026-06-01',
+        diagnosis: 'routine checkup',
+      },
+    };
+  },
+});

packages/core/src/datasets/experiment/__tests__/runExperiment.test.ts

@@ -553,6 +553,32 @@ describe('runExperiment', () => {
       expect(result.results[0].input).toEqual({ prompt: 'from-factory' });
     });
 
+    // Test 2b — Per-item requestContext on inline data reaches agent.generate
+    it('forwards per-item requestContext from inline data, merged over the global context', async () => {
+      const mockAgent = createMockAgent('Response');
+      const localMastra = {
+        ...mastra,
+        getAgent: vi.fn().mockReturnValue(mockAgent),
+        getAgentById: vi.fn().mockReturnValue(mockAgent),
+      } as unknown as Mastra;
+
+      await runExperiment(localMastra, {
+        datasetId,
+        data: [{ input: { prompt: 'Hello' }, requestContext: { clinicId: 'clinic-1' } }],
+        targetType: 'agent',
+        targetId: 'test-agent',
+        // Global context — per-item value should win on key collision
+        requestContext: { clinicId: 'global-clinic', environment: 'development' },
+      });
+
+      const callOptions = (mockAgent.generate as ReturnType<typeof vi.fn>).mock.calls[0][1];
+      expect(callOptions.requestContext).toBeInstanceOf(RequestContext);
+      expect(callOptions.requestContext.all).toEqual({
+        clinicId: 'clinic-1',
+        environment: 'development',
+      });
+    });
+
     // Test 3 — Inline task function
     it('runs experiment with inline task function', async () => {
       const result = await runExperiment(mastra, {

packages/core/src/datasets/experiment/index.ts

@@ -122,6 +122,7 @@ export async function runExperiment(mastra: Mastra, config: ExperimentConfig): P
           datasetVersion: null,
           input: dataItem.input,
           groundTruth: dataItem.groundTruth,
+          requestContext: dataItem.requestContext,
           metadata: dataItem.metadata,
           resumeSteps: dataItem.resumeSteps,
           resumeData: dataItem.resumeData,

packages/core/src/datasets/experiment/types.ts

@@ -17,6 +17,8 @@ export interface DataItem<I = unknown, E = unknown> {
   groundTruth?: E;
   /** Additional metadata */
   metadata?: Record<string, unknown>;
+  /** Per-item request context merged over the global request context (item takes precedence) */
+  requestContext?: Record<string, unknown>;
   /**
    * Resume data for suspended workflow steps, keyed by step ID.
    * When a workflow suspends during experiment execution, the executor

packages/playground/src/domains/datasets/components/add-item-dialog.tsx

@@ -69,6 +69,7 @@ export function AddItemDialog({ datasetId, open, onOpenChange, onSuccess }: AddI
   const [input, setInput] = useState('{}');
   const [groundTruth, setGroundTruth] = useState('');
   const [expectedTrajectory, setExpectedTrajectory] = useState('');
+  const [requestContext, setRequestContext] = useState('');
   const [validationErrors, setValidationErrors] = useState<SchemaValidationError | null>(null);
   const { addItem } = useDatasetMutations();
 
@@ -105,12 +106,24 @@ export function AddItemDialog({ datasetId, open, onOpenChange, onSuccess }: AddI
       }
     }
 
+    // Parse requestContext if provided
+    let parsedRequestContext: Record<string, unknown> | undefined;
+    if (requestContext.trim()) {
+      try {
+        parsedRequestContext = JSON.parse(requestContext);
+      } catch {
+        toast.error('Request Context must be valid JSON');
+        return;
+      }
+    }
+
     try {
       await addItem.mutateAsync({
         datasetId,
         input: parsedInput,
         groundTruth: parsedGroundTruth,
         expectedTrajectory: parsedTrajectory,
+        requestContext: parsedRequestContext,
       });
 
       toast.success('Item added successfully');
@@ -120,6 +133,7 @@ export function AddItemDialog({ datasetId, open, onOpenChange, onSuccess }: AddI
       setInput('{}');
       setGroundTruth('');
       setExpectedTrajectory('');
+      setRequestContext('');
       onOpenChange(false);
 
       onSuccess?.();
@@ -154,6 +168,7 @@ export function AddItemDialog({ datasetId, open, onOpenChange, onSuccess }: AddI
     setInput('{}');
     setGroundTruth('');
     setExpectedTrajectory('');
+    setRequestContext('');
     setValidationErrors(null);
     onOpenChange(false);
   };
@@ -197,6 +212,16 @@ export function AddItemDialog({ datasetId, open, onOpenChange, onSuccess }: AddI
               />
             </div>
 
+            <div className="space-y-2">
+              <Label htmlFor="item-request-context">Request Context (JSON, optional)</Label>
+              <CodeEditor
+                value={requestContext}
+                onChange={setRequestContext}
+                showCopyButton={false}
+                className="min-h-[80px]"
+              />
+            </div>
+
             <div className="flex justify-end gap-2 pt-4">
               <Button type="button" onClick={handleCancel}>
                 Cancel