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

package/.docs/organized/code-examples/agent-network.md

@@ -0,0 +1,282 @@
+### package.json
+```json
+{
+  "name": "examples-agent-network",
+  "type": "module",
+  "private": true,
+  "description": "",
+  "main": "index.js",
+  "version": "0.0.1",
+  "scripts": {
+    "start": "npx bun src/index.ts"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@ai-sdk/openai": "^1.2.5",
+    "@mastra/client-js": "workspace:*",
+    "@mastra/core": "workspace:*",
+    "zod": "^3.24.2"
+  }
+}
+
+```
+
+### agent-workflow.ts
+```typescript
+import { mastra } from './mastra';
+
+async function main() {
+  const wflow = mastra.getWorkflow('agentWorkflow');
+
+  const { runId, start } = wflow.createRun();
+
+  const result = await start({
+    triggerData: {
+      prompt: 'What is the capital of France?',
+    },
+  });
+
+  console.log(JSON.stringify(result, null, 2));
+}
+
+main().catch(console.error);
+
+```
+
+### index.ts
+```typescript
+import { mastra } from './mastra';
+
+async function main() {
+  const researchNetwork = mastra.getNetwork('Research_Network');
+
+  if (!researchNetwork) {
+    throw new Error('Research network not found');
+  }
+
+  console.log('🔍 Starting research on Napoleon Bonaparte...\n');
+
+  // Generate a report using the research network
+  // Using the generate() method as per the API update (MEMORY[8bf54da9-89a8-4e5b-b875-234a1aa8a53b])
+  const result = await researchNetwork.stream('Give me a report on Napoleon Bonaparte', {
+    maxSteps: 20, // Allow enough steps for the LLM router to determine the best agents to use
+  });
+
+  for await (const part of result.fullStream) {
+    switch (part.type) {
+      case 'error':
+        console.error(part.error);
+        break;
+      case 'text-delta':
+        process.stdout.write(part.textDelta);
+        break;
+      case 'tool-call':
+        console.log(`calling tool ${part.toolName} with args ${JSON.stringify(part.args, null, 2)}`);
+        break;
+      case 'tool-result':
+        console.log(`tool result ${JSON.stringify(part.result, null, 2)}`);
+        break;
+    }
+  }
+
+  // Display the final result
+  console.log('\n\n📝 Final Research Report:\n');
+
+  console.log('\n\n📊 Agent Interaction Summary:');
+  console.log(researchNetwork.getAgentInteractionSummary());
+
+  console.log('\n🏁 Research complete!');
+}
+
+// Run the main function with error handling
+main().catch(error => {
+  console.error('❌ Error:', error);
+  process.exit(1);
+});
+
+```
+
+### mastra/agents/index.ts
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { Agent } from '@mastra/core/agent';
+
+export const primaryResearchAgent = new Agent({
+  name: 'Primary Research Agent',
+  instructions: `
+    You are the primary research coordinator. Your job is to:
+    1. Analyze user queries to determine what type of research is needed
+    2. Break down complex research questions into manageable sub-questions
+    3. Synthesize information from specialized research agents into a coherent response
+    4. Ensure all claims are properly supported by evidence
+    5. Identify any gaps in the research that need further investigation
+    
+    You should maintain a neutral, objective tone and prioritize accuracy over speed.
+  `,
+  model: openai('gpt-4o'),
+});
+
+export const webSearchAgent = new Agent({
+  name: 'Web Search Agent',
+  instructions: `
+    You are a web search specialist. Your job is to:
+    1. Find the most relevant and up-to-date information online for a given query
+    2. Evaluate the credibility of sources and prioritize reliable information
+    3. Extract key facts and data points from web content
+    4. Provide direct quotes and citations when appropriate
+    5. Summarize findings in a clear, concise manner
+    
+    Always include source URLs when reporting information.
+
+    Use the "web_search_preview" tool to search the web for information.
+  `,
+  model: openai.responses('gpt-4o-mini'),
+  tools: {
+    web_search_preview: openai.tools.webSearchPreview(),
+  },
+});
+
+export const academicResearchAgent = new Agent({
+  name: 'Academic Research Agent',
+  instructions: `
+    You are an academic research specialist. Your job is to:
+    1. Analyze topics from an academic perspective
+    2. Identify key theories, frameworks, and scholarly debates relevant to a query
+    3. Provide historical context and development of ideas
+    4. Cite academic sources properly
+    5. Explain complex academic concepts in accessible language
+    
+    Prioritize peer-reviewed research and established academic sources.
+  `,
+  model: openai('gpt-4o'),
+});
+
+export const factCheckingAgent = new Agent({
+  name: 'Fact Checking Agent',
+  instructions: `
+    You are a fact-checking specialist. Your job is to:
+    1. Verify claims made by other agents or in user queries
+    2. Identify potential misinformation or unsubstantiated claims
+    3. Cross-reference information across multiple reliable sources
+    4. Provide corrections with supporting evidence
+    5. Rate the confidence level of verified information
+    
+    Be thorough and skeptical, but fair in your assessments.
+  `,
+  model: openai('gpt-4o-mini'),
+});
+
+export const dataAnalysisAgent = new Agent({
+  name: 'Data Analysis Agent',
+  instructions: `
+    You are a data analysis specialist. Your job is to:
+    1. Interpret numerical data and statistics related to research queries
+    2. Identify trends, patterns, and correlations in data
+    3. Evaluate the methodology behind data collection and analysis
+    4. Explain statistical concepts in accessible language
+    5. Create clear summaries of data-driven findings
+    
+    Always consider sample sizes, statistical significance, and potential biases in data.
+  `,
+  model: openai('gpt-4o'),
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core';
+import { createLogger } from '@mastra/core/logger';
+import { researchNetwork } from './network';
+import { webSearchAgent } from './agents';
+import { agentWorkflow } from './workflows';
+
+export const mastra = new Mastra({
+  agents: {
+    webSearchAgent,
+  },
+  networks: {
+    researchNetwork,
+  },
+  workflows: {
+    agentWorkflow,
+  },
+  logger: createLogger({ name: 'Chef', level: 'info' }),
+  serverMiddleware: [
+    {
+      handler: (c, next) => {
+        console.log('Middleware called');
+        return next();
+      },
+    },
+  ],
+});
+
+```
+
+### mastra/network/index.ts
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { AgentNetwork } from '@mastra/core/network';
+import {
+  primaryResearchAgent,
+  webSearchAgent,
+  academicResearchAgent,
+  factCheckingAgent,
+  dataAnalysisAgent,
+} from '../agents';
+
+export const researchNetwork = new AgentNetwork({
+  name: 'Research Network',
+  agents: [primaryResearchAgent, webSearchAgent, academicResearchAgent, factCheckingAgent, dataAnalysisAgent],
+  model: openai('gpt-4o'), // Add the model property which is required
+  instructions: `
+      You are a research coordination system that routes queries to the appropriate specialized agents.
+      
+      Your available agents are:
+      1. Primary Research Agent: Coordinates research efforts, breaks down complex questions, and synthesizes information
+      2. Web Search Agent: Finds up-to-date information online with proper citations
+      3. Academic Research Agent: Provides academic perspectives, theories, and scholarly context
+      4. Fact Checking Agent: Verifies claims and identifies potential misinformation
+      5. Data Analysis Agent: Interprets numerical data, statistics, and identifies patterns
+      
+      For each user query:
+      1. Start with the Primary Research Agent to analyze the query and break it down
+      2. Route sub-questions to the appropriate specialized agents based on their expertise
+      3. Use the Fact Checking Agent to verify important claims when necessary
+      4. Return to the Primary Research Agent to synthesize all findings into a comprehensive response
+      
+      Always maintain a chain of evidence and proper attribution between agents.
+    `,
+});
+
+```
+
+### mastra/workflows/index.ts
+```typescript
+import { Workflow } from '@mastra/core/workflows';
+import { z } from 'zod';
+import { webSearchAgent } from '../agents';
+
+export const agentWorkflow = new Workflow({
+  name: 'Agent Workflow',
+  steps: [webSearchAgent.toStep()],
+  triggerSchema: z.object({
+    prompt: z.string(),
+  }),
+});
+
+agentWorkflow
+  .step(webSearchAgent, {
+    variables: {
+      prompt: {
+        step: 'trigger',
+        path: 'prompt',
+      },
+    },
+  })
+  .commit();
+
+```

package/.docs/organized/code-examples/agent.md

@@ -0,0 +1,388 @@
+### package.json
+```json
+{
+  "name": "examples-agent",
+  "type": "module",
+  "private": true,
+  "description": "",
+  "main": "index.js",
+  "version": "0.0.1",
+  "scripts": {
+    "start-deployed": "npx bun src/with-deployed.ts",
+    "start": "npx bun src/index.ts"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@ai-sdk/openai": "latest",
+    "@mastra/core": "workspace:*",
+    "zod": "^3.24.2"
+  }
+}
+
+```
+
+### index.ts
+```typescript
+import { z } from 'zod';
+import { mastra } from './mastra';
+
+const agent = mastra.getAgent('chefAgent');
+const responsesAgent = mastra.getAgent('chefAgentResponses');
+
+async function text() {
+  // Query 1: Basic pantry ingredients
+  const query1 =
+    'In my kitchen I have: pasta, canned tomatoes, garlic, olive oil, and some dried herbs (basil and oregano). What can I make?';
+  console.log(`Query 1: ${query1}`);
+
+  const pastaResponse = await agent.generate(query1);
+  console.log('\n👨‍🍳 Chef Michel:', pastaResponse.text);
+  console.log('\n-------------------\n');
+}
+
+async function generateText() {
+  // Query 1: Basic pantry ingredients
+
+  const query1 =
+    'In my kitchen I have: pasta, canned tomatoes, garlic, olive oil, and some dried herbs (basil and oregano). What can I make?';
+  console.log(`Query 1: ${query1}`);
+
+  const pastaResponse = await agent.generate(query1);
+
+  console.log('\n👨‍🍳 Chef Michel:', pastaResponse.text);
+  console.log('\n-------------------\n');
+}
+
+async function textStream() {
+  // Query 2: More ingredients
+  const query2 =
+    "Now I'm over at my friend's house, and they have: chicken thighs, coconut milk, sweet potatoes, and some curry powder.";
+  console.log(`Query 2: ${query2}`);
+
+  const curryResponse = await agent.stream(query2);
+
+  console.log('\n👨‍🍳 Chef Michel: ');
+
+  // Handle the stream
+  for await (const chunk of curryResponse.textStream) {
+    // Write each chunk without a newline to create a continuous stream
+    process.stdout.write(chunk);
+  }
+
+  console.log('\n\n✅ Recipe complete!');
+}
+
+async function generateStream() {
+  // Query 2: More ingredients
+  const query2 =
+    "Now I'm over at my friend's house, and they have: chicken thighs, coconut milk, sweet potatoes, and some curry powder.";
+  console.log(`Query 2: ${query2}`);
+
+  const curryResponse = await agent.stream([query2]);
+
+  console.log('\n👨‍🍳 Chef Michel: ');
+
+  // Handle the stream
+  for await (const chunk of curryResponse.textStream) {
+    // Write each chunk without a newline to create a continuous stream
+    process.stdout.write(chunk);
+  }
+
+  console.log('\n\n✅ Recipe complete!');
+}
+
+async function textObject() {
+  // Query 3: Generate a lasagna recipe
+  const query3 = 'I want to make lasagna, can you generate a lasagna recipe for me?';
+  console.log(`Query 3: ${query3}`);
+
+  const lasagnaResponse = await agent.generate(query3, {
+    output: z.object({
+      ingredients: z.array(
+        z.object({
+          name: z.string(),
+          amount: z.number(),
+        }),
+      ),
+      steps: z.array(z.string()),
+    }),
+  });
+  console.log('\n👨‍🍳 Chef Michel:', lasagnaResponse.object);
+  console.log('\n-------------------\n');
+}
+
+async function experimentalTextObject() {
+  // Query 3: Generate a lasagna recipe
+  const query3 = 'I want to make lasagna, can you generate a lasagna recipe for me?';
+  console.log(`Query 3: ${query3}`);
+
+  const lasagnaResponse = await agent.generate(query3, {
+    experimental_output: z.object({
+      ingredients: z.array(
+        z.object({
+          name: z.string(),
+          amount: z.number(),
+        }),
+      ),
+      steps: z.array(z.string()),
+    }),
+  });
+  console.log('\n👨‍🍳 Chef Michel:', lasagnaResponse.object);
+  console.log('\n-------------------\n');
+}
+
+async function textObjectJsonSchema() {
+  // Query 3: Generate a lasagna recipe
+  const query3 = 'I want to make lasagna, can you generate a lasagna recipe for me?';
+  console.log(`Query 3: ${query3}`);
+
+  const lasagnaResponse = await agent.generate(query3, {
+    output: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['ingredients', 'steps'],
+      properties: {
+        ingredients: {
+          type: 'array',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              name: { type: 'string' },
+              amount: { type: 'number' },
+            },
+            required: ['name', 'amount'],
+          },
+        },
+        steps: {
+          type: 'array',
+          items: { type: 'string' },
+        },
+      },
+    },
+  });
+
+  console.log('\n👨‍🍳 Chef Michel:', lasagnaResponse.object);
+  console.log('\n-------------------\n');
+}
+
+async function generateObject() {
+  // Query 3: Generate a lasagna recipe
+  const query3 = 'I want to make lasagna, can you generate a lasagna recipe for me?';
+  console.log(`Query 3: ${query3}`);
+
+  const lasagnaResponse = await agent.generate([query3], {
+    output: z.object({
+      ingredients: z.array(
+        z.object({
+          name: z.string(),
+          amount: z.number(),
+        }),
+      ),
+      steps: z.array(z.string()),
+    }),
+  });
+  console.log('\n👨‍🍳 Chef Michel:', lasagnaResponse.object);
+  console.log('\n-------------------\n');
+}
+
+async function streamObject() {
+  // Query 8: Generate a lasagna recipe
+  const query8 = 'I want to make lasagna, can you generate a lasagna recipe for me?';
+  console.log(`Query 8: ${query8}`);
+
+  const lasagnaStreamResponse = await agent.stream(query8, {
+    output: z.object({
+      ingredients: z.array(
+        z.object({
+          name: z.string(),
+          amount: z.number(),
+        }),
+      ),
+      steps: z.array(z.string()),
+    }),
+  });
+
+  console.log('\n👨‍🍳 Chef Michel: ');
+
+  // Handle the stream
+  for await (const chunk of lasagnaStreamResponse.textStream) {
+    // Write each chunk without a newline to create a continuous stream
+    process.stdout.write(chunk);
+  }
+
+  console.log('\n\n✅ Recipe complete!');
+}
+
+async function generateStreamObject() {
+  // Query 9: Generate a lasagna recipe
+  const query9 = 'I want to make lasagna, can you generate a lasagna recipe for me?';
+  console.log(`Query 9: ${query9}`);
+
+  const lasagnaStreamResponse = await agent.stream([query9], {
+    output: z.object({
+      ingredients: z.array(
+        z.object({
+          name: z.string(),
+          amount: z.number(),
+        }),
+      ),
+      steps: z.array(z.string()),
+    }),
+  });
+
+  console.log('\n👨‍🍳 Chef Michel: ');
+
+  // Handle the stream
+  for await (const chunk of lasagnaStreamResponse.textStream) {
+    // Write each chunk without a newline to create a continuous stream
+    process.stdout.write(chunk);
+  }
+
+  console.log('\n\n✅ Recipe complete!');
+}
+
+async function generateExperimentalStreamObject() {
+  // Query 9: Generate a lasagna recipe
+  const query9 = 'I want to make lasagna, can you generate a lasagna recipe for me?';
+  console.log(`Query 9: ${query9}`);
+
+  const lasagnaStreamResponse = await agent.stream([query9], {
+    experimental_output: z.object({
+      ingredients: z.array(
+        z.object({
+          name: z.string(),
+          amount: z.number(),
+        }),
+      ),
+      steps: z.array(z.string()),
+    }),
+  });
+
+  console.log('\n👨‍🍳 Chef Michel: ');
+
+  // Handle the stream
+  for await (const chunk of lasagnaStreamResponse.textStream) {
+    // Write each chunk without a newline to create a continuous stream
+    process.stdout.write(chunk);
+  }
+
+  console.log('\n\n✅ Recipe complete!');
+}
+
+async function main() {
+  // await text();
+
+  // await experimentalTextObject();
+
+  // await generateExperimentalStreamObject();
+
+  // await generateText();
+
+  // await textStream();
+
+  // await generateStream();
+
+  // await textObject();
+
+  // await textObjectJsonSchema();
+
+  // await generateObject();
+
+  // await streamObject();
+
+  // await generateStreamObject();
+
+  const query1 = 'What happened in San Francisco last week?';
+
+  const pastaResponse = await responsesAgent.generate(query1, {
+    instructions: 'You take every recipe you get an exaggerate it and use weird ingredients.',
+  });
+
+  console.log(pastaResponse.text);
+}
+
+main();
+
+```
+
+### mastra/agents/index.ts
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { Agent } from '@mastra/core/agent';
+import { cookingTool } from '../tools/index.js';
+
+export const chefAgent = new Agent({
+  name: 'Chef Agent',
+  instructions: `
+    YOU MUST USE THE TOOL cooking-tool
+    You are Michel, a practical and experienced home chef who helps people cook great meals with whatever 
+    ingredients they have available. Your first priority is understanding what ingredients and equipment the user has access to, then suggesting achievable recipes. 
+    You explain cooking steps clearly and offer substitutions when needed, maintaining a friendly and encouraging tone throughout.
+    `,
+  model: openai('gpt-4o-mini'),
+  tools: {
+    cookingTool,
+  },
+});
+
+export const chefAgentResponses = new Agent({
+  name: 'Chef Agent',
+  instructions: `
+    You are Michel, a practical and experienced home chef who helps people cook great meals with whatever 
+    ingredients they have available. Your first priority is understanding what ingredients and equipment the user has access to, then suggesting achievable recipes. 
+    You explain cooking steps clearly and offer substitutions when needed, maintaining a friendly and encouraging tone throughout.
+    `,
+  model: openai.responses('gpt-4o'),
+  tools: {
+    web_search_preview: openai.tools.webSearchPreview(),
+  },
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core';
+import { createLogger } from '@mastra/core/logger';
+
+import { chefAgent, chefAgentResponses } from './agents/index';
+
+export const mastra = new Mastra({
+  agents: { chefAgent, chefAgentResponses },
+  logger: createLogger({ name: 'Chef', level: 'info' }),
+  serverMiddleware: [
+    {
+      handler: (c, next) => {
+        console.log('Middleware called');
+        return next();
+      },
+    },
+  ],
+});
+
+```
+
+### mastra/tools/index.ts
+```typescript
+import { createTool } from '@mastra/core/tools';
+import { z } from 'zod';
+
+export const cookingTool = createTool({
+  id: 'cooking-tool',
+  description: 'My tool description',
+  inputSchema: z.object({
+    ingredient: z.string(),
+  }),
+  execute: async ({ context }, options) => {
+    console.log('My tool is running!', context.ingredient);
+    if (options?.toolCallId) {
+      console.log('Tool call ID:', options.toolCallId);
+    }
+    return 'My tool result';
+  },
+});
+
+```