@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.
- package/CHANGELOG.md +9405 -3
- package/LICENSE.md +15 -0
- package/README.md +11 -13
- package/dist/_types/@ai-sdk_provider/dist/index.d.ts +1587 -0
- package/dist/_types/@ai-sdk_provider-utils/dist/index.d.ts +379 -0
- package/dist/_types/@ai-sdk_ui-utils/dist/index.d.ts +820 -0
- package/dist/agent-learning.d.ts +182 -0
- package/dist/agent-learning.d.ts.map +1 -0
- package/dist/client.d.ts +767 -80
- package/dist/client.d.ts.map +1 -1
- package/dist/docs/SKILL.md +52 -0
- package/dist/docs/assets/SOURCE_MAP.json +6 -0
- package/dist/docs/references/docs-agents-a2a.md +340 -0
- package/dist/docs/references/docs-editor-overview.md +349 -0
- package/dist/docs/references/docs-long-running-agents-schedules.md +201 -0
- package/dist/docs/references/docs-long-running-agents-signals.md +426 -0
- package/dist/docs/references/docs-server-auth-auth0.md +262 -0
- package/dist/docs/references/docs-server-auth-clerk.md +154 -0
- package/dist/docs/references/docs-server-auth-firebase.md +294 -0
- package/dist/docs/references/docs-server-auth-jwt.md +116 -0
- package/dist/docs/references/docs-server-auth-supabase.md +139 -0
- package/dist/docs/references/docs-server-auth-workos.md +271 -0
- package/dist/docs/references/docs-server-mastra-client.md +323 -0
- package/dist/docs/references/reference-ai-sdk-to-ai-sdk-messages.md +97 -0
- package/dist/docs/references/reference-ai-sdk-to-ai-sdk-stream.md +282 -0
- package/dist/docs/references/reference-ai-sdk-to-ai-sdk-v4-messages.md +81 -0
- package/dist/docs/references/reference-ai-sdk-to-ai-sdk-v5-messages.md +78 -0
- package/dist/docs/references/reference-client-js-agents.md +959 -0
- package/dist/docs/references/reference-client-js-conversations.md +137 -0
- package/dist/docs/references/reference-client-js-error-handling.md +18 -0
- package/dist/docs/references/reference-client-js-logs.md +26 -0
- package/dist/docs/references/reference-client-js-mastra-client.md +96 -0
- package/dist/docs/references/reference-client-js-memory.md +237 -0
- package/dist/docs/references/reference-client-js-observability.md +183 -0
- package/dist/docs/references/reference-client-js-responses.md +219 -0
- package/dist/docs/references/reference-client-js-telemetry.md +22 -0
- package/dist/docs/references/reference-client-js-tools.md +46 -0
- package/dist/docs/references/reference-client-js-vectors.md +81 -0
- package/dist/docs/references/reference-client-js-workflows.md +393 -0
- package/dist/docs/references/reference-editor-versioning.md +130 -0
- package/dist/index.cjs +7638 -3257
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.ts +9 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +7606 -3252
- package/dist/index.js.map +1 -1
- package/dist/observability/collector.d.ts +45 -0
- package/dist/observability/collector.d.ts.map +1 -0
- package/dist/observability/index.d.ts +14 -0
- package/dist/observability/index.d.ts.map +1 -0
- package/dist/observability/types.d.ts +27 -0
- package/dist/observability/types.d.ts.map +1 -0
- package/dist/resources/a2a.d.ts +80 -11
- package/dist/resources/a2a.d.ts.map +1 -1
- package/dist/resources/agent-builder.d.ts +57 -72
- package/dist/resources/agent-builder.d.ts.map +1 -1
- package/dist/resources/agent-controller.d.ts +589 -0
- package/dist/resources/agent-controller.d.ts.map +1 -0
- package/dist/resources/agent.d.ts +368 -59
- package/dist/resources/agent.d.ts.map +1 -1
- package/dist/resources/base.d.ts +2 -1
- package/dist/resources/base.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/conversations.d.ts +15 -0
- package/dist/resources/conversations.d.ts.map +1 -0
- package/dist/resources/index.d.ts +14 -0
- package/dist/resources/index.d.ts.map +1 -1
- package/dist/resources/mcp-tool.d.ts +5 -5
- package/dist/resources/mcp-tool.d.ts.map +1 -1
- package/dist/resources/memory-thread.d.ts +51 -16
- package/dist/resources/memory-thread.d.ts.map +1 -1
- package/dist/resources/observability.d.ts +222 -19
- package/dist/resources/observability.d.ts.map +1 -1
- package/dist/resources/processor-provider.d.ts +15 -0
- package/dist/resources/processor-provider.d.ts.map +1 -0
- package/dist/resources/processor.d.ts +20 -0
- package/dist/resources/processor.d.ts.map +1 -0
- package/dist/resources/responses.d.ts +22 -0
- package/dist/resources/responses.d.ts.map +1 -0
- package/dist/resources/run.d.ts +256 -0
- package/dist/resources/run.d.ts.map +1 -0
- package/dist/resources/stored-agent.d.ts +112 -0
- package/dist/resources/stored-agent.d.ts.map +1 -0
- package/dist/resources/stored-mcp-client.d.ts +30 -0
- package/dist/resources/stored-mcp-client.d.ts.map +1 -0
- package/dist/resources/stored-prompt-block.d.ts +83 -0
- package/dist/resources/stored-prompt-block.d.ts.map +1 -0
- package/dist/resources/stored-scorer.d.ts +83 -0
- package/dist/resources/stored-scorer.d.ts.map +1 -0
- package/dist/resources/stored-skill.d.ts +40 -0
- package/dist/resources/stored-skill.d.ts.map +1 -0
- package/dist/resources/stored-workflow.d.ts +18 -0
- package/dist/resources/stored-workflow.d.ts.map +1 -0
- package/dist/resources/tool-provider.d.ts +80 -0
- package/dist/resources/tool-provider.d.ts.map +1 -0
- package/dist/resources/tool.d.ts +4 -4
- package/dist/resources/vector.d.ts +9 -9
- package/dist/resources/vector.d.ts.map +1 -1
- package/dist/resources/workflow.d.ts +32 -231
- package/dist/resources/workflow.d.ts.map +1 -1
- package/dist/resources/workspace.d.ts +129 -0
- package/dist/resources/workspace.d.ts.map +1 -0
- package/dist/route-types.generated.d.ts +18087 -0
- package/dist/route-types.generated.d.ts.map +1 -0
- package/dist/tools.d.ts +3 -6
- package/dist/tools.d.ts.map +1 -1
- package/dist/types.d.ts +2740 -197
- package/dist/types.d.ts.map +1 -1
- package/dist/utils/client-tool-model-output.d.ts +16 -0
- package/dist/utils/client-tool-model-output.d.ts.map +1 -0
- package/dist/utils/index.d.ts +65 -4
- package/dist/utils/index.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/dist/utils/process-client-tools.d.ts.map +1 -1
- package/dist/utils/process-mastra-stream.d.ts +8 -7
- package/dist/utils/process-mastra-stream.d.ts.map +1 -1
- package/dist/utils/stream-transforms.d.ts +9 -0
- package/dist/utils/stream-transforms.d.ts.map +1 -0
- package/dist/utils/verify-agent-card-signature.d.ts +21 -0
- package/dist/utils/verify-agent-card-signature.d.ts.map +1 -0
- package/dist/utils/zod-to-json-schema.d.ts +11 -2
- package/dist/utils/zod-to-json-schema.d.ts.map +1 -1
- package/package.json +26 -19
- package/dist/resources/network-memory-thread.d.ts +0 -47
- 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)
|