도구(Tools) 개요

도구(Tools)는 에이전트(Agents)가 특정 작업을 수행하거나 외부 정보에 접근하기 위해 실행할 수 있는 함수입니다. 이들은 에이전트의 기능을 단순한 텍스트 생성 이상으로 확장하여, API, 데이터베이스 또는 기타 시스템과의 상호작용을 가능하게 합니다.

각 도구는 일반적으로 다음을 정의해야 합니다:

• 입력(Inputs): 도구가 실행되기 위해 필요한 정보 (inputSchema로 정의되며, zod가 사용되기도 함.)

• 출력(Outputs): 도구가 반환하는 데이터의 구조 (outputSchema로 정의됨.)

• 실행 로직(Execution Logic): 도구의 동작을 수행하는 코드

• 설명(Description): 에이전트가 도구의 기능과 사용 시점을 이해하는 데 도움이 되는 텍스트.

도구(Tool) 생성하기

Mastra에서는 @mastra/core/tools 패키지의 createTool 함수를 사용하여 도구를 생성할 수 있습니다.

src/mastra/tools/weatherInfo.ts:

Copyimport { createTool } from "@mastra/core/tools";
import { z } from "zod";
 
const getWeatherInfo = async (city: string) => {
  // Replace with an actual API call to a weather service
  console.log(`Fetching weather for ${city}...`);
  // Example data structure
  return { temperature: 20, conditions: "Sunny" };
};
 
export const weatherTool = createTool({
  id: "Get Weather Information",
  description: `Fetches the current weather information for a given city`,
  inputSchema: z.object({
    city: z.string().describe("City name"),
  }),
  outputSchema: z.object({
    temperature: z.number(),
    conditions: z.string(),
  }),
  execute: async ({ context: { city } }) => {
    console.log("Using tool to fetch weather information for", city);
    return await getWeatherInfo(city);
  },
});

이 예제는 도시에 대한 입력 스키마, 날씨 데이터에 대한 출력 스키마, 그리고 도구의 로직을 포함하는 execute함수가 있는 weatherTool을 정의합니다.

도구를 생성할 때는, 도구 설명을 간단하게 하고 도구가 무엇을 하는지와 언제 사용해야 하는지에 초점을 맞춰 주요 사용 사례를 강조하세요. 기술적인 세부사항은 매개변수 스키마에 포함되어야 하며, 설명적인 이름, 명확한 설명, 그리고 기본값에 대한 설명을 통해 에이전트가 도구를 올바르게 사용하는 방법을 안내해야 합니다.

에이전트에 도구 추가하기

에이전트가 도구를 사용할 수 있도록 하려면 에이전트 정의에서 도구들을 설정합니다. 에이전트의 시스템 프롬프트(system prompt)에 사용 가능한 도구와 그 일반적인 목적을 언급하는 것으로 도구 사용성을 개선할 수 있습니다. 자세한 사용 방법과 예제는 에이전트에 도구 및 MCP 사용하기 가이드를 참조하세요.

도구 스키마를 위한 호환성 레이어(Compatibility Layer)

각기 다른 모델들은 스키마를 서로 다르게 해석합니다. 일부 모델은 특정 스키마 속성이 전달될 때 오류를 발생시키고, 일부 모델은 특정 스키마 속성을 무시하지만 오류를 발생시키지는 않습니다. Mastra는 도구 스키마를 위한 호환성 레이어를 추가하여, 서로 다른 모델 제공업체에서도 도구가 일관되게 작동하고 스키마 제약사항이 준수되도록 보장합니다.

이 레이어를 적용하는 일부 제공업체는 다음과 같습니다:

• Google Gemini & Anthropic: 지원되지 않는 스키마 속성을 제거하고 관련 제약사항을 도구 설명에 추가합니다.

• OpenAI(추론 모델 포함): 무시되거나 지원되지 않는 스키마 필드를 제거하거나 조정하고, 에이전트 가이드를 위해 설명에 지시사항을 추가합니다.

• Deepseek & Meta: 스키마 정렬과 도구 사용성을 보장하기 위해 유사한 호환성 로직을 적용합니다.

이 접근 방식은 커스텀 도구와 MCP 도구 모두에 대해 도구 사용을 더욱 안정적이고 모델에 구애받지 않게 만듭니다.

---

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