@mastra/client-js 0.0.0-error-handler-fix-20251020202607 → 0.0.0-esbuild-bundle-worker-20260807182016

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.
Files changed (127) hide show
  1. package/CHANGELOG.md +9405 -3
  2. package/LICENSE.md +15 -0
  3. package/README.md +11 -13
  4. package/dist/_types/@ai-sdk_provider/dist/index.d.ts +1587 -0
  5. package/dist/_types/@ai-sdk_provider-utils/dist/index.d.ts +379 -0
  6. package/dist/_types/@ai-sdk_ui-utils/dist/index.d.ts +820 -0
  7. package/dist/agent-learning.d.ts +182 -0
  8. package/dist/agent-learning.d.ts.map +1 -0
  9. package/dist/client.d.ts +767 -80
  10. package/dist/client.d.ts.map +1 -1
  11. package/dist/docs/SKILL.md +52 -0
  12. package/dist/docs/assets/SOURCE_MAP.json +6 -0
  13. package/dist/docs/references/docs-agents-a2a.md +340 -0
  14. package/dist/docs/references/docs-editor-overview.md +349 -0
  15. package/dist/docs/references/docs-long-running-agents-schedules.md +201 -0
  16. package/dist/docs/references/docs-long-running-agents-signals.md +426 -0
  17. package/dist/docs/references/docs-server-auth-auth0.md +262 -0
  18. package/dist/docs/references/docs-server-auth-clerk.md +154 -0
  19. package/dist/docs/references/docs-server-auth-firebase.md +294 -0
  20. package/dist/docs/references/docs-server-auth-jwt.md +116 -0
  21. package/dist/docs/references/docs-server-auth-supabase.md +139 -0
  22. package/dist/docs/references/docs-server-auth-workos.md +271 -0
  23. package/dist/docs/references/docs-server-mastra-client.md +323 -0
  24. package/dist/docs/references/reference-ai-sdk-to-ai-sdk-messages.md +97 -0
  25. package/dist/docs/references/reference-ai-sdk-to-ai-sdk-stream.md +282 -0
  26. package/dist/docs/references/reference-ai-sdk-to-ai-sdk-v4-messages.md +81 -0
  27. package/dist/docs/references/reference-ai-sdk-to-ai-sdk-v5-messages.md +78 -0
  28. package/dist/docs/references/reference-client-js-agents.md +959 -0
  29. package/dist/docs/references/reference-client-js-conversations.md +137 -0
  30. package/dist/docs/references/reference-client-js-error-handling.md +18 -0
  31. package/dist/docs/references/reference-client-js-logs.md +26 -0
  32. package/dist/docs/references/reference-client-js-mastra-client.md +96 -0
  33. package/dist/docs/references/reference-client-js-memory.md +237 -0
  34. package/dist/docs/references/reference-client-js-observability.md +183 -0
  35. package/dist/docs/references/reference-client-js-responses.md +219 -0
  36. package/dist/docs/references/reference-client-js-telemetry.md +22 -0
  37. package/dist/docs/references/reference-client-js-tools.md +46 -0
  38. package/dist/docs/references/reference-client-js-vectors.md +81 -0
  39. package/dist/docs/references/reference-client-js-workflows.md +393 -0
  40. package/dist/docs/references/reference-editor-versioning.md +130 -0
  41. package/dist/index.cjs +7638 -3257
  42. package/dist/index.cjs.map +1 -1
  43. package/dist/index.d.ts +9 -0
  44. package/dist/index.d.ts.map +1 -1
  45. package/dist/index.js +7606 -3252
  46. package/dist/index.js.map +1 -1
  47. package/dist/observability/collector.d.ts +45 -0
  48. package/dist/observability/collector.d.ts.map +1 -0
  49. package/dist/observability/index.d.ts +14 -0
  50. package/dist/observability/index.d.ts.map +1 -0
  51. package/dist/observability/types.d.ts +27 -0
  52. package/dist/observability/types.d.ts.map +1 -0
  53. package/dist/resources/a2a.d.ts +80 -11
  54. package/dist/resources/a2a.d.ts.map +1 -1
  55. package/dist/resources/agent-builder.d.ts +57 -72
  56. package/dist/resources/agent-builder.d.ts.map +1 -1
  57. package/dist/resources/agent-controller.d.ts +589 -0
  58. package/dist/resources/agent-controller.d.ts.map +1 -0
  59. package/dist/resources/agent.d.ts +368 -59
  60. package/dist/resources/agent.d.ts.map +1 -1
  61. package/dist/resources/base.d.ts +2 -1
  62. package/dist/resources/base.d.ts.map +1 -1
  63. package/dist/resources/channels.d.ts +63 -0
  64. package/dist/resources/channels.d.ts.map +1 -0
  65. package/dist/resources/conversations.d.ts +15 -0
  66. package/dist/resources/conversations.d.ts.map +1 -0
  67. package/dist/resources/index.d.ts +14 -0
  68. package/dist/resources/index.d.ts.map +1 -1
  69. package/dist/resources/mcp-tool.d.ts +5 -5
  70. package/dist/resources/mcp-tool.d.ts.map +1 -1
  71. package/dist/resources/memory-thread.d.ts +51 -16
  72. package/dist/resources/memory-thread.d.ts.map +1 -1
  73. package/dist/resources/observability.d.ts +222 -19
  74. package/dist/resources/observability.d.ts.map +1 -1
  75. package/dist/resources/processor-provider.d.ts +15 -0
  76. package/dist/resources/processor-provider.d.ts.map +1 -0
  77. package/dist/resources/processor.d.ts +20 -0
  78. package/dist/resources/processor.d.ts.map +1 -0
  79. package/dist/resources/responses.d.ts +22 -0
  80. package/dist/resources/responses.d.ts.map +1 -0
  81. package/dist/resources/run.d.ts +256 -0
  82. package/dist/resources/run.d.ts.map +1 -0
  83. package/dist/resources/stored-agent.d.ts +112 -0
  84. package/dist/resources/stored-agent.d.ts.map +1 -0
  85. package/dist/resources/stored-mcp-client.d.ts +30 -0
  86. package/dist/resources/stored-mcp-client.d.ts.map +1 -0
  87. package/dist/resources/stored-prompt-block.d.ts +83 -0
  88. package/dist/resources/stored-prompt-block.d.ts.map +1 -0
  89. package/dist/resources/stored-scorer.d.ts +83 -0
  90. package/dist/resources/stored-scorer.d.ts.map +1 -0
  91. package/dist/resources/stored-skill.d.ts +40 -0
  92. package/dist/resources/stored-skill.d.ts.map +1 -0
  93. package/dist/resources/stored-workflow.d.ts +18 -0
  94. package/dist/resources/stored-workflow.d.ts.map +1 -0
  95. package/dist/resources/tool-provider.d.ts +80 -0
  96. package/dist/resources/tool-provider.d.ts.map +1 -0
  97. package/dist/resources/tool.d.ts +4 -4
  98. package/dist/resources/vector.d.ts +9 -9
  99. package/dist/resources/vector.d.ts.map +1 -1
  100. package/dist/resources/workflow.d.ts +32 -231
  101. package/dist/resources/workflow.d.ts.map +1 -1
  102. package/dist/resources/workspace.d.ts +129 -0
  103. package/dist/resources/workspace.d.ts.map +1 -0
  104. package/dist/route-types.generated.d.ts +18087 -0
  105. package/dist/route-types.generated.d.ts.map +1 -0
  106. package/dist/tools.d.ts +3 -6
  107. package/dist/tools.d.ts.map +1 -1
  108. package/dist/types.d.ts +2740 -197
  109. package/dist/types.d.ts.map +1 -1
  110. package/dist/utils/client-tool-model-output.d.ts +16 -0
  111. package/dist/utils/client-tool-model-output.d.ts.map +1 -0
  112. package/dist/utils/index.d.ts +65 -4
  113. package/dist/utils/index.d.ts.map +1 -1
  114. package/dist/utils/process-a2a-stream.d.ts +4 -0
  115. package/dist/utils/process-a2a-stream.d.ts.map +1 -0
  116. package/dist/utils/process-client-tools.d.ts.map +1 -1
  117. package/dist/utils/process-mastra-stream.d.ts +8 -7
  118. package/dist/utils/process-mastra-stream.d.ts.map +1 -1
  119. package/dist/utils/stream-transforms.d.ts +9 -0
  120. package/dist/utils/stream-transforms.d.ts.map +1 -0
  121. package/dist/utils/verify-agent-card-signature.d.ts +21 -0
  122. package/dist/utils/verify-agent-card-signature.d.ts.map +1 -0
  123. package/dist/utils/zod-to-json-schema.d.ts +11 -2
  124. package/dist/utils/zod-to-json-schema.d.ts.map +1 -1
  125. package/package.json +26 -19
  126. package/dist/resources/network-memory-thread.d.ts +0 -47
  127. package/dist/resources/network-memory-thread.d.ts.map +0 -1
