@mastra/mcp-docs-server 1.1.42-alpha.8 → 1.1.43-alpha.0

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

@@ -0,0 +1,261 @@
+# 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()`.
+
+## 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.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.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.5',
+    },
+    local: {
+      cwd: process.cwd(),
+    },
+    mcpServers,
+  },
+})
+```
+
+## 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'
+
+export const mastra = new Mastra({
+  agents: {
+    claudeSDKAgent,
+    cursorSDKAgent,
+  },
+})
+```
+
+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)
+}
+```
+
+## 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.
+
+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)

package/.docs/docs/agents/signals.md

@@ -1,6 +1,6 @@
 # Signals
 
-> **Experimental:** This feature is in alpha. Breaking changes may occur without a major version bump until the API is stable.
+> **Alpha:** This feature is in alpha. Breaking changes may occur without a major version bump until the API is stable.
 
 Signals are a way to interact with an agent through a thread. Instead of starting every interaction with `agent.stream()`, subscribe to a thread and send messages or signals. Mastra either wakes the agent when the thread is idle, drops input into the running agent loop, or queues input for the next turn.
 
@@ -97,7 +97,7 @@ The behavior options are:
 - `ifIdle.behavior: 'persist'`: Save the signal or message to memory without starting a stream.
 - `ifIdle.behavior: 'discard'`: Ignore the signal or message while the thread is idle.
 
-Pass `ifIdle.streamOptions` when the idle wake-up stream needs options such as model settings, tools, or runtime context. You do not need to repeat `memory.resource` or `memory.thread`; Mastra uses the top-level `resourceId` and `threadId` for the thread.
+Pass `ifIdle.streamOptions` when the idle wake-up stream needs options such as model settings, tools, or runtime context. You don't need to repeat `memory.resource` or `memory.thread`; Mastra uses the top-level `resourceId` and `threadId` for the thread.
 
 ```typescript
 agent.sendMessage('Continue with the next step.', {
@@ -143,6 +143,10 @@ The model receives the signal as context like this:
 
 Use XML-safe `tagName` and attribute names. They can contain letters, numbers, underscores, periods, and hyphens. They must start with a letter or underscore.
 
+### Storage support
+
+Notification inbox storage is available in the storage adapters that support richer memory and signal workflows: [libSQL](https://mastra.ai/reference/storage/libsql), [PostgreSQL](https://mastra.ai/reference/storage/postgresql), and [MongoDB](https://mastra.ai/reference/storage/mongodb). These adapters expose notification records through `getStore('notifications')`.
+
 ## Send processor context
 
 Processors can send reactive signals during a run. A processor should inspect the chat history, react to a specific trigger, and avoid sending the same context more than once.
@@ -220,7 +224,224 @@ When the agent is idle:
 <user source="chat" delivery="new-message">Also cover the edge cases.</user>
 ```
 
-Top-level `attributes` always apply. The selected branch's `attributes` are merged into them at delivery time. The `delivery` name shown above is not a special Mastra API field. It is a custom attribute name used for this example, you can add any attribute names that suit your use case.
+Top-level `attributes` always apply. The selected branch's `attributes` are merged into them at delivery time. The `delivery` name shown above isn't a special Mastra API field. It's a custom attribute name used for this example. Add any attribute names that suit your use case.
+
+## State signals
+
+State signals expose named, thread-scoped context lanes. Use them for durable context that changes over time, such as browser state, editor state, or a background watcher result.
+
+Each state signal needs:
+
+- `id`: The state lane name, such as `browser`.
+- `cacheKey`: A producer-owned key for deduping the current state.
+- `mode`: `snapshot` for an authoritative state copy, or `delta` for a change event.
+
+Use `sendStateSignal()` when an external producer detects a state change.
+
+```typescript
+await agent.sendStateSignal(
+  {
+    id: 'browser',
+    mode: 'snapshot',
+    cacheKey: 'browser:https://example.com:3-tabs',
+    contents: 'Browser is open on https://example.com with 3 tabs.',
+    value: {
+      activeUrl: 'https://example.com',
+      tabCount: 3,
+      open: true,
+    },
+  },
+  {
+    resourceId: 'user_123',
+    threadId: 'thread_456',
+  },
+)
+```
+
+When Mastra accepts a state signal, it stores compact tracking metadata on the thread. The metadata records the lane's current `cacheKey`, current mode, version, last signal id, and last snapshot signal id. If a producer sends the same `cacheKey` and mode again while that state is still current, Mastra skips the duplicate.
+
+State signal fields have separate roles:
+
+- `contents`: The representation the model reads.
+- `value`: The structured snapshot for `mode: 'snapshot'`.
+- `delta`: The structured change for `mode: 'delta'`.
+- `metadata.state`: The runtime tracking envelope with `id`, `mode`, `cacheKey`, `version`, and `threadId`.
+
+Use `computeStateSignal()` when a processor owns a state lane. Mastra calls it once per model input step after `processInputStep()`. If the processor omits `id`, Mastra uses the processor id as the state lane id. Set `stateId` when the public state lane should differ from the processor id.
+
+```typescript
+import type { ComputeStateSignalArgs, Processor } from '@mastra/core/processors'
+
+export const browserStateProcessor: Processor = {
+  id: 'browser-state',
+  stateId: 'browser',
+  computeStateSignal(args: ComputeStateSignalArgs) {
+    const browser = readCurrentBrowserState()
+    const previous = readMostRecentBrowserState(args.activeStateSignals)
+    const changed = previous ? diffBrowserState(previous, browser) : browser
+    const shouldRefreshSnapshot = Boolean(args.lastSnapshot && !args.contextWindow.hasSnapshot)
+
+    if (previous && Object.keys(changed).length === 0 && !shouldRefreshSnapshot) {
+      return
+    }
+
+    const isDelta = Boolean(previous && !shouldRefreshSnapshot)
+
+    return {
+      mode: isDelta ? 'delta' : 'snapshot',
+      cacheKey: stableBrowserStateCacheKey(browser),
+      contents: isDelta ? describeBrowserDelta(changed) : describeBrowserSnapshot(browser),
+      value: browser,
+      ...(isDelta ? { delta: changed } : {}),
+    }
+  },
+}
+```
+
+Mastra passes `lastSnapshot` and `deltasSinceSnapshot` into `computeStateSignal()`. It resolves them from message history when the current message list doesn't contain the latest snapshot. The processor still owns merge and diff logic.
+
+`contextWindow.hasSnapshot` tells the processor whether the active message window already contains a snapshot for this state lane. If it's `false`, return a fresh `snapshot` so the model sees the current state even after older state messages are trimmed from the context window.
+
+The built-in browser context processor emits state under the `browser` id with snapshot and delta modes.
+
+## Notification signals
+
+Notification signals represent external events such as GitHub activity, email, Slack mentions, CI status, incidents, recordings, or direct messages. Use `agent.sendNotificationSignal()` when the event should create a durable inbox record.
+
+Notification delivery has two phases:
+
+- **Ingress**: `agent.sendNotificationSignal()` stores a notification record, then resolves the agent's delivery policy.
+- **Dispatch**: Mastra consumes due records stamped with `deliverAt` or `summaryAt` and emits full notification or summary signals.
+
+A notification record stores the source, kind, priority, summary, payload, resource id, thread id, agent id, coalescing keys, and delivery metadata. The delivery decision controls what happens after ingress:
+
+- `deliver` or `queue`: Emit a full `<notification>` signal and mark the record `delivered`.
+- `defer`: Keep the record `pending` with `deliverAt`.
+- `summarize`: Keep the record `pending` with `summaryAt`, or emit an immediate summary when the policy requests it.
+- `persist`: Keep the record `pending` in the inbox without scheduled delivery.
+- `discard`: Mark the record `discarded` and emit no signal.
+
+The default delivery policy is priority-aware:
+
+| Priority | Active thread                                                                                            | Idle thread                                                                                     |
+| -------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `urgent` | Deliver a full notification immediately                                                                  | Deliver a full notification immediately                                                         |
+| `high`   | Emit a summary immediately, keep `deliverAt`, then deliver the full notification when the thread is idle | Deliver a full notification immediately                                                         |
+| `medium` | Batch with `summaryAt` and later deliver one notification summary                                        | Deliver a full notification immediately                                                         |
+| `low`    | Batch with `summaryAt` and later deliver one notification summary                                        | Batch with `summaryAt` and later deliver one notification summary without waking the model loop |
+
+```typescript
+await agent.sendNotificationSignal(
+  {
+    source: 'github',
+    kind: 'ci-status',
+    priority: 'high',
+    summary: 'CI failed on main: 3 tests failed.',
+    payload: {
+      repository: 'acme/app',
+      branch: 'main',
+    },
+    dedupeKey: 'github:acme/app:main:ci',
+  },
+  {
+    resourceId: 'user_123',
+    threadId: 'thread_456',
+  },
+)
+```
+
+The model receives full notifications as context:
+
+```xml
+<notification source="github" type="ci-status" priority="high" status="delivered">CI failed on main: 3 tests failed.</notification>
+```
+
+Notification summaries tell the model that inbox records are waiting:
+
+```xml
+<notification-summary pending="10">github: 3, email: 5, slack: 2</notification-summary>
+```
+
+When Mastra emits a summary, it clears `summaryAt` and sets `summarySignalId` on each summarized record. The records stay pending and readable. When Mastra emits a full notification, it sets `deliveredSignalId` and marks the record `delivered`. If the inbox tool reads a notification first, it can inject the full notification signal and mark the record `seen`, which prevents duplicate full delivery.
+
+Configure a delivery policy on the agent when some notifications should wait for a different dispatch window or summary rollup.
+
+```typescript
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support Agent',
+  instructions: 'Help the user triage updates.',
+  model: 'openai/gpt-5.5',
+  notifications: {
+    deliveryPolicy: {
+      priorities: {
+        urgent: 'deliver',
+      },
+      decide: ({ record }) => {
+        if (record.priority === 'low') {
+          return {
+            action: 'summarize',
+            summaryAt: new Date(Date.now() + 30 * 60 * 1000),
+          }
+        }
+      },
+    },
+  },
+})
+```
+
+Enable scheduled dispatch at the Mastra level so deferred notifications and summary rollups are delivered through the existing workflow scheduler.
+
+```typescript
+export const mastra = new Mastra({
+  agents: { supportAgent },
+  storage,
+  notifications: {
+    dispatch: {
+      enabled: true,
+      cron: '*/1 * * * *',
+      batchSize: 100,
+    },
+  },
+})
+```
+
+`notifications.dispatch.enabled` registers an internal workflow with the default cron `*/1 * * * *`. The dispatcher reads due notification records from storage, groups summaries by `agentId`, `resourceId`, and `threadId`, and emits signals through the Agent thread runtime. It isn't a user-facing entrypoint.
+
+### Notification inbox tool
+
+Use `createNotificationInboxTool()` to give agents one tool for inbox actions instead of many CRUD tools.
+
+```typescript
+import { createNotificationInboxTool } from '@mastra/core/notifications'
+
+const notificationsStorage = await storage.getStore('notifications')
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support Agent',
+  instructions: 'Help the user triage updates.',
+  model: 'openai/gpt-5.5',
+  tools: {
+    notificationInbox: createNotificationInboxTool({ storage: notificationsStorage }),
+  },
+})
+```
+
+The tool id is `notification-inbox`. It supports these actions:
+
+- `list`: List notifications for the current thread.
+- `read`: Deliver readable full notification signals into the chat when possible, then mark records `seen`.
+- `markSeen`: Mark one record `seen`.
+- `dismiss`: Mark one record `dismissed`.
+- `archive`: Mark one record `archived`.
+- `search`: Search notification summaries in the current thread.
+
+The tool uses the current `threadId` from the tool execution context unless one is provided. Use `read` after a `<notification-summary>` signal when the agent needs the full records behind the summary. The `read` result reports how many notifications will be delivered; it doesn't use normal tool output as the main context channel for the notification contents.
+
+`sendNotificationSignal()` requires a storage domain with `notifications` support. LibSQL supports notifications. Other storage adapters need matching notification domain support before they can store notification records.
+
+Use `sendSignal({ type: 'notification' })` only for lower-level notification-shaped context that should bypass inbox storage.
 
 ## Compatibility
 
@@ -229,7 +450,7 @@ Mastra still accepts legacy signal payloads such as `type: 'user-message'` and `
 - `type: 'user-message'`: Normalizes to `type: 'user'` and `tagName: 'user'`
 - `type: 'system-reminder'`: Normalizes to `type: 'reactive'` and `tagName: 'system-reminder'`
 
