使用工具

🌐 Using Tools

工具是代理可以执行的功能，用于完成特定任务或获取外部信息。它们扩展了代理的能力，不仅限于简单的文本生成，还可以与 API、数据库或其他系统进行交互。

🌐 Tools are functions that agents can execute to perform specific tasks or access external information. They extend an agent's capabilities beyond simple text generation, allowing interaction with APIs, databases, or other systems.

每个工具通常定义：

🌐 Each tool typically defines:

• 输入: 工具运行所需的信息（用 inputSchema 定义，通常使用 Zod）。
• 输出: 工具返回的数据结构（用 outputSchema 定义）。
• 执行逻辑： 执行工具操作的代码。
• 描述： 帮助代理了解该工具的功能以及何时使用的文本。

创建工具

🌐 Creating Tools

在 Mastra 中，你可以使用 @mastra/core/tools 包中的 createTool 函数来创建工具。

🌐 In Mastra, you create tools using the createTool function from the @mastra/core/tools package.

src/mastra/tools/weatherInfo.ts

import { 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 (inputData) => {
    console.log("Using tool to fetch weather information for", inputData.city);
    return await getWeatherInfo(inputData.city);
  },
});

这个例子定义了一个 weatherTool，它有一个用于城市的输入模式，一个用于天气数据的输出模式，以及一个包含该工具逻辑的 execute 函数。

🌐 This example defines a weatherTool with an input schema for the city, an output schema for the weather data, and an execute function that contains the tool's logic.

在创建工具时，保持工具描述简洁，并专注于工具 能做什么 以及 何时使用，强调其主要使用场景。技术细节应放在参数模式中，指导代理如何正确使用工具，并使用描述性名称、清晰的描述及默认值说明。

🌐 When creating tools, keep tool descriptions simple and focused on what the tool does and when to use it, emphasizing its primary use case. Technical details belong in the parameter schemas, guiding the agent on how to use the tool correctly with descriptive names, clear descriptions, and explanations of default values.

向代理添加工具

🌐 Adding Tools to an Agent

要让代理可以使用工具，你需要在代理的定义中配置这些工具。在代理的系统提示中提及可用工具及其一般用途，也可以改善工具的使用。有关详细步骤和示例，请参阅《使用工具与代理》指南。

🌐 To make tools available to an agent, you configure them in the agent's definition. Mentioning available tools and their general purpose in the agent's system prompt can also improve tool usage. For detailed steps and examples, see the guide on Using Tools with Agents.

使用 RequestContext

🌐 Using RequestContext

使用 RequestContext 来访问特定请求的值。这使你可以根据请求的上下文有条件地调整行为。

🌐 Use RequestContext to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.

src/mastra/tools/test-tool.ts

export type UserTier = {
  "user-tier": "enterprise" | "pro";
};

const advancedTools = () => {};

const baseTools = () => {};

export const testTool = createTool({
  execute: async (inputData, context) => {
    const userTier = context?.requestContext?.get("user-tier") as UserTier["user-tier"];

    return userTier === "enterprise" ? advancedTools : baseTools;
  },
});

info

请访问 Request Context 以获取更多信息。

🌐 Visit Request Context for more information.

使用 Studio 进行测试

🌐 Testing with Studio

使用 Studio 测试不同输入的工具，检查执行结果，并验证工具行为。

🌐 Use Studio to test tools with different inputs, inspect execution results, and verify tool behavior.