@mastra/mcp-docs-server 0.13.34 → 0.13.35

package/.docs/raw/workflows/human-in-the-loop.mdx

@@ -0,0 +1,268 @@
+---
+title: "Human in the Loop | Workflows | Mastra Docs"
+description: Example of using Mastra to create workflows with multi-turn human/agent interaction points using suspend/resume and dountil methods.
+---
+
+import { GithubLink } from "@/components/github-link";
+
+# Human-in-the-loop
+
+Human-in-the-loop workflows enable ongoing interaction between humans and AI agents, allowing for complex decision-making processes that require multiple rounds of input and response. These workflows can suspend execution at specific points, wait for human input, and continue processing based on the responses received.
+
+In this example, the multi-turn workflow is used to create a Heads Up game that demonstrates how to create interactive workflows using suspend/resume functionality and conditional logic with `dountil` to repeat a workflow step until a specific condition is met.
+
+This example consists of three main components:
+
+1. A [**Famous Person Agent**](#famous-person-agent) that generates a famous person's name.
+2. A [**Game Agent**](#game-agent) that handles the gameplay.
+3. A [**Multi-Turn Workflow**](#multi-turn-workflow) that orchestrates the interaction.
+
+## Prerequisites
+
+This example uses the `openai` model. Make sure to add the following to your `.env` file:
+
+```bash filename=".env" copy
+OPENAI_API_KEY=<your-api-key>
+```
+
+## Famous person agent
+
+The `famousPersonAgent` generates a unique name each time the game is played, using semantic memory to avoid repeating suggestions.
+
+```typescript filename="src/mastra/agents/example-famous-person-agent.ts" showLineNumbers copy
+import { openai } from "@ai-sdk/openai";
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+import { LibSQLVector } from "@mastra/libsql";
+
+export const famousPersonAgent = new Agent({
+  name: "Famous Person Generator",
+  instructions: `You are a famous person generator for a "Heads Up" guessing game.
+
+Generate the name of a well-known famous person who:
+- Is recognizable to most people
+- Has distinctive characteristics that can be described with yes/no questions
+- Is appropriate for all audiences
+- Has a clear, unambiguous name
+
+IMPORTANT: Use your memory to check what famous people you've already suggested and NEVER repeat a person you've already suggested.
+
+Examples: Albert Einstein, Beyoncé, Leonardo da Vinci, Oprah Winfrey, Michael Jordan
+
+Return only the person's name, nothing else.`,
+  model: openai("gpt-4o"),
+  memory: new Memory({
+    vector: new LibSQLVector({
+      connectionUrl: "file:../mastra.db"
+    }),
+    embedder: openai.embedding("text-embedding-3-small"),
+    options: {
+      lastMessages: 5,
+      semanticRecall: {
+        topK: 10,
+        messageRange: 1
+      }
+    }
+  })
+});
+```
+
+> See [Agent](../../reference/agents/agent.mdx) for a full list of configuration options.
+
+## Game agent
+
+The `gameAgent` handles user interactions by responding to questions and validating guesses.
+
+```typescript filename="src/mastra/agents/example-game-agent.ts" showLineNumbers copy
+import { openai } from "@ai-sdk/openai";
+import { Agent } from "@mastra/core/agent";
+
+export const gameAgent = new Agent({
+  name: "Game Agent",
+  instructions: `You are a helpful game assistant for a "Heads Up" guessing game.
+
+CRITICAL: You know the famous person's name but you must NEVER reveal it in any response.
+
+When a user asks a question about the famous person:
+- Answer truthfully based on the famous person provided
+- Keep responses concise and friendly
+- NEVER mention the person's name, even if it seems natural
+- NEVER reveal gender, nationality, or other characteristics unless specifically asked about them
+- Answer yes/no questions with clear "Yes" or "No" responses
+- Be consistent - same question asked differently should get the same answer
+- Ask for clarification if a question is unclear
+- If multiple questions are asked at once, ask them to ask one at a time
+
+When they make a guess:
+- If correct: Congratulate them warmly
+- If incorrect: Politely correct them and encourage them to try again
+
+Encourage players to make a guess when they seem to have enough information.
+
+You must return a JSON object with:
+- response: Your response to the user
+- gameWon: true if they guessed correctly, false otherwise`,
+  model: openai("gpt-4o")
+});
+```
+
+
+## Multi-turn workflow
+
+The workflow coordinates the full interaction using `suspend`/`resume` to pause for human input and `dountil` to repeat the game loop until a condition is met.
+
+The `startStep` generates a name using the `famousPersonAgent`, while the `gameStep` runs the interaction through the `gameAgent`, which handles both questions and guesses and produces structured output that includes a `gameWon` boolean.
+
+```typescript filename="src/mastra/workflows/example-heads-up-workflow.ts" showLineNumbers copy
+import { createWorkflow, createStep } from '@mastra/core/workflows';
+import { z } from 'zod';
+
+const startStep = createStep({
+  id: 'start-step',
+  description: 'Get the name of a famous person',
+  inputSchema: z.object({
+    start: z.boolean(),
+  }),
+  outputSchema: z.object({
+    famousPerson: z.string(),
+    guessCount: z.number(),
+  }),
+  execute: async ({ mastra }) => {
+    const agent = mastra.getAgent('famousPersonAgent');
+    const response = await agent.generate("Generate a famous person's name", {
+      temperature: 1.2,
+      topP: 0.9,
+      memory: {
+        resource: 'heads-up-game',
+        thread: 'famous-person-generator',
+      },
+    });
+    const famousPerson = response.text.trim();
+    return { famousPerson, guessCount: 0 };
+  },
+});
+
+const gameStep = createStep({
+  id: 'game-step',
+  description: 'Handles the question-answer-continue loop',
+  inputSchema: z.object({
+    famousPerson: z.string(),
+    guessCount: z.number(),
+  }),
+  resumeSchema: z.object({
+    userMessage: z.string(),
+  }),
+  suspendSchema: z.object({
+    suspendResponse: z.string(),
+  }),
+  outputSchema: z.object({
+    famousPerson: z.string(),
+    gameWon: z.boolean(),
+    agentResponse: z.string(),
+    guessCount: z.number(),
+  }),
+  execute: async ({ inputData, mastra, resumeData, suspend }) => {
+    let { famousPerson, guessCount } = inputData;
+    const { userMessage } = resumeData ?? {};
+
+    if (!userMessage) {
+      return await suspend({
+        suspendResponse: "I'm thinking of a famous person. Ask me yes/no questions to figure out who it is!",
+      });
+    }
+
+    const agent = mastra.getAgent('gameAgent');
+    const response = await agent.generate(
+      `
+        The famous person is: ${famousPerson}
+        The user said: "${userMessage}"
+        Please respond appropriately. If this is a guess, tell me if it's correct.
+      `,
+      {
+        structuredOutput: {
+          schema: z.object({
+            response: z.string(),
+            gameWon: z.boolean(),
+          })
+        },
+      },
+    );
+
+    const { response: agentResponse, gameWon } = response.object;
+
+    guessCount++;
+
+    return { famousPerson, gameWon, agentResponse, guessCount };
+  },
+});
+
+const winStep = createStep({
+  id: 'win-step',
+  description: 'Handle game win logic',
+  inputSchema: z.object({
+    famousPerson: z.string(),
+    gameWon: z.boolean(),
+    agentResponse: z.string(),
+    guessCount: z.number(),
+  }),
+  outputSchema: z.object({
+    famousPerson: z.string(),
+    gameWon: z.boolean(),
+    guessCount: z.number(),
+  }),
+  execute: async ({ inputData }) => {
+    const { famousPerson, gameWon, guessCount } = inputData;
+
+    console.log('famousPerson: ', famousPerson);
+    console.log('gameWon: ', gameWon);
+    console.log('guessCount: ', guessCount);
+
+    return { famousPerson, gameWon, guessCount };
+  },
+});
+
+export const headsUpWorkflow = createWorkflow({
+  id: 'heads-up-workflow',
+  inputSchema: z.object({
+    start: z.boolean(),
+  }),
+  outputSchema: z.object({
+    famousPerson: z.string(),
+    gameWon: z.boolean(),
+    guessCount: z.number(),
+  }),
+})
+  .then(startStep)
+  .dountil(gameStep, async ({ inputData: { gameWon } }) => gameWon)
+  .then(winStep)
+  .commit();
+
+```
+> See [Workflow](../../reference/workflows/workflow.mdx) for a full list of configuration options.
+
+## Registering the agents and workflow
+
+To use a workflow or an agent, register them in your main Mastra instance.
+
+```typescript filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+
+import { headsUpWorkflow } from "./workflows/example-heads-up-workflow";
+import { famousPersonAgent } from "./agents/example-famous-person-agent";
+import { gameAgent } from "./agents/example-game-agent";
+
+export const mastra = new Mastra({
+  workflows: { headsUpWorkflow },
+  agents: { famousPersonAgent, gameAgent }
+});
+```
+
+<GithubLink
+  marginTop='mt-16'
+  link="https://github.com/mastra-ai/mastra/blob/main/examples/heads-up-game/"
+/>
+
+## Related
+
+- [Running Workflows](./running-workflows.mdx)
+- [Control Flow](../../docs/workflows/control-flow.mdx)

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/mcp-docs-server
 
+## 0.13.35
+
+### Patch Changes
+
+- Updated dependencies [[`f743dbb`](https://github.com/mastra-ai/mastra/commit/f743dbb8b40d1627b5c10c0e6fc154f4ebb6e394), [`5df9cce`](https://github.com/mastra-ai/mastra/commit/5df9cce1a753438413f64c11eeef8f845745c2a8), [`2060766`](https://github.com/mastra-ai/mastra/commit/20607667bf78ea104cca3e15dfb93ae0b62c9d18), [`2c4438b`](https://github.com/mastra-ai/mastra/commit/2c4438b87817ab7eed818c7990fef010475af1a3)]:
+  - @mastra/core@0.23.0
+
+## 0.13.35-alpha.0
+
+### Patch Changes
+
+- Updated dependencies [[`f743dbb`](https://github.com/mastra-ai/mastra/commit/f743dbb8b40d1627b5c10c0e6fc154f4ebb6e394), [`5df9cce`](https://github.com/mastra-ai/mastra/commit/5df9cce1a753438413f64c11eeef8f845745c2a8), [`2060766`](https://github.com/mastra-ai/mastra/commit/20607667bf78ea104cca3e15dfb93ae0b62c9d18), [`2c4438b`](https://github.com/mastra-ai/mastra/commit/2c4438b87817ab7eed818c7990fef010475af1a3)]:
+  - @mastra/core@0.23.0-alpha.0
+
 ## 0.13.34
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "0.13.34",
+  "version": "0.13.35",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -33,7 +33,7 @@
     "uuid": "^11.1.0",
     "zod": "^3.25.76",
     "zod-to-json-schema": "^3.24.6",
-    "@mastra/core": "0.22.2",
+    "@mastra/core": "0.23.0",
     "@mastra/mcp": "^0.14.0"
   },
   "devDependencies": {
@@ -49,8 +49,8 @@
     "tsx": "^4.19.4",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@internal/lint": "0.0.53",
-    "@mastra/core": "0.22.2"
+    "@internal/lint": "0.0.54",
+    "@mastra/core": "0.23.0"
   },
   "homepage": "https://mastra.ai",
   "repository": {
@@ -61,6 +61,13 @@
   "bugs": {
     "url": "https://github.com/mastra-ai/mastra/issues"
   },
+  "publishConfig": {
+    "access": "public",
+    "publish-branch": [
+      "main",
+      "0.x"
+    ]
+  },
   "scripts": {
     "prepare-docs": "cross-env PREPARE=true node dist/prepare-docs/prepare.js",
     "build:cli": "tsup src/stdio.ts src/prepare-docs/prepare.ts --format esm --no-dts --treeshake=smallest --splitting && tsc -p tsconfig.build.json",