Agent 类

🌐 Agent Class

Agent 类是 Mastra 中创建 AI 代理的基础。它提供了生成响应、流式交互以及处理语音功能的方法。

🌐 The Agent class is the foundation for creating AI agents in Mastra. It provides methods for generating responses, streaming interactions, and handling voice capabilities.

用法示例

🌐 Usage examples

基本字符串指令

🌐 Basic string instructions

src/mastra/agents/string-agent.ts

import { Agent } from "@mastra/core/agent";

// String instructions
export const agent = new Agent({
  id: "test-agent",
  name: "Test Agent",
  instructions: "You are a helpful assistant that provides concise answers.",
  model: "openai/gpt-5.1",
});

// System message object
export const agent2 = new Agent({
  id: "test-agent-2",
  name: "Test Agent 2",
  instructions: {
    role: "system",
    content: "You are an expert programmer",
  },
  model: "openai/gpt-5.1",
});

// Array of system messages
export const agent3 = new Agent({
  id: "test-agent-3",
  name: "Test Agent 3",
  instructions: [
    { role: "system", content: "You are a helpful assistant" },
    { role: "system", content: "You have expertise in TypeScript" },
  ],
  model: "openai/gpt-5.1",
});

单核系统消息

🌐 Single CoreSystemMessage

使用 CoreSystemMessage 格式访问其他属性，例如用于特定提供商配置的 providerOptions：

🌐 Use CoreSystemMessage format to access additional properties like providerOptions for provider-specific configurations:

src/mastra/agents/core-message-agent.ts

import { Agent } from "@mastra/core/agent";

export const agent = new Agent({
  id: "core-message-agent",
  name: "Core Message Agent",
  instructions: {
    role: "system",
    content:
      "You are a helpful assistant specialized in technical documentation.",
    providerOptions: {
      openai: {
        reasoningEffort: "low",
      },
    },
  },
  model: "openai/gpt-5.1",
});

多个核心系统消息

🌐 Multiple CoreSystemMessages

src/mastra/agents/multi-message-agent.ts

import { Agent } from "@mastra/core/agent";

// This could be customizable based on the user
const preferredTone = {
  role: "system",
  content: "Always maintain a professional and empathetic tone.",
};

export const agent = new Agent({
  id: "multi-message-agent",
  name: "Multi Message Agent",
  instructions: [
    { role: "system", content: "You are a customer service representative." },
    preferredTone,
    {
      role: "system",
      content: "Escalate complex issues to human agents when needed.",
      providerOptions: {
        anthropic: { cacheControl: { type: "ephemeral" } },
      },
    },
  ],
  model: "anthropic/claude-sonnet-4-20250514",
});

构造函数参数

🌐 Constructor parameters

id?:

string

Unique identifier for the agent. Defaults to `name` if not provided.

name:

string

Display name for the agent. Used as the identifier if `id` is not provided.

description?:

string

Optional description of the agent's purpose and capabilities.

instructions:

SystemMessage | ({ requestContext: RequestContext }) => SystemMessage | Promise<SystemMessage>

Instructions that guide the agent's behavior. Can be a string, array of strings, system message object, array of system messages, or a function that returns any of these types dynamically. SystemMessage types: string | string[] | CoreSystemMessage | CoreSystemMessage[] | SystemModelMessage | SystemModelMessage[]

model:

MastraLanguageModel | ({ requestContext: RequestContext }) => MastraLanguageModel | Promise<MastraLanguageModel>

The language model used by the agent. Can be provided statically or resolved at runtime.

agents?:

Record<string, Agent> | ({ requestContext: RequestContext }) => Record<string, Agent> | Promise<Record<string, Agent>>

Sub-Agents that the agent can access. Can be provided statically or resolved dynamically.

tools?:

ToolsInput | ({ requestContext: RequestContext }) => ToolsInput | Promise<ToolsInput>

Tools that the agent can access. Can be provided statically or resolved dynamically.

workflows?:

Record<string, Workflow> | ({ requestContext: RequestContext }) => Record<string, Workflow> | Promise<Record<string, Workflow>>

Workflows that the agent can execute. Can be static or dynamically resolved.

defaultOptions?:

AgentExecutionOptions | ({ requestContext: RequestContext }) => AgentExecutionOptions | Promise<AgentExecutionOptions>

Default options used when calling `stream()` and `generate()`.

defaultGenerateOptionsLegacy?:

AgentGenerateOptions | ({ requestContext: RequestContext }) => AgentGenerateOptions | Promise<AgentGenerateOptions>

Default options used when calling `generateLegacy()`.

defaultStreamOptionsLegacy?:

AgentStreamOptions | ({ requestContext: RequestContext }) => AgentStreamOptions | Promise<AgentStreamOptions>

Default options used when calling `streamLegacy()`.

mastra?:

Mastra

Reference to the Mastra runtime instance (injected automatically).

scorers?:

MastraScorers | ({ requestContext: RequestContext }) => MastraScorers | Promise<MastraScorers>

Scoring configuration for runtime evaluation and telemetry. Can be static or dynamically provided.

memory?:

MastraMemory | ({ requestContext: RequestContext }) => MastraMemory | Promise<MastraMemory>

Memory module used for storing and retrieving stateful context.

voice?:

CompositeVoice

Voice settings for speech input and output.

inputProcessors?:

(Processor | ProcessorWorkflow)[] | ({ requestContext: RequestContext }) => (Processor | ProcessorWorkflow)[] | Promise<(Processor | ProcessorWorkflow)[]>

Input processors that can modify or validate messages before they are processed by the agent. Can be individual Processor objects or workflows created with `createWorkflow()` using ProcessorStepSchema.

outputProcessors?:

(Processor | ProcessorWorkflow)[] | ({ requestContext: RequestContext }) => (Processor | ProcessorWorkflow)[] | Promise<(Processor | ProcessorWorkflow)[]>

Output processors that can modify or validate messages from the agent before they are sent to the client. Can be individual Processor objects or workflows.

maxProcessorRetries?:

number

Maximum number of times a processor can request retrying the LLM step.

返回

🌐 Returns

agent:

Agent<TAgentId, TTools>

A new Agent instance with the specified configuration.

相关

🌐 Related

• 代理概览