Agents and Tools
ワークフローステップは構成可能で、通常はexecute
関数内で直接ロジックを実行します。しかし、エージェントやツールを呼び出すことがより適切な場合があります。このパターンは特に以下の場合に有用です:
- LLMを使用してユーザー入力から自然言語応答を生成する場合。
- 複雑または再利用可能なロジックを専用ツールに抽象化する場合。
- 構造化された、または再利用可能な方法でサードパーティAPIと相互作用する場合。
ワークフローは、Mastraエージェントやツールを直接ステップとして使用できます。例:createStep(testAgent)
またはcreateStep(testTool)
。
Agents
ワークフローにエージェントを含めるには、通常の方法でエージェントを定義し、createStep(testAgent)
を使用してワークフローに直接追加するか、ステップのexecute
関数内で.generate()
を使用して呼び出します。
エージェントの例
このエージェントはOpenAIを使用して、都市、国、タイムゾーンに関する事実を生成します。
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()
で完成されます。
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()
で完成されます。
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を使用して都市の地理的位置の詳細を取得し、その名前、国、タイムゾーンを返します。
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()
で完了します。
import { testTool } from "../tools/test-tool";
const step1 = createStep(testTool);
export const testWorkflow = createWorkflow({...})
.then(step1)
.commit();
ツールの実行
この例では、step1
が.execute()
メソッドを使用してtestTool
を直接呼び出します。ツールは提供されたcity
でジオコーディング検索を実行し、対応するcountry
を返します。
結果はステップから構造化された出力として返されます。ステップは.then()
を使用してワークフローに組み込まれ、ワークフローの入力を処理し、型付きの出力を生成できます。ワークフローは.commit()
で完了します。
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インスタンスに追加されています。
import { Mastra } from "@mastra/core/mastra";
import { testWorkflow, cityStringWorkflow } from "./workflows/test-workflow";
export const mastra = new Mastra({
...
workflows: { testWorkflow, cityStringWorkflow },
});
ワークフローが登録されると、ツール内からgetWorkflow
を使用して参照できます。
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
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で接続できます。
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