Agent 네트워크

:::warning[사용되지 않음]

Agent 네트워크는 더 이상 사용되지 않으며 향후 주요 릴리스에서 제거될 예정입니다. 이제 agent.stream() 또는 agent.generate()를 사용하는 감독자 Agent가 권장되는 접근 방식입니다. 더 나은 제어, 더 단순한 API, 더 쉬운 디버깅과 함께 동일한 다중 Agent 조정 기능을 제공합니다. 업그레이드하려면 마이그레이션 가이드를 참조하세요. :::

라우팅 Agent는 LLM을 사용하여 요청을 해석하고 어떤 기본 요소(하위 Agent, Workflow, Tool)를 어떤 순서로 어떤 데이터와 함께 호출할지 결정합니다.

Agent 네트워크 생성

agents, workflows, tools를 사용하여 라우팅 Agent를 구성합니다. .network()는 작업 기록을 저장하고 작업 완료 여부를 판단하는 데 Memory를 사용하므로 Memory가 필요합니다. 라우팅 Agent가 사용할 기본 요소를 결정할 수 있도록 각 기본 요소에는 명확한 description이 필요합니다. Workflow와 Tool의 경우 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',
    }),
  }),
})

노트

하위 Agent에는 Agent 인스턴스의 description이 필요합니다. Workflow와 Tool에는 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)

Tool 호출 승인 및 거부

기본 요소에 승인이 필요하면 스트림에서 agent-execution-approval 또는 tool-execution-approval 청크가 생성됩니다. 응답하려면 approveNetworkToolCall() 또는 declineNetworkToolCall()을 사용합니다. 네트워크 승인은 스냅샷을 사용하여 실행 상태를 캡처합니다. Mastra 인스턴스에서 storage provider가 활성화되어 있는지 확인하세요.

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()를 호출하면 스트림에서 일시 중지 청크(예: 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가 메시지 간에 일시 중지된 Tool을 추적하려면 Memory가 필요합니다.
• 같은 스레드: 후속 메시지는 동일한 thread 및 resource 식별자를 사용해야 합니다.
• 정의된 resumeSchema: 네트워크가 사용자 메시지에서 데이터를 추출할 수 있도록 Tool은 resumeSchema를 정의해야 합니다. | | 수동 (resumeNetwork) | 자동 (autoResumeSuspendedTools) | | - | - | - | | 적합한 용도 | 승인 버튼이 있는 사용자 지정 UI | 채팅 스타일 인터페이스 | | 제어 | 재개 시점과 데이터를 완전히 제어 | 네트워크가 사용자 메시지에서 데이터를 추출 | | 설정 | 일시 중지 청크를 처리하고 resumeNetwork 호출 | 플래그를 설정하고 Tool에 resumeSchema 정의 |

관련된

• 감독자 Agent
• 마이그레이션: .network()에서 감독자 Agent로