@@ -0,0 +1,271 @@
1
+ > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
2
+
3
+ # WorkOS
4
+
5
+ The `@mastra/auth-workos` package provides authentication for Mastra using WorkOS. It verifies incoming requests using WorkOS access tokens and integrates with the Mastra server using the `auth` option.
6
+
7
+ ## Prerequisites
8
+
9
+ This example uses WorkOS authentication. Make sure to:
10
+
11
+ 1. Create a WorkOS account at [workos.com](https://workos.com/)
12
+ 2. Set up an Application in your WorkOS Dashboard
13
+ 3. Configure your redirect URIs and allowed origins
14
+ 4. Set up Organizations and configure user roles as needed
15
+
16
+ ```env
17
+ WORKOS_API_KEY=sk_live_...
18
+ WORKOS_CLIENT_ID=client_...
19
+ ```
20
+
21
+ > **Note:** You can find your API key and Client ID in the WorkOS Dashboard under API Keys and Applications respectively.
22
+ >
23
+ > For detailed setup instructions, refer to the [WorkOS documentation](https://workos.com/docs) for your specific platform.
24
+
25
+ ## Installation
26
+
27
+ Before you can use the `MastraAuthWorkos` class you have to install the `@mastra/auth-workos` package.
28
+
29
+ **npm**:
30
+
31
+ ```bash
32
+ npm install @mastra/auth-workos@latest
33
+ ```
34
+
35
+ **pnpm**:
36
+
37
+ ```bash
38
+ pnpm add @mastra/auth-workos@latest
39
+ ```
40
+
41
+ **Yarn**:
42
+
43
+ ```bash
44
+ yarn add @mastra/auth-workos@latest
45
+ ```
46
+
47
+ **Bun**:
48
+
49
+ ```bash
50
+ bun add @mastra/auth-workos@latest
51
+ ```
52
+
53
+ ## Usage examples
54
+
55
+ ### Basic usage with environment variables
56
+
57
+ ```typescript
58
+ import { Mastra } from '@mastra/core'
59
+ import { MastraAuthWorkos } from '@mastra/auth-workos'
60
+
61
+ export const mastra = new Mastra({
62
+ server: {
63
+ auth: new MastraAuthWorkos(),
64
+ },
65
+ })
66
+ ```
67
+
68
+ ### Custom configuration
69
+
70
+ ```typescript
71
+ import { Mastra } from '@mastra/core'
72
+ import { MastraAuthWorkos } from '@mastra/auth-workos'
73
+
74
+ export const mastra = new Mastra({
75
+ server: {
76
+ auth: new MastraAuthWorkos({
77
+ apiKey: process.env.WORKOS_API_KEY,
78
+ clientId: process.env.WORKOS_CLIENT_ID,
79
+ }),
80
+ },
81
+ })
82
+ ```
83
+
84
+ ## Configuration
85
+
86
+ ### Default authorization
87
+
88
+ By default, `MastraAuthWorkos` grants access to any authenticated WorkOS user. The authorization check succeeds when the resolved user object contains both a Mastra user ID and a WorkOS user ID.
89
+
90
+ ### FGA membership loading
91
+
92
+ Set `fetchMemberships: true` when you use [`MastraFGAWorkos`](https://mastra.ai/docs/server/auth/fga). This tells the auth provider to load the user's WorkOS organization memberships during authentication so FGA checks can resolve the correct organization membership ID.
93
+
94
+ ```typescript
95
+ import { MastraAuthWorkos, MastraFGAWorkos } from '@mastra/auth-workos'
96
+
97
+ const workosAuth = new MastraAuthWorkos({
98
+ apiKey: process.env.WORKOS_API_KEY,
99
+ clientId: process.env.WORKOS_CLIENT_ID,
100
+ fetchMemberships: true,
101
+ })
102
+
103
+ const workosFga = new MastraFGAWorkos({
104
+ apiKey: process.env.WORKOS_API_KEY,
105
+ clientId: process.env.WORKOS_CLIENT_ID,
106
+ })
107
+ ```
108
+
109
+ When `fetchMemberships` is `false`, Mastra skips the extra WorkOS `listOrganizationMemberships()` call on each authenticated request.
110
+
111
+ ### Service tokens and custom JWT templates
112
+
113
+ For machine-to-machine or service-account access, you can configure `MastraAuthWorkos` to trust verified bearer-token claims from a WorkOS custom JWT template.
114
+
115
+ ```typescript
116
+ import { MastraAuthWorkos } from '@mastra/auth-workos'
117
+
118
+ const workosAuth = new MastraAuthWorkos({
119
+ apiKey: process.env.WORKOS_API_KEY,
120
+ clientId: process.env.WORKOS_CLIENT_ID,
121
+ redirectUri: process.env.WORKOS_REDIRECT_URI,
122
+ trustJwtClaims: true,
123
+ jwtClaims: {
124
+ organizationId: 'org_id',
125
+ organizationMembershipId: 'urn:mastra:organization_membership_id',
126
+ },
127
+ })
128
+ ```
129
+
130
+ This is useful when your JWT template already includes the exact FGA context Mastra needs, such as `organizationMembershipId`, tenant IDs, or service-principal identifiers. When `trustJwtClaims` is enabled, Mastra can fall back to those verified claims if a bearer token isn't meant to round-trip through `workos.userManagement.getUser()`.
131
+
132
+ ### Custom authorization
133
+
134
+ If you need stricter authorization, subclass `MastraAuthWorkos` and override `authorizeUser()`:
135
+
136
+ ```typescript
137
+ import { MastraAuthWorkos } from '@mastra/auth-workos'
138
+ import type { HonoRequest } from 'hono'
139
+
140
+ class AdminOnlyWorkosAuth extends MastraAuthWorkos {
141
+ async authorizeUser(user: any, _request: HonoRequest): Promise<boolean> {
142
+ return user?.metadata?.role === 'admin'
143
+ }
144
+ }
145
+
146
+ const workosAuth = new AdminOnlyWorkosAuth({
147
+ apiKey: process.env.WORKOS_API_KEY,
148
+ clientId: process.env.WORKOS_CLIENT_ID,
149
+ })
150
+ ```
151
+
152
+ Visit [MastraAuthWorkos](https://mastra.ai/reference/auth/workos) for all available configuration options.
153
+
154
+ ## Client-side setup
155
+
156
+ When using WorkOS auth, you'll need to implement the WorkOS authentication flow to exchange an authorization code for an access token, then use that token with your Mastra requests.
157
+
158
+ ### Installing WorkOS SDK
159
+
160
+ First, install the WorkOS SDK in your application:
161
+
162
+ **npm**:
163
+
164
+ ```bash
165
+ npm install @workos-inc/node
166
+ ```
167
+
168
+ **pnpm**:
169
+
170
+ ```bash
171
+ pnpm add @workos-inc/node
172
+ ```
173
+
174
+ **Yarn**:
175
+
176
+ ```bash
177
+ yarn add @workos-inc/node
178
+ ```
179
+
180
+ **Bun**:
181
+
182
+ ```bash
183
+ bun add @workos-inc/node
184
+ ```
185
+
186
+ ### Exchanging code for access token
187
+
188
+ After users complete the WorkOS authentication flow and return with an authorization code, exchange it for an access token:
189
+
190
+ ```typescript
191
+ import { WorkOS } from '@workos-inc/node'
192
+
193
+ const workos = new WorkOS(process.env.WORKOS_API_KEY)
194
+
195
+ export const authenticateWithWorkos = async (code: string, clientId: string) => {
196
+ const authenticationResponse = await workos.userManagement.authenticateWithCode({
197
+ code,
198
+ clientId,
199
+ })
200
+
201
+ return authenticationResponse.accessToken
202
+ }
203
+ ```
204
+
205
+ > **Note:** Refer to the [WorkOS User Management documentation](https://workos.com/docs/authkit/vanilla/nodejs) for more authentication methods and configuration options.
206
+
207
+ ## Configuring `MastraClient`
208
+
209
+ When `auth` is enabled, all requests made with `MastraClient` must include a valid WorkOS access token in the `Authorization` header:
210
+
211
+ ```typescript
212
+ import { MastraClient } from '@mastra/client-js'
213
+
214
+ export const createMastraClient = (accessToken: string) => {
215
+ return new MastraClient({
216
+ baseUrl: 'https://<mastra-api-url>',
217
+ headers: {
218
+ Authorization: `Bearer ${accessToken}`,
219
+ },
220
+ })
221
+ }
222
+ ```
223
+
224
+ > **Info:** The access token must be prefixed with `Bearer` in the Authorization header.
225
+ >
226
+ > Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
227
+
228
+ ### Making authenticated requests
229
+
230
+ Once `MastraClient` is configured with the WorkOS access token, you can send authenticated requests:
231
+
232
+ **React**:
233
+
234
+ ```typescript
235
+ import { WorkOS } from '@workos-inc/node'
236
+ import { MastraClient } from '@mastra/client-js'
237
+
238
+ const workos = new WorkOS(process.env.WORKOS_API_KEY)
239
+
240
+ export const callMastraWithWorkos = async (code: string, clientId: string) => {
241
+ const authenticationResponse = await workos.userManagement.authenticateWithCode({
242
+ code,
243
+ clientId,
244
+ })
245
+
246
+ const token = authenticationResponse.accessToken
247
+
248
+ const mastra = new MastraClient({
249
+ baseUrl: 'http://localhost:4111',
250
+ headers: {
251
+ Authorization: `Bearer ${token}`,
252
+ },
253
+ })
254
+
255
+ const weatherAgent = mastra.getAgent('weatherAgent')
256
+ const response = await weatherAgent.generate("What's the weather like in Nairobi")
257
+
258
+ return response.text
259
+ }
260
+ ```
261
+
262
+ **cURL**:
263
+
264
+ ```bash
265
+ curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
266
+ -H "Content-Type: application/json" \
267
+ -H "Authorization: Bearer <your-workos-access-token>" \
268
+ -d '{
269
+ "messages": "Weather in London"
270
+ }'
271
+ ```
@@ -0,0 +1,323 @@
1
+ > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
2
+
3
+ # Mastra client SDK
4
+
5
+ The Mastra Client SDK provides a concise and type-safe interface for interacting with your [Mastra Server](https://mastra.ai/docs/server/mastra-server) from your client environment.
6
+
7
+ ## Prerequisites
8
+
9
+ Before you start local development, have:
10
+
11
+ - Node.js `v22.13.0` or later
12
+ - TypeScript `v4.7` or higher (if using TypeScript)
13
+ - Your local Mastra server running (typically on port `4111`)
14
+
15
+ > **Note:** The Mastra Client SDK is designed for browser environments and uses the native `fetch` API for making HTTP requests to your Mastra server.
16
+
17
+ ## Installation
18
+
19
+ To use the Mastra Client SDK, install the required dependencies:
20
+
21
+ **npm**:
22
+
23
+ ```bash
24
+ npm install @mastra/client-js@latest
25
+ ```
26
+
27
+ **pnpm**:
28
+
29
+ ```bash
30
+ pnpm add @mastra/client-js@latest
31
+ ```
32
+
33
+ **Yarn**:
34
+
35
+ ```bash
36
+ yarn add @mastra/client-js@latest
37
+ ```
38
+
39
+ **Bun**:
40
+
41
+ ```bash
42
+ bun add @mastra/client-js@latest
43
+ ```
44
+
45
+ ### Initialize the `MastraClient`
46
+
47
+ Once initialized with a `baseUrl`, `MastraClient` exposes a type-safe interface for calling agents, tools, and workflows.
48
+
49
+ ```typescript
50
+ import { MastraClient } from '@mastra/client-js'
51
+
52
+ export const mastraClient = new MastraClient({
53
+ baseUrl: process.env.MASTRA_API_URL || 'http://localhost:4111',
54
+ })
55
+ ```
56
+
57
+ ## Core APIs
58
+
59
+ The Mastra Client SDK exposes all resources served by the Mastra Server.
60
+
61
+ - **[Agents](https://mastra.ai/reference/client-js/agents)**: Generate responses and stream conversations.
62
+ - **[A2A](https://mastra.ai/docs/agents/a2a)**: Discover agents through agent cards and work with task-based A2A streams.
63
+ - **[Memory](https://mastra.ai/reference/client-js/memory)**: Manage conversation threads and message history.
64
+ - **[Tools](https://mastra.ai/reference/client-js/tools)**: Executed and managed tools.
65
+ - **[Workflows](https://mastra.ai/reference/client-js/workflows)**: Trigger workflows and track their execution.
66
+ - **[Vectors](https://mastra.ai/reference/client-js/vectors)**: Use vector embeddings for semantic search.
67
+ - **[Responses](https://mastra.ai/reference/client-js/responses)**: Use Mastra Agents as a Responses API with an OpenAI-compatible, agent-backed interface. This API is currently experimental.
68
+ - **[Conversations](https://mastra.ai/reference/client-js/conversations)**: Work with the stored conversation threads and item history behind Mastra Agents as a Responses API. This API is currently experimental.
69
+ - **[Logs](https://mastra.ai/reference/client-js/logs)**: View logs and debug system behavior.
70
+ - **[Telemetry](https://mastra.ai/reference/client-js/telemetry)**: View app performance and trace activity.
71
+
72
+ ## Create and run stored workflows
73
+
74
+ Use `upsertStoredWorkflow()` to create or replace a persisted workflow definition. A successful upsert validates the complete definition, registers it with the running Mastra instance, and makes it available through the standard workflow execution API.
75
+
76
+ The following example shows the full lifecycle of a mapping workflow, from creation and inspection through execution and deletion:
77
+
78
+ ```typescript
79
+ import { MastraClient } from '@mastra/client-js'
80
+ import type { UpsertStoredWorkflowParams } from '@mastra/client-js'
81
+
82
+ const client = new MastraClient({
83
+ baseUrl: process.env.MASTRA_API_URL || 'http://localhost:4111',
84
+ })
85
+
86
+ const definition = {
87
+ id: 'greeting-workflow',
88
+ description: 'Returns a greeting for the supplied name',
89
+ inputSchema: {
90
+ type: 'object',
91
+ properties: { name: { type: 'string' } },
92
+ required: ['name'],
93
+ },
94
+ outputSchema: {
95
+ type: 'object',
96
+ properties: { message: { type: 'string' } },
97
+ required: ['message'],
98
+ },
99
+ graph: [
100
+ {
101
+ type: 'mapping',
102
+ id: 'create-greeting',
103
+ mapConfig: JSON.stringify({
104
+ message: { template: 'Hello, ${initData.name}!' },
105
+ }),
106
+ },
107
+ ],
108
+ } satisfies UpsertStoredWorkflowParams
109
+
110
+ await client.upsertStoredWorkflow(definition)
111
+
112
+ const storedWorkflow = client.getStoredWorkflow(definition.id)
113
+ const storedDefinition = await storedWorkflow.details()
114
+
115
+ const workflow = client.getWorkflow(storedDefinition.id)
116
+ const run = await workflow.createRun()
117
+ const result = await run.startAsync({ inputData: { name: 'Ada' } })
118
+
119
+ console.log(result)
120
+
121
+ await storedWorkflow.delete()
122
+ ```
123
+
124
+ Use `listStoredWorkflows()` to list persisted definitions. Calling `upsertStoredWorkflow()` again with the same `id` replaces the stored definition and live workflow registration.
125
+
126
+ > **Warning:** Durable storage requires a configured storage adapter that supports the `workflowDefinitions` domain. Without that domain, Core can register a workflow in memory, but the server's stored-workflow API can't preserve it across restarts.
127
+ >
128
+ > Stored definitions support declarative agent, tool, mapping, nested workflow, parallel, foreach, sleep, sleep-until, conditional, and loop entries. They can't contain JavaScript closures. Conditional and loop logic must use the declarative predicate format, and referenced agents, tools, and nested workflows must already be registered.
129
+ >
130
+ > Authenticated servers require `stored-workflows:read` or `stored-workflows:write` for definition operations and `workflows:execute` to run the workflow.
131
+
132
+ ## Generating responses
133
+
134
+ Call `.generate()` with a string prompt:
135
+
136
+ ```typescript
137
+ import { mastraClient } from 'lib/mastra-client'
138
+
139
+ const testAgent = async () => {
140
+ try {
141
+ const agent = mastraClient.getAgent('testAgent')
142
+
143
+ const response = await agent.generate('Hello')
144
+
145
+ console.log(response.text)
146
+ } catch (error) {
147
+ return 'Error occurred while generating response'
148
+ }
149
+ }
150
+ ```
151
+
152
+ > **Info:** You can also call `.generate()` with an array of message objects that include `role` and `content`. Visit the [.generate() reference](https://mastra.ai/reference/client-js/agents) for more information.
153
+
154
+ ## Streaming responses
155
+
156
+ Use `.stream()` for real-time responses with a string prompt:
157
+
158
+ ```typescript
159
+ import { mastraClient } from 'lib/mastra-client'
160
+
161
+ const testAgent = async () => {
162
+ try {
163
+ const agent = mastraClient.getAgent('testAgent')
164
+
165
+ const stream = await agent.stream('Hello')
166
+
167
+ stream.processDataStream({
168
+ onTextPart: text => {
169
+ console.log(text)
170
+ },
171
+ })
172
+ } catch (error) {
173
+ return 'Error occurred while generating response'
174
+ }
175
+ }
176
+ ```
177
+
178
+ > **Info:** You can also call `.stream()` with an array of message objects that include `role` and `content`. Visit the [.stream() reference](https://mastra.ai/reference/client-js/agents) for more information.
179
+
180
+ ## Configuration options
181
+
182
+ `MastraClient` accepts optional parameters like `retries`, `backoffMs`, and `headers` to control request behavior. These parameters are useful for controlling retry behavior and including diagnostic metadata.
183
+
184
+ ```typescript
185
+ import { MastraClient } from '@mastra/client-js'
186
+
187
+ export const mastraClient = new MastraClient({
188
+ retries: 3,
189
+ backoffMs: 300,
190
+ maxBackoffMs: 5000,
191
+ headers: {
192
+ 'X-Development': 'true',
193
+ },
194
+ })
195
+ ```
196
+
197
+ Visit [MastraClient](https://mastra.ai/reference/client-js/mastra-client) for more configuration options.
198
+
199
+ ## Credentials and session cookies
200
+
201
+ **Authenticate Mastra API calls with session cookies** when your UI and Mastra API aren't on the same origin, different host, subdomain, or port (for example Mastra Studio on one port and a custom server on another). Add **`credentials: 'include'`** to `MastraClient` so each request carries the cookies the user already has after sign-in. Skip this and you will often get **`401`** responses from Mastra even though login succeeded in the browser.
202
+
203
+ ```typescript
204
+ import { MastraClient } from '@mastra/client-js'
205
+
206
+ export const mastraClient = new MastraClient({
207
+ baseUrl: process.env.MASTRA_API_URL || 'http://localhost:4111',
208
+ credentials: 'include',
209
+ })
210
+ ```
211
+
212
+ **Allow credentialed cross-origin requests on your server**, see [CORS: requests with credentials](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS#requests_with_credentials). You need a concrete `Access-Control-Allow-Origin` (not `*`) and `Access-Control-Allow-Credentials: true`, or the browser will block the call before it reaches Mastra.
213
+
214
+ **Using `@mastra/react`?** Wrap your app with `MastraReactProvider`, set `baseUrl` and `apiPrefix` to match your server, and rely on the default `credentials: 'include'`. Change `credentials` only when you want `same-origin` or `omit` behavior.
215
+
216
+ ## Adding request cancelling
217
+
218
+ `MastraClient` supports request cancellation using the standard Node.js `AbortSignal` API. Useful for canceling in-flight requests, such as when users abort an operation or to clean up stale network calls.
219
+
220
+ Pass an `AbortSignal` to the client constructor to enable cancellation across all requests.
221
+
222
+ ```typescript
223
+ import { MastraClient } from '@mastra/client-js'
224
+
225
+ export const controller = new AbortController()
226
+
227
+ export const mastraClient = new MastraClient({
228
+ baseUrl: process.env.MASTRA_API_URL || 'http://localhost:4111',
229
+ abortSignal: controller.signal,
230
+ })
231
+ ```
232
+
233
+ ### Using the `AbortController`
234
+
235
+ Calling `.abort()` will cancel any ongoing requests tied to that signal.
236
+
237
+ ```typescript
238
+ import { mastraClient, controller } from 'lib/mastra-client'
239
+
240
+ const handleAbort = () => {
241
+ controller.abort()
242
+ }
243
+ ```
244
+
245
+ ## Client tools
246
+
247
+ Define tools directly in client-side applications using the `createTool()` function. Pass them to agents via the `clientTools` parameter in `.generate()` or `.stream()` calls.
248
+
249
+ This lets agents trigger browser-side functionality such as DOM manipulation, local storage access, or other Web APIs, enabling tool execution in the user's environment rather than on the server.
250
+
251
+ ```typescript
252
+ import { createTool } from '@mastra/client-js'
253
+ import { z } from 'zod'
254
+
255
+ const handleClientTool = async () => {
256
+ try {
257
+ const agent = mastraClient.getAgent('colorAgent')
258
+
259
+ const colorChangeTool = createTool({
260
+ id: 'color-change-tool',
261
+ description: 'Changes the HTML background color',
262
+ inputSchema: z.object({
263
+ color: z.string(),
264
+ }),
265
+ outputSchema: z.object({
266
+ success: z.boolean(),
267
+ }),
268
+ execute: async inputData => {
269
+ const { color } = inputData
270
+
271
+ document.body.style.backgroundColor = color
272
+ return { success: true }
273
+ },
274
+ })
275
+
276
+ const response = await agent.generate('Change the background to blue', {
277
+ clientTools: { colorChangeTool },
278
+ })
279
+
280
+ console.log(response)
281
+ } catch (error) {
282
+ console.error(error)
283
+ }
284
+ }
285
+ ```
286
+
287
+ ### Client tool agent
288
+
289
+ This is a standard Mastra [agent](https://mastra.ai/docs/agents/overview) configured to return hex color codes, intended to work with the browser-based client tool defined above.
290
+
291
+ ```typescript
292
+ import { Agent } from '@mastra/core/agent'
293
+
294
+ export const colorAgent = new Agent({
295
+ id: 'color-agent',
296
+ name: 'Color Agent',
297
+ instructions: `You are a helpful CSS assistant.
298
+ You can change the background color of web pages.
299
+ Respond with a hex reference for the color requested by the user`,
300
+ model: 'openai/gpt-5.6-sol',
301
+ })
302
+ ```
303
+
304
+ ## Use MastraClient on the server
305
+
306
+ You can also use `MastraClient` in server-side environments such as API routes, serverless functions, or actions. The usage remains the same, but you may need to recreate the response for your client:
307
+
308
+ ```typescript
309
+ export async function action() {
310
+ const agent = mastraClient.getAgent('testAgent')
311
+
312
+ const stream = await agent.stream('Hello')
313
+
314
+ return new Response(stream.body)
315
+ }
316
+ ```
317
+
318
+ ## Best practices
319
+
320
+ 1. **Error Handling**: Use [error handling](https://mastra.ai/reference/client-js/error-handling) for development scenarios.
321
+ 2. **Environment Variables**: Use environment variables for configuration.
322
+ 3. **Debugging**: Enable detailed [logging](https://mastra.ai/reference/client-js/logs) when needed.
323
+ 4. **Performance**: Track application performance, [telemetry](https://mastra.ai/reference/client-js/telemetry), and traces.
@@ -0,0 +1,97 @@
1
+ > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
2
+
3
+ # toAISdkMessages()
4
+
5
+ Converts messages from input formats to AI SDK UI message format. `toAISdkMessages()` keeps the existing AI SDK v5/default behavior. If your app is typed against AI SDK v6, pass `version: 'v6'`.
6
+
7
+ `version: 'v6'` uses the MessageList AI SDK v6 UI output path. MessageList input detection and ingestion remain unchanged.
8
+
9
+ ## Usage example
10
+
11
+ ```typescript
12
+ import { toAISdkMessages } from '@mastra/ai-sdk/ui'
13
+ import { useChat } from 'ai/react'
14
+
15
+ // Stored messages from your database, memory, or API
16
+ const storedMessages = [
17
+ { id: '1', role: 'user', content: 'Hello', parts: [{ type: 'text', text: 'Hello' }] },
18
+ {
19
+ id: '2',
20
+ role: 'assistant',
21
+ content: 'Hi there!',
22
+ parts: [{ type: 'text', text: 'Hi there!' }],
23
+ },
24
+ ]
25
+
26
+ export default function Chat() {
27
+ const { messages } = useChat({
28
+ initialMessages: toAISdkMessages(storedMessages, { version: 'v6' }),
29
+ })
30
+
31
+ return (
32
+ <div>
33
+ {messages.map(message => (
34
+ <div key={message.id}>
35
+ {message.role}: {message.parts.map(part => (part.type === 'text' ? part.text : null))}
36
+ </div>
37
+ ))}
38
+ </div>
39
+ )
40
+ }
41
+ ```
42
+
43
+ ## Parameters
44
+
45
+ **messages** (`MessageListInput`): Messages to convert. Can be a string, array of strings, a single message object, or an array of message objects in any supported format.
46
+
47
+ **options.version** (`'v5' | 'v6'`): Selects the AI SDK message type to return. Omit it or pass 'v5' for the existing default behavior. Pass 'v6' when your app is typed against AI SDK v6 useChat() message types.
48
+
49
+ ## Returns
50
+
51
+ Returns an array of AI SDK `UIMessage` objects typed for the selected version.
52
+
53
+ **id** (`string`): Unique message identifier.
54
+
55
+ **role** (`'user' | 'assistant' | 'system'`): The role of the message sender.
56
+
57
+ **parts** (`UIMessagePart[]`): Array of UI parts including text, tool results, files, reasoning, sources, and step markers.
58
+
59
+ **metadata** (`Record<string, unknown>`): Optional metadata including createdAt, threadId, resourceId, and custom fields.
60
+
61
+ ## Examples
62
+
63
+ ### Using the default AI SDK v5 types
64
+
65
+ ```typescript
66
+ import { toAISdkMessages } from '@mastra/ai-sdk/ui'
67
+
68
+ const messages = toAISdkMessages(['Hello', 'How can I help you today?'])
69
+ ```
70
+
71
+ ### Returning AI SDK v6 message types
72
+
73
+ ```typescript
74
+ import { toAISdkMessages } from '@mastra/ai-sdk/ui'
75
+
76
+ const messages = toAISdkMessages(['Hello', 'How can I help you today?'], {
77
+ version: 'v6',
78
+ })
79
+ ```
80
+
81
+ ### Loading messages with Mastra client
82
+
83
+ ```typescript
84
+ import { MastraClient } from '@mastra/client-js'
85
+ import { toAISdkMessages } from '@mastra/ai-sdk/ui'
86
+
87
+ const client = new MastraClient()
88
+
89
+ const { messages } = await client.listThreadMessages('thread-id', { agentId: 'myAgent' })
90
+ const uiMessages = toAISdkMessages(messages)
91
+ ```
92
+
93
+ ## Related
94
+
95
+ - [`toAISdkStream()`](https://mastra.ai/reference/ai-sdk/to-ai-sdk-stream)
96
+ - [`toAISdkV5Messages()`](https://mastra.ai/reference/ai-sdk/to-ai-sdk-v5-messages)
97
+ - [`toAISdkV4Messages()`](https://mastra.ai/reference/ai-sdk/to-ai-sdk-v4-messages)