@mastra/client-js 1.0.0-beta.9 → 1.0.0

package/dist/docs/client-js/01-reference.md

@@ -0,0 +1,1180 @@
+# Client js API Reference
+
+> API reference for client js - 10 entries
+
+
+---
+
+## Reference: Agents API
+
+> Learn how to interact with Mastra AI agents, including generating responses, streaming interactions, and managing agent tools using the client-js SDK.
+
+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 title="src/mastra/agents/my-agent.ts"
+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 title="client-ai-sdk-transform.ts"
+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
+```
+
+---
+
+## Reference: Error Handling
+
+> Learn about the built-in retry mechanism and error handling capabilities in the Mastra client-js SDK.
+
+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);
+}
+```
+
+---
+
+## Reference: Logs API
+
+> Learn how to access and query system logs and debugging information in Mastra using the client-js SDK.
+
+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",
+});
+```
+
+---
+
+## Reference: Mastra Client SDK
+
+> Learn how to interact with Mastra using the client-js SDK.
+
+The Mastra Client SDK provides a simple and type-safe interface for interacting with your [Mastra Server](https://mastra.ai/docs/v1/deployment/mastra-server) from your client environment.
+
+## Usage example
+
+```typescript title="lib/mastra/mastra-client.ts"
+import { MastraClient } from "@mastra/client-js";
+
+export const mastraClient = new MastraClient({
+  baseUrl: "http://localhost:4111/",
+});
+```
+
+## Parameters
+
+## Methods
+
+---
+
+## Reference: Memory API
+
+> Learn how to manage conversation threads and message history in Mastra using the client-js SDK.
+
+The Memory API provides methods to manage conversation threads and message history in Mastra.
+
+### Get All Threads
+
+Retrieve all memory threads for a specific resource:
+
+```typescript
+const threads = await mastraClient.getMemoryThreads({
+  resourceId: "resource-1",
+  agentId: "agent-1", // Optional - can be omitted if storage is configured
+});
+```
+
+When `agentId` is omitted and storage is configured on the server, threads will be retrieved using storage directly. This is useful when multiple agents share the same threads (e.g., in workflows with multiple agent steps).
+
+### Create a New Thread
+
+Create a new memory thread:
+
+```typescript
+const thread = await mastraClient.createMemoryThread({
+  title: "New Conversation",
+  metadata: { category: "support" },
+  resourceId: "resource-1",
+  agentId: "agent-1",
+});
+```
+
+### Working with a Specific Thread
+
+Get an instance of a specific memory thread:
+
+```typescript
+const thread = mastraClient.getMemoryThread({ threadId: "thread-id", agentId: "agent-id" });
+```
+
+## Thread Methods
+
+### Get Thread Details
+
+Retrieve details about a specific thread:
+
+```typescript
+const details = await thread.get();
+```
+
+### Update Thread
+
+Update thread properties:
+
+```typescript
+const updated = await thread.update({
+  title: "Updated Title",
+  metadata: { status: "resolved" },
+  resourceId: "resource-1",
+});
+```
+
+### Delete Thread
+
+Delete a thread and its messages:
+
+```typescript
+await thread.delete();
+```
+
+### Clone Thread
+
+Create a copy of a thread with all its messages:
+
+```typescript
+const { thread: clonedThread, clonedMessages } = await thread.clone();
+```
+
+Clone with options:
+
+```typescript
+const { thread: clonedThread, clonedMessages } = await thread.clone({
+  newThreadId: "custom-clone-id",
+  title: "Cloned Conversation",
+  metadata: { branch: "experiment-1" },
+  options: {
+    messageLimit: 10, // Only clone last 10 messages
+  },
+});
+```
+
+Clone with message filtering:
+
+```typescript
+const { thread: clonedThread } = await thread.clone({
+  options: {
+    messageFilter: {
+      startDate: new Date("2024-01-01"),
+      endDate: new Date("2024-01-31"),
+    },
+  },
+});
+```
+
+The clone response includes:
+- `thread`: The newly created cloned thread with clone metadata
+- `clonedMessages`: Array of the cloned messages with new IDs
+
+## Message Operations
+
+### Save Messages
+
+Save messages to memory:
+
+```typescript
+const result = await mastraClient.saveMessageToMemory({
+  messages: [
+    {
+      role: "user",
+      content: "Hello!",
+      id: "1",
+      threadId: "thread-1",
+      resourceId: "resource-1",
+      createdAt: new Date(),
+      format: 2,
+    },
+  ],
+  agentId: "agent-1",
+});
+
+// result.messages contains the saved messages
+console.log(result.messages);
+```
+
+### Retrieve Thread Messages
+
+Get messages associated with a memory thread:
+
+```typescript
+// Get all messages in the thread (paginated)
+const result = await thread.listMessages();
+console.log(result.messages); // Array of messages
+console.log(result.total); // Total count
+console.log(result.hasMore); // Whether more pages exist
+
+// Get messages with pagination
+const result = await thread.listMessages({
+  page: 0,
+  perPage: 20
+});
+
+// Get messages with ordering
+const result = await thread.listMessages({
+  orderBy: { field: 'createdAt', direction: 'ASC' }
+});
+```
+
+### Delete Messages
+
+Delete one or more messages from a thread:
+
+```typescript
+// Delete a single message
+const result = await thread.deleteMessages("message-id");
+
+// Delete multiple messages
+const result = await thread.deleteMessages([
+  "message-1",
+  "message-2",
+  "message-3",
+]);
+
+// Returns: { success: true, message: "Message deleted successfully" }
+```
+
+## Working Memory
+
+Working memory allows agents to maintain persistent information about users across interactions. It can be scoped to either a specific thread or across all threads for a resource (user).
+
+### Get Working Memory
+
+Retrieve the current working memory for a thread:
+
+```typescript
+const workingMemory = await mastraClient.getWorkingMemory({
+  agentId: "agent-1",
+  threadId: "thread-1",
+  resourceId: "user-123", // Optional, required for resource-scoped memory
+});
+```
+
+The response includes:
+- `workingMemory`: The current working memory content (string or null)
+- `source`: Whether the memory is from `"thread"` or `"resource"` scope
+- `workingMemoryTemplate`: The template used for working memory (if configured)
+- `threadExists`: Whether the thread exists
+
+### Update Working Memory
+
+Update the working memory content for a thread:
+
+```typescript
+await mastraClient.updateWorkingMemory({
+  agentId: "agent-1",
+  threadId: "thread-1",
+  workingMemory: `# User Profile
+- Name: John Doe
+- Location: New York
+- Preferences: Prefers formal communication
+`,
+  resourceId: "user-123", // Optional, required for resource-scoped memory
+});
+
+// Returns: { success: true }
+```
+
+**Note:** For resource-scoped working memory, you must provide the `resourceId` parameter. This allows the memory to persist across all conversation threads for that user.
+
+### Get Memory Status
+
+Check the status of the memory system:
+
+```typescript
+const status = await mastraClient.getMemoryStatus("agent-id");
+```
+
+---
+
+## Reference: Observability API
+
+> Learn how to retrieve traces, monitor application performance, and score traces using the client-js SDK.
+
+The Observability API provides methods to retrieve traces, monitor your application's performance, and score traces for evaluation. This helps you understand how your AI agents and workflows are performing.
+
+## Getting a Specific Trace
+
+Retrieve a specific trace by its ID, including all its spans and details:
+
+```typescript
+const trace = await mastraClient.getTrace("trace-id-123");
+```
+
+## Getting Traces with Filtering
+
+Retrieve a paginated list of trace root spans with optional filtering:
+
+```typescript
+const traces = await mastraClient.getTraces({
+  pagination: {
+    page: 1,
+    perPage: 20,
+    dateRange: {
+      start: new Date("2024-01-01"),
+      end: new Date("2024-01-31"),
+    },
+  },
+  filters: {
+    name: "weather-agent", // Filter by trace name
+    spanType: "agent", // Filter by span type
+    entityId: "weather-agent-id", // Filter by entity ID
+    entityType: "agent", // Filter by entity type
+  },
+});
+
+console.log(`Found ${traces.spans.length} root spans`);
+console.log(`Total pages: ${traces.pagination.totalPages}`);
+
+// To get the complete trace with all spans, use getTrace
+const completeTrace = await mastraClient.getTrace(traces.spans[0].traceId);
+```
+
+## Scoring Traces
+
+Score specific traces using registered scorers for evaluation:
+
+```typescript
+const result = await mastraClient.score({
+  scorerName: "answer-relevancy",
+  targets: [
+    { traceId: "trace-1", spanId: "span-1" }, // Score specific span
+    { traceId: "trace-2" }, // Score specific span which defaults to the parent span
+  ],
+});
+```
+
+## Getting Scores by Span
+
+Retrieve scores for a specific span within a trace:
+
+```typescript
+const scores = await mastraClient.listScoresBySpan({
+  traceId: "trace-123",
+  spanId: "span-456",
+  page: 1,
+  perPage: 20,
+});
+```
+
+## Related
+
+- [Agents API](./agents) - Learn about agent interactions that generate traces
+- [Workflows API](./workflows) - Understand workflow execution monitoring
+
+---
+
+## Reference: Telemetry API
+
+> Learn how to retrieve and analyze traces from your Mastra application for monitoring and debugging using the client-js SDK.
+
+The Telemetry API provides methods to retrieve and analyze traces from your Mastra application. This helps you monitor and debug your application's behavior and performance.
+
+## Getting Traces
+
+Retrieve traces with optional filtering and pagination:
+
+```typescript
+const telemetry = await mastraClient.getTelemetry({
+  name: "trace-name", // Optional: Filter by trace name
+  scope: "scope-name", // Optional: Filter by scope
+  page: 1, // Optional: Page number for pagination
+  perPage: 10, // Optional: Number of items per page
+  attribute: {
+    // Optional: Filter by custom attributes
+    key: "value",
+  },
+});
+```
+
+---
+
+## Reference: Tools API
+
+> Learn how to interact with and execute tools available in the Mastra platform using the client-js SDK.
+
+The Tools API provides methods to interact with and execute tools available in the Mastra platform.
+
+## Getting All Tools
+
+Retrieve a list of all available tools:
+
+```typescript
+const tools = await mastraClient.listTools();
+```
+
+## Working with a Specific Tool
+
+Get an instance of a specific tool:
+
+```typescript
+const tool = mastraClient.getTool("tool-id");
+```
+
+## Tool Methods
+
+### Get Tool Details
+
+Retrieve detailed information about a tool:
+
+```typescript
+const details = await tool.details();
+```
+
+### Execute Tool
+
+Execute a tool with specific arguments:
+
+```typescript
+const result = await tool.execute({
+  args: {
+    param1: "value1",
+    param2: "value2",
+  },
+  threadId: "thread-1", // Optional: Thread context
+  resourceId: "resource-1", // Optional: Resource identifier
+});
+```
+
+---
+
+## Reference: Vectors API
+
+> Learn how to work with vector embeddings for semantic search and similarity matching in Mastra using the client-js SDK.
+
+The Vectors API provides methods to work with vector embeddings for semantic search and similarity matching in Mastra.
+
+## Working with Vectors
+
+Get an instance of a vector store:
+
+```typescript
+const vector = mastraClient.getVector("vector-name");
+```
+
+## Vector Methods
+
+### Get Vector Index Details
+
+Retrieve information about a specific vector index:
+
+```typescript
+const details = await vector.details("index-name");
+```
+
+### Create Vector Index
+
+Create a new vector index:
+
+```typescript
+const result = await vector.createIndex({
+  indexName: "new-index",
+  dimension: 128,
+  metric: "cosine", // 'cosine', 'euclidean', or 'dotproduct'
+});
+```
+
+### Upsert Vectors
+
+Add or update vectors in an index:
+
+```typescript
+const ids = await vector.upsert({
+  indexName: "my-index",
+  vectors: [
+    [0.1, 0.2, 0.3], // First vector
+    [0.4, 0.5, 0.6], // Second vector
+  ],
+  metadata: [{ label: "first" }, { label: "second" }],
+  ids: ["id1", "id2"], // Optional: Custom IDs
+});
+```
+
+### Query Vectors
+
+Search for similar vectors:
+
+```typescript
+const results = await vector.query({
+  indexName: "my-index",
+  queryVector: [0.1, 0.2, 0.3],
+  topK: 10,
+  filter: { label: "first" }, // Optional: Metadata filter
+  includeVector: true, // Optional: Include vectors in results
+});
+```
+
+### Get All Indexes
+
+List all available indexes:
+
+```typescript
+const indexes = await vector.getIndexes();
+```
+
+### Delete Index
+
+Delete a vector index:
+
+```typescript
+const result = await vector.delete("index-name");
+```
+
+---
+
+## Reference: Workflows API
+
+> Learn how to interact with and execute automated workflows in Mastra using the client-js SDK.
+
+The Workflows API provides methods to interact with and execute automated workflows in Mastra.
+
+## Getting All Workflows
+
+Retrieve a list of all available workflows:
+
+```typescript
+const workflows = await mastraClient.listWorkflows();
+```
+
+## Working with a Specific Workflow
+
+Get an instance of a specific workflow by its ID:
+
+```typescript title="src/mastra/workflows/test-workflow.ts"
+export const testWorkflow = createWorkflow({
+  id: "city-workflow",
+});
+```
+
+```typescript
+const workflow = mastraClient.getWorkflow("city-workflow");
+```
+
+## Workflow Methods
+
+### details()
+
+Retrieve detailed information about a workflow:
+
+```typescript
+const details = await workflow.details();
+```
+
+### createRun()
+
+Create a new workflow run instance:
+
+```typescript
+const run = await workflow.createRun();
+
+// Or with an existing runId
+const run = await workflow.createRun({ runId: "existing-run-id" });
+
+// Or with a resourceId to associate the run with a specific resource
+const run = await workflow.createRun({
+  runId: "my-run-id",
+  resourceId: "user-123"
+});
+```
+
+The `resourceId` parameter associates the workflow run with a specific resource (e.g., user ID, tenant ID). This value is persisted with the run and can be used for filtering and querying runs later.
+
+### startAsync()
+
+Start a workflow run and await the full result:
+
+```typescript
+const run = await workflow.createRun();
+
+const result = await run.startAsync({
+  inputData: {
+    city: "New York",
+  },
+});
+```
+
+You can also pass `initialState` to set the starting values for the workflow's state:
+
+```typescript
+const result = await run.startAsync({
+  inputData: {
+    city: "New York",
+  },
+  initialState: {
+    count: 0,
+    items: [],
+  },
+});
+```
+
+The `initialState` object should match the structure defined in the workflow's `stateSchema`. See [Workflow State](https://mastra.ai/docs/v1/workflows/workflow-state) for more details.
+
+To associate a run with a specific resource, pass `resourceId` to `createRun()`:
+
+```typescript
+const run = await workflow.createRun({ resourceId: "user-123" });
+
+const result = await run.startAsync({
+  inputData: {
+    city: "New York",
+  },
+});
+```
+
+### start()
+
+Start a workflow run without waiting for completion:
+
+```typescript
+const run = await workflow.createRun();
+
+await run.start({
+  inputData: {
+    city: "New York",
+  },
+});
+
+// Poll for results later
+const result = await workflow.runById(run.runId);
+```
+
+This is useful for long-running workflows where you want to start execution and check results later.
+
+### resumeAsync()
+
+Resume a suspended workflow step and await the full result:
+
+```typescript
+const run = await workflow.createRun({ runId: prevRunId });
+
+const result = await run.resumeAsync({
+  step: "step-id",
+  resumeData: { key: "value" },
+});
+```
+
+### resume()
+
+Resume a suspended workflow step without waiting for completion:
+
+```typescript
+const run = await workflow.createRun({ runId: prevRunId });
+
+await run.resume({
+  step: "step-id",
+  resumeData: { key: "value" },
+});
+```
+
+### cancel()
+
+Cancel a running workflow:
+
+```typescript
+const run = await workflow.createRun({ runId: existingRunId });
+
+const result = await run.cancel();
+// Returns: { message: 'Workflow run canceled' }
+```
+
+This method stops any running steps and prevents subsequent steps from executing. Steps that check the `abortSignal` parameter can respond to cancellation by cleaning up resources (timeouts, network requests, etc.).
+
+See the [Run.cancel()](https://mastra.ai/reference/v1/workflows/run-methods/cancel) reference for detailed information about how cancellation works and how to write steps that respond to cancellation.
+
+### stream()
+
+Stream workflow execution for real-time updates:
+
+```typescript
+const run = await workflow.createRun();
+
+const stream = await run.stream({
+  inputData: {
+    city: "New York",
+  },
+});
+
+for await (const chunk of stream) {
+  console.log(JSON.stringify(chunk, null, 2));
+}
+```
+
+### runById()
+
+Get the execution result for a workflow run:
+
+```typescript
+const result = await workflow.runById(runId);
+
+// Or with options for performance optimization:
+const result = await workflow.runById(runId, {
+  fields: ['status', 'result'],  // Only fetch specific fields
+  withNestedWorkflows: false,    // Skip expensive nested workflow data
+  requestContext: { userId: 'user-123' }, // Optional request context
+});
+```
+
+<h3>Run result format</h3>
+
+A workflow run result yields the following: