@mastra/client-js 0.0.0-studio-deploy-20260404182525 → 0.0.0-studio-cli-20260504022012
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +917 -3
- package/dist/_types/@internal_ai-sdk-v5/dist/index.d.ts +466 -1764
- package/dist/client.d.ts +46 -3
- package/dist/client.d.ts.map +1 -1
- package/dist/docs/SKILL.md +3 -1
- package/dist/docs/assets/SOURCE_MAP.json +7 -2
- package/dist/docs/references/docs-editor-overview.md +290 -0
- package/dist/docs/references/docs-server-mastra-client.md +2 -2
- package/dist/docs/references/reference-ai-sdk-to-ai-sdk-messages.md +95 -0
- package/dist/docs/references/reference-ai-sdk-to-ai-sdk-stream.md +15 -0
- package/dist/docs/references/reference-client-js-agents.md +166 -0
- package/dist/docs/references/reference-client-js-conversations.md +1 -1
- package/dist/docs/references/reference-client-js-mastra-client.md +23 -0
- package/dist/docs/references/reference-client-js-observability.md +2 -2
- package/dist/docs/references/reference-client-js-responses.md +1 -1
- package/dist/docs/references/reference-client-js-workflows.md +62 -1
- package/dist/index.cjs +660 -35
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +657 -35
- package/dist/index.js.map +1 -1
- package/dist/resources/a2a.d.ts +56 -10
- package/dist/resources/a2a.d.ts.map +1 -1
- package/dist/resources/agent.d.ts +69 -0
- package/dist/resources/agent.d.ts.map +1 -1
- package/dist/resources/channels.d.ts +63 -0
- package/dist/resources/channels.d.ts.map +1 -0
- package/dist/resources/index.d.ts +1 -0
- package/dist/resources/index.d.ts.map +1 -1
- package/dist/resources/memory-thread.d.ts.map +1 -1
- package/dist/resources/observability.d.ts +18 -1
- package/dist/resources/observability.d.ts.map +1 -1
- package/dist/resources/run.d.ts +26 -2
- package/dist/resources/run.d.ts.map +1 -1
- package/dist/resources/vector.d.ts +5 -5
- package/dist/resources/vector.d.ts.map +1 -1
- package/dist/types.d.ts +115 -6
- package/dist/types.d.ts.map +1 -1
- package/dist/utils/process-a2a-stream.d.ts +4 -0
- package/dist/utils/process-a2a-stream.d.ts.map +1 -0
- package/package.json +12 -12
|
@@ -151,6 +151,30 @@ for await (const part of uiMessageStream) {
|
|
|
151
151
|
}
|
|
152
152
|
```
|
|
153
153
|
|
|
154
|
+
### `streamUntilIdle()`
|
|
155
|
+
|
|
156
|
+
Stream a response and keep the stream open until every [background task](https://mastra.ai/docs/agents/background-tasks) dispatched during the run completes. The server re-enters the agentic loop on each task completion so the LLM can react to results in the same call. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call falls through to a plain `stream()`.
|
|
157
|
+
|
|
158
|
+
```typescript
|
|
159
|
+
const response = await agent.streamUntilIdle('Research solana for me', {
|
|
160
|
+
memory: {
|
|
161
|
+
thread: 'thread-1',
|
|
162
|
+
resource: 'resource-1',
|
|
163
|
+
},
|
|
164
|
+
maxIdleMs: 5 * 60_000,
|
|
165
|
+
})
|
|
166
|
+
|
|
167
|
+
response.processDataStream({
|
|
168
|
+
onChunk: async chunk => {
|
|
169
|
+
if (chunk.type === 'background-task-completed') {
|
|
170
|
+
console.log('task complete:', chunk.payload.taskId)
|
|
171
|
+
}
|
|
172
|
+
},
|
|
173
|
+
})
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
The stream emits the same chunk types as `stream()`, plus `background-task-*` chunks for task lifecycle events. Visit [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle) for the full server-side API and [background task chunks](https://mastra.ai/reference/streaming/ChunkType) for the payload shapes.
|
|
177
|
+
|
|
154
178
|
### `getTool()`
|
|
155
179
|
|
|
156
180
|
Retrieve information about a specific tool available to the agent:
|
|
@@ -217,6 +241,26 @@ response.processDataStream({
|
|
|
217
241
|
})
|
|
218
242
|
```
|
|
219
243
|
|
|
244
|
+
### `resumeStream()`
|
|
245
|
+
|
|
246
|
+
Resume a suspended agent stream with custom data. Use this to continue execution after a suspension point, such as a workflow suspend within an agent:
|
|
247
|
+
|
|
248
|
+
```typescript
|
|
249
|
+
const response = await agent.resumeStream(
|
|
250
|
+
{ approved: true, selectedOption: 'plan-b' },
|
|
251
|
+
{
|
|
252
|
+
runId: 'run-123',
|
|
253
|
+
toolCallId: 'tool-call-456', // optional
|
|
254
|
+
},
|
|
255
|
+
)
|
|
256
|
+
|
|
257
|
+
await response.processDataStream({
|
|
258
|
+
onChunk: chunk => {
|
|
259
|
+
console.log(chunk)
|
|
260
|
+
},
|
|
261
|
+
})
|
|
262
|
+
```
|
|
263
|
+
|
|
220
264
|
### `approveToolCallGenerate()`
|
|
221
265
|
|
|
222
266
|
Approve a pending tool call when using `generate()` (non-streaming). Returns the complete response:
|
|
@@ -439,4 +483,126 @@ Delete a stored agent:
|
|
|
439
483
|
```typescript
|
|
440
484
|
const result = await storedAgent.delete()
|
|
441
485
|
console.log(result.success) // true
|
|
486
|
+
```
|
|
487
|
+
|
|
488
|
+
## Version management
|
|
489
|
+
|
|
490
|
+
Both `Agent` (code-defined) and `StoredAgent` instances have methods for managing configuration versions. See the [Editor overview](https://mastra.ai/docs/editor/overview) for an introduction to version management.
|
|
491
|
+
|
|
492
|
+
### Getting an agent with a specific version
|
|
493
|
+
|
|
494
|
+
Pass a version identifier when getting an agent:
|
|
495
|
+
|
|
496
|
+
```typescript
|
|
497
|
+
// Load the published version (default)
|
|
498
|
+
const agent = mastraClient.getAgent('support-agent')
|
|
499
|
+
|
|
500
|
+
// Load the latest draft
|
|
501
|
+
const draftAgent = mastraClient.getAgent('support-agent', { status: 'draft' })
|
|
502
|
+
|
|
503
|
+
// Load a specific version
|
|
504
|
+
const versionedAgent = mastraClient.getAgent('support-agent', { versionId: 'abc-123' })
|
|
505
|
+
```
|
|
506
|
+
|
|
507
|
+
For stored agents, pass a status option to `details()`:
|
|
508
|
+
|
|
509
|
+
```typescript
|
|
510
|
+
const storedAgent = mastraClient.getStoredAgent('my-agent')
|
|
511
|
+
const draft = await storedAgent.details(undefined, { status: 'draft' })
|
|
512
|
+
```
|
|
513
|
+
|
|
514
|
+
### `listVersions()`
|
|
515
|
+
|
|
516
|
+
List all versions for an agent:
|
|
517
|
+
|
|
518
|
+
```typescript
|
|
519
|
+
const versions = await agent.listVersions()
|
|
520
|
+
console.log(versions.items) // Array of version snapshots
|
|
521
|
+
console.log(versions.total)
|
|
522
|
+
```
|
|
523
|
+
|
|
524
|
+
With pagination and sorting:
|
|
525
|
+
|
|
526
|
+
```typescript
|
|
527
|
+
const versions = await agent.listVersions({
|
|
528
|
+
page: 0,
|
|
529
|
+
perPage: 10,
|
|
530
|
+
orderBy: {
|
|
531
|
+
field: 'createdAt',
|
|
532
|
+
direction: 'DESC',
|
|
533
|
+
},
|
|
534
|
+
})
|
|
535
|
+
```
|
|
536
|
+
|
|
537
|
+
### `createVersion()`
|
|
538
|
+
|
|
539
|
+
Create a new version snapshot:
|
|
540
|
+
|
|
541
|
+
```typescript
|
|
542
|
+
const version = await agent.createVersion({
|
|
543
|
+
changeMessage: 'Updated tone to be more friendly',
|
|
544
|
+
})
|
|
545
|
+
```
|
|
546
|
+
|
|
547
|
+
### `getVersion()`
|
|
548
|
+
|
|
549
|
+
Get a specific version by ID:
|
|
550
|
+
|
|
551
|
+
```typescript
|
|
552
|
+
const version = await agent.getVersion('version-123')
|
|
553
|
+
console.log(version.versionNumber)
|
|
554
|
+
console.log(version.changedFields)
|
|
555
|
+
console.log(version.createdAt)
|
|
556
|
+
```
|
|
557
|
+
|
|
558
|
+
### `activateVersion()`
|
|
559
|
+
|
|
560
|
+
Set a version as the active published version:
|
|
561
|
+
|
|
562
|
+
```typescript
|
|
563
|
+
await agent.activateVersion('version-123')
|
|
564
|
+
```
|
|
565
|
+
|
|
566
|
+
### `restoreVersion()`
|
|
567
|
+
|
|
568
|
+
Restore a previous version by creating a new version with the same configuration:
|
|
569
|
+
|
|
570
|
+
```typescript
|
|
571
|
+
await agent.restoreVersion('version-456')
|
|
572
|
+
```
|
|
573
|
+
|
|
574
|
+
### `deleteVersion()`
|
|
575
|
+
|
|
576
|
+
Delete a version:
|
|
577
|
+
|
|
578
|
+
```typescript
|
|
579
|
+
await agent.deleteVersion('version-789')
|
|
580
|
+
```
|
|
581
|
+
|
|
582
|
+
### `compareVersions()`
|
|
583
|
+
|
|
584
|
+
Compare two versions and return their differences:
|
|
585
|
+
|
|
586
|
+
```typescript
|
|
587
|
+
const diff = await agent.compareVersions('version-123', 'version-456')
|
|
588
|
+
console.log(diff.changes) // Fields that changed between versions
|
|
589
|
+
```
|
|
590
|
+
|
|
591
|
+
### React SDK
|
|
592
|
+
|
|
593
|
+
In the React SDK, pass an `agentVersionId` through `requestContext` when using the `useChat` hook:
|
|
594
|
+
|
|
595
|
+
```typescript
|
|
596
|
+
import { useChat } from '@mastra/react'
|
|
597
|
+
|
|
598
|
+
function Chat() {
|
|
599
|
+
const { messages, input, handleInputChange, handleSubmit } = useChat({
|
|
600
|
+
agentId: 'support-agent',
|
|
601
|
+
requestContext: {
|
|
602
|
+
agentVersionId: 'abc-123',
|
|
603
|
+
},
|
|
604
|
+
})
|
|
605
|
+
|
|
606
|
+
// ... render chat UI
|
|
607
|
+
}
|
|
442
608
|
```
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# OpenAI Responses API Conversations
|
|
2
2
|
|
|
3
|
-
The OpenAI Responses API Conversations surface provides methods to create, retrieve, delete, and inspect thread-backed conversations in Mastra.
|
|
3
|
+
The OpenAI Responses API Conversations surface gives you the conversation-management side of Mastra Agents as a Responses API. It provides methods to create, retrieve, delete, and inspect thread-backed conversations in Mastra.
|
|
4
4
|
|
|
5
5
|
This API follows up on the [OpenAI Responses API](https://mastra.ai/reference/client-js/responses). Stored Responses calls return `conversation_id`, and in Mastra that value is the raw memory `threadId`. Use `client.conversations` when you want to work with that thread directly.
|
|
6
6
|
|
|
@@ -12,6 +12,29 @@ export const mastraClient = new MastraClient({
|
|
|
12
12
|
})
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
+
## `RequestContext`
|
|
16
|
+
|
|
17
|
+
When you use `RequestContext` with the client SDK, import it from `@mastra/client-js`.
|
|
18
|
+
|
|
19
|
+
```typescript
|
|
20
|
+
import { MastraClient, RequestContext } from '@mastra/client-js'
|
|
21
|
+
|
|
22
|
+
const client = new MastraClient({
|
|
23
|
+
baseUrl: 'http://localhost:4111/',
|
|
24
|
+
})
|
|
25
|
+
|
|
26
|
+
const requestContext = new RequestContext()
|
|
27
|
+
requestContext.set('userId', 'user-123')
|
|
28
|
+
|
|
29
|
+
const agent = client.getAgent('support-agent')
|
|
30
|
+
|
|
31
|
+
const response = await agent.generate('Summarize this ticket', {
|
|
32
|
+
requestContext,
|
|
33
|
+
})
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
You can also pass `requestContext` as a `Record<string, any>`.
|
|
37
|
+
|
|
15
38
|
## Parameters
|
|
16
39
|
|
|
17
40
|
**baseUrl** (`string`): The base URL for the Mastra API. All requests will be sent relative to this URL.
|
|
@@ -68,5 +68,5 @@ const scores = await mastraClient.listScoresBySpan({
|
|
|
68
68
|
|
|
69
69
|
## Related
|
|
70
70
|
|
|
71
|
-
- [Agents API](https://mastra.ai/reference/client-js/agents)
|
|
72
|
-
- [Workflows API](https://mastra.ai/reference/client-js/workflows)
|
|
71
|
+
- [Agents API](https://mastra.ai/reference/client-js/agents): Learn about agent interactions that generate traces
|
|
72
|
+
- [Workflows API](https://mastra.ai/reference/client-js/workflows): Understand workflow execution monitoring
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# OpenAI Responses API
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
This OpenAI-compatible, agent-backed interface lets you use Mastra Agents as a Responses API. It provides methods to create, retrieve, stream, and delete responses through Mastra agents.
|
|
4
4
|
|
|
5
5
|
These routes are agent-backed adapters over Mastra agents, memory, and storage. Use `agent_id` to select the Mastra agent that should handle the request. You can pass `model` to override the agent's configured model for a single request, or omit it to use the model already configured on the agent.
|
|
6
6
|
|
|
@@ -140,6 +140,18 @@ await run.resume({
|
|
|
140
140
|
})
|
|
141
141
|
```
|
|
142
142
|
|
|
143
|
+
When a [`.foreach()`](https://mastra.ai/reference/workflows/workflow-methods/foreach) step suspends across multiple iterations, pass `forEachIndex` (zero-based; `0` targets the first iteration) to resume one iteration at a time. Iterations you don't target remain suspended.
|
|
144
|
+
|
|
145
|
+
```typescript
|
|
146
|
+
await run.resume({
|
|
147
|
+
step: 'approve',
|
|
148
|
+
resumeData: { ok: true },
|
|
149
|
+
forEachIndex: 1, // resumes the second iteration
|
|
150
|
+
})
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
`forEachIndex` is also supported by `resumeAsync()` and `resumeStream()`.
|
|
154
|
+
|
|
143
155
|
### `cancel()`
|
|
144
156
|
|
|
145
157
|
Cancel a running workflow:
|
|
@@ -196,4 +208,53 @@ A workflow run result yields the following:
|
|
|
196
208
|
|
|
197
209
|
**eventTimestamp** (`Date`): The timestamp of the event
|
|
198
210
|
|
|
199
|
-
**payload** (`object`): Contains currentStep (id, status, output, payload) and workflowState (status, steps record)
|
|
211
|
+
**payload** (`object`): Contains currentStep (id, status, output, payload) and workflowState (status, steps record)
|
|
212
|
+
|
|
213
|
+
## Schedules
|
|
214
|
+
|
|
215
|
+
Schedules are declared in code via the `schedule` field on `createWorkflow`. The client SDK exposes read and operational methods for managing them at runtime. See [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows).
|
|
216
|
+
|
|
217
|
+
### `listSchedules()`
|
|
218
|
+
|
|
219
|
+
List all schedules, optionally filtered by workflow id or status.
|
|
220
|
+
|
|
221
|
+
```typescript
|
|
222
|
+
const schedules = await mastraClient.listSchedules({
|
|
223
|
+
workflowId: 'daily-report',
|
|
224
|
+
status: 'active',
|
|
225
|
+
})
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
### `getSchedule()`
|
|
229
|
+
|
|
230
|
+
Fetch a single schedule by id.
|
|
231
|
+
|
|
232
|
+
```typescript
|
|
233
|
+
const schedule = await mastraClient.getSchedule('daily-report')
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
### `pauseSchedule()`
|
|
237
|
+
|
|
238
|
+
Pause a schedule so the scheduler stops firing it. Returns the updated schedule. Idempotent.
|
|
239
|
+
|
|
240
|
+
```typescript
|
|
241
|
+
await mastraClient.pauseSchedule('daily-report')
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
### `resumeSchedule()`
|
|
245
|
+
|
|
246
|
+
Resume a paused schedule. The next fire time is recomputed from now, so a long-paused schedule does not fire a backlog. Returns the updated schedule. Idempotent.
|
|
247
|
+
|
|
248
|
+
```typescript
|
|
249
|
+
await mastraClient.resumeSchedule('daily-report')
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
### `listScheduleTriggers()`
|
|
253
|
+
|
|
254
|
+
List the trigger history for a schedule, including the joined run summary for each fire.
|
|
255
|
+
|
|
256
|
+
```typescript
|
|
257
|
+
const { triggers } = await mastraClient.listScheduleTriggers('daily-report', {
|
|
258
|
+
limit: 50,
|
|
259
|
+
})
|
|
260
|
+
```
|