@mastra/claude 0.1.1-alpha.0 → 0.2.0-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @mastra/claude
 
+## 0.2.0-alpha.1
+
+### Minor Changes
+
+- Added structured output support for Claude and OpenAI SDK agents using their provider-native structured output APIs. Cursor SDK agent calls now fail clearly when structuredOutput is requested because the Cursor TypeScript SDK does not expose a schema-constrained output API. SDK agents now implement provider-native resume through Mastra's existing resumeGenerate/resumeStream methods by accepting provider-specific resumeData with a message payload. Cursor SDK agent options now use the same clear source split as OpenAI: pass either a pre-created agent or SDK options for wrapper-created agents. ([#17580](https://github.com/mastra-ai/mastra/pull/17580))
+
+  Example:
+
+  ```ts
+  await claudeAgent.resumeGenerate({
+    message: 'Continue the task.',
+    sessionId: 'claude-session-id',
+  });
+
+  await openAIAgent.resumeStream({
+    message: 'Continue the task.',
+    previousResponseId: 'resp_123',
+  });
+
+  const result = await openAIAgent.generate('Return the answer as JSON.', {
+    structuredOutput: {
+      schema: z.object({ answer: z.string() }),
+    },
+  });
+  // result.object has shape { answer: string }
+  ```
+
+  Claude and OpenAI SDK agents support `structuredOutput` through their native SDK APIs. `CursorSDKAgent` throws a clear error when `structuredOutput` is requested because the Cursor TypeScript SDK does not expose schema-constrained output.
+
+### Patch Changes
+
+- Updated dependencies [[`575f815`](https://github.com/mastra-ai/mastra/commit/575f815c5c3567b71c0b83cbb7fa98c8253a9d9c), [`306909a`](https://github.com/mastra-ai/mastra/commit/306909a693de77d709b38706e2673c9547d24a28), [`5191af8`](https://github.com/mastra-ai/mastra/commit/5191af80c799eea25357c545fc05d91b3883531d), [`43bd3d4`](https://github.com/mastra-ai/mastra/commit/43bd3d421987463fdf35386a45199c49499ed069), [`e6fa79e`](https://github.com/mastra-ai/mastra/commit/e6fa79ec72a2ddffdd25e85270398951e9d552a4), [`904bcdf`](https://github.com/mastra-ai/mastra/commit/904bcdf7b8004aa7be823f9f70ca63580e47e470), [`7f5ee1d`](https://github.com/mastra-ai/mastra/commit/7f5ee1dca46daee8d2817f2ebe49e6335da81956), [`1e9aab5`](https://github.com/mastra-ai/mastra/commit/1e9aab50ff11e6e88fde4d7cbf512c44a9fe8d61), [`bf8eb6d`](https://github.com/mastra-ai/mastra/commit/bf8eb6d0ec213a403eb9265a594ad283c44ab3dc), [`493a328`](https://github.com/mastra-ai/mastra/commit/493a328f4346a1deeb9f1e2e44c8f2a3a4d7591b), [`029a414`](https://github.com/mastra-ai/mastra/commit/029a4141719793bd3e898a39eb5a0466a55f5f3a), [`b147b29`](https://github.com/mastra-ai/mastra/commit/b147b2907f0cd1aa812efe6d6e3f58d22e66fc88), [`d371ac1`](https://github.com/mastra-ai/mastra/commit/d371ac1d9820afaaf7cfdbc380a475946a994d8f), [`cf182b7`](https://github.com/mastra-ai/mastra/commit/cf182b7fb495767946d9840ef29f19cfa906f31f), [`a049c2a`](https://github.com/mastra-ai/mastra/commit/a049c2a9dfb41d0ee2e7a28874a88cd64fd5669f), [`b147b29`](https://github.com/mastra-ai/mastra/commit/b147b2907f0cd1aa812efe6d6e3f58d22e66fc88), [`2a96528`](https://github.com/mastra-ai/mastra/commit/2a9652848dfa3c5a2426f952e9d93554c26fd90f), [`2656d9c`](https://github.com/mastra-ai/mastra/commit/2656d9c2976d4f3354253bfbbbf9b88a1b2bbf34), [`63e3fe1`](https://github.com/mastra-ai/mastra/commit/63e3fe13cc1ea96f91d7c68aea92f400faf9e4da), [`1d4ce8d`](https://github.com/mastra-ai/mastra/commit/1d4ce8daaa54511f325c1b609d31b8e54009d677), [`8c68372`](https://github.com/mastra-ai/mastra/commit/8c68372e85fe0b066ec12c58bd29ffb93e54c552)]:
+  - @mastra/core@1.42.0-alpha.4
+
 ## 0.1.1-alpha.0
 
 ### Patch Changes

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-claude
 description: Documentation for @mastra/claude. Use when working with @mastra/claude APIs, configuration, or implementation.
 metadata:
   package: "@mastra/claude"
-  version: "0.1.1-alpha.0"
+  version: "0.2.0-alpha.1"
 ---
 
 ## When to use
@@ -16,7 +16,7 @@ Read the individual reference documents for detailed explanations and code examp
 
 ### Docs
 
-- [SDK agents](references/docs-agents-sdk-agents.md) - Use Claude Agent SDK and Cursor Agent SDK agents from Mastra.
+- [SDK agents](references/docs-agents-sdk-agents.md) - Use Claude Agent SDK, Cursor Agent SDK, and OpenAI Agents SDK agents from Mastra.
 
 
 Read [assets/SOURCE_MAP.json](assets/SOURCE_MAP.json) for source code references.

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.1-alpha.0",
+  "version": "0.2.0-alpha.1",
   "package": "@mastra/claude",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-agents-sdk-agents.md

@@ -13,6 +13,7 @@ SDK agents let you use other agent SDK frameworks inside Mastra. Use them to reg
 
 - [Claude Agent SDK](#claude-agent-sdk): Use `@mastra/claude` to register a Claude SDK agent and call it with Mastra `generate()` and `stream()`.
 - [Cursor Agent SDK](#cursor-agent-sdk): Use `@mastra/cursor` to register a Cursor SDK agent and call it with Mastra `generate()` and `stream()`.
+- [OpenAI Agents SDK](#openai-agents-sdk): Use `@mastra/openai` to register an OpenAI SDK agent and call it with Mastra `generate()` and `stream()`.
 
 ## Claude Agent SDK
 
@@ -216,6 +217,117 @@ export const cursorSDKAgent = new CursorSDKAgent({
 })
 ```
 
+## OpenAI Agents SDK
+
+Use `@mastra/openai` to register an OpenAI Agents SDK agent in Mastra while keeping OpenAI-specific agent settings in OpenAI SDK options.
+
+### Install OpenAI packages
+
+Install the Mastra package and the OpenAI Agents SDK peer dependency:
+
+**npm**:
+
+```bash
+npm install @mastra/openai @openai/agents zod
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/openai @openai/agents zod
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/openai @openai/agents zod
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/openai @openai/agents zod
+```
+
+Set the OpenAI SDK credential:
+
+```bash
+export OPENAI_API_KEY="..."
+```
+
+### Create an OpenAI SDK agent
+
+Configure OpenAI Agents SDK through `sdkOptions`. `OpenAISDKAgent` creates the OpenAI SDK agent on first use.
+
+```typescript
+import { OpenAISDKAgent } from '@mastra/openai'
+
+export const openaiSDKAgent = new OpenAISDKAgent({
+  id: 'openai-sdk-agent',
+  name: 'OpenAI SDK Agent',
+  description: 'Use OpenAI Agents SDK through Mastra.',
+  sdkOptions: {
+    name: 'Repository assistant',
+    instructions: 'Answer clearly and cite the relevant files.',
+    model: 'gpt-5',
+  },
+})
+```
+
+### Use an existing OpenAI SDK agent
+
+If your app already creates an OpenAI SDK agent, pass that agent to `OpenAISDKAgent` instead:
+
+```typescript
+import { Agent as OpenAIAgent } from '@openai/agents'
+import { OpenAISDKAgent } from '@mastra/openai'
+
+const sdkAgent = new OpenAIAgent({
+  name: 'Repository assistant',
+  instructions: 'Answer clearly and cite the relevant files.',
+  model: 'gpt-5',
+})
+
+export const openaiSDKAgent = new OpenAISDKAgent({
+  id: 'openai-sdk-agent',
+  name: 'OpenAI SDK Agent',
+  description: 'Use OpenAI Agents SDK through Mastra.',
+  agent: sdkAgent,
+})
+```
+
+### Add OpenAI SDK tools
+
+OpenAI Agents SDK tools are configured with OpenAI SDK options. Create tools with the OpenAI SDK, then pass them through `sdkOptions.tools`.
+
+```typescript
+import { tool } from '@openai/agents'
+import { OpenAISDKAgent } from '@mastra/openai'
+import { z } from 'zod'
+
+const getTemperature = tool({
+  name: 'get_temperature',
+  description: 'Get the current temperature for a city.',
+  parameters: z.object({
+    city: z.string(),
+  }),
+  execute: async ({ city }) => {
+    return `${city}: 27 C`
+  },
+})
+
+export const openaiSDKAgent = new OpenAISDKAgent({
+  id: 'openai-sdk-agent',
+  name: 'OpenAI SDK Agent',
+  description: 'Use OpenAI Agents SDK through Mastra.',
+  sdkOptions: {
+    name: 'Weather assistant',
+    model: 'gpt-5',
+    tools: [getTemperature],
+  },
+})
+```
+
 ## Register SDK agents
 
 Register SDK agents in the Mastra instance like other agents:
@@ -224,11 +336,13 @@ Register SDK agents in the Mastra instance like other agents:
 import { Mastra } from '@mastra/core'
 import { claudeSDKAgent } from './agents/claude-sdk-agent'
 import { cursorSDKAgent } from './agents/cursor-sdk-agent'
+import { openaiSDKAgent } from './agents/openai-sdk-agent'
 
 export const mastra = new Mastra({
   agents: {
     claudeSDKAgent,
     cursorSDKAgent,
+    openaiSDKAgent,
   },
 })
 ```
@@ -246,11 +360,61 @@ for await (const chunk of stream.textStream) {
 }
 ```
 
+## Resume SDK runs
+
+SDK agents support Mastra `resumeGenerate()` and `resumeStream()` with provider-native resume data. Pass the message to continue with and the resume identifier used by the underlying SDK.
+
+Claude SDK agents can resume a known session with `sessionId`:
+
+```typescript
+const result = await claudeSDKAgent.resumeGenerate({
+  message: 'Continue the previous task.',
+  sessionId: 'claude-session-id',
+})
+
+console.log(result.text)
+```
+
+OpenAI SDK agents can resume with a previous response, conversation, or session:
+
+```typescript
+const stream = await openaiSDKAgent.resumeStream({
+  message: 'Continue the previous task.',
+  previousResponseId: 'resp_123',
+})
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk)
+}
+```
+
+Cursor SDK agents can continue with the wrapped SDK agent. If you need to resume a stored Cursor SDK agent by ID, pass `agentId` in `resumeData`.
+
+## Structured output
+
+Claude and OpenAI SDK agents support Mastra `structuredOutput` through their provider-native structured output APIs. The validated value is available on `result.object`.
+
+```typescript
+import { z } from 'zod'
+
+const result = await openaiSDKAgent.generate<{ summary: string }>('Summarize this project.', {
+  structuredOutput: {
+    schema: z.object({
+      summary: z.string(),
+    }),
+  },
+})
+
+console.log(result.object.summary)
+```
+
+Cursor SDK agents throw a clear error when `structuredOutput` is requested because the Cursor TypeScript SDK doesn't expose a schema-constrained output API.
+
 ## Observability
 
 SDK agents create Mastra agent and model spans for `generate()` and `stream()` calls. Mastra records SDK-provided usage, tool activity, and provider metadata when the vendor SDK exposes those events.
 
-Claude SDK runs can include SDK-estimated cost from the Claude result message. Cursor SDK runs include token usage from Cursor interaction updates.
+Claude SDK runs can include SDK-estimated cost from the Claude result message. Cursor SDK runs include token usage from Cursor interaction updates. OpenAI SDK runs include token usage from OpenAI run state.
 
 For storage and dashboard setup, see [Observability](https://mastra.ai/docs/observability/overview).
 

package/dist/index.cjs

@@ -8,6 +8,7 @@ var requestContext = require('@mastra/core/request-context');
 var stream = require('@mastra/core/stream');
 var messageList = require('@mastra/core/agent/message-list');
 var observability = require('@mastra/core/observability');
+var schema = require('@mastra/core/schema');
 
 // src/index.ts
 function createNoopModel({ modelId, provider }) {
@@ -35,7 +36,8 @@ function createCompletedMastraStream({
   modelId,
   usage,
   providerMetadata,
-  costContext
+  costContext,
+  object
 }) {
   return new web.ReadableStream({
     start(controller) {
@@ -60,7 +62,8 @@ function createCompletedMastraStream({
         modelId,
         usage,
         providerMetadata,
-        costContext
+        costContext,
+        object
       });
       controller.close();
     }
@@ -109,7 +112,8 @@ function toFullOutput({
     modelId: result.response.modelId,
     usage: toLanguageModelUsage(result.usage),
     providerMetadata: result.providerMetadata,
-    costContext: result.costContext
+    costContext: result.costContext,
+    object: result.object
   });
   return createMastraOutput({
     messages,
@@ -488,7 +492,8 @@ function enqueueFinishChunks(controller, {
   modelId,
   usage,
   providerMetadata,
-  costContext
+  costContext,
+  object
 }) {
   const timestamp = /* @__PURE__ */ new Date();
   const response = {
@@ -512,6 +517,14 @@ function enqueueFinishChunks(controller, {
       providerMetadata
     }
   });
+  if (object !== void 0) {
+    controller.enqueue({
+      type: "object-result",
+      runId,
+      from: stream.ChunkFrom.AGENT,
+      object
+    });
+  }
   controller.enqueue({
     type: "step-finish",
     runId,
@@ -616,6 +629,48 @@ function promptToText(prompt) {
   }
   return "";
 }
+function getStructuredOutputSchema(structuredOutput) {
+  if (!structuredOutput?.schema) {
+    return void 0;
+  }
+  return schema.standardSchemaToJSONSchema(schema.toStandardSchema(structuredOutput.schema));
+}
+async function getStructuredOutputFromValue(value, structuredOutput) {
+  if (!structuredOutput?.schema) {
+    return void 0;
+  }
+  let parsed;
+  if (typeof value === "string") {
+    try {
+      parsed = JSON.parse(value);
+    } catch (error) {
+      return handleStructuredOutputError(
+        new Error("Structured output must be valid JSON.", { cause: error }),
+        structuredOutput
+      );
+    }
+  } else {
+    parsed = value;
+  }
+  const schema$1 = schema.toStandardSchema(structuredOutput.schema);
+  const result = await schema$1["~standard"].validate(parsed);
+  if (!result.issues) {
+    return result.value;
+  }
+  const message = result.issues.map((issue) => `- ${issue.path?.join(".") || "root"}: ${issue.message}`).join("\n");
+  return handleStructuredOutputError(new Error(`Structured output validation failed:
+${message}`), structuredOutput);
+}
+function handleStructuredOutputError(error, structuredOutput) {
+  if (structuredOutput.errorStrategy === "fallback") {
+    return structuredOutput.fallbackValue;
+  }
+  if (structuredOutput.errorStrategy === "warn") {
+    structuredOutput.logger?.warn(error.message);
+    return void 0;
+  }
+  throw error;
+}
 function sumDefined(...values) {
   const defined = values.filter((value) => typeof value === "number");
   if (defined.length === 0) {
@@ -676,9 +731,7 @@ var ClaudeSDKAgent = class extends agent.Agent {
     });
     let result;
     try {
-      result = await telemetry.execute(
-        () => runClaudeGenerate(prompt, this.options, telemetry, options?.abortSignal ?? options?.signal)
-      );
+      result = await telemetry.execute(() => runClaudeGenerate(prompt, this.options, telemetry, options));
       telemetry.endGenerate(result);
     } catch (error) {
       telemetry.fail(error);
@@ -689,7 +742,7 @@ var ClaudeSDKAgent = class extends agent.Agent {
       runId,
       provider: PROVIDER,
       result,
-      options: telemetry.outputOptions()
+      options: { ...telemetry.outputOptions(), structuredOutput: options?.structuredOutput }
     });
   }
   async stream(messages, options) {
@@ -722,26 +775,82 @@ var ClaudeSDKAgent = class extends agent.Agent {
       runId,
       modelId,
       provider: PROVIDER,
-      stream: telemetry.wrapStream(
-        runClaudeAsMastraStream(prompt, this.options, runId, telemetry, options?.abortSignal ?? options?.signal)
-      ),
-      options: telemetry.outputOptions()
+      stream: telemetry.wrapStream(runClaudeAsMastraStream(prompt, this.options, runId, telemetry, options)),
+      options: { ...telemetry.outputOptions(), structuredOutput: options?.structuredOutput }
     });
   }
+  async resumeGenerate(resumeData, options) {
+    const data = validateClaudeResumeData(resumeData);
+    return this.generate(data.message, createClaudeResumeRunOptions(data, options));
+  }
+  async resumeStream(resumeData, options) {
+    const data = validateClaudeResumeData(resumeData);
+    return this.stream(data.message, createClaudeResumeRunOptions(data, options));
+  }
 };
-async function runClaudeGenerate(prompt, options, telemetry, signal) {
+function validateClaudeResumeData(resumeData) {
+  if (!isRecord(resumeData) || !("message" in resumeData)) {
+    throw new Error("ClaudeSDKAgent resumeData must include a message.");
+  }
+  const hasSessionId = "sessionId" in resumeData;
+  const hasContinue = "continue" in resumeData;
+  if (hasSessionId && hasContinue) {
+    throw new Error("ClaudeSDKAgent resumeData must include either sessionId or continue: true, not both.");
+  }
+  if (hasSessionId) {
+    if (typeof resumeData.sessionId !== "string") {
+      throw new Error("ClaudeSDKAgent resumeData.sessionId must be a string.");
+    }
+    return resumeData;
+  }
+  if (hasContinue) {
+    if (resumeData.continue !== true) {
+      throw new Error("ClaudeSDKAgent resumeData.continue must be true when provided.");
+    }
+    return resumeData;
+  }
+  throw new Error("ClaudeSDKAgent resumeData must include sessionId or continue: true.");
+}
+function createClaudeResumeRunOptions(resumeData, options) {
+  const sdkOptions = { ...options?.sdkOptions };
+  if ("sessionId" in resumeData && typeof resumeData.sessionId === "string") {
+    sdkOptions.resume = resumeData.sessionId;
+    if (resumeData.forkSession !== void 0) {
+      sdkOptions.forkSession = resumeData.forkSession;
+    }
+    if (resumeData.resumeSessionAt !== void 0) {
+      sdkOptions.resumeSessionAt = resumeData.resumeSessionAt;
+    }
+  } else {
+    sdkOptions.continue = true;
+  }
+  return {
+    ...options,
+    sdkOptions
+  };
+}
+async function runClaudeGenerate(prompt, options, telemetry, runOptions) {
   let text = "";
+  let structuredOutputValue;
   const usage = createClaudeUsageCollector();
-  for await (const message of observeClaudeMessages(runClaude(prompt, options, signal), telemetry)) {
+  for await (const message of observeClaudeMessages(
+    runClaude(prompt, options, runOptions?.abortSignal ?? runOptions?.signal, runOptions),
+    telemetry
+  )) {
     usage.record(message);
     if (message.type === "result") {
       if (message.subtype !== "success") {
         throw new Error(message.errors.join("\n") || `Claude Agent SDK failed with ${message.subtype}`);
       }
       text = message.result;
+      structuredOutputValue = getClaudeStructuredOutput(message);
     }
   }
   const totals = usage.totals();
+  const object = await getStructuredOutputFromValue(
+    structuredOutputValue === void 0 ? text : structuredOutputValue,
+    runOptions?.structuredOutput
+  );
   return {
     content: [{ type: "text", text }],
     finishReason: { unified: "stop", raw: "stop" },
@@ -752,10 +861,11 @@ async function runClaudeGenerate(prompt, options, telemetry, signal) {
       timestamp: /* @__PURE__ */ new Date()
     },
     providerMetadata: getClaudeProviderMetadata(options, totals),
-    costContext: getClaudeCostContext(options, totals)
+    costContext: getClaudeCostContext(options, totals),
+    object
   };
 }
-function runClaudeAsMastraStream(prompt, options, runId, telemetry, signal) {
+function runClaudeAsMastraStream(prompt, options, runId, telemetry, runOptions) {
   return new web.ReadableStream({
     start: async (controller) => {
       const textId = crypto.randomUUID();
@@ -763,6 +873,7 @@ function runClaudeAsMastraStream(prompt, options, runId, telemetry, signal) {
       const modelId = getModelId(options);
       const usage = createClaudeUsageCollector();
       let text = "";
+      let structuredOutputValue;
       let sawDelta = false;
       try {
         enqueueStartChunks(controller, {
@@ -773,7 +884,10 @@ function runClaudeAsMastraStream(prompt, options, runId, telemetry, signal) {
           modelId,
           providerMetadata: getClaudeProviderMetadata(options, usage.totals())
         });
-        for await (const message of observeClaudeMessages(runClaude(prompt, options, signal), telemetry)) {
+        for await (const message of observeClaudeMessages(
+          runClaude(prompt, options, runOptions?.abortSignal ?? runOptions?.signal, runOptions),
+          telemetry
+        )) {
           usage.record(message);
           const delta = getTextDelta(message);
           if (delta) {
@@ -789,6 +903,7 @@ function runClaudeAsMastraStream(prompt, options, runId, telemetry, signal) {
               text += message.result;
               enqueueTextDelta(controller, runId, textId, message.result);
             }
+            structuredOutputValue = getClaudeStructuredOutput(message);
           }
         }
         const totals = usage.totals();
@@ -802,7 +917,11 @@ function runClaudeAsMastraStream(prompt, options, runId, telemetry, signal) {
           modelId,
           usage: usage.toLanguageModelUsage(),
           providerMetadata,
-          costContext: getClaudeCostContext(options, totals)
+          costContext: getClaudeCostContext(options, totals),
+          object: await getStructuredOutputFromValue(
+            structuredOutputValue === void 0 ? text : structuredOutputValue,
+            runOptions?.structuredOutput
+          )
         });
         controller.close();
       } catch (error) {
@@ -817,11 +936,19 @@ function runClaudeAsMastraStream(prompt, options, runId, telemetry, signal) {
     }
   });
 }
-function runClaude(prompt, options, signal) {
+function runClaude(prompt, options, signal, runOptions) {
   const abortController = createAbortController(signal);
   const queryOptions = {
-    ...options.sdkOptions
+    ...options.sdkOptions,
+    ...runOptions?.sdkOptions
   };
+  const outputSchema = getStructuredOutputSchema(runOptions?.structuredOutput);
+  if (outputSchema) {
+    queryOptions.outputFormat = {
+      type: "json_schema",
+      schema: outputSchema
+    };
+  }
   if (abortController) {
     queryOptions.abortController = abortController;
   }
@@ -830,6 +957,12 @@ function runClaude(prompt, options, signal) {
     options: queryOptions
   });
 }
+function getClaudeStructuredOutput(message) {
+  if (message.type !== "result") {
+    return void 0;
+  }
+  return message.structured_output;
+}
 async function* observeClaudeMessages(messages, telemetry) {
   for await (const message of messages) {
     recordClaudeToolTelemetry(message, telemetry);