メインコンテンツへ移動

Workflow.agent()

.agent() メソッドは、Agent を宣言的なステップとして追加します。このステップは入力として { prompt: string } を受け取り、デフォルトでは { text: string } を返します。Workflow のデータからプロンプトを構築するには、Agent の前に .map() を使用します。

Agent を createStep() でラップする場合とは異なり、.agent() は Workflow グラフに宣言的なエントリを記録します。これにより Workflow は移植可能になり、同じグラフをシリアライズして動的 Workflow として永続化できます。

使用例
使用例への直接リンク

workflow
  .map({ prompt: mapVariable({ initData: workflow, path: "topic" }) })
  .agent(testAgent)
  .commit();

パラメーター
パラメーターへの直接リンク

agentOrId:

Agent | string
Agent インスタンス、または Mastra インスタンスに登録されている Agent の ID。ID を渡した場合、実行時にレジストリから Agent が解決されます。

options?:

AgentStepOptions & { structuredOutput?: { schema }, retries?: number, scorers?: DynamicArgument<MastraScorers>, metadata?: StepMetadata }
maxSteps、modelSettings、memory、providerOptions などの Agent 呼び出しオプションに加え、ステップレベルの retries、scorers、metadata を指定します。requestContext、resourceId、threadId、onStepFinish など、リクエスト単位のフィールドは Workflow エンジンによって管理されるため、対象外です。

stepOptions?:

{ id?: string }
Workflow 内でのステップの呼び出し位置 ID。デフォルトは Agent の ID です。同じ Workflow 内に同じ Agent が複数回登場する場合に設定します。

戻り値
戻り値への直接リンク

workflow:

Workflow
メソッドチェーンに使用する Workflow インスタンス

構造化出力
構造化出力への直接リンク

デフォルトでは、このステップの出力は { text: string } です。ステップから別の形式を返すには、structuredOutput.schema を渡します。このスキーマがステップの出力スキーマになるため、後続のステップへ完全な型安全性を保ったままチェーンできます。

workflow
  .agent(testAgent, {
    structuredOutput: {
      schema: z.object({
        subtopics: z.array(z.string()),
      }),
    },
  })
  .commit();

ID で Agent を参照する
ID で Agent を参照するへの直接リンク

登録済みの Agent をインポートせずに参照するには、文字列を渡します。Workflow の実行時に、その Agent が Mastra インスタンスへ登録されている必要があります。

workflow.agent("test-agent", { maxSteps: 3 }).commit();

Agent ステップを永続化する
Agent ステップを永続化するへの直接リンク

.agent() で構築した Workflow は、動的 Workflow が使用するものと同じ宣言的なエントリにシリアライズされます。保存と復元の間で維持されるのは retries と metadata のみです。onFinish や関数値の toolChoice など、関数を保持するオプションがある場合、Workflow の保存時にエラーがスローされます。

On this page