에이전트(Agents) 개요

에이전트(Agents)는 Mastra의 핵심 구성 요소 중 하나입니다. 에이전트는 언어 모델을 사용하여 일련의 작업을 결정합니다. 에이전트는 함수(도구(Tools)라고 부름)를 호출할 수 있습니다. 에이전트를 워크플로우(Workflows)(Mastra의 또 다른 주요 구성 요소)와 결합할 수 있는데, 에이전트에게 워크플로우를 도구로 제공하거나 워크플로우 내에서 에이전트를 실행할 수 있습니다.

에이전트는 루프에서 자율적으로 실행되거나, 한 번만 실행되거나, 사용자와 번갈아 가며 실행될 수 있습니다. 에이전트에게 사용자 상호작용의 단기, 장기, 작업 메모리를 제공할 수 있습니다. 에이전트는 텍스트를 스트리밍하거나 구조화된 출력(예: JSON)을 반환할 수 있습니다. 에이전트는 서드파티 API에 액세스하고, 지식 베이스를 쿼리하는 등의 작업을 수행할 수 있습니다.

또한 에이전트는 동적 구성을 지원하여, 사용자 선호도, 구독 계층, 환경 설정과 같은 런타임 컨텍스트에 따라 지시사항, 모델, 도구, 메모리를 변경할 수 있습니다.

1. 에이전트(Agent) 생성하기

Mastra에서 에이전트를 생성하려면 Agent 클래스를 사용하고 속성을 정의합니다:

Copyimport { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";

export const myAgent = new Agent({
  name: "My Agent",
  instructions: "당신은 도움이 되는 어시스턴트입니다.",
  model: openai("gpt-4o-mini"),
});

참고: .env 파일에 OpenAI API 키와 같은 필요한 환경 변수를 설정했는지 확인하세요:

CopyOPENAI_API_KEY=your_openai_api_key

또한 @mastra/core 패키지가 설치되어 있는지 확인하세요:

Copynpm install @mastra/core@latest

모든 에이전트 속성(지시사항, 모델, 도구, 메모리)은 런타임 컨텍스트를 사용하여 동적으로 구성할 수 있습니다. 사용자 컨텍스트, 구독 계층 또는 기타 런타임 변수에 따라 에이전트 동작을 조정하는 방법의 예시는 동적 에이전트 가이드를 참조하세요.

에이전트 등록하기

로깅을 활성화하고 구성된 도구 및 통합에 액세스하려면 에이전트를 Mastra에 등록하세요:

Copyimport { Mastra } from "@mastra/core";
import { myAgent } from "./agents";

export const mastra = new Mastra({
  agents: { myAgent },
});

2. 텍스트 생성 및 스트리밍

텍스트 생성

.generate() 메서드를 사용하여 에이전트가 텍스트 응답을 생성하도록 합니다:

Copyconst response = await myAgent.generate([
  { role: "user", content: "안녕하세요, 오늘 어떻게 도와드릴까요?" },
]);

console.log("에이전트:", response.text);

generate 메서드와 옵션에 대한 자세한 내용은 generate 참조 문서를 참조하세요.

스트리밍 응답

보다 실시간적인 응답을 위해 에이전트의 응답을 스트리밍할 수 있습니다:

Copyconst stream = await myAgent.stream([
  { role: "user", content: "이야기를 들려주세요." },
]);

console.log("에이전트:");

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}

스트리밍 응답에 대한 자세한 내용은 stream 참조 문서를 참조하세요.

3. 구조화된 출력

에이전트는 JSON 스키마(Schema) 또는 Zod 스키마를 제공하여 구조화된 데이터를 반환할 수 있습니다.

JSON 스키마 사용

Copyconst schema = {
  type: "object",
  properties: {
    summary: { type: "string" },
    keywords: { type: "array", items: { type: "string" } },
  },
  additionalProperties: false,
  required: ["summary", "keywords"],
};

const response = await myAgent.generate(
  [
    {
      role: "user",
      content:
        "다음 텍스트에 대한 요약과 키워드를 제공해주세요: ...",
    },
  ],
  {
    output: schema,
  },
);

console.log("구조화된 출력:", response.object);

Zod 사용

타입 안전한 구조화된 출력을 위해 Zod 스키마를 사용할 수도 있습니다.

먼저 Zod를 설치하세요:

Copynpm install zod

그런 다음 Zod 스키마를 정의하고 에이전트와 함께 사용하세요:

Copyimport { z } from "zod";

// Zod 스키마 정의
const schema = z.object({
  summary: z.string(),
  keywords: z.array(z.string()),
});

// 에이전트와 스키마 사용
const response = await myAgent.generate(
  [
    {
      role: "user",
      content:
        "다음 텍스트에 대한 요약과 키워드를 제공해주세요: ...",
    },
  ],
  {
    output: schema,
  },
);

console.log("구조화된 출력:", response.object);

도구와 함께 사용

구조화된 출력을 도구 호출과 함께 생성해야 하는 경우, output 대신 experimental_output 속성을 사용해야 합니다:

Copyconst schema = z.object({
  summary: z.string(),
  keywords: z.array(z.string()),
});

const response = await myAgent.generate(
  [
    {
      role: "user",
      content:
        "이 리포지토리를 분석하고 요약과 키워드를 제공해주세요...",
    },
  ],
  {
    // 구조화된 출력과 도구 호출을 모두 활성화하려면 experimental_output 사용
    experimental_output: schema,
  },
);

console.log("구조화된 출력:", response.object);

이를 통해 에이전트가 반환하는 구조화된 데이터에 대한 강력한 타이핑과 검증을 할 수 있습니다.

4. 멀티스텝 도구 사용

에이전트는 도구로 강화될 수 있습니다. 도구는 텍스트 생성을 넘어 에이전트의 능력을 확장하는 함수입니다. 도구를 통해 에이전트는 계산을 수행하고, 외부 시스템에 액세스하며, 데이터를 처리할 수 있습니다. 에이전트는 제공된 도구를 호출할지 여부를 결정할 뿐만 아니라, 해당 도구에 제공해야 할 매개변수도 결정합니다.

도구 생성 및 구성에 대한 자세한 가이드는 도구 추가 문서를 참조하세요. 아래는 알아야 할 중요한 사항들입니다.

maxSteps 사용

maxSteps 매개변수는 에이전트가 수행할 수 있는 순차적 LLM 호출의 최대 수를 제어합니다. 특히 도구 호출을 사용할 때 중요합니다. 기본값은 1로 설정되어 있어 잘못 구성된 도구로 인한 무한 루프를 방지합니다. 사용 사례에 따라 이 제한을 늘릴 수 있습니다:

Copyimport { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import * as mathjs from "mathjs";
import { z } from "zod";

export const myAgent = new Agent({
  name: "My Agent",
  instructions: "당신은 수학 문제를 해결할 수 있는 도움이 되는 어시스턴트입니다.",
  model: openai("gpt-4o-mini"),
  tools: {
    calculate: {
      description: "수학적 표현식을 위한 계산기",
      schema: z.object({ expression: z.string() }),
      execute: async ({ expression }) => mathjs.evaluate(expression),
    },
  },
});

const response = await myAgent.generate(
  [
    {
      role: "user",
      content:
        "택시 기사가 시간당 41달러를 벌고 하루에 12시간 일한다면, 하루에 얼마를 벌까요?",
    },
  ],
  {
    maxSteps: 5, // 최대 5단계의 도구 사용 허용
  },
);

onStepFinish로 진행 상황 스트리밍

onStepFinish 콜백을 사용하여 멀티스텝 작업의 진행 상황을 모니터링할 수 있습니다. 이는 디버깅이나 사용자에게 진행 상황을 제공하는 데 유용합니다.

onStepFinish는 구조화된 출력 없이 스트리밍하거나 텍스트를 생성할 때만 사용할 수 있습니다.

Copyconst response = await myAgent.generate(
  [{ role: "user", content: "택시 기사의 일일 수입을 계산해주세요." }],
  {
    maxSteps: 5,
    onStepFinish: ({ text, toolCalls, toolResults }) => {
      console.log("단계 완료:", { text, toolCalls, toolResults });
    },
  },
);

onFinish로 완료 감지

onFinish 콜백은 스트리밍 응답에서 사용할 수 있으며 완료된 상호작용에 대한 상세 정보를 제공합니다. LLM이 응답 생성을 완료하고 모든 도구 실행이 완료된 후에 호출됩니다.

이 콜백은 최종 응답 텍스트, 실행 단계, 토큰 사용량 통계 및 모니터링과 로깅에 유용할 수 있는 기타 메타데이터를 받습니다:

Copyconst stream = await myAgent.stream(
  [{ role: "user", content: "택시 기사의 일일 수입을 계산해주세요." }],
  {
    maxSteps: 5,
    onFinish: ({
      steps,
      text,
      finishReason, // 'complete', 'length', 'tool' 등
      usage, // 토큰 사용량 통계
      reasoningDetails, // 에이전트 결정에 대한 추가 컨텍스트
    }) => {
      console.log("스트림 완료:", {
        totalSteps: steps.length,
        finishReason,
        usage,
      });
    },
  },
);

5. 로컬에서 에이전트 테스트하기

Mastra는 에이전트를 API 뒤에서 실행하는 CLI 명령 mastra dev를 제공합니다. 기본적으로 이는 src/mastra/agents 디렉토리의 파일에서 내보낸 에이전트를 찾습니다. 에이전트 테스트를 위한 엔드포인트(예: http://localhost:4111/api/agents/myAgent/generate)를 생성하고 에이전트와 대화하고 추적을 볼 수 있는 시각적 플레이그라운드를 제공합니다.

자세한 내용은 로컬 개발 플레이그라운드 문서를 참조하세요.

다음 단계

• 에이전트 메모리 가이드에서 에이전트 메모리에 대해 알아보세요.

• 동적 에이전트 가이드에서 동적 에이전트 구성에 대해 알아보세요.

• 에이전트 도구 및 MCP 가이드에서 에이전트 도구에 대해 알아보세요.

• 셰프 미셸 예제에서 실제 에이전트를 확인해보세요.실용적인 활용 예시

고객 지원 에이전트

Copyexport const supportAgent = new Agent({
  name: "고객 지원 에이전트",
  instructions: `
    당신은 친절하고 전문적인 고객 지원 담당자입니다.
    - 고객의 문의를 정확히 이해하고 도움을 제공하세요
    - 필요시 관련 도구를 사용하여 정보를 조회하세요
    - 항상 정중하고 해결 지향적인 톤을 유지하세요
  `,
  model: openai("gpt-4o-mini"),
  tools: {
    searchKnowledgeBase,
    createTicket,
    checkOrderStatus,
  },
});

콘텐츠 작성 에이전트

Copyexport const writerAgent = new Agent({
  name: "콘텐츠 작성자",
  instructions: `
    당신은 창의적이고 전문적인 콘텐츠 작성자입니다.
    - 주제에 맞는 매력적인 글을 작성하세요
    - SEO 최적화를 고려하여 작성하세요
    - 한국어 문법과 맞춤법을 정확히 사용하세요
  `,
  model: openai("gpt-4o"),
  tools: {
    researchTopic,
    checkSEO,
    generateImages,
  },
});

2025년 7월 26일 기준 번역
by dongne.lab@gmail.com