@mastra/openai 1.0.1-alpha.9 → 1.0.3

package/CHANGELOG.md

@@ -0,0 +1,126 @@
+# @mastra/openai
+
+## 0.1.0
+
+### 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.
+
+- Added `@mastra/openai`, a new package for using OpenAI Agents SDK agents in Mastra. ([#17525](https://github.com/mastra-ai/mastra/pull/17525))
+
+  `OpenAISDKAgent` lets you register an OpenAI Agents SDK agent with Mastra, call it with Mastra-compatible `generate()` and `stream()` methods, and keep usage and tracing data connected to the Mastra run.
+
+  ```ts
+  import { OpenAISDKAgent } from '@mastra/openai';
+
+  export const openaiAgent = 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: '__GATEWAY_OPENAI_MODEL_BASE__',
+    },
+  });
+  ```
+
+  Use `sdkOptions` when you want Mastra to create the OpenAI SDK agent. Pass `agent` when your app already creates and owns the SDK agent.
+
+### Patch Changes
+
+- Updated dependencies [[`d468acb`](https://github.com/mastra-ai/mastra/commit/d468acb07aec1bb19a2cb0ada8042b05b46746b2), [`575f815`](https://github.com/mastra-ai/mastra/commit/575f815c5c3567b71c0b83cbb7fa98c8253a9d9c), [`34839c1`](https://github.com/mastra-ai/mastra/commit/34839c1910b6964bf59ed0cee58844efebbb684e), [`053735a`](https://github.com/mastra-ai/mastra/commit/053735a75c2c18e23ce34d9468007efa4a45f4c4), [`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), [`2bccba4`](https://github.com/mastra-ai/mastra/commit/2bccba4c03cadc815c2d54cbf4dd43a922140a8d), [`bf8eb6d`](https://github.com/mastra-ai/mastra/commit/bf8eb6d0ec213a403eb9265a594ad283c44ab3dc), [`e9be4e7`](https://github.com/mastra-ai/mastra/commit/e9be4e747ec3d8b65548bff92f9377db06105376), [`493a328`](https://github.com/mastra-ai/mastra/commit/493a328f4346a1deeb9f1e2e44c8f2a3a4d7591b), [`d53cfc2`](https://github.com/mastra-ai/mastra/commit/d53cfc2c7f8d78343a4aa84ec4e129ba25f3325e), [`65799d4`](https://github.com/mastra-ai/mastra/commit/65799d4d549e5ebb9c848fbe3f51ac090f64becf), [`c268c89`](https://github.com/mastra-ai/mastra/commit/c268c89f4c63a93ee474d3cffdf3ea60bf00d4f2), [`34839c1`](https://github.com/mastra-ai/mastra/commit/34839c1910b6964bf59ed0cee58844efebbb684e), [`014e00f`](https://github.com/mastra-ai/mastra/commit/014e00f2b3a597a016b72f9901c6ab27d491f822), [`029a414`](https://github.com/mastra-ai/mastra/commit/029a4141719793bd3e898a39eb5a0466a55f5f3a), [`d468acb`](https://github.com/mastra-ai/mastra/commit/d468acb07aec1bb19a2cb0ada8042b05b46746b2), [`b147b29`](https://github.com/mastra-ai/mastra/commit/b147b2907f0cd1aa812efe6d6e3f58d22e66fc88), [`d371ac1`](https://github.com/mastra-ai/mastra/commit/d371ac1d9820afaaf7cfdbc380a475946a994d8f), [`2bccba4`](https://github.com/mastra-ai/mastra/commit/2bccba4c03cadc815c2d54cbf4dd43a922140a8d), [`0c72f03`](https://github.com/mastra-ai/mastra/commit/0c72f032abb13254df5a7856d64be2f207b8006d), [`cf182b7`](https://github.com/mastra-ai/mastra/commit/cf182b7fb495767946d9840ef29f19cfa906f31f), [`3b45ea9`](https://github.com/mastra-ai/mastra/commit/3b45ea95015557a6cb9d70dc5252af54ab1b78ac), [`a049c2a`](https://github.com/mastra-ai/mastra/commit/a049c2a9dfb41d0ee2e7a28874a88cd64fd5669f), [`f084be1`](https://github.com/mastra-ai/mastra/commit/f084be1fcbe33ad7480913e44d6130c421c0976f), [`b147b29`](https://github.com/mastra-ai/mastra/commit/b147b2907f0cd1aa812efe6d6e3f58d22e66fc88), [`2a96528`](https://github.com/mastra-ai/mastra/commit/2a9652848dfa3c5a2426f952e9d93554c26fd90f), [`f2ab060`](https://github.com/mastra-ai/mastra/commit/f2ab060162bea81505fda553e2cee29c1979fd04), [`5d302c8`](https://github.com/mastra-ai/mastra/commit/5d302c8eda1a6ac74eab5e442c4f64db6cc97a06), [`34839c1`](https://github.com/mastra-ai/mastra/commit/34839c1910b6964bf59ed0cee58844efebbb684e), [`a952852`](https://github.com/mastra-ai/mastra/commit/a952852c971a21fb646cd907c75fcf4443cdc963), [`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
+
+## 0.1.0-alpha.2
+
+### 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.0-alpha.1
+
+### Minor Changes
+
+- Added `@mastra/openai`, a new package for using OpenAI Agents SDK agents in Mastra. ([#17525](https://github.com/mastra-ai/mastra/pull/17525))
+
+  `OpenAISDKAgent` lets you register an OpenAI Agents SDK agent with Mastra, call it with Mastra-compatible `generate()` and `stream()` methods, and keep usage and tracing data connected to the Mastra run.
+
+  ```ts
+  import { OpenAISDKAgent } from '@mastra/openai';
+
+  export const openaiAgent = 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: '__GATEWAY_OPENAI_MODEL_BASE__',
+    },
+  });
+  ```
+
+  Use `sdkOptions` when you want Mastra to create the OpenAI SDK agent. Pass `agent` when your app already creates and owns the SDK agent.
+
+### Patch Changes
+
+- Updated dependencies [[`d468acb`](https://github.com/mastra-ai/mastra/commit/d468acb07aec1bb19a2cb0ada8042b05b46746b2), [`e9be4e7`](https://github.com/mastra-ai/mastra/commit/e9be4e747ec3d8b65548bff92f9377db06105376), [`d53cfc2`](https://github.com/mastra-ai/mastra/commit/d53cfc2c7f8d78343a4aa84ec4e129ba25f3325e), [`65799d4`](https://github.com/mastra-ai/mastra/commit/65799d4d549e5ebb9c848fbe3f51ac090f64becf), [`c268c89`](https://github.com/mastra-ai/mastra/commit/c268c89f4c63a93ee474d3cffdf3ea60bf00d4f2), [`d468acb`](https://github.com/mastra-ai/mastra/commit/d468acb07aec1bb19a2cb0ada8042b05b46746b2), [`0c72f03`](https://github.com/mastra-ai/mastra/commit/0c72f032abb13254df5a7856d64be2f207b8006d), [`3b45ea9`](https://github.com/mastra-ai/mastra/commit/3b45ea95015557a6cb9d70dc5252af54ab1b78ac), [`f084be1`](https://github.com/mastra-ai/mastra/commit/f084be1fcbe33ad7480913e44d6130c421c0976f)]:
+  - @mastra/core@1.42.0-alpha.0
+
+## 0.1.0-alpha.0
+
+### Initial release
+
+- Added `OpenAISDKAgent` for registering OpenAI Agents SDK agents with Mastra.

package/LICENSE.md

@@ -0,0 +1,30 @@
+Portions of this software are licensed as follows:
+
+- All content that resides under any directory named "ee/" within this
+  repository, including but not limited to:
+  - `packages/core/src/auth/ee/`
+  - `packages/server/src/server/auth/ee/`
+    is licensed under the license defined in `ee/LICENSE`.
+
+- All third-party components incorporated into the Mastra Software are
+  licensed under the original license provided by the owner of the
+  applicable component.
+
+- Content outside of the above-mentioned directories or restrictions is
+  available under the "Apache License 2.0" as defined below.
+
+# Apache License 2.0
+
+Copyright (c) 2025 Kepler Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,92 @@
+# @mastra/openai
+
+`@mastra/openai` connects Mastra to the OpenAI Agents SDK. Use it when you want to register an OpenAI SDK agent with Mastra and call it through Mastra-compatible `generate()` and `stream()` methods.
+
+## Installation
+
+```bash
+npm install @mastra/openai @openai/agents
+```
+
+## Overview
+
+The package exports `OpenAISDKAgent`, a Mastra `Agent` wrapper around the OpenAI Agents SDK run loop.
+
+`OpenAISDKAgent` keeps the OpenAI SDK run loop in charge. Mastra receives compatible outputs, usage data, and tracing data for the run.
+
+## Create an OpenAI SDK agent
+
+Pass OpenAI Agents SDK configuration through `sdkOptions`. `OpenAISDKAgent` creates the SDK agent on first use.
+
+```typescript
+import { OpenAISDKAgent } from '@mastra/openai';
+
+export const openaiAgent = 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: '__GATEWAY_OPENAI_MODEL_BASE__',
+  },
+});
+```
+
+You can also pass an existing OpenAI SDK agent when your app already creates or owns it.
+
+```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: '__GATEWAY_OPENAI_MODEL_BASE__',
+});
+
+export const openaiAgent = new OpenAISDKAgent({
+  id: 'openai-sdk-agent',
+  description: 'Use OpenAI Agents SDK through Mastra.',
+  agent: sdkAgent,
+});
+```
+
+You can register the wrapper anywhere Mastra accepts an `Agent`.
+
+```typescript
+import { Mastra } from '@mastra/core/mastra';
+
+export const mastra = new Mastra({
+  agents: {
+    openaiAgent,
+  },
+});
+```
+
+## Run the agent
+
+```typescript
+const result = await openaiAgent.generate('Summarize the latest changes in this repository.', {
+  runId: 'openai-run',
+  maxSteps: 3,
+});
+
+console.log(result.text);
+```
+
+```typescript
+const stream = await openaiAgent.stream('Review this package for test gaps.');
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'text-delta') {
+    process.stdout.write(chunk.payload.text);
+  }
+}
+```
+
+## Configure OpenAI
+
+`OpenAISDKAgent` forwards `sdkOptions` to the OpenAI SDK `Agent` constructor when `agent` is not provided. These include `name`, `instructions`, `model`, `tools`, `handoffs`, guardrails, and other OpenAI Agents SDK agent settings.
+
+Mastra `generate()` and `stream()` execution options drive the run. `maxSteps` maps to OpenAI `maxTurns`, and `abortSignal` maps to OpenAI `signal`.

package/dist/docs/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: mastra-openai
+description: Documentation for @mastra/openai. Use when working with @mastra/openai APIs, configuration, or implementation.
+metadata:
+  package: "@mastra/openai"
+  version: "1.0.3"
+---
+
+## When to use
+
+Use this skill whenever you are working with @mastra/openai to obtain the domain-specific knowledge.
+
+## How to use
+
+Read the individual reference documents for detailed explanations and code examples.
+
+### Docs
+
+- [SDK agents](references/docs-agents-sdk-agents.md) - Use Claude Agent SDK, Cursor Agent SDK, and OpenAI Agents SDK agents from Mastra.
+- [Memory processors](references/docs-memory-memory-processors.md) - Learn how to use memory processors in Mastra to filter, trim, and transform messages before they're sent to the language model to manage context window limits.
+
+
+Read [assets/SOURCE_MAP.json](assets/SOURCE_MAP.json) for source code references.

package/dist/docs/assets/SOURCE_MAP.json

@@ -0,0 +1,6 @@
+{
+  "version": "1.0.3",
+  "package": "@mastra/openai",
+  "exports": {},
+  "modules": {}
+}