@mastra/mcp-docs-server 0.0.0-commonjs-20250414101718

package/.docs/raw/reference/networks/agent-network.mdx

@@ -0,0 +1,159 @@
+---
+title: 'AgentNetwork (Experimental)'
+description: 'Reference documentation for the AgentNetwork class'
+---
+
+# AgentNetwork (Experimental)
+
+> **Note:** The AgentNetwork feature is experimental and may change in future releases.
+
+The `AgentNetwork` class provides a way to create a network of specialized agents that can collaborate to solve complex tasks. Unlike Workflows, which require explicit control over execution paths, AgentNetwork uses an LLM-based router to dynamically determine which agent to call next.
+
+## Key Concepts
+
+- **LLM-based Routing**: AgentNetwork exclusively uses an LLM to figure out the best way to use your agents
+- **Agent Collaboration**: Multiple specialized agents can work together to solve complex tasks
+- **Dynamic Decision Making**: The router decides which agent to call based on the task requirements
+
+## Usage
+
+```typescript
+import { AgentNetwork } from '@mastra/core/network';
+import { openai } from '@mastra/openai';
+
+// Create specialized agents
+const webSearchAgent = new Agent({
+  name: 'Web Search Agent',
+  instructions: 'You search the web for information.',
+  model: openai('gpt-4o'),
+  tools: { /* web search tools */ },
+});
+
+const dataAnalysisAgent = new Agent({
+  name: 'Data Analysis Agent',
+  instructions: 'You analyze data and provide insights.',
+  model: openai('gpt-4o'),
+  tools: { /* data analysis tools */ },
+});
+
+// Create the network
+const researchNetwork = new AgentNetwork({
+  name: 'Research Network',
+  instructions: 'Coordinate specialized agents to research topics thoroughly.',
+  model: openai('gpt-4o'),
+  agents: [webSearchAgent, dataAnalysisAgent],
+});
+
+// Use the network
+const result = await researchNetwork.generate('Research the impact of climate change on agriculture');
+console.log(result.text);
+```
+
+## Constructor
+
+```typescript
+constructor(config: AgentNetworkConfig)
+```
+
+### Parameters
+
+- `config`: Configuration object for the AgentNetwork
+  - `name`: Name of the network
+  - `instructions`: Instructions for the routing agent
+  - `model`: Language model to use for routing
+  - `agents`: Array of specialized agents in the network
+
+## Methods
+
+### generate()
+
+Generates a response using the agent network. This method has replaced the deprecated `run()` method for consistency with the rest of the codebase.
+
+```typescript
+async generate(
+  messages: string | string[] | CoreMessage[],
+  args?: AgentGenerateOptions
+): Promise<GenerateTextResult>
+```
+
+### stream()
+
+Streams a response using the agent network.
+
+```typescript
+async stream(
+  messages: string | string[] | CoreMessage[],
+  args?: AgentStreamOptions
+): Promise<StreamTextResult>
+```
+
+### getRoutingAgent()
+
+Returns the routing agent used by the network.
+
+```typescript
+getRoutingAgent(): Agent
+```
+
+### getAgents()
+
+Returns the array of specialized agents in the network.
+
+```typescript
+getAgents(): Agent[]
+```
+
+### getAgentHistory()
+
+Returns the history of interactions for a specific agent.
+
+```typescript
+getAgentHistory(agentId: string): Array<{
+  input: string;
+  output: string;
+  timestamp: string;
+}>
+```
+
+### getAgentInteractionHistory()
+
+Returns the history of all agent interactions that have occurred in the network.
+
+```typescript
+getAgentInteractionHistory(): Record<
+  string,
+  Array<{
+    input: string;
+    output: string;
+    timestamp: string;
+  }>
+>
+```
+
+### getAgentInteractionSummary()
+
+Returns a formatted summary of agent interactions in chronological order.
+
+```typescript
+getAgentInteractionSummary(): string
+```
+
+## When to Use AgentNetwork vs Workflows
+
+- **Use AgentNetwork when:** You want the AI to figure out the best way to use your agents, with dynamic routing based on the task requirements.
+
+- **Use Workflows when:** You need explicit control over execution paths, with predetermined sequences of agent calls and conditional logic.
+
+## Internal Tools
+
+The AgentNetwork uses a special `transmit` tool that allows the routing agent to call specialized agents. This tool handles:
+
+- Single agent calls
+- Multiple parallel agent calls
+- Context sharing between agents
+
+## Limitations
+
+- The AgentNetwork approach may use more tokens than a well-designed Workflow for the same task
+- Debugging can be more challenging as the routing decisions are made by the LLM
+- Performance may vary based on the quality of the routing instructions and the capabilities of the specialized agents

