Agent 및 Tool

Workflow 단계에서는 Agent를 호출하여 LLM 추론을 사용하거나 유형 안전 논리를 위한 Tool을 호출할 수 있습니다. 단계 내에서 호출할 수 있습니다.execute()함수를 사용하거나 다음을 사용하여 단계로 직접 구성합니다.createStep().

Workflow에서 Agent 사용

추론, 언어 생성 또는 기타 LLM 기반 작업이 필요하면 Workflow 단계에서 Agent를 사용하세요. Agent 호출을 더 세밀하게 제어해야 하는 경우(예: 메시지 기록 추적 또는 구조화된 출력 반환) 단계의 execute() 함수에서 Agent를 호출합니다. Agent의 호출 방식을 변경할 필요가 없으면 Agent를 단계로 구성하세요.

Agent 호출

단계의 execute() 함수 내에서 .generate() 또는 .stream()을 사용하여 Agent를 호출합니다. 이를 통해 다음 단계로 전달하기 전에 Agent 호출을 수정하고 응답을 처리할 수 있습니다.

src/mastra/workflows/test-workflow.ts

const step1 = createStep({
  execute: async ({ inputData, mastra }) => {
    const { message } = inputData

    const testAgent = mastra.getAgent('testAgent')
    const response = await testAgent.generate(
      `Convert this message into bullet points: ${message}`,
      {
        memory: {
          thread: 'user-123',
          resource: 'test-123',
        },
      },
    )

    return {
      list: response.text,
    }
  },
})

단계로서의 Agent

Agent 호출을 수정할 필요가 없으면 createStep()을 사용하여 Agent를 단계로 구성합니다. .map()을 사용하여 이전 단계의 출력을 Agent가 사용할 수 있는 prompt로 변환하세요.

src/mastra/workflows/test-workflow.ts

import { testAgent } from '../agents/test-agent'
const step1 = createStep(testAgent)

export const testWorkflow = createWorkflow({})
  .map(async ({ inputData }) => {
    const { message } = inputData
    return {
      prompt: `Convert this message into bullet points: ${message}`,
    }
  })
  .then(step1)
  .then(step2)
  .commit()

자세한 내용은 입력 데이터 매핑을 참조하세요. structuredOutput 옵션을 제공하지 않으면 Mastra Agent는 입력으로 prompt 문자열을 받고 출력으로 text 문자열을 반환하는 기본 스키마를 사용합니다.

{
  inputSchema: {
    prompt: string
  },
  outputSchema: {
    text: string
  }
}

구조화된 출력이 있는 Agent

Agent가 일반 텍스트 대신 구조화된 데이터를 반환해야 하면 createStep()에 structuredOutput 옵션을 전달합니다. 단계의 출력 스키마가 제공한 스키마와 일치하므로 이후 단계를 타입 안전하게 연결할 수 있습니다.

src/mastra/workflows/test-workflow.ts

const articleSchema = z.object({
  title: z.string(),
  summary: z.string(),
  tags: z.array(z.string()),
})

const agentStep = createStep(testAgent, {
  structuredOutput: { schema: articleSchema },
})

// Next step receives typed structured data
const processStep = createStep({
  id: 'process',
  inputSchema: articleSchema, // Matches agent's outputSchema
  outputSchema: z.object({ tagCount: z.number() }),
  execute: async ({ inputData }) => ({
    tagCount: inputData.tags.length, // Fully typed
  }),
})

export const testWorkflow = createWorkflow({})
  .map(async ({ inputData }) => ({
    prompt: `Generate an article about: ${inputData.topic}`,
  }))
  .then(agentStep)
  .then(processStep)
  .commit()

structuredOutput.schema 옵션은 모든 Standard JSON Schema를 허용합니다. Agent는 이 스키마를 준수하는 출력을 생성하며, 단계의 outputSchema는 이에 맞게 자동으로 설정됩니다. 오류 처리 전략과 구조화된 출력 스트리밍 같은 추가 옵션은 구조화된 출력을 참조하세요.

그만큼.agent() shorthand

Agent를 createStep()으로 래핑하는 대신 .agent()를 사용하여 직접 추가하세요. 이 메서드는 createStep(agent, options)과 동일한 옵션을 받으며, 인스턴스 대신 Agent ID 문자열을 전달할 수도 있습니다.

src/mastra/workflows/test-workflow.ts

import { testAgent } from '../agents/test-agent'

export const testWorkflow = createWorkflow({})
  .map(async ({ inputData }) => ({
    prompt: `Generate an article about: ${inputData.topic}`,
  }))
  .agent(testAgent, { structuredOutput: { schema: articleSchema } })
  .commit()

.agent()는 불투명한 단계가 아니라 Workflow 그래프에 선언적 항목을 기록하므로, 이 방식으로 구축한 Workflow는 동적 Workflow처럼 영구 저장할 수 있습니다. 모든 매개변수는 Workflow.agent()을 참조하세요.

Workflow에서 Tool 사용

Workflow 단계에서 Tool을 사용해 기존 Tool 로직을 활용합니다. 컨텍스트를 준비하거나 응답을 처리해야 할 때는 단계 내에서 .execute() 함수를 호출하세요. Tool의 사용 방식을 수정할 필요가 없다면 Tool을 단계로 구성하세요.

호출 Tool

단계 내에서 Tool의 .execute() 함수를 호출하세요. Tool의 입력 컨텍스트를 더 세밀하게 제어하거나, 응답을 처리한 후 다음 단계로 전달할 수 있습니다.

src/mastra/workflows/test-workflow.ts

import { testTool } from '../tools/test-tool'

const step2 = createStep({
  execute: async ({ inputData, requestContext }) => {
    const { text } = inputData

    const response = await testTool.execute({ text }, { requestContext })

    return {
      emphasized: response.emphasized,
    }
  },
})

단계로서의 Tool

이전 단계의 출력이 Tool의 입력 컨텍스트와 일치하면 createStep()을 사용해 Tool을 단계로 구성하세요. 일치하지 않으면 .map()을 사용해 이전 단계의 출력을 변환할 수 있습니다.

src/mastra/workflows/test-workflow.ts

import { testTool } from '../tools/test-tool'

const step2 = createStep(testTool)

export const testWorkflow = createWorkflow({})
  .then(step1)
  .map(async ({ inputData }) => {
    const { formatted } = inputData
    return {
      text: formatted,
    }
  })
  .then(step2)
  .commit()

자세한 내용은 입력 데이터 매핑을 참조하세요.

그만큼.tool() shorthand

Tool을 createStep()으로 래핑하는 대신 .tool()을 사용해 직접 추가하세요. Tool 인스턴스 또는 등록된 Tool ID 문자열과 단계 수준의 retries 및 metadata를 받습니다.

src/mastra/workflows/test-workflow.ts

import { testTool } from '../tools/test-tool'

export const testWorkflow = createWorkflow({}).then(step1).tool(testTool).commit()

.agent()와 마찬가지로 .tool()은 선언적 항목을 기록하므로 Workflow를 동적 Workflow로 영속화할 수 있습니다. 모든 매개변수는 Workflow.tool()을 참조하세요.

관련된

• Agent 사용
• MCP 개요