Agent networks

已弃用

Agent networks 已弃用，并将在未来某个主版本中移除。请改用基于 agent.stream() 或 agent.generate() 的监督者 agents。监督者 agents 通过更简单的 API 提供相同的多 Agent 协调能力，并改进了控制和调试体验。

升级请参阅迁移指南。

路由 Agent 使用 LLM 解释请求，并决定调用哪些原语（子 Agents、workflows 或工具）、以什么顺序调用以及传入什么数据。

创建 Agent 网络

使用 agents、workflows 和 tools 配置路由 Agent。Memory 是必需的，因为 .network() 会用它存储任务历史并判断任务何时完成。

每个原语都需要清晰的 description，以便路由 Agent 决定使用哪个。对于 workflows 和工具，inputSchema 和 outputSchema 也有助于路由器确定正确的输入。

src/mastra/agents/routing-agent.ts

import { Agent } from '@mastra/core/agent'
import { Memory } from '@mastra/memory'
import { LibSQLStore } from '@mastra/libsql'

import { researchAgent } from './research-agent'
import { writingAgent } from './writing-agent'
import { cityWorkflow } from '../workflows/city-workflow'
import { weatherTool } from '../tools/weather-tool'

export const routingAgent = new Agent({
  id: 'routing-agent',
  name: 'Routing Agent',
  instructions: `
    You are a network of writers and researchers. The user will ask you to research a topic. Always respond with a complete report—no bullet points. Write in full paragraphs, like a blog post. Do not answer with incomplete or uncertain information.`,
  model: 'openai/gpt-5.6-sol',
  agents: {
    researchAgent,
    writingAgent,
  },
  workflows: {
    cityWorkflow,
  },
  tools: {
    weatherTool,
  },
  memory: new Memory({
    storage: new LibSQLStore({
      id: 'mastra-storage',
      url: 'file:../mastra.db',
    }),
  }),
})

备注

子 Agents 需要在 Agent 实例上提供 description。Workflows 和工具需要在 createWorkflow() 或 createTool() 上提供 description 以及 inputSchema 和 outputSchema。

调用网络

使用用户消息调用 .network()。该方法返回一个可迭代的事件流。

const result = await routingAgent.network('Tell me three cool ways to use Mastra')

for await (const chunk of result) {
  console.log(chunk.type)
  if (chunk.type === 'network-execution-event-step-finish') {
    console.log(chunk.payload.result)
  }
}

结构化输出

传入 structuredOutput 以获得带类型、经过校验的结果。使用 objectStream 获取生成过程中的部分对象。

import { z } from 'zod'

const resultSchema = z.object({
  summary: z.string().describe('A brief summary of the findings'),
  recommendations: z.array(z.string()).describe('List of recommendations'),
  confidence: z.number().min(0).max(1).describe('Confidence score'),
})

const stream = await routingAgent.network('Research AI trends', {
  structuredOutput: { schema: resultSchema },
})

for await (const partial of stream.objectStream) {
  console.log('Building result:', partial)
}

const final = await stream.object
console.log(final?.summary)

批准和拒绝工具调用

当原语需要审批时，流会发出 agent-execution-approval 或 tool-execution-approval chunk。使用 approveNetworkToolCall() 或 declineNetworkToolCall() 进行响应。

网络审批使用快照捕获执行状态。请确保在 Mastra 实例中启用了存储提供商。

src/approve-network.ts

const stream = await routingAgent.network('Perform some sensitive action', {
  memory: {
    thread: 'user-123',
    resource: 'my-app',
  },
})

for await (const chunk of stream) {
  if (chunk.type === 'agent-execution-approval' || chunk.type === 'tool-execution-approval') {
    // Approve
    const approvedStream = await routingAgent.approveNetworkToolCall(chunk.payload.toolCallId, {
      runId: stream.runId,
      memory: { thread: 'user-123', resource: 'my-app' },
    })

    for await (const c of approvedStream) {
      if (c.type === 'network-execution-event-step-finish') {
        console.log(c.payload.result)
      }
    }
  }
}

若要拒绝，请使用相同参数调用 declineNetworkToolCall()。

挂起与恢复

当原语调用 suspend() 时，流会发出挂起 chunk（例如 tool-execution-suspended）。使用 resumeNetwork() 提供请求的数据并继续执行。

src/resume-network.ts

const stream = await routingAgent.network('Delete the old records', {
  memory: { thread: 'user-123', resource: 'my-app' },
})

for await (const chunk of stream) {
  if (chunk.type === 'workflow-execution-suspended') {
    console.log(chunk.payload.suspendPayload)
  }
}

// Resume with user confirmation
const resumedStream = await routingAgent.resumeNetwork(
  { confirmed: true },
  {
    runId: stream.runId,
    memory: { thread: 'user-123', resource: 'my-app' },
  },
)

for await (const chunk of resumedStream) {
  if (chunk.type === 'network-execution-event-step-finish') {
    console.log(chunk.payload.result)
  }
}

自动恢复

将 autoResumeSuspendedTools 设为 true，网络会根据用户的下一条消息恢复被挂起的原语。这会形成对话式流程，让用户自然地提供所需信息。

const stream = await routingAgent.network('Delete the old records', {
  autoResumeSuspendedTools: true,
  memory: { thread: 'user-123', resource: 'my-app' },
})

自动恢复的要求：

• 已配置 memory：Agent 需要 memory 才能跨消息跟踪被挂起的工具。
• 同一线程：后续消息必须使用相同的 thread 和 resource 标识符。
• 定义了 resumeSchema：工具必须定义 resumeSchema，以便网络从用户消息中提取数据。

	手动（resumeNetwork）	自动（autoResumeSuspendedTools）
最适合	带审批按钮的自定义 UI	聊天式界面
控制	完全控制恢复时机和数据	网络从用户消息中提取数据
设置	处理挂起 chunks，调用 resumeNetwork	设置标志，在工具上定义 resumeSchema

相关内容

• 监督者 agents
• 迁移：.network() 到监督者 agents