package/.docs/raw/reference/observability/create-logger.mdx

@@ -0,0 +1,106 @@
+---
+title: "Reference: createLogger() | Mastra Observability Docs"
+description: Documentation for the createLogger function, which instantiates a logger based on a given configuration.
+---
+
+# createLogger()
+
+The `createLogger()` function is used to instantiate a logger based on a given configuration. You can create console-based, file-based, or Upstash Redis-based loggers by specifying the type and any additional parameters relevant to that type.
+
+### Usage
+
+#### Console Logger (Development)
+
+```typescript showLineNumbers copy
+const consoleLogger = createLogger({ name: "Mastra", level: "debug" });
+consoleLogger.info("App started");
+```
+
+#### File Transport (Structured Logs)
+
+```typescript showLineNumbers copy
+import { FileTransport } from "@mastra/loggers/file";
+
+const fileLogger = createLogger({
+  name: "Mastra",
+  transports: { file: new FileTransport({ path: "test-dir/test.log" }) },
+  level: "warn",
+});
+fileLogger.warn("Low disk space", {
+  destinationPath: "system",
+  type: "WORKFLOW",
+});
+```
+
+#### Upstash Logger (Remote Log Drain)
+
+```typescript showLineNumbers copy
+import { UpstashTransport } from "@mastra/loggers/upstash";
+
+const logger = createLogger({
+  name: "Mastra",
+  transports: {
+    upstash: new UpstashTransport({
+      listName: "production-logs",
+      upstashUrl: process.env.UPSTASH_URL!,
+      upstashToken: process.env.UPSTASH_TOKEN!,
+    }),
+  },
+  level: "info",
+});
+
+logger.info({
+  message: "User signed in",
+  destinationPath: "auth",
+  type: "AGENT",
+  runId: "run_123",
+});
+```
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "type",
+      type: "CONSOLE" | "FILE" | "UPSTASH",
+      description: "Specifies the logger implementation to create.",
+    },
+    {
+      name: "level",
+      type: "LogLevel",
+      isOptional: true,
+      default: "INFO",
+      description:
+        "Minimum severity level of logs to record. One of DEBUG, INFO, WARN, or ERROR.",
+    },
+    {
+      name: "dirPath",
+      type: "string",
+      isOptional: true,
+      description:
+        'For FILE type only. Directory path where log files are stored (default: "logs").',
+    },
+    {
+      name: "url",
+      type: "string",
+      isOptional: true,
+      description:
+        "For UPSTASH type only. Upstash Redis endpoint URL used for storing logs.",
+    },
+    {
+      name: "token",
+      type: "string",
+      isOptional: true,
+      description: "For UPSTASH type only. Upstash Redis access token.",
+    },
+    {
+      name: "key",
+      type: "string",
+      isOptional: true,
+      default: "logs",
+      description:
+        "For UPSTASH type only. Redis list key under which logs are stored.",
+    },
+  ]}
+/>

package/.docs/raw/reference/observability/logger.mdx

