Agent：让模型能决定下一步

问题场景

普通 LLM 调用像一次函数调用：输入 prompt，输出文本。Agent 多了一层循环：它可以根据目标判断是否需要调用工具、读取记忆、继续追问或输出最终答案。

Mastra 官方文档把 Agent 定义为使用 LLM 和工具解决开放式任务的组件：任务步骤不一定预先知道，Agent 会决定调用哪些工具、循环多少次以及何时停止。

核心原理

sequenceDiagram
  participant U as User
  participant A as Agent
  participant M as Model
  participant T as Tools
  participant S as State/Memory

  U->>A: 目标和上下文
  A->>S: 读取历史和偏好
  A->>M: instructions + message + memory
  M-->>A: 回答或工具调用请求
  alt 需要工具
    A->>T: 执行工具
    T-->>A: 工具结果
    A->>M: 带工具结果继续推理
  else 可以回答
    A-->>U: 最终回答
  end
  A->>S: 写入消息和结果

Agent 的关键不是“模型变聪明了”，而是你把模型放进一个受控运行时：

• instructions 规定角色、边界和输出要求。
• model 规定本次推理由哪个供应商和模型承担。
• tools 让模型能请求外部能力。
• memory 让多轮对话能延续。
• workflow 让确定性步骤不要交给模型自由发挥。
• observability 让你知道每一步发生了什么。

Mastra 映射

官方 Agent 快速示例的关键形态是：

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

export const studyAgent = new Agent({
  id: 'study-agent',
  name: 'Study Agent',
  instructions: '你是一个课程学习助手。',
  model: 'openai/gpt-5.4',
})

注册到 Mastra 实例：

import { Mastra } from '@mastra/core'
import { studyAgent } from './agents/study-agent'

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

什么时候用 Agent

适合 Agent	不适合只用 Agent
用户目标开放，比如“帮我制定学习计划”	步骤固定，比如“先解析 CSV，再写入数据库”
需要动态选择工具	必须严格按审批流程执行
需要多轮对话	单次确定性转换
容许模型做少量判断	每一步都要求可审计和可重放

Vibe coding 提示词

请帮我新增一个 Mastra Agent。
要求：
- id 使用 study-agent。
- instructions 要明确说明它只能基于工具返回的课程资料回答。
- model 使用 process.env.MASTRA_MODEL ?? 'openai/gpt-5.4'。
- 不要在 Agent 里写业务查询逻辑，查询逻辑放到 tool。
- 最后告诉我如何在 Mastra Studio 验证。

验证方式

最小验证不是“代码看起来对”，而是：

npm run typecheck
npm run final:dev

进入 Studio 后确认：

• 能看到 studyAgent。
• instructions 符合预期。
• 发送问题时能触发工具，或者在无密钥模式下使用离线脚本验证同等链路。

常见错误

错误	表现	处理
instructions 太空泛	回答跑题	写清职责、禁止事项和输出格式
把工具逻辑写进 Agent	后续无法复用和测试	拆到 tools/
Agent 没注册	Studio 看不到	检查 src/mastra/index.ts
model 写死	换模型麻烦	用环境变量做默认值

下一步

Agent 能运行后，不要急着堆工具。先读 模型与路由，把模型选择、fallback、embedding 和成本验证设计清楚。