@mastra/openai 1.0.1-alpha.8 → 1.0.3

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

@@ -0,0 +1,425 @@
+# SDK agents
+
+SDK agents let you use other agent SDK frameworks inside Mastra. Use them to register SDK-backed agents in a Mastra project while the provider SDK keeps its own runtime, tools, permissions, and agent loop.
+
+## When to use SDK agents
+
+- A vendor SDK already owns the agent loop, tools, permissions, or local runtime.
+- You want to register that SDK-backed agent in a Mastra project.
+- You need Mastra-compatible `generate()` and `stream()` outputs.
+- You want usage, cost, and tool activity from the SDK run to appear in Mastra observability.
+
+## Supported SDK agents
+
+- [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
+
+Use `@mastra/claude` for Claude Code runtime configuration, permissions, tools, and agent-loop behavior.
+
+### Install Claude packages
+
+Install the Mastra package and the Claude Agent SDK peer dependency:
+
+**npm**:
+
+```bash
+npm install @mastra/claude @anthropic-ai/claude-agent-sdk
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/claude @anthropic-ai/claude-agent-sdk
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/claude @anthropic-ai/claude-agent-sdk
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/claude @anthropic-ai/claude-agent-sdk
+```
+
+Set the Claude SDK credential:
+
+```bash
+export ANTHROPIC_API_KEY="..."
+```
+
+### Create a Claude SDK agent
+
+Configure Claude Agent SDK through `sdkOptions`.
+
+```typescript
+import { ClaudeSDKAgent } from '@mastra/claude'
+
+export const claudeSDKAgent = new ClaudeSDKAgent({
+  id: 'claude-sdk-agent',
+  name: 'Claude SDK Agent',
+  description: 'Use Claude Agent SDK through Mastra.',
+  sdkOptions: {
+    model: 'claude-sonnet-4-6',
+    cwd: process.cwd(),
+  },
+})
+```
+
+### Add Claude SDK tools
+
+Claude Agent SDK tools are provided through Claude SDK Model Context Protocol (MCP) servers. Create the server with the Claude SDK, then pass it through `sdkOptions.mcpServers`.
+
+```typescript
+import { createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk'
+import { ClaudeSDKAgent } from '@mastra/claude'
+import { getTemperature } from '../tools/get-temperature'
+
+const weatherServer = createSdkMcpServer({
+  name: 'weather',
+  version: '1.0.0',
+  tools: [getTemperature],
+})
+
+export const claudeSDKAgent = new ClaudeSDKAgent({
+  id: 'claude-sdk-agent',
+  name: 'Claude SDK Agent',
+  description: 'Use Claude Agent SDK through Mastra.',
+  sdkOptions: {
+    model: 'claude-sonnet-4-6',
+    cwd: process.cwd(),
+    mcpServers: {
+      weather: weatherServer,
+    },
+    allowedTools: ['mcp__weather__get_temperature'],
+  },
+})
+```
+
+The `allowedTools` value uses Claude Agent SDK MCP tool naming: `mcp__<server name>__<tool name>`.
+
+## Cursor Agent SDK
+
+Use `@mastra/cursor` to register a Cursor SDK agent in Mastra while keeping Cursor-specific setup in Cursor SDK options.
+
+### Install Cursor packages
+
+Install the Mastra package and the Cursor SDK peer dependency:
+
+**npm**:
+
+```bash
+npm install @mastra/cursor @cursor/sdk
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/cursor @cursor/sdk
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/cursor @cursor/sdk
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/cursor @cursor/sdk
+```
+
+Set the Cursor SDK credential:
+
+```bash
+export CURSOR_API_KEY="..."
+```
+
+### Create a Cursor SDK agent
+
+Configure Cursor Agent SDK through `sdkOptions`.
+
+```typescript
+import { CursorSDKAgent } from '@mastra/cursor'
+
+export const cursorSDKAgent = new CursorSDKAgent({
+  id: 'cursor-sdk-agent',
+  name: 'Cursor SDK Agent',
+  description: 'Use Cursor Agent SDK through Mastra.',
+  sdkOptions: {
+    apiKey: process.env.CURSOR_API_KEY,
+    model: {
+      id: 'gpt-5',
+    },
+    local: {
+      cwd: process.cwd(),
+    },
+  },
+})
+```
+
+Cursor local agents require an explicit model. Set it in `sdkOptions.model`.
+
+### Use an existing Cursor SDK agent
+
+If your app already creates a Cursor SDK agent, pass that agent to `CursorSDKAgent` instead:
+
+```typescript
+import { Agent as CursorAgent } from '@cursor/sdk'
+import { CursorSDKAgent } from '@mastra/cursor'
+
+const cursorAgent = CursorAgent.create({
+  apiKey: process.env.CURSOR_API_KEY,
+  model: {
+    id: 'gpt-5',
+  },
+  local: {
+    cwd: process.cwd(),
+  },
+})
+
+export const cursorSDKAgent = new CursorSDKAgent({
+  id: 'cursor-sdk-agent',
+  name: 'Cursor SDK Agent',
+  description: 'Use Cursor Agent SDK through Mastra.',
+  agent: cursorAgent,
+})
+```
+
+### Add Cursor SDK tools
+
+Cursor Agent SDK tools are configured with Cursor SDK options. Pass Model Context Protocol (MCP) servers through `sdkOptions.mcpServers`:
+
+```typescript
+import { CursorSDKAgent } from '@mastra/cursor'
+import { mcpServers } from '../mcp/cursor'
+
+export const cursorSDKAgent = new CursorSDKAgent({
+  id: 'cursor-sdk-agent',
+  name: 'Cursor SDK Agent',
+  description: 'Use Cursor Agent SDK through Mastra.',
+  sdkOptions: {
+    apiKey: process.env.CURSOR_API_KEY,
+    model: {
+      id: 'gpt-5',
+    },
+    local: {
+      cwd: process.cwd(),
+    },
+    mcpServers,
+  },
+})
+```
+
+## 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:
+
+```typescript
+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,
+  },
+})
+```
+
+After registration, call them with `mastra.getAgentById()`:
+
+```typescript
+import { mastra } from './index'
+
+const agent = mastra.getAgentById('cursor-sdk-agent')
+const stream = await agent.stream('Inspect this project and describe the test setup.')
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk)
+}
+```
+
+## 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. OpenAI SDK runs include token usage from OpenAI run state.
+
+For storage and dashboard setup, see [Observability](https://mastra.ai/docs/observability/overview).
+
+## Related
+
+- [Agents overview](https://mastra.ai/docs/agents/overview)
+- [Tools](https://mastra.ai/docs/agents/using-tools)
+- [Observability](https://mastra.ai/docs/observability/overview)