@@ -0,0 +1,55 @@
+---
+title: "Reference: Logger Instance | Mastra Observability Docs"
+description: Documentation for Logger instances, which provide methods to record events at various severity levels.
+---
+
+# Logger Instance
+
+A Logger instance is created by `createLogger()` and provides methods to record events at various severity levels. Depending on the logger type, messages may be written to the console, file, or an external service.
+
+## Example
+
+```typescript showLineNumbers copy
+// Using a console logger
+const logger = createLogger({ name: 'Mastra', level: 'info' });
+
+logger.debug('Debug message'); // Won't be logged because level is INFO
+logger.info({ message: 'User action occurred', destinationPath: 'user-actions', type: 'AGENT' }); // Logged
+logger.error('An error occurred'); // Logged as ERROR
+```
+
+## Methods
+
+<PropertiesTable
+  content={[
+    {
+      name: 'debug',
+      type: '(message: BaseLogMessage | string, ...args: any[]) => void | Promise<void>',
+      description: 'Write a DEBUG-level log. Only recorded if level ≤ DEBUG.',
+    },
+    {
+      name: 'info',
+      type: '(message: BaseLogMessage | string, ...args: any[]) => void | Promise<void>',
+      description: 'Write an INFO-level log. Only recorded if level ≤ INFO.',
+    },
+    {
+      name: 'warn',
+      type: '(message: BaseLogMessage | string, ...args: any[]) => void | Promise<void>',
+      description: 'Write a WARN-level log. Only recorded if level ≤ WARN.',
+    },
+    {
+      name: 'error',
+      type: '(message: BaseLogMessage | string, ...args: any[]) => void | Promise<void>',
+      description: 'Write an ERROR-level log. Only recorded if level ≤ ERROR.',
+    },
+    {
+      name: 'cleanup',
+      type: '() => Promise<void>',
+      isOptional: true,
+      description:
+        'Cleanup resources held by the logger (e.g., network connections for Upstash). Not all loggers implement this.',
+    },
+  ]}
+/>
+
+**Note:** Some loggers require a `BaseLogMessage` object (with `message`, `destinationPath`, `type` fields). For instance, the `File` and `Upstash` loggers need structured messages.

package/.docs/raw/reference/observability/otel-config.mdx

@@ -0,0 +1,120 @@
+---
+title: "Reference: OtelConfig | Mastra Observability Docs"
+description: Documentation for the OtelConfig object, which configures OpenTelemetry instrumentation, tracing, and exporting behavior.
+---
+
+# `OtelConfig`
+
+The `OtelConfig` object is used to configure OpenTelemetry instrumentation, tracing, and exporting behavior within your application. By adjusting its properties, you can control how telemetry data (such as traces) is collected, sampled, and exported. 
+
+To use the `OtelConfig` within Mastra, pass it as the value of the `telemetry` key when initializing Mastra. This will configure Mastra to use your custom OpenTelemetry settings for tracing and instrumentation.
+
+```typescript showLineNumbers copy
+import { Mastra } from 'mastra';
+
+const otelConfig: OtelConfig = {
+  serviceName: 'my-awesome-service',
+  enabled: true,
+  sampling: {
+    type: 'ratio',
+    probability: 0.5,
+  },
+  export: {
+    type: 'otlp',
+    endpoint: 'https://otel-collector.example.com/v1/traces',
+    headers: {
+      Authorization: 'Bearer YOUR_TOKEN_HERE',
+    },
+  },
+};
+```
+
+### Properties
+
+<PropertiesTable
+  content={[
+    {
+      name: 'serviceName',
+      type: 'string',
+      isOptional: true,
+      default: 'default-service',
+      description:
+        'Human-readable name used to identify your service in telemetry backends.',
+    },
+    {
+      name: 'enabled',
+      type: 'boolean',
+      isOptional: true,
+      default: 'true',
+      description:
+        'Whether telemetry collection and export are enabled.',
+    },
+    {
+      name: 'sampling',
+      type: 'SamplingStrategy',
+      isOptional: true,
+      description:
+        'Defines the sampling strategy for traces, controlling how much data is collected.',
+      properties: [
+        {
+          name: 'type',
+          type: `'ratio' | 'always_on' | 'always_off' | 'parent_based'`,
+          description:
+            'Specifies the sampling strategy type.',
+        },
+        {
+          name: 'probability',
+          type: 'number (0.0 to 1.0)',
+          isOptional: true,
+          description:
+            'For `ratio` or `parent_based` strategies, defines the sampling probability.',
+        },
+        {
+          name: 'root',
+          type: 'object',
+          isOptional: true,
+          description:
+            'For `parent_based` strategy, configures root-level probability sampling.',
+          properties: [
+            {
+              name: 'probability',
+              type: 'number (0.0 to 1.0)',
+              isOptional: true,
+              description:
+                'Sampling probability for root traces in `parent_based` strategy.',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'export',
+      type: 'object',
+      isOptional: true,
+      description:
+        'Configuration for exporting collected telemetry data.',
+      properties: [
+        {
+          name: 'type',
+          type: `'otlp' | 'console'`,
+          description:
+            'Specifies the exporter type. Use `otlp` for external exporters or `console` for development.',
+        },
+        {
+          name: 'endpoint',
+          type: 'string',
+          isOptional: true,
+          description:
+            'For `otlp` type, the OTLP endpoint URL to send traces to.',
+        },
+        {
+          name: 'headers',
+          type: 'Record<string, string>',
+          isOptional: true,
+          description:
+            'Additional headers to send with OTLP requests, useful for authentication or routing.',
+        },
+      ],
+    },
+  ]}
+/>

package/.docs/raw/reference/observability/providers/braintrust.mdx

@@ -0,0 +1,40 @@
+---
+title: "Reference: Braintrust | Observability | Mastra Docs"
+description: Documentation for integrating Braintrust with Mastra, an evaluation and monitoring platform for LLM applications.
+---
+
+# Braintrust
+
+Braintrust is an evaluation and monitoring platform for LLM applications.
+
+## Configuration
+
+To use Braintrust with Mastra, configure these environment variables:
+
+```env
+OTEL_EXPORTER_OTLP_ENDPOINT=https://api.braintrust.dev/otel
+OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <Your API Key>, x-bt-parent=project_id:<Your Project ID>"
+```
+
+## Implementation
+
+Here's how to configure Mastra to use Braintrust:
+
+```typescript
+import { Mastra } from "@mastra/core";
+
+export const mastra = new Mastra({
+  // ... other config
+  telemetry: {
+    serviceName: "your-service-name",
+    enabled: true,
+    export: {
+      type: "otlp",
+    },
+  },
+});
+```
+
+## Dashboard
+
+Access your Braintrust dashboard at [braintrust.dev](https://www.braintrust.dev/)

package/.docs/raw/reference/observability/providers/dash0.mdx

@@ -0,0 +1,40 @@
+---
+title: "Reference: Dash0 Integration | Mastra Observability Docs"
+description: Documentation for integrating Mastra with Dash0, an Open Telementry native observability solution.
+---
+
+# Dash0
+
+Dash0, an Open Telementry native observability solution that provides full-stack monitoring capabilities as well as integrations with other CNCF projects like Perses and Prometheus.
+
+## Configuration
+
+To use Dash0 with Mastra, configure these environment variables:
+
+```env
+OTEL_EXPORTER_OTLP_ENDPOINT=https://ingress.<region>.dash0.com
+OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <your-auth-token>, Dash0-Dataset=<optional-dataset>
+```
+
+## Implementation
+
+Here's how to configure Mastra to use Dash0:
+
+```typescript
+import { Mastra } from "@mastra/core";
+
+export const mastra = new Mastra({
+  // ... other config
+  telemetry: {
+    serviceName: "your-service-name",
+    enabled: true,
+    export: {
+      type: "otlp",
+    },
+  },
+});
+```
+
+## Dashboard
+
+Access your Dash0 dashboards at [dash0.com](https://www.dash0.com/) and find out how to do more [Distributed Tracing](https://www.dash0.com/distributed-tracing) integrations in the [Dash0 Integration Hub](https://www.dash0.com/hub/integrations) 

package/.docs/raw/reference/observability/providers/index.mdx

@@ -0,0 +1,16 @@
+---
+title: "Reference: Provider List | Observability | Mastra Docs"
+description: Overview of observability providers supported by Mastra, including Dash0, SigNoz, Braintrust, Langfuse, and more.
+---
+
+# Observability Providers
+
+Observability providers include:
+- [Braintrust](./providers/braintrust.mdx)
+- [Dash0](./providers/dash0.mdx)
+- [Laminar](./providers/laminar.mdx)
+- [Langfuse](./providers/langfuse.mdx)
+- [Langsmith](./providers/langsmith.mdx)
+- [New Relic](./providers/new-relic.mdx)
+- [SigNoz](./providers/signoz.mdx)
+- [Traceloop](./providers/traceloop.mdx)

package/.docs/raw/reference/observability/providers/laminar.mdx

@@ -0,0 +1,41 @@
+---
+title: "Reference: Laminar Integration | Mastra Observability Docs"
+description: Documentation for integrating Laminar with Mastra, a specialized observability platform for LLM applications.
+---
+
+# Laminar
+
+Laminar is a specialized observability platform for LLM applications.
+
+## Configuration
+
+To use Laminar with Mastra, configure these environment variables:
+
+```env
+OTEL_EXPORTER_OTLP_ENDPOINT=https://api.lmnr.ai:8443
+OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your_api_key, x-laminar-team-id=your_team_id"
+```
+
+## Implementation
+
+Here's how to configure Mastra to use Laminar:
+
+```typescript
+import { Mastra } from "@mastra/core";
+
+export const mastra = new Mastra({
+  // ... other config
+  telemetry: {
+    serviceName: "your-service-name",
+    enabled: true,
+    export: {
+      type: "otlp",
+      protocol: "grpc",
+    },
+  },
+});
+```
+
+## Dashboard
+
+Access your Laminar dashboard at [https://lmnr.ai/](https://lmnr.ai/)

package/.docs/raw/reference/observability/providers/langfuse.mdx

@@ -0,0 +1,51 @@
+---
+title: "Reference: Langfuse Integration | Mastra Observability Docs"
+description: Documentation for integrating Langfuse with Mastra, an open-source observability platform for LLM applications.
+---
+
+# Langfuse
+
+Langfuse is an open-source observability platform designed specifically for LLM applications.
+
+> **Note**: Currently, only AI-related calls will contain detailed telemetry data. Other operations will create traces but with limited information.
+
+## Configuration
+
+To use Langfuse with Mastra, you'll need to configure the following environment variables:
+
+```env
+LANGFUSE_PUBLIC_KEY=your_public_key
+LANGFUSE_SECRET_KEY=your_secret_key
+LANGFUSE_BASEURL=https://cloud.langfuse.com  # Optional - defaults to cloud.langfuse.com
+```
+
+**Important**: When configuring the telemetry export settings, the `traceName` parameter must be set to `"ai"` for the Langfuse integration to work properly.
+
+## Implementation
+
+Here's how to configure Mastra to use Langfuse:
+
+```typescript
+import { Mastra } from "@mastra/core";
+import { LangfuseExporter } from "langfuse-vercel";
+
+export const mastra = new Mastra({
+  // ... other config
+  telemetry: {
+    serviceName: "ai", // this must be set to "ai" so that the LangfuseExporter thinks it's an AI SDK trace
+    enabled: true,
+    export: {
+      type: "custom",
+      exporter: new LangfuseExporter({
+        publicKey: process.env.LANGFUSE_PUBLIC_KEY,
+        secretKey: process.env.LANGFUSE_SECRET_KEY,
+        baseUrl: process.env.LANGFUSE_BASEURL,
+      }),
+    },
+  },
+});
+```
+
+## Dashboard
+
+Once configured, you can view your traces and analytics in the Langfuse dashboard at [cloud.langfuse.com](https://cloud.langfuse.com)

package/.docs/raw/reference/observability/providers/langsmith.mdx

@@ -0,0 +1,48 @@
+---
+title: "Reference: LangSmith Integration | Mastra Observability Docs"
+description: Documentation for integrating LangSmith with Mastra, a platform for debugging, testing, evaluating, and monitoring LLM applications.
+---
+
+# LangSmith
+
+LangSmith is LangChain's platform for debugging, testing, evaluating, and monitoring LLM applications.
+
+> **Note**: Currently, this integration only traces AI-related calls in your application. Other types of operations are not captured in the telemetry data.
+
+## Configuration
+
+To use LangSmith with Mastra, you'll need to configure the following environment variables:
+
+```env
+LANGSMITH_TRACING=true
+LANGSMITH_ENDPOINT=https://api.smith.langchain.com
+LANGSMITH_API_KEY=your-api-key
+LANGSMITH_PROJECT=your-project-name
+```
+
+## Implementation
+
+Here's how to configure Mastra to use LangSmith:
+
+```typescript
+import { Mastra } from "@mastra/core";
+import { AISDKExporter } from "langsmith/vercel";
+
+export const mastra = new Mastra({
+  // ... other config
+  telemetry: {
+    serviceName: "your-service-name",
+    enabled: true,
+    export: {
+      type: "custom",
+      exporter: new AISDKExporter(),
+    },
+  },
+});
+```
+
+## Dashboard
+
+Access your traces and analytics in the LangSmith dashboard at [smith.langchain.com](https://smith.langchain.com)
+
+> **Note**: Even if you run your workflows, you may not see data appearing in a new project. You will need to sort by Name column to see all projects, select your project, then filter by LLM Calls instead of Root Runs.