Agent.네트워크()

그만큼.network()방법을 사용하면 다중 Agent 협업 및 라우팅이 가능합니다. 이 메서드는 메시지와 선택적 실행 옵션을 허용합니다.

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

.network() primitive은 더 이상 사용되지 않으며 향후 메이저 릴리스에서 제거될 예정입니다. 대신 agent.stream() 또는 agent.generate()와 함께 supervisor Agent를 사용하세요. 업그레이드하려면 마이그레이션 가이드를 참고하세요. :::

사용예
사용예에 대한 직접 링크

import { Agent } from '@mastra/core/agent'
import { agent1, agent2 } from './agents'
import { workflow1 } from './workflows'
import { tool1, tool2 } from './tools'

const agent = new Agent({
  id: 'network-agent',
  name: 'Network Agent',
  instructions: 'You are a network agent that can help users with a variety of tasks.',
  model: 'openai/gpt-5.6-sol',
  agents: {
    agent1,
    agent2,
  },
  workflows: {
    workflow1,
  },
  tools: {
    tool1,
    tool2,
  },
})

await agent.network(`
  Find me the weather in Tokyo.
  Based on the weather, plan an activity for me.
`)

매개변수
매개변수에 대한 직접 링크

messages:

string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]

Agent에 전송할 메시지입니다. 단일 문자열, 문자열 배열 또는 구조화된 메시지 객체를 사용할 수 있습니다.

options?:

MultiPrimitiveExecutionOptions

네트워크 프로세스를 위한 선택적 구성입니다.

MultiPrimitiveExecutionOptions

maxSteps?:

number

실행 중 수행할 최대 단계 수입니다.

abortSignal?:

AbortSignal

네트워크 실행을 중단하는 신호입니다. 중단되면 네트워크가 라우팅을 멈추고 진행 중인 모든 subagent, Tool 또는 Workflow 실행을 취소하며 부분 결과를 Memory에 저장하지 않습니다.

onAbort?:

(event: { primitiveType: string; primitiveId: string; iteration: number }) => void | Promise<void>

네트워크가 중단될 때 실행되는 콜백입니다. 중단 시 실행 중이던 primitive의 유형과 ID가 포함된 이벤트를 받습니다.

memory?:

object

Memory 구성입니다. Memory를 관리할 때 권장되는 방식입니다.

object

thread:

string | { id: string; metadata?: Record<string, any>, title?: string }

대화 스레드로, 문자열 ID 또는 id와 선택적 metadata가 있는 객체입니다.

resource:

string

스레드와 연결된 사용자 또는 리소스의 식별자입니다.

options?:

MemoryConfig

메시지 기록 및 의미 기반 회상과 같은 Memory 동작 구성입니다.

tracingContext?:

TracingContext

자식 span을 생성하고 메타데이터를 추가하기 위한 Tracing 컨텍스트입니다. Mastra의 Tracing 시스템을 사용하면 자동으로 주입됩니다.

TracingContext

currentSpan?:

Span

자식 span을 생성하고 메타데이터를 추가하기 위한 현재 span입니다. 실행 중 사용자 지정 자식 span을 생성하거나 span 속성을 업데이트할 때 사용하세요.

tracingOptions?:

TracingOptions

Tracing 구성을 위한 옵션입니다.

TracingOptions

metadata?:

Record<string, any>

루트 Trace span에 추가할 메타데이터입니다. 사용자 ID, 세션 ID 또는 기능 플래그와 같은 사용자 지정 속성을 추가할 때 유용합니다.

requestContextKeys?:

string[]

이 Trace의 메타데이터로 추출할 추가 RequestContext 키입니다. 중첩된 값에 점 표기법(예: 'user.id')을 지원합니다.

traceId?:

string

이 실행에 사용할 Trace ID입니다(1~32자의 16진수). 제공하면 이 Trace가 지정된 Trace의 일부가 됩니다.

parentSpanId?:

string

이 실행에 사용할 부모 span ID입니다(1~16자의 16진수). 제공하면 루트 span이 이 span의 자식으로 생성됩니다.

tags?:

string[]

이 Trace에 적용할 태그입니다. Trace를 분류하고 필터링하기 위한 문자열 레이블입니다.

telemetry?:

TelemetrySettings

스트리밍 중 OTLP 텔레메트리 수집을 위한 설정입니다(Tracing 아님).

TelemetrySettings

isEnabled?:

boolean

텔레메트리를 활성화하거나 비활성화합니다. 실험 기능인 동안에는 기본적으로 비활성화됩니다.

recordInputs?:

boolean

입력 기록을 활성화하거나 비활성화합니다. 기본적으로 활성화됩니다. 민감한 정보가 기록되지 않도록 입력 기록을 비활성화할 수 있습니다.

recordOutputs?:

boolean

출력 기록을 활성화하거나 비활성화합니다. 기본적으로 활성화됩니다. 민감한 정보가 기록되지 않도록 출력 기록을 비활성화할 수 있습니다.

functionId?:

string

이 함수의 식별자입니다. 텔레메트리 데이터를 함수별로 그룹화하는 데 사용됩니다.

modelSettings?:

CallSettings

Model-specific settings like temperature, maxOutputTokens, topP, etc. These settings control how the language model generates responses.

temperature?:

number

Controls randomness in generation (0-2). Higher values make output more random.

maxOutputTokens?:

number

Maximum number of tokens to generate in the response. Note: Use maxOutputTokens (not maxTokens) as per AI SDK v5 convention.

maxRetries?:

number

Maximum number of retry attempts for failed requests.

topP?:

number

Nucleus sampling parameter (0-1). Controls diversity of generated text.

topK?:

number

Top-k sampling parameter. Limits vocabulary to k most likely tokens.

presencePenalty?:

number

Penalty for token presence (-2 to 2). Reduces repetition.

frequencyPenalty?:

number

Penalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.

stopSequences?:

string[]

Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.

structuredOutput?:

StructuredOutputOptions

네트워크 결과에서 타입이 지정된 구조화 출력을 생성하기 위한 구성입니다.

StructuredOutputOptions

schema:

ZodSchema | JSONSchema7

출력을 검증할 스키마입니다. Zod 스키마 또는 JSON Schema를 사용할 수 있습니다.

model?:

MastraModelConfig

구조화 출력을 생성하는 데 사용할 Model입니다. 기본값은 Agent의 Model입니다.

instructions?:

string

구조화 출력을 생성하기 위한 사용자 지정 지침입니다.

runId?:

string

이 생성 실행의 고유 ID입니다. 추적 및 디버깅에 유용합니다.

requestContext?:

RequestContext

의존성 주입과 컨텍스트 정보를 위한 요청 컨텍스트입니다.

traceId?:

string

Tracing이 활성화되었을 때 이 실행과 연결되는 Trace ID입니다. 로그의 상관관계를 파악하고 실행 흐름을 디버깅할 때 사용하세요.

spanId?:

string

Tracing이 활성화되었을 때 이 실행과 연결되는 루트 span ID입니다. span 수준 조회 및 상관관계 분석에 사용하세요.

onStepFinish?:

(event: any) => Promise<void> | void

subagent 실행 내 각 LLM 단계 후에 실행되는 콜백입니다. 완료 이유와 토큰 사용량을 포함한 단계 세부 정보를 받습니다.

onError?:

({ error }: { error: Error | string }) => Promise<void> | void

subagent 실행 중 오류가 발생할 때 실행되는 콜백입니다.

보고
보고에 대한 직접 링크

stream:

MastraAgentNetworkStream<NetworkChunkType>

추가적인 네트워크별 속성으로 ReadableStream<NetworkChunkType>을 확장한 사용자 지정 스트림입니다.

status:

Promise<RunStatus>

현재 Workflow 실행 상태로 이행되는 Promise입니다.

result:

Promise<WorkflowResult<TState, TOutput, TSteps>>

최종 Workflow 결과로 이행되는 Promise입니다.

usage:

Promise<{ promptTokens: number; completionTokens: number; totalTokens: number }>

토큰 사용량 통계로 이행되는 Promise입니다.

object:

Promise<OUTPUT | undefined>

구조화 출력 객체로 이행되는 Promise입니다. structuredOutput 옵션이 제공된 경우에만 사용할 수 있습니다. 스키마가 지정되지 않으면 undefined로 이행됩니다.

objectStream:

ReadableStream<Partial<OUTPUT>>

구조화 출력 생성 중의 부분 객체 스트림입니다. 생성되는 부분 결과를 스트리밍할 때 유용합니다.

구조화된 출력
구조화된 출력에 대한 직접 링크

네트워크에서 타입이 지정되고 검증된 결과가 필요하면 structuredOutput 옵션을 사용하세요. 네트워크는 작업 완료 후 스키마와 일치하는 응답을 생성합니다.

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 agent.network('Research AI trends and summarize', {
  structuredOutput: {
    schema: resultSchema,
  },
})

// Consume the stream
for await (const chunk of stream) {
  // Handle streaming events
}

// Get the typed result
const result = await stream.object
// result is typed as { summary: string; recommendations: string[]; confidence: number }
console.log(result?.summary)
console.log(result?.recommendations)

부분 개체 스트리밍
부분 개체 스트리밍에 대한 직접 링크

생성되는 부분 객체를 스트리밍할 수도 있습니다.

const stream = await agent.network('Analyze data', {
  structuredOutput: { schema: resultSchema },
})

// Stream partial objects
for await (const partial of stream.objectStream) {
  console.log('Partial result:', partial)
}

// Get final result
const final = await stream.object

청크 유형
청크 유형에 대한 직접 링크

구조화된 출력을 사용하는 경우 추가 청크 유형이 방출됩니다.

network-object: 스트리밍 중에 부분 개체와 함께 방출됩니다.
network-object-result: 최종 구조화된 객체와 함께 방출됨

네트워크 중단
네트워크 중단에 대한 직접 링크

실행 중인 네트워크를 취소하려면 abortSignal을 사용하세요. 중단되면 네트워크가 라우팅을 멈추고 진행 중인 모든 subagent, Tool 또는 Workflow 실행을 취소하며 부분 결과를 Memory에 저장하지 않습니다.

const controller = new AbortController()

// Abort after 30 seconds
setTimeout(() => controller.abort(), 30_000)

const stream = await agent.network('Research this topic thoroughly', {
  abortSignal: controller.signal,
  onAbort: ({ primitiveType, primitiveId, iteration }) => {
    console.log(`Aborted ${primitiveType} "${primitiveId}" at iteration ${iteration}`)
  },
})

for await (const chunk of stream) {
  if (
    chunk.type === 'routing-agent-abort' ||
    chunk.type === 'agent-execution-abort' ||
    chunk.type === 'tool-execution-abort' ||
    chunk.type === 'workflow-execution-abort'
  ) {
    console.log('Network was aborted')
  }
}

사용예사용예에 대한 직접 링크

매개변수매개변수에 대한 직접 링크

messages:

options?:

maxSteps?:

abortSignal?:

onAbort?:

memory?:

thread:

resource:

options?:

tracingContext?:

currentSpan?:

tracingOptions?:

metadata?:

requestContextKeys?:

traceId?:

parentSpanId?:

tags?:

telemetry?:

isEnabled?:

recordInputs?:

recordOutputs?:

functionId?:

modelSettings?:

temperature?:

maxOutputTokens?:

maxRetries?:

topP?:

topK?:

presencePenalty?:

frequencyPenalty?:

stopSequences?:

structuredOutput?:

schema:

model?:

instructions?:

runId?:

requestContext?:

traceId?:

spanId?:

onStepFinish?:

onError?:

보고보고에 대한 직접 링크

stream:

status:

result:

usage:

object:

objectStream:

구조화된 출력구조화된 출력에 대한 직접 링크

부분 개체 스트리밍부분 개체 스트리밍에 대한 직접 링크

청크 유형청크 유형에 대한 직접 링크

네트워크 중단네트워크 중단에 대한 직접 링크

사용예
사용예에 대한 직접 링크

매개변수
매개변수에 대한 직접 링크

보고
보고에 대한 직접 링크

구조화된 출력
구조화된 출력에 대한 직접 링크

부분 개체 스트리밍
부분 개체 스트리밍에 대한 직접 링크

청크 유형
청크 유형에 대한 직접 링크

네트워크 중단
네트워크 중단에 대한 직접 링크