도구 고급 사용법

이 페이지는 Mastra에서 도구를 사용하는 것과 관련된 더 고급 기법과 기능들을 다룹니다.

중단 신호(Abort Signals)

generate() 또는 stream()을 사용하여 에이전트 상호작용을 시작할 때 AbortSignal을 제공할 수 있습니다. Mastra는 해당 상호작용 중에 발생하는 모든 도구 실행에 이 신호를 자동으로 전달합니다.

이는 상위 에이전트 호출이 중단될 경우 네트워크 요청이나 집약적인 계산과 같은 도구 내의 장기 실행 작업을 취소할 수 있게 해줍니다.

도구의 execute 함수의 두 번째 매개변수에서 abortSignal에 액세스할 수 있습니다.

Copyimport { createTool } from "@mastra/core/tools";
import { z } from "zod";

export const longRunningTool = createTool({
  id: "long-computation",
  description: "잠재적으로 긴 계산을 수행합니다",
  inputSchema: z.object({ /* ... */ }),
  execute: async ({ context }, { abortSignal }) => {
    // 예제: fetch에 신호 전달
    const response = await fetch("https://api.example.com/data", {
      signal: abortSignal, // 여기서 신호 전달
    });

    if (abortSignal?.aborted) {
      console.log("도구 실행이 중단되었습니다.");
      throw new Error("중단됨");
    }

    // 예제: 루프 중 신호 확인
    for (let i = 0; i < 1000000; i++) {
      if (abortSignal?.aborted) {
        console.log("루프 중 도구 실행이 중단되었습니다.");
        throw new Error("중단됨");
      }
      // ... 계산 단계 수행 ...
    }

    const data = await response.json();
    return { result: data };
  },
});

이를 사용하려면 에이전트를 호출할 때 AbortController의 신호를 제공하세요:

Copyimport { Agent } from "@mastra/core/agent";
// 'agent'는 longRunningTool이 구성된 Agent 인스턴스라고 가정

const controller = new AbortController();

// 에이전트 호출 시작
const promise = agent.generate("긴 계산을 수행하세요.", {
  abortSignal: controller.signal,
});

// 나중에 필요한 경우:
// controller.abort();

try {
  const result = await promise;
  console.log(result.text);
} catch (error) {
  if (error.name === "AbortError") {
    console.log("에이전트 생성이 중단되었습니다.");
  } else {
    console.error("오류가 발생했습니다:", error);
  }
}

AI SDK 도구 형식

Mastra는 Vercel AI SDK(ai 패키지)에서 사용하는 도구 형식과의 호환성을 유지합니다. ai 패키지의 tool 함수를 사용하여 도구를 정의하고, Mastra의 createTool로 생성된 도구와 함께 Mastra 에이전트 내에서 직접 사용할 수 있습니다.

먼저 ai 패키지가 설치되어 있는지 확인하세요:

Copynpm install ai

다음은 Vercel AI SDK 형식을 사용하여 정의된 도구의 예제입니다:

src/mastra/tools/vercelWeatherTool.ts:

Copyimport { tool } from "ai";
import { z } from "zod";

export const vercelWeatherTool = tool({
  description: "Vercel AI SDK 형식을 사용하여 현재 날씨를 가져옵니다",
  parameters: z.object({
    city: z.string().describe("날씨를 확인할 도시"),
  }),
  execute: async ({ city }) => {
    console.log(`${city}의 날씨를 가져오는 중 (Vercel 형식 도구)`);
    // 실제 API 호출로 교체
    const data = await fetch(`https://api.example.com/weather?city=${city}`);
    return data.json();
  },
});

그 다음 이 도구를 다른 도구와 마찬가지로 Mastra 에이전트에 추가할 수 있습니다:

src/mastra/agents/mixedToolsAgent.ts:

Copyimport { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import { vercelWeatherTool } from "../tools/vercelWeatherTool"; // Vercel AI SDK 도구
import { mastraTool } from "../tools/mastraTool"; // Mastra createTool 도구

export const mixedToolsAgent = new Agent({
  name: "Mixed Tools Agent",
  instructions: "다양한 형식으로 정의된 도구를 사용할 수 있습니다.",
  model: openai("gpt-4o-mini"),
  tools: {
    weatherVercel: vercelWeatherTool,
    someMastraTool: mastraTool,
  },
});

Mastra는 이 두 형식을 모두 지원하므로 필요에 따라 혼합하여 사용할 수 있습니다.

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