@mastra/client-js 1.2.0 → 1.2.1-alpha.0

package/dist/docs/references/reference-ai-sdk-to-ai-sdk-v5-messages.md

@@ -0,0 +1,73 @@
+# toAISdkV5Messages()
+
+Converts messages from various input formats to AI SDK V5 (and later) UI message format. This function accepts messages in multiple formats (strings, AI SDK V4/V5 messages, Mastra DB messages, etc.) and normalizes them to the AI SDK V5+ `UIMessage` format, which is suitable for use with AI SDK UI components like `useChat()`.
+
+## Usage example
+
+```typescript
+import { toAISdkV5Messages } from "@mastra/ai-sdk/ui";
+import { useChat } from "ai/react";
+
+// Stored messages from your database, memory or API
+const storedMessages = [
+  { id: "1", role: "user", content: "Hello", parts: [{ type: "text", text: "Hello" }] },
+  { id: "2", role: "assistant", content: "Hi there!", parts: [{ type: "text", text: "Hi there!" }] }
+];
+
+export default function Chat() {
+  const { messages } = useChat({
+    initialMessages: toAISdkV5Messages(storedMessages)
+  });
+
+  return (
+    <div>
+      {messages.map((message) => (
+        <div key={message.id}>
+          {message.role}: {message.parts.map(part =>
+            part.type === "text" ? part.text : null
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Parameters
+
+**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.
+
+## Returns
+
+Returns an array of AI SDK V5+ `UIMessage` objects with the following structure:
+
+**id:** (`string`): Unique message identifier.
+
+**role:** (`'user' | 'assistant' | 'system'`): The role of the message sender.
+
+**parts:** (`UIMessagePart[]`): Array of UI parts including text, tool results, files, reasoning, sources, and step markers.
+
+**metadata?:** (`Record<string, unknown>`): Optional metadata including createdAt, threadId, resourceId, and custom fields.
+
+## Examples
+
+### Converting simple text messages
+
+```typescript
+import { toAISdkV5Messages } from "@mastra/ai-sdk/ui";
+
+const messages = toAISdkV5Messages(["Hello", "How can I help you today?"]);
+// Returns array of UIMessage objects with user role
+```
+
+### Loading messages with Mastra client
+
+```typescript
+import { MastraClient } from "@mastra/client-js";
+import { toAISdkV5Messages } from "@mastra/ai-sdk/ui";
+
+const client = new MastraClient();
+
+const { messages } = await client.listThreadMessages("thread-id", { agentId: "myAgent" });
+const uiMessages = toAISdkV5Messages(messages);
+```

package/dist/docs/references/reference-client-js-agents.md

@@ -0,0 +1,438 @@
+# Agents API
+
+The Agents API provides methods to interact with Mastra AI agents, including generating responses, streaming interactions, and managing agent tools.
+
+## Getting All Agents
+
+Retrieve a list of all available agents:
+
+```typescript
+const agents = await mastraClient.listAgents();
+```
+
+Returns a record of agent IDs to their serialized agent configurations.
+
+## Working with a Specific Agent
+
+Get an instance of a specific agent by its ID:
+
+```typescript
+export const myAgent = new Agent({
+  id: "my-agent",
+});
+```
+
+```typescript
+const agent = mastraClient.getAgent("my-agent");
+```
+
+## Agent Methods
+
+### details()
+
+Retrieve detailed information about an agent:
+
+```typescript
+const details = await agent.details();
+```
+
+### generate()
+
+Generate a response from the agent:
+
+```typescript
+const response = await agent.generate(
+  [
+    {
+      role: "user",
+      content: "Hello, how are you?",
+    },
+  ],
+  {
+    memory: {
+      thread: "thread-abc", // Optional: Thread ID for conversation context
+      resource: "user-123", // Optional: Resource ID
+    },
+    structuredOutput: {}    // Optional: Structured Output configuration
+  }
+);
+```
+
+You can also use the simplified string format with memory options:
+
+```typescript
+const response = await agent.generate("Hello, how are you?", {
+  memory: {
+    thread: "thread-1",
+    resource: "resource-1",
+  },
+});
+```
+
+### stream()
+
+Stream responses from the agent for real-time interactions:
+
+```typescript
+const response = await agent.stream("Tell me a story");
+
+// Process data stream with the processDataStream util
+response.processDataStream({
+  onChunk: async (chunk) => {
+    console.log(chunk);
+  },
+});
+```
+
+You can also use the simplified string format with memory options:
+
+```typescript
+const response = await agent.stream("Tell me a story", {
+  memory: {
+    thread: "thread-1",
+    resource: "resource-1",
+  },
+  clientTools: { colorChangeTool },
+});
+
+response.processDataStream({
+  onChunk: async (chunk) => {
+    if (chunk.type === "text-delta") {
+      console.log(chunk.payload.text);
+    }
+  },
+});
+```
+
+You can also read from response body directly:
+
+```typescript
+const reader = response.body.getReader();
+while (true) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  console.log(new TextDecoder().decode(value));
+}
+```
+
+#### AI SDK compatible format
+
+To stream AI SDK-formatted parts on the client from an `agent.stream(...)` response, wrap `response.processDataStream` into a `ReadableStream<ChunkType>` and use `toAISdkStream`:
+
+```typescript
+import { createUIMessageStream } from "ai";
+import { toAISdkStream } from "@mastra/ai-sdk";
+import type { ChunkType, MastraModelOutput } from "@mastra/core/stream";
+
+const response = await agent.stream("Tell me a story");
+
+const chunkStream: ReadableStream<ChunkType> = new ReadableStream<ChunkType>({
+  start(controller) {
+    response
+      .processDataStream({
+        onChunk: async (chunk) => controller.enqueue(chunk as ChunkType),
+      })
+      .finally(() => controller.close());
+  },
+});
+
+const uiMessageStream = createUIMessageStream({
+  execute: async ({ writer }) => {
+    for await (const part of toAISdkStream(
+      chunkStream as unknown as MastraModelOutput,
+      { from: "agent" },
+    )) {
+      writer.write(part);
+    }
+  },
+});
+
+for await (const part of uiMessageStream) {
+  console.log(part);
+}
+```
+
+### getTool()
+
+Retrieve information about a specific tool available to the agent:
+
+```typescript
+const tool = await agent.getTool("tool-id");
+```
+
+### executeTool()
+
+Execute a specific tool for the agent:
+
+```typescript
+const result = await agent.executeTool("tool-id", {
+  data: { input: "value" },
+});
+```
+
+### network()
+
+Stream responses from an agent network for multi-agent interactions:
+
+```typescript
+const response = await agent.network("Research this topic and write a summary");
+
+response.processDataStream({
+  onChunk: async (chunk) => {
+    console.log(chunk);
+  },
+});
+```
+
+### approveToolCall()
+
+Approve a pending tool call that requires human confirmation:
+
+```typescript
+const response = await agent.approveToolCall({
+  runId: "run-123",
+  toolCallId: "tool-call-456",
+});
+
+response.processDataStream({
+  onChunk: async (chunk) => {
+    console.log(chunk);
+  },
+});
+```
+
+### declineToolCall()
+
+Decline a pending tool call that requires human confirmation:
+
+```typescript
+const response = await agent.declineToolCall({
+  runId: "run-123",
+  toolCallId: "tool-call-456",
+});
+
+response.processDataStream({
+  onChunk: async (chunk) => {
+    console.log(chunk);
+  },
+});
+```
+
+### approveToolCallGenerate()
+
+Approve a pending tool call when using `generate()` (non-streaming). Returns the complete response:
+
+```typescript
+const output = await agent.generate("Find user John", {
+  requireToolApproval: true,
+});
+
+if (output.finishReason === "suspended") {
+  const result = await agent.approveToolCallGenerate({
+    runId: output.runId,
+    toolCallId: output.suspendPayload.toolCallId,
+  });
+
+  console.log(result.text);
+}
+```
+
+### declineToolCallGenerate()
+
+Decline a pending tool call when using `generate()` (non-streaming). Returns the complete response:
+
+```typescript
+const output = await agent.generate("Find user John", {
+  requireToolApproval: true,
+});
+
+if (output.finishReason === "suspended") {
+  const result = await agent.declineToolCallGenerate({
+    runId: output.runId,
+    toolCallId: output.suspendPayload.toolCallId,
+  });
+
+  console.log(result.text);
+}
+```
+
+## Client Tools
+
+Client-side tools allow you to execute custom functions on the client side when the agent requests them.
+
+```typescript
+import { createTool } from "@mastra/client-js";
+import { z } from "zod";
+
+const colorChangeTool = createTool({
+  id: "changeColor",
+  description: "Changes the background color",
+  inputSchema: z.object({
+    color: z.string(),
+  }),
+  execute: async (inputData) => {
+    document.body.style.backgroundColor = inputData.color;
+    return { success: true };
+  },
+});
+
+// Use with generate
+const response = await agent.generate("Change the background to blue", {
+  clientTools: { colorChangeTool },
+});
+
+// Use with stream
+const response = await agent.stream("Tell me a story", {
+  memory: {
+    thread: "thread-1",
+    resource: "resource-1",
+  },
+  clientTools: { colorChangeTool },
+});
+
+response.processDataStream({
+  onChunk: async (chunk) => {
+    if (chunk.type === "text-delta") {
+      console.log(chunk.payload.text);
+    } else if (chunk.type === "tool-call") {
+      console.log(
+        `calling tool ${chunk.payload.toolName} with args ${JSON.stringify(
+          chunk.payload.args,
+          null,
+          2
+        )}`
+      );
+    }
+  },
+});
+```
+
+## Stored Agents
+
+Stored agents are agent configurations stored in a database that can be created, updated, and deleted at runtime. They reference primitives (tools, workflows, other agents, memory, scorers) by key, which are resolved from the Mastra registry when the agent is instantiated.
+
+### listStoredAgents()
+
+Retrieve a paginated list of all stored agents:
+
+```typescript
+const result = await mastraClient.listStoredAgents();
+console.log(result.agents); // Array of stored agents
+console.log(result.total); // Total count
+```
+
+With pagination and ordering:
+
+```typescript
+const result = await mastraClient.listStoredAgents({
+  page: 0,
+  perPage: 20,
+  orderBy: {
+    field: "createdAt",
+    direction: "DESC",
+  },
+});
+```
+
+### createStoredAgent()
+
+Create a new stored agent:
+
+```typescript
+const agent = await mastraClient.createStoredAgent({
+  id: "my-agent",
+  name: "My Assistant",
+  instructions: "You are a helpful assistant.",
+  model: {
+    provider: "openai",
+    name: "gpt-4",
+  },
+});
+```
+
+With all options:
+
+```typescript
+const agent = await mastraClient.createStoredAgent({
+  id: "full-agent",
+  name: "Full Agent",
+  description: "A fully configured agent",
+  instructions: "You are a helpful assistant.",
+  model: {
+    provider: "openai",
+    name: "gpt-4",
+  },
+  tools: ["calculator", "weather"],
+  workflows: ["data-processing"],
+  agents: ["sub-agent-1"],
+  memory: "my-memory",
+  scorers: {
+    "quality-scorer": {
+      sampling: { type: "ratio", rate: 0.1 },
+    },
+  },
+  defaultOptions: {
+    maxSteps: 10,
+  },
+  metadata: {
+    version: "1.0",
+    team: "engineering",
+  },
+});
+```
+
+### getStoredAgent()
+
+Get an instance of a specific stored agent:
+
+```typescript
+const storedAgent = mastraClient.getStoredAgent("my-agent");
+```
+
+## Stored Agent Methods
+
+### details()
+
+Retrieve the stored agent configuration:
+
+```typescript
+const details = await storedAgent.details();
+console.log(details.name);
+console.log(details.instructions);
+console.log(details.model);
+```
+
+### update()
+
+Update specific fields of a stored agent. All fields are optional:
+
+```typescript
+const updated = await storedAgent.update({
+  name: "Updated Agent Name",
+  instructions: "New instructions for the agent.",
+});
+```
+
+```typescript
+// Update just the tools
+await storedAgent.update({
+  tools: ["new-tool-1", "new-tool-2"],
+});
+
+// Update metadata
+await storedAgent.update({
+  metadata: {
+    version: "2.0",
+    lastModifiedBy: "admin",
+  },
+});
+```
+
+### delete()
+
+Delete a stored agent:
+
+```typescript
+const result = await storedAgent.delete();
+console.log(result.success); // true
+```

package/dist/docs/references/reference-client-js-error-handling.md

@@ -0,0 +1,16 @@
+# Error Handling
+
+The Mastra Client SDK includes built-in retry mechanism and error handling capabilities.
+
+## Error Handling
+
+All API methods can throw errors that you can catch and handle:
+
+```typescript
+try {
+  const agent = mastraClient.getAgent("agent-id");
+  const response = await agent.generate("Hello");
+} catch (error) {
+  console.error("An error occurred:", error.message);
+}
+```

package/dist/docs/references/reference-client-js-logs.md

@@ -0,0 +1,24 @@
+# Logs API
+
+The Logs API provides methods to access and query system logs and debugging information in Mastra.
+
+## Getting Logs
+
+Retrieve system logs with optional filtering:
+
+```typescript
+const logs = await mastraClient.listLogs({
+  transportId: "transport-1",
+});
+```
+
+## Getting Logs for a Specific Run
+
+Retrieve logs for a specific execution run:
+
+```typescript
+const runLogs = await mastraClient.getLogForRun({
+  runId: "run-1",
+  transportId: "transport-1",
+});
+```

package/dist/docs/references/reference-client-js-mastra-client.md

@@ -0,0 +1,63 @@
+# Mastra Client SDK
+
+The Mastra Client SDK provides a simple and type-safe interface for interacting with your [Mastra Server](https://mastra.ai/docs/deployment/mastra-server) from your client environment.
+
+## Usage example
+
+```typescript
+import { MastraClient } from "@mastra/client-js";
+
+export const mastraClient = new MastraClient({
+  baseUrl: "http://localhost:4111/",
+});
+```
+
+## Parameters
+
+**baseUrl:** (`string`): The base URL for the Mastra API. All requests will be sent relative to this URL.
+
+**retries?:** (`number`): The number of times a request will be retried on failure before throwing an error. (Default: `3`)
+
+**backoffMs?:** (`number`): The initial delay in milliseconds before retrying a failed request. This value is doubled with each retry (exponential backoff). (Default: `300`)
+
+**maxBackoffMs?:** (`number`): The maximum backoff time in milliseconds. Prevents retries from waiting too long between attempts. (Default: `5000`)
+
+**headers?:** (`Record<string, string>`): An object containing custom HTTP headers to include with every request.
+
+**credentials?:** (`"omit" | "same-origin" | "include"`): Credentials mode for requests. See https\://developer.mozilla.org/en-US/docs/Web/API/Request/credentials for more info.
+
+## Methods
+
+**listAgents():** (`Promise<Record<string, GetAgentResponse>>`): Returns all available agent instances.
+
+**getAgent(agentId):** (`Agent`): Retrieves a specific agent instance by ID.
+
+**getMemoryThreads(params):** (`Promise<StorageThreadType[]>`): Retrieves memory threads for the specified resource and agent. Requires a \`resourceId\` and an \`agentId\`.
+
+**createMemoryThread(params):** (`Promise<MemoryThread>`): Creates a new memory thread with the given parameters.
+
+**getMemoryThread({ threadId, agentId }):** (`MemoryThread`): Fetches a specific memory thread by ID.
+
+**saveMessageToMemory(params):** (`Promise<{ messages: (MastraMessageV1 | MastraDBMessage)[] }>`): Saves one or more messages to the memory system. Returns the saved messages.
+
+**getMemoryStatus():** (`Promise<MemoryStatus>`): Returns the current status of the memory system.
+
+**listTools():** (`Record<string, Tool>`): Returns all available tools.
+
+**getTool(toolId):** (`Tool`): Retrieves a specific tool instance by ID.
+
+**listWorkflows():** (`Record<string, Workflow>`): Returns all available workflow instances.
+
+**getWorkflow(workflowId):** (`Workflow`): Retrieves a specific workflow instance by ID.
+
+**getVector(vectorName):** (`MastraVector`): Returns a vector store instance by name.
+
+**listLogs(params):** (`Promise<LogEntry[]>`): Fetches system logs matching the provided filters.
+
+**getLog(params):** (`Promise<LogEntry>`): Retrieves a specific log entry by ID or filter.
+
+**listLogTransports():** (`string[]`): Returns the list of configured log transport types.
+
+**getTrace(traceId):** (`Promise<TraceRecord>`): Retrieves a specific trace by ID, including all its spans and details.
+
+**getTraces(params):** (`Promise<GetTracesResponse>`): Retrieves paginated list of trace root spans with optional filtering. Use getTrace() to get complete traces with all spans.