@blazingagents/sdk 0.43.0 → 0.44.0

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 (10) hide show
  1. package/README.md +67 -33
  2. package/dist/contracts/entities/agent-approval.d.ts +3 -0
  3. package/dist/contracts/entities/agent-tools.d.ts +7 -2
  4. package/dist/contracts/entities/agent-tools.js +7 -1
  5. package/dist/contracts/entities/agents.d.ts +16 -0
  6. package/dist/contracts/entities/memories.js +1 -1
  7. package/dist/contracts/entities/sessions.d.ts +5 -0
  8. package/dist/contracts/entities/tasks.d.ts +6 -0
  9. package/dist/generation.js +13 -2
  10. package/package.json +1 -1
package/README.md CHANGED
@@ -10,19 +10,24 @@
10
10
  </p>
11
11
  </div>
12
12
 
13
- The official resource-style client SDK for the Blazing Agents `/v1` API. It
14
- requires Node.js 24 or newer.
13
+ The official TypeScript SDK is a client for the Blazing Agents `/v1` API that
14
+ your backend uses to manage Agents and run them for your users. It requires
15
+ Node.js 24 or newer.
15
16
 
16
17
  ## Features
17
18
 
18
- - Typed clients for Agents, Workspaces, Skills, Providers, Prompts, Tasks,
19
- Sessions, Artifacts, Slack and Telegram Chat Connections, usage, Tenant settings, and merchant monetization.
20
- - Stateful chat with explicit message batches, steer receipts, and one-call Tool approvals.
21
- - Stateless text or structured-object generation.
22
- - Public Zod contracts for validating API requests and responses.
23
- - Cursor pagination and binary transfers.
24
- - Request correlation and a typed, forward-compatible error model.
25
- - End-user scoped clients for user-owned resources and generation.
19
+ - A typed method for every `/v1` operation an API key can call: Agents,
20
+ Skills, Sessions, Memories, Prompts, Tasks, Workspaces, Artifacts,
21
+ Providers, MCP Connections, Chat Connections, usage, spending limits, Tenant
22
+ settings, and merchant monetization.
23
+ - Chat streams in the AI SDK UI message stream format, with steering, Tool
24
+ approvals, and backend functions that run in your process.
25
+ - Text and structured-object generation.
26
+ - End-user scoped clients through `forUser`.
27
+ - Cursor pagination, uploads, and downloads.
28
+ - Request IDs and typed errors.
29
+ - `BlazingAgentsChatTransport` and `createChatRelay` connect AI SDK `useChat`
30
+ to your backend.
26
31
 
27
32
  ## Installation
28
33
 
@@ -30,19 +35,21 @@ requires Node.js 24 or newer.
30
35
  npm install @blazingagents/sdk ai@^7.0.84 zod@^4.5.4
31
36
  ```
32
37
 
33
- `ai` (`^7.0.84`) and `zod` (`^4.5.4`) are peer dependencies. The SDK
34
- re-exports AI SDK message types and Zod schemas, so consumers share these
35
- dependencies with the SDK.
38
+ `ai` and `zod` are required peer dependencies. The SDK re-exports AI SDK
39
+ message types and Zod schemas, so your app and the SDK share one copy of each.
36
40
 
37
41
  ## Quick start
38
42
 
39
- Create a Tenant API key in the Blazing Agents dashboard, then pass it to the
40
- client or read it from your server environment.
43
+ Create a Full API key in the Blazing Agents dashboard and set
44
+ `BLAZING_AGENTS_API_KEY` in your server environment. The key acts for your
45
+ whole Tenant, so keep it on your backend and never send it to a browser.
41
46
 
42
47
  ```ts
43
48
  import { BlazingAgents } from "@blazingagents/sdk";
44
49
 
45
- const client = new BlazingAgents({ apiKey: "ba_..." });
50
+ const client = new BlazingAgents({
51
+ apiKey: process.env.BLAZING_AGENTS_API_KEY!,
52
+ });
46
53
 
47
54
  const result = await client.completion({
48
55
  agentId: "ag_...",
@@ -52,32 +59,59 @@ const result = await client.completion({
52
59
  console.log(await result.text);
53
60
  ```
54
61
 
55
- For stateful chat, pass one user message or an ordered batch.
62
+ Replace `ag_...` with an Agent ID from the dashboard.
56
63
 
57
- ```ts
58
- const chat = await client.chat({
59
- agentId: "ag_...",
60
- messages: [
61
- { id: "first", role: "user", parts: [{ type: "text", text: "Compare the plans." }] },
62
- { id: "second", role: "user", parts: [{ type: "text", text: "Include annual pricing." }] },
63
- ],
64
- });
64
+ For requests from your users, scope the client to the user ID that your
65
+ backend verified at sign-in, never to an ID from the request body. A scoped
66
+ client reaches only that End-user's Agents, Sessions, and Workspace. An
67
+ unscoped Agent shares one Workspace across all your users, so give each user
68
+ an Agent of their own:
65
69
 
66
- const sessionId = await chat.sessionId;
67
- return chat.toResponse();
70
+ ```ts
71
+ export async function createAgentForUser(userId: string): Promise<string> {
72
+ const agent = await client.forUser(userId).agents.create({
73
+ name: "Assistant",
74
+ providerId: "prv_...",
75
+ model: "openai/gpt-6-luna",
76
+ });
77
+ return agent.id;
78
+ }
79
+
80
+ export async function chatAsUser(
81
+ userId: string,
82
+ agentId: string,
83
+ text: string
84
+ ): Promise<Response> {
85
+ const chat = await client.forUser(userId).chat({
86
+ agentId,
87
+ message: {
88
+ id: crypto.randomUUID(),
89
+ role: "user",
90
+ parts: [{ type: "text", text }],
91
+ },
92
+ });
93
+ return chat.toResponse();
94
+ }
68
95
  ```
69
96
 
70
- Keep API keys on the server. For browser chat applications, serve
71
- `createChatRelay` from your backend and use `BlazingAgentsChatTransport` with
72
- AI SDK `useChat`. The relay runs each request as the signed-in End-user with
73
- `client.forUser(userId)`.
97
+ Call `createAgentForUser` once per user and store the Agent ID with the user.
98
+ A scoped chat with an Agent created without the scope fails with `404`.
99
+ `chatAsUser` returns the chat as a streaming `Response`. To chat from the
100
+ browser with `useChat`, serve `createChatRelay` from your backend and use
101
+ `BlazingAgentsChatTransport`. The relay scopes each request to the user that
102
+ your `resolveContext` returns.
103
+
104
+ ## Examples
105
+
106
+ The [examples repository](https://github.com/blazingagents/examples) has
107
+ complete TypeScript and Python apps built on the Blazing Agents SDKs.
74
108
 
75
109
  ## Documentation
76
110
 
77
111
  Read the
78
112
  [TypeScript SDK documentation](https://docs.blazingagents.com/sdk/typescript)
79
- for authentication, resource guides, generation and streaming, React
80
- integration, error handling, and the complete API reference.
113
+ for client setup, End-user scoping, chat and generation, a guide to each
114
+ resource, and error handling.
81
115
 
82
116
  ## Development
83
117
 
package/dist/contracts/entities/agent-approval.d.ts CHANGED
@@ -20,6 +20,7 @@ export declare const toolReferenceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
20
20
  save_memory: "save_memory";
21
21
  search_memories: "search_memories";
22
22
  update_memory: "update_memory";
23
+ web_fetch: "web_fetch";
23
24
  web_search: "web_search";
24
25
  write: "write";
25
26
  write_todos: "write_todos";
@@ -49,6 +50,7 @@ export declare const toolExecutionReferenceSchema: z.ZodDiscriminatedUnion<[z.Zo
49
50
  save_memory: "save_memory";
50
51
  search_memories: "search_memories";
51
52
  update_memory: "update_memory";
53
+ web_fetch: "web_fetch";
52
54
  web_search: "web_search";
53
55
  write: "write";
54
56
  write_todos: "write_todos";
@@ -84,6 +86,7 @@ export declare const approvalPolicySchema: z.ZodObject<{
84
86
  save_memory: "save_memory";
85
87
  search_memories: "search_memories";
86
88
  update_memory: "update_memory";
89
+ web_fetch: "web_fetch";
87
90
  web_search: "web_search";
88
91
  write: "write";
89
92
  write_todos: "write_todos";
package/dist/contracts/entities/agent-tools.d.ts CHANGED
@@ -20,7 +20,7 @@ export declare const AGENT_TOOL_GROUPS: readonly [{
20
20
  }, {
21
21
  readonly tag: "web";
22
22
  readonly name: "Web";
23
- readonly description: "Search the public web for current information.";
23
+ readonly description: "Search the public web and read pages by URL.";
24
24
  }];
25
25
  export type AgentToolGroupTag = (typeof AGENT_TOOL_GROUPS)[number]["tag"];
26
26
  /**
@@ -114,6 +114,11 @@ declare const CATALOG: readonly [{
114
114
  readonly tags: readonly ["web"];
115
115
  readonly requiresWorkspace: false;
116
116
  readonly description: "Search the public web for current results. Each search consumes Usage credit.";
117
+ }, {
118
+ readonly name: "web_fetch";
119
+ readonly tags: readonly ["web"];
120
+ readonly requiresWorkspace: false;
121
+ readonly description: "Read a public web page or text document by URL, returned as markdown.";
117
122
  }];
118
123
  export type AgentToolName = (typeof CATALOG)[number]["name"];
119
124
  /** Declared rather than inferred, so `tool.tags.includes(tag)` accepts any tag. */
@@ -122,7 +127,7 @@ export declare const AGENT_TOOLS: readonly (AgentToolDefinition & {
122
127
  })[];
123
128
  export declare const agentToolNames: readonly AgentToolName[];
124
129
  /** Built-in tool names an approval policy can reference. */
125
- export declare const builtinToolNames: readonly [...("bash" | "delete_memory" | "edit" | "get_memory" | "glob" | "grep" | "publish_artifacts" | "read" | "save_memory" | "search_memories" | "update_memory" | "web_search" | "write" | "write_todos")[], "activate_skill"];
130
+ export declare const builtinToolNames: readonly [...("bash" | "delete_memory" | "edit" | "get_memory" | "glob" | "grep" | "publish_artifacts" | "read" | "save_memory" | "search_memories" | "update_memory" | "web_fetch" | "web_search" | "write" | "write_todos")[], "activate_skill"];
126
131
  /**
127
132
  * A model-facing tool name. Built-in tool names and the `mcp__` prefix used
128
133
  * for MCP tools are reserved so a caller function never shadows them.
package/dist/contracts/entities/agent-tools.js CHANGED
@@ -24,7 +24,7 @@ export const AGENT_TOOL_GROUPS = [
24
24
  {
25
25
  tag: "web",
26
26
  name: "Web",
27
- description: "Search the public web for current information.",
27
+ description: "Search the public web and read pages by URL.",
28
28
  },
29
29
  ];
30
30
  /**
@@ -126,6 +126,12 @@ const CATALOG = [
126
126
  requiresWorkspace: false,
127
127
  description: "Search the public web for current results. Each search consumes Usage credit.",
128
128
  },
129
+ {
130
+ name: "web_fetch",
131
+ tags: ["web"],
132
+ requiresWorkspace: false,
133
+ description: "Read a public web page or text document by URL, returned as markdown.",
134
+ },
129
135
  ];
130
136
  /** Declared rather than inferred, so `tool.tags.includes(tag)` accepts any tag. */
131
137
  export const AGENT_TOOLS = CATALOG;
package/dist/contracts/entities/agents.d.ts CHANGED
@@ -14,6 +14,7 @@ export declare const agentToolsSchema: z.ZodArray<z.ZodEnum<{
14
14
  save_memory: "save_memory";
15
15
  search_memories: "search_memories";
16
16
  update_memory: "update_memory";
17
+ web_fetch: "web_fetch";
17
18
  web_search: "web_search";
18
19
  write: "write";
19
20
  write_todos: "write_todos";
@@ -47,6 +48,7 @@ export declare const agentResponseSchema: z.ZodObject<{
47
48
  save_memory: "save_memory";
48
49
  search_memories: "search_memories";
49
50
  update_memory: "update_memory";
51
+ web_fetch: "web_fetch";
50
52
  web_search: "web_search";
51
53
  write: "write";
52
54
  write_todos: "write_todos";
@@ -87,6 +89,7 @@ export declare const agentResponseSchema: z.ZodObject<{
87
89
  save_memory: "save_memory";
88
90
  search_memories: "search_memories";
89
91
  update_memory: "update_memory";
92
+ web_fetch: "web_fetch";
90
93
  web_search: "web_search";
91
94
  write: "write";
92
95
  write_todos: "write_todos";
@@ -126,6 +129,7 @@ export declare const agentResponseSchema: z.ZodObject<{
126
129
  save_memory: "save_memory";
127
130
  search_memories: "search_memories";
128
131
  update_memory: "update_memory";
132
+ web_fetch: "web_fetch";
129
133
  web_search: "web_search";
130
134
  write: "write";
131
135
  write_todos: "write_todos";
@@ -167,6 +171,7 @@ export declare const agentsResponseSchema: z.ZodObject<{
167
171
  save_memory: "save_memory";
168
172
  search_memories: "search_memories";
169
173
  update_memory: "update_memory";
174
+ web_fetch: "web_fetch";
170
175
  web_search: "web_search";
171
176
  write: "write";
172
177
  write_todos: "write_todos";
@@ -207,6 +212,7 @@ export declare const agentsResponseSchema: z.ZodObject<{
207
212
  save_memory: "save_memory";
208
213
  search_memories: "search_memories";
209
214
  update_memory: "update_memory";
215
+ web_fetch: "web_fetch";
210
216
  web_search: "web_search";
211
217
  write: "write";
212
218
  write_todos: "write_todos";
@@ -246,6 +252,7 @@ export declare const agentsResponseSchema: z.ZodObject<{
246
252
  save_memory: "save_memory";
247
253
  search_memories: "search_memories";
248
254
  update_memory: "update_memory";
255
+ web_fetch: "web_fetch";
249
256
  web_search: "web_search";
250
257
  write: "write";
251
258
  write_todos: "write_todos";
@@ -294,6 +301,7 @@ export declare const agentConfigSchema: z.ZodObject<{
294
301
  save_memory: "save_memory";
295
302
  search_memories: "search_memories";
296
303
  update_memory: "update_memory";
304
+ web_fetch: "web_fetch";
297
305
  web_search: "web_search";
298
306
  write: "write";
299
307
  write_todos: "write_todos";
@@ -334,6 +342,7 @@ export declare const agentConfigSchema: z.ZodObject<{
334
342
  save_memory: "save_memory";
335
343
  search_memories: "search_memories";
336
344
  update_memory: "update_memory";
345
+ web_fetch: "web_fetch";
337
346
  web_search: "web_search";
338
347
  write: "write";
339
348
  write_todos: "write_todos";
@@ -370,6 +379,7 @@ export declare const agentConfigSchema: z.ZodObject<{
370
379
  save_memory: "save_memory";
371
380
  search_memories: "search_memories";
372
381
  update_memory: "update_memory";
382
+ web_fetch: "web_fetch";
373
383
  web_search: "web_search";
374
384
  write: "write";
375
385
  write_todos: "write_todos";
@@ -406,6 +416,7 @@ export declare const createAgentBodySchema: z.ZodObject<{
406
416
  save_memory: "save_memory";
407
417
  search_memories: "search_memories";
408
418
  update_memory: "update_memory";
419
+ web_fetch: "web_fetch";
409
420
  web_search: "web_search";
410
421
  write: "write";
411
422
  write_todos: "write_todos";
@@ -446,6 +457,7 @@ export declare const createAgentBodySchema: z.ZodObject<{
446
457
  save_memory: "save_memory";
447
458
  search_memories: "search_memories";
448
459
  update_memory: "update_memory";
460
+ web_fetch: "web_fetch";
449
461
  web_search: "web_search";
450
462
  write: "write";
451
463
  write_todos: "write_todos";
@@ -483,6 +495,7 @@ export declare const createAgentBodySchema: z.ZodObject<{
483
495
  save_memory: "save_memory";
484
496
  search_memories: "search_memories";
485
497
  update_memory: "update_memory";
498
+ web_fetch: "web_fetch";
486
499
  web_search: "web_search";
487
500
  write: "write";
488
501
  write_todos: "write_todos";
@@ -516,6 +529,7 @@ export declare const updateAgentBodySchema: z.ZodObject<{
516
529
  save_memory: "save_memory";
517
530
  search_memories: "search_memories";
518
531
  update_memory: "update_memory";
532
+ web_fetch: "web_fetch";
519
533
  web_search: "web_search";
520
534
  write: "write";
521
535
  write_todos: "write_todos";
@@ -556,6 +570,7 @@ export declare const updateAgentBodySchema: z.ZodObject<{
556
570
  save_memory: "save_memory";
557
571
  search_memories: "search_memories";
558
572
  update_memory: "update_memory";
573
+ web_fetch: "web_fetch";
559
574
  web_search: "web_search";
560
575
  write: "write";
561
576
  write_todos: "write_todos";
@@ -593,6 +608,7 @@ export declare const updateAgentBodySchema: z.ZodObject<{
593
608
  save_memory: "save_memory";
594
609
  search_memories: "search_memories";
595
610
  update_memory: "update_memory";
611
+ web_fetch: "web_fetch";
596
612
  web_search: "web_search";
597
613
  write: "write";
598
614
  write_todos: "write_todos";
package/dist/contracts/entities/memories.js CHANGED
@@ -41,7 +41,7 @@ export const createMemoryBodySchema = z
41
41
  text: memoryTextSchema.describe("The note to remember, up to 10 KiB."),
42
42
  userId: userIdSchema
43
43
  .default("")
44
- .describe("The end user this memory belongs to. Only turns that pass the same `userId` see it. Leave it out or send an empty string for a general memory that every turn of the agent sees. It cannot change after creation."),
44
+ .describe("The end user this memory belongs to. Turns for that end user see it. Leave it out or send an empty string for a general memory, which unscoped turns see; a turn made through `forUser` sees only its end user's memories. It cannot change after creation."),
45
45
  })
46
46
  .strict();
47
47
  export const updateMemoryBodySchema = z
package/dist/contracts/entities/sessions.d.ts CHANGED
@@ -60,6 +60,7 @@ export declare const sessionResponseSchema: z.ZodObject<{
60
60
  save_memory: "save_memory";
61
61
  search_memories: "search_memories";
62
62
  update_memory: "update_memory";
63
+ web_fetch: "web_fetch";
63
64
  web_search: "web_search";
64
65
  write: "write";
65
66
  write_todos: "write_todos";
@@ -100,6 +101,7 @@ export declare const sessionResponseSchema: z.ZodObject<{
100
101
  save_memory: "save_memory";
101
102
  search_memories: "search_memories";
102
103
  update_memory: "update_memory";
104
+ web_fetch: "web_fetch";
103
105
  web_search: "web_search";
104
106
  write: "write";
105
107
  write_todos: "write_todos";
@@ -136,6 +138,7 @@ export declare const sessionResponseSchema: z.ZodObject<{
136
138
  save_memory: "save_memory";
137
139
  search_memories: "search_memories";
138
140
  update_memory: "update_memory";
141
+ web_fetch: "web_fetch";
139
142
  web_search: "web_search";
140
143
  write: "write";
141
144
  write_todos: "write_todos";
@@ -262,6 +265,7 @@ export declare const toolApprovalStateSchema: z.ZodObject<{
262
265
  save_memory: "save_memory";
263
266
  search_memories: "search_memories";
264
267
  update_memory: "update_memory";
268
+ web_fetch: "web_fetch";
265
269
  web_search: "web_search";
266
270
  write: "write";
267
271
  write_todos: "write_todos";
@@ -314,6 +318,7 @@ export declare const toolApprovalsResponseSchema: z.ZodObject<{
314
318
  save_memory: "save_memory";
315
319
  search_memories: "search_memories";
316
320
  update_memory: "update_memory";
321
+ web_fetch: "web_fetch";
317
322
  web_search: "web_search";
318
323
  write: "write";
319
324
  write_todos: "write_todos";
package/dist/contracts/entities/tasks.d.ts CHANGED
@@ -284,6 +284,7 @@ export declare const taskRunResponseSchema: z.ZodObject<{
284
284
  save_memory: "save_memory";
285
285
  search_memories: "search_memories";
286
286
  update_memory: "update_memory";
287
+ web_fetch: "web_fetch";
287
288
  web_search: "web_search";
288
289
  write: "write";
289
290
  write_todos: "write_todos";
@@ -324,6 +325,7 @@ export declare const taskRunResponseSchema: z.ZodObject<{
324
325
  save_memory: "save_memory";
325
326
  search_memories: "search_memories";
326
327
  update_memory: "update_memory";
328
+ web_fetch: "web_fetch";
327
329
  web_search: "web_search";
328
330
  write: "write";
329
331
  write_todos: "write_todos";
@@ -360,6 +362,7 @@ export declare const taskRunResponseSchema: z.ZodObject<{
360
362
  save_memory: "save_memory";
361
363
  search_memories: "search_memories";
362
364
  update_memory: "update_memory";
365
+ web_fetch: "web_fetch";
363
366
  web_search: "web_search";
364
367
  write: "write";
365
368
  write_todos: "write_todos";
@@ -419,6 +422,7 @@ export declare const taskRunsListResponseSchema: z.ZodObject<{
419
422
  save_memory: "save_memory";
420
423
  search_memories: "search_memories";
421
424
  update_memory: "update_memory";
425
+ web_fetch: "web_fetch";
422
426
  web_search: "web_search";
423
427
  write: "write";
424
428
  write_todos: "write_todos";
@@ -459,6 +463,7 @@ export declare const taskRunsListResponseSchema: z.ZodObject<{
459
463
  save_memory: "save_memory";
460
464
  search_memories: "search_memories";
461
465
  update_memory: "update_memory";
466
+ web_fetch: "web_fetch";
462
467
  web_search: "web_search";
463
468
  write: "write";
464
469
  write_todos: "write_todos";
@@ -495,6 +500,7 @@ export declare const taskRunsListResponseSchema: z.ZodObject<{
495
500
  save_memory: "save_memory";
496
501
  search_memories: "search_memories";
497
502
  update_memory: "update_memory";
503
+ web_fetch: "web_fetch";
498
504
  web_search: "web_search";
499
505
  write: "write";
500
506
  write_todos: "write_todos";
package/dist/generation.js CHANGED
@@ -145,6 +145,18 @@ function buildChatResult(config, response, resumeSessionId, dispatch) {
145
145
  sessionIdError = error;
146
146
  }
147
147
  }
148
+ const { functions } = dispatch;
149
+ /**
150
+ * Function calls are dispatched against the Session, so without its id the
151
+ * stream cannot be filtered; refuse it rather than pass private
152
+ * `data-ba-function-call` frames through.
153
+ */
154
+ if (functions && sessionId === undefined) {
155
+ response.body?.cancel().catch(() => {
156
+ /* no-op — the stream is discarded */
157
+ });
158
+ throw sessionIdError;
159
+ }
148
160
  const sessionIdPromise = sessionId === undefined
149
161
  ? Promise.reject(sessionIdError)
150
162
  : Promise.resolve(sessionId);
@@ -162,8 +174,7 @@ function buildChatResult(config, response, resumeSessionId, dispatch) {
162
174
  turnIdPromise.catch(() => {
163
175
  /* no-op — prevents unhandled rejection if the caller never awaits */
164
176
  });
165
- const { functions } = dispatch;
166
- const streamResponse = functions && sessionId !== undefined
177
+ const streamResponse = functions && sessionId
167
178
  ? withFilteredBody(response, (body) => dispatchChatFunctions(config, { ...dispatch, functions, sessionId }, body))
168
179
  : response;
169
180
  return {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@blazingagents/sdk",
3
- "version": "0.43.0",
3
+ "version": "0.44.0",
4
4
  "description": "TypeScript SDK for the Blazing Agents API",
5
5
  "homepage": "https://docs.blazingagents.com",
6
6
  "bugs": {