跳至主要內容

Workflow.agent()

.agent() 方法會將 Agent 新增為宣告式步驟。此步驟接受 { prompt: string } 作為輸入，預設回傳 { text: string }。請在 Agent 之前使用 .map()，根據 Workflow 資料建立 prompt。

與使用 createStep() 包裝 Agent 不同，.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 }
Agent 呼叫選項，例如 maxSteps、modelSettings、memory 與 providerOptions，以及步驟層級的 retries、scorers 和 metadata。requestContext、resourceId、threadId 與 onStepFinish 等逐次請求欄位由 Workflow 引擎管理，因此會排除。

stepOptions?:

{ id?: string }
此步驟在 Workflow 中呼叫位置的 ID。預設為 Agent 的 ID。同一個 Agent 在同一個 Workflow 中出現多次時，請設定此值。

回傳值
「回傳值」的直接連結

workflow:

Workflow
可供方法連結使用的 Workflow 執行個體

結構化輸出
「結構化輸出」的直接連結

此步驟預設輸出 { text: string }。傳入 structuredOutput.schema，即可改為回傳該結構。此 schema 會成為步驟的輸出 schema，因此後續步驟能以完整的型別安全機制接續處理：

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

透過 ID 參照 Agent
「透過 ID 參照 Agent」的直接連結

傳入字串，即可在不匯入 Agent 的情況下參照已註冊的 Agent。Workflow 執行時，該 Agent 必須已註冊於 Mastra 執行個體：

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

保存 Agent 步驟
「保存 Agent 步驟」的直接連結

使用 .agent() 建立的 Workflow，會序列化為與動態 Workflow 相同的宣告式項目。只有 retries 與 metadata 能完整寫入儲存空間後再還原。保存 Workflow 時，onFinish 或值為函式的 toolChoice 等含有函式的選項會擲回錯誤。

On this page