-Existing stored signal rows and older clients continue to load through the compatibility layer.
+Existing stored signal rows and older clients continue to load through the compatibility layer. New clients call the message routes when the server supports them; React's thread signal path falls back to the legacy `/signals` route when it detects an older server.
 
 > **Note:** Visit [Agent signals reference](https://mastra.ai/reference/agents/agent) for the full message, signal, and subscription types.
 
@@ -264,11 +485,8 @@ const subscription = await agent.subscribeToThread({
   threadId: 'thread_456',
 })
 
-await agent.sendSignal({
-  signal: {
-    type: 'user-message',
-    contents: 'Show the shorter version.',
-  },
+await agent.sendMessage({
+  message: 'Show the shorter version.',
   resourceId: 'user_123',
   threadId: 'thread_456',
 })
@@ -307,7 +525,9 @@ Use heartbeats together with client-side reconnect logic. Heartbeats reduce idle
 - [`Agent.queueMessage()`](https://mastra.ai/reference/agents/agent)
 - [`Agent.sendSignal()`](https://mastra.ai/reference/agents/agent)
 - [`Agent.subscribeToThread()`](https://mastra.ai/reference/agents/agent)
-- [Server agent routes](https://mastra.ai/reference/server/routes)
+- [`client.getAgent().sendMessage()`](https://mastra.ai/reference/client-js/agents)
+- [`client.getAgent().queueMessage()`](https://mastra.ai/reference/client-js/agents)
 - [`client.getAgent().sendSignal()`](https://mastra.ai/reference/client-js/agents)
+- [Server agent routes](https://mastra.ai/reference/server/routes)
 - [`client.getAgent().subscribeToThread()`](https://mastra.ai/reference/client-js/agents)
 - [`client.getAgent().sendToolApproval()`](https://mastra.ai/reference/client-js/agents)

package/.docs/docs/agents/structured-output.md

@@ -178,7 +178,7 @@ const response = await testAgent.generate('Analyze the TypeScript programming la
         differentiators: z.array(z.string()),
       }),
     }),
-    model: 'openai/gpt-5.4',
+    model: 'openai/gpt-5.5',
   },
 })
 
@@ -248,7 +248,7 @@ When `model` is provided to the `structuredOutput` property, Mastra uses a separ
 const response = await testAgent.generate('Tell me about TypeScript.', {
   structuredOutput: {
     schema: yourSchema,
-    model: 'openai/gpt-5.4',
+    model: 'openai/gpt-5.5',
   },
 })
 ```
@@ -267,7 +267,7 @@ const response = await testAgent.generate('Return my profile as structured data.
       hometown: z.string(),
       petName: z.string(),
     }),
-    model: 'openai/gpt-5.4',
+    model: 'openai/gpt-5.5',
     useAgent: true,
   },
 })
@@ -284,7 +284,7 @@ const result = await agent.stream('weather in vancouver?', {
   prepareStep: async ({ stepNumber }) => {
     if (stepNumber === 0) {
       return {
-        model: 'openai/gpt-5.4',
+        model: 'openai/gpt-5.5',
         tools: {
           weatherTool,
         },
@@ -292,7 +292,7 @@ const result = await agent.stream('weather in vancouver?', {
       }
     }
     return {
-      model: 'openai/gpt-5.4',
+      model: 'openai/gpt-5.5',
       tools: undefined,
       structuredOutput: {
         schema: z.object({

package/.docs/docs/agents/supervisor-agents.md

@@ -41,7 +41,7 @@ const supervisor = new Agent({
   id: 'supervisor',
   instructions: `You coordinate research and writing using specialized agents.
     Delegate to research-agent for facts, then writing-agent for content.`,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   agents: { researchAgent, writingAgent },
   memory: new Memory({
     storage: new LibSQLStore({ id: 'storage', url: 'file:mastra.db' }),
@@ -326,7 +326,7 @@ Enable the [backgroundTasks manager](https://mastra.ai/reference/configuration)
 const supervisor = new Agent({
   id: 'supervisor',
   instructions: 'Coordinate research and writing using the available agents.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   agents: { researchAgent, writingAgent },
   backgroundTasks: {
     tools: {

package/.docs/docs/agents/using-tools.md

@@ -52,7 +52,7 @@ export const weatherAgent = new Agent({
   instructions: `
     You are a helpful weather assistant.
     Use the weatherTool to fetch current weather data.`,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   tools: { weatherTool },
 })
 ```
@@ -145,7 +145,7 @@ export const weatherAgent = new Agent({
     You are a helpful weather assistant.
     Use the weatherTool to fetch current weather data.
     Use the hazardsTool to provide information about potential weather hazards.`,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   tools: { weatherTool, hazardsTool },
 })
 ```
@@ -162,14 +162,14 @@ const writer = new Agent({
   name: 'Writer',
   description: 'Drafts and edits written content',
   instructions: 'You are a skilled writer.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
 })
 
 export const supervisor = new Agent({
   id: 'supervisor',
   name: 'Supervisor',
   instructions: 'Coordinate the writer to produce content.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   agents: { writer },
 })
 ```
@@ -186,7 +186,7 @@ export const researchAgent = new Agent({
   id: 'research-agent',
   name: 'Research Agent',
   instructions: 'You are a research assistant.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   workflows: { researchWorkflow },
 })
 ```

package/.docs/docs/browser/agent-browser.md

@@ -52,7 +52,7 @@ const browser = new AgentBrowser({
 export const browserAgent = new Agent({
   id: 'browser-agent',
   name: 'Browser Agent',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   browser,
   instructions: `You are a web automation assistant.
 

package/.docs/docs/browser/browser-viewer.md

@@ -73,7 +73,7 @@ const workspace = new Workspace({
 
 const browserAgent = new Agent({
   id: 'browser-agent',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   workspace,
   instructions: `You are a web automation assistant.
 Use browser-use commands to navigate and interact with websites.`,

package/.docs/docs/browser/overview.md

@@ -72,7 +72,7 @@ export const webAgent = new Agent({
   id: 'web-agent',
   name: 'Web Agent',
   description: 'A web automation assistant that can navigate websites and complete tasks.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   browser,
   instructions:
     'You are a web automation assistant. Use browser tools to navigate websites and complete tasks.',