Skip to Content
ドキュメントワークフローエージェントとツールでワークフローを使う | ワークフロー | Mastra ドキュメント

Agents and Tools

ワークフローステップは構成可能で、通常はexecute関数内で直接ロジックを実行します。しかし、エージェントやツールを呼び出すことがより適切な場合があります。このパターンは特に以下の場合に有用です：

  • LLMを使用してユーザー入力から自然言語応答を生成する場合。
  • 複雑または再利用可能なロジックを専用ツールに抽象化する場合。
  • 構造化された、または再利用可能な方法でサードパーティAPIと相互作用する場合。

ワークフローは、Mastraエージェントやツールを直接ステップとして使用できます。例：createStep(testAgent)またはcreateStep(testTool)。

Agents

ワークフローにエージェントを含めるには、通常の方法でエージェントを定義し、createStep(testAgent)を使用してワークフローに直接追加するか、ステップのexecute関数内で.generate()を使用して呼び出します。

エージェントの例

このエージェントはOpenAIを使用して、都市、国、タイムゾーンに関する事実を生成します。

src/mastra/agents/test-agent.ts
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
 
export const testAgent = new Agent({
  name: "test-agent",
  description: "Create facts for a country based on the city",
  instructions: `Return an interesting fact about the country based on the city provided`,
  model: openai("gpt-4o")
});

ステップとしてのエージェント

この例では、step1はtestAgentを使用して、指定された都市に基づいてその国に関する興味深い事実を生成します。

.mapメソッドは、ワークフローの入力をtestAgentと互換性のあるprompt文字列に変換します。

ステップは.then()を使用してワークフローに組み込まれ、マップされた入力を受け取り、エージェントの構造化された出力を返すことができます。ワークフローは.commit()で完成されます。

src/mastra/workflows/test-workflow.ts
import { testAgent } from "../agents/test-agent";
 
const step1 = createStep(testAgent);
 
export const testWorkflow = createWorkflow({
  id: "test-workflow",
  description: 'Test workflow',
  inputSchema: z.object({
    input: z.string()
  }),
  outputSchema: z.object({
    output: z.string()
  })
})
  .map(({ inputData }) => {
    const { input } = inputData;
    return {
      prompt: `Provide facts about the city: ${input}`
    };
  })
  .then(step1)
  .commit();

エージェントの生成

この例では、step1は提供されたinputを使用してプロンプトを構築し、それをtestAgentに渡します。エージェントは都市とその国に関する事実を含むプレーンテキストの応答を返します。

ステップは順次.then()メソッドを使用してワークフローに追加され、ワークフローから入力を受け取り、構造化された出力を返すことができます。ワークフローは.commit()で完成されます。

src/mastra/workflows/test-workflow.ts
import { testAgent } from "../agents/test-agent";
 
const step1 = createStep({
  id: "step-1",
  description: "Create facts for a country based on the city",
  inputSchema: z.object({
    input: z.string()
  }),
  outputSchema: z.object({
    output: z.string()
  }),
 
  execute: async ({ inputData }) => {
    const { input } = inputData;
 
    const  prompt = `Provide facts about the city: ${input}`
 
    const { text } = await testAgent.generate([
      { role: "user", content: prompt }
    ]);
 
    return {
      output: text
    };
  }
});
 
export const testWorkflow = createWorkflow({...})
  .then(step1)
  .commit();

Tools

ワークフロー内でツールを使用するには、通常の方法で定義し、createStep(testTool)を使用してワークフローに直接追加するか、ステップのexecute関数内で.execute()を使用して呼び出します。

ツールの例

以下の例では、Open Meteo APIを使用して都市の地理的位置の詳細を取得し、その名前、国、タイムゾーンを返します。

src/mastra/tools/test-tool.ts
import { createTool } from "@mastra/core";
import { z } from "zod";
 
export const testTool = createTool({
  id: "test-tool",
  description: "Gets country for a city",
  inputSchema: z.object({
    input: z.string()
  }),
  outputSchema: z.object({
    country_name: z.string()
  }),
  execute: async ({ context }) => {
    const { input } = context;
    const geocodingResponse = await fetch(`https://geocoding-api.open-meteo.com/v1/search?name=${input}`);
    const geocodingData = await geocodingResponse.json();
 
    const { country } = geocodingData.results[0];
 
    return {
      country_name: country
    };
  }
});

ステップとしてのツール

この例では、step1がtestToolを使用し、提供されたcityを使用してジオコーディング検索を実行し、解決されたcountryを返します。

ステップは順次.then()メソッドを使用してワークフローに追加され、ワークフローから入力を受け取り、構造化された出力を返すことができます。ワークフローは.commit()で完了します。

src/mastra/workflows/test-workflow.ts
import { testTool } from "../tools/test-tool";
 
const step1 = createStep(testTool);
 
export const testWorkflow = createWorkflow({...})
  .then(step1)
  .commit();

ツールの実行

この例では、step1が.execute()メソッドを使用してtestToolを直接呼び出します。ツールは提供されたcityでジオコーディング検索を実行し、対応するcountryを返します。

結果はステップから構造化された出力として返されます。ステップは.then()を使用してワークフローに組み込まれ、ワークフローの入力を処理し、型付きの出力を生成できます。ワークフローは.commit()で完了します。

src/mastra/workflows/test-workflow.ts
import { RuntimeContext } from "@mastra/core/di";
 
import { testTool } from "../tools/test-tool";
 
const runtimeContext = new RuntimeContext();
 
const step1 = createStep({
  id: "step-1",
  description: "Gets country for a city",
  inputSchema: z.object({
    input: z.string()
  }),
  outputSchema: z.object({
    output: z.string()
  }),
 
  execute: async ({ inputData }) => {
    const { input } = inputData;
 
    const { country_name } = await testTool.execute({
      context: { input },
      runtimeContext
    });
 
    return {
      output: country_name
    };
  }
});
 
export const testWorkflow = createWorkflow({...})
  .then(step1)
  .commit();

ツールとしてのワークフロー

この例では、cityStringWorkflowワークフローがメインのMastraインスタンスに追加されています。

src/mastra/index.ts
import { Mastra } from "@mastra/core/mastra";
 
import { testWorkflow, cityStringWorkflow } from "./workflows/test-workflow";
 
export const mastra = new Mastra({
  ...
  workflows: { testWorkflow, cityStringWorkflow },
});

ワークフローが登録されると、ツール内からgetWorkflowを使用して参照できます。

src/mastra/tools/test-tool.ts
export const cityCoordinatesTool = createTool({
  id: "city-tool",
  description: "Convert city details",
  inputSchema: z.object({
    city: z.string()
  }),
  outputSchema: z.object({
    outcome: z.string()
  }),
  execute: async ({ context, mastra }) => {
    const { city } = context;
    const geocodingResponse = await fetch(`https://geocoding-api.open-meteo.com/v1/search?name=${city}`);
    const geocodingData = await geocodingResponse.json();
 
    const { name, country, timezone } = geocodingData.results[0];
 
    const workflow = mastra?.getWorkflow("cityStringWorkflow");
 
    const run = workflow?.createRun();
 
    const { result } = await run?.start({
      inputData: {
        city_name: name,
        country_name: country,
        country_timezone: timezone
      }
    });
 
    return {
      outcome: result.outcome
    };
  }
});

MCP Server

ワークフローをMastra MCPServerのインスタンスに渡すことで、ワークフローをツールに変換できます。これにより、MCP互換のクライアントがあなたのワークフローにアクセスできるようになります。

ワークフローの説明がツールの説明となり、入力スキーマがツールの入力スキーマとなります。

サーバーにワークフローを提供すると、各ワークフローは自動的に呼び出し可能なツールとして公開されます。例えば：

  • run_testWorkflow
src/test-mcp-server.ts
import { MCPServer } from "@mastra/mcp";
 
import { testAgent } from "./mastra/agents/test-agent";
import { testTool } from "./mastra/tools/test-tool";
import { testWorkflow } from "./mastra/workflows/test-workflow";
 
async function startServer() {
  const server = new MCPServer({
    name: "test-mcp-server",
    version: "1.0.0",
    workflows: {
      testWorkflow
    }
  });
 
  await server.startStdio();
  console.log("MCPServer started on stdio");
}
 
startServer().catch(console.error);

ワークフローがサーバーで利用可能であることを確認するには、MCPClientで接続できます。

src/test-mcp-client.ts
import { MCPClient } from "@mastra/mcp";
 
async function main() {
  const mcp = new MCPClient({
    servers: {
      local: {
        command: "npx",
        args: ["tsx", "src/test-mcp-server.ts"]
      }
    }
  });
 
  const tools = await mcp.getTools();
  console.log(tools);
}
 
main().catch(console.error);

クライアントスクリプトを実行して、ワークフローツールを確認してください。

npx tsx src/test-mcp-client.ts

その他のリソース

ワークフローの一時停止と再開 | Human-in-the-Loop | Mastra ドキュメントワークフロー変数によるデータマッピング | Mastra ドキュメント