Tools

tools()为 agent 提供连接到你的项目的提供方的现成 tools，例如用于 Linear 的 linear_list_issues 和 linear_create_issue。每次调用都会经过平台代理，代理会在转发请求之前添加连接的凭据。你无需实现这些 tools，也无需在应用中存储提供方凭据。

开始之前，请遵循 Connect 设置配置项目并连接提供方。

向 agent 添加 tools

将 tools() 传递给 agent 的 tools 选项：

src/mastra/agents/ops.ts

import { Agent } from '@mastra/core/agent'
import { tools } from '@mastra/connect'

export const opsAgent = new Agent({
  id: 'ops',
  name: 'ops',
  instructions: 'You help the team track work in Linear and GitHub.',
  model: 'openai/gpt-5-mini',
  tools: tools(),
})

不传任何选项时，agent 会获得每个具有受支持 toolset 的已连接提供方的 tools。Resolver 无需重启即可获取连接变化。关于缓存、手动刷新以及向单个 agent 调用传递 tools，参见 resolver 参考。

一些提供方通过托管的 Model Context Protocol (MCP) 服务器提供 tools。你为这些提供方使用相同的 tools() API，但它们的 tool 名称是在运行时发现的，而不是包含在包中。

与你自己的 tools 组合

要让 agent 同时获得 Connect tools 和你自己定义的 tools，请在 tools 函数中展开 resolver 的结果。当 key 冲突时，你的 tools 优先：

src/mastra/agents/ops.ts

import { Agent } from '@mastra/core/agent'
import { tools } from '@mastra/connect'
import { weatherTool } from '../tools/weather'

const connectTools = tools()

export const opsAgent = new Agent({
  id: 'ops',
  name: 'ops',
  instructions: 'You help the team track work in Linear and GitHub.',
  model: 'openai/gpt-5-mini',
  tools: async ctx => ({ ...(await connectTools(ctx)), weatherTool }),
})

限制可用的 tools

使用 providers 让 agent 只获得所选提供方的 tools，而不是每个已连接账户的 tools：

tools({
  providers: ['linear', 'github'],
})

要限制 agent 可以执行的操作，请为每个提供方配置 tool keys 的允许列表：

tools({
  providers: {
    linear: { allowTools: ['linear_list_issues', 'linear_create_issue'] },
  },
})

在提供方 toolsets 参考中查找 tool keys。tools() 参考涵盖排除过滤器、通配符模式、共享策略和验证行为。

按请求过滤 tools

要按请求改变提供方选项，请向 tools() 传入回调而不是选项对象。回调接收请求上下文并返回该请求的选项：

src/mastra/agents/ops.ts

import { Agent } from '@mastra/core/agent'
import { tools } from '@mastra/connect'

export const opsAgent = new Agent({
  id: 'ops',
  name: 'ops',
  instructions: 'You help the team track work in Linear.',
  model: 'openai/gpt-5-mini',
  tools: tools(ctx => ({
    providers: {
      linear:
        ctx?.requestContext?.get('role') === 'viewer'
          ? { allowTools: ['linear_list_*'] }
          : { requireApproval: ['linear_delete_*'] },
    },
  })),
})

此示例为 viewers 仅提供 Linear 读取 tools，并为其他角色将删除操作置于审批之后。请在受信任的服务器端代码中根据已认证用户设置角色。Resolver 会为每个不同的选项值缓存一个 toolset，因此产生相同选项的请求会共享缓存的快照。请从小的、封闭的输入集（例如角色）派生选项，而不是从无界的按请求数据派生。

要改为对解析后的 tool 记录进行后处理（例如，基于 tool keys 之外的内容进行过滤），请将 resolver 提升并把它包装在 agent 的 tools 函数中：

src/mastra/agents/ops.ts

import { Agent } from '@mastra/core/agent'
import { tools } from '@mastra/connect'

const connectTools = tools({ providers: ['linear'] })
const viewerTools = new Set(['linear_list_issues'])

export const opsAgent = new Agent({
  id: 'ops',
  name: 'ops',
  instructions: 'You help the team track work in Linear.',
  model: 'openai/gpt-5-mini',
  tools: async ctx => {
    const all = await connectTools(ctx)

    if (ctx.requestContext?.get('role') === 'viewer') {
      return Object.fromEntries(Object.entries(all).filter(([key]) => viewerTools.has(key)))
    }
    return all
  },
})

对敏感 tools 要求审批

默认情况下，tools 在没有人审批的情况下运行。设置 requireApproval 以在选定的 tools 执行前暂停：

tools({
  providers: {
    linear: { requireApproval: ['linear_create_issue'] },
  },
})

传入 requireApproval: true 以要求对提供方的每个 tool 进行审批。审批适用于生成的 toolsets 和 MCP 提供方。遵循 human-in-the-loop 指南处理审批请求并恢复执行。

在连接之间选择

如果一个项目链接了两个 Slack workspaces，agent 会在每次调用时选择一个工作区。对于任何具有多个连接的提供方也是如此：toolset 会获得一个 <provider>__list_connections tool，其他每个 tool 都接受 connection_name 输入。为连接指定易于区分的名称。

要始终使用一个连接，请固定它：

tools({
  providers: {
    slack: { connectionId: 'c_yourconnectionid' },
  },
})