> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# Agent.네트워크()

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

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

`.network()` primitive은 더 이상 사용되지 않으며 향후 메이저 릴리스에서 제거될 예정입니다. 대신 `agent.stream()` 또는 `agent.generate()`와 함께 [supervisor Agent](https://mastra.zisheng.pro/ko/docs/capabilities/subagents)를 사용하세요. 업그레이드하려면 [마이그레이션 가이드](https://mastra.zisheng.pro/ko/guides/migrations/network-to-supervisor)를 참고하세요. :::

## 사용예

```typescript
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`): 네트워크 프로세스를 위한 선택적 구성입니다.

**options.maxSteps** (`number`): 실행 중 수행할 최대 단계 수입니다.

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

**options.onAbort** (`(event: { primitiveType: string; primitiveId: string; iteration: number }) => void | Promise<void>`): 네트워크가 중단될 때 실행되는 콜백입니다. 중단 시 실행 중이던 primitive의 유형과 ID가 포함된 이벤트를 받습니다.

**options.memory** (`object`): Memory 구성입니다. Memory를 관리할 때 권장되는 방식입니다.

**options.memory.thread** (`string | { id: string; metadata?: Record<string, any>, title?: string }`): 대화 스레드로, 문자열 ID 또는 id와 선택적 metadata가 있는 객체입니다.

**options.memory.resource** (`string`): 스레드와 연결된 사용자 또는 리소스의 식별자입니다.

**options.memory.options** (`MemoryConfig`): 메시지 기록 및 의미 기반 회상과 같은 Memory 동작 구성입니다.

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

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

**options.tracingOptions** (`TracingOptions`): Tracing 구성을 위한 옵션입니다.

**options.tracingOptions.metadata** (`Record<string, any>`): 루트 Trace span에 추가할 메타데이터입니다. 사용자 ID, 세션 ID 또는 기능 플래그와 같은 사용자 지정 속성을 추가할 때 유용합니다.

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

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

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

**options.tracingOptions.tags** (`string[]`): 이 Trace에 적용할 태그입니다. Trace를 분류하고 필터링하기 위한 문자열 레이블입니다.

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

**options.telemetry.isEnabled** (`boolean`): 텔레메트리를 활성화하거나 비활성화합니다. 실험 기능인 동안에는 기본적으로 비활성화됩니다.

**options.telemetry.recordInputs** (`boolean`): 입력 기록을 활성화하거나 비활성화합니다. 기본적으로 활성화됩니다. 민감한 정보가 기록되지 않도록 입력 기록을 비활성화할 수 있습니다.

**options.telemetry.recordOutputs** (`boolean`): 출력 기록을 활성화하거나 비활성화합니다. 기본적으로 활성화됩니다. 민감한 정보가 기록되지 않도록 출력 기록을 비활성화할 수 있습니다.

**options.telemetry.functionId** (`string`): 이 함수의 식별자입니다. 텔레메트리 데이터를 함수별로 그룹화하는 데 사용됩니다.

**options.modelSettings** (`CallSettings`): Model-specific settings like temperature, maxOutputTokens, topP, etc. These settings control how the language model generates responses.

**options.modelSettings.temperature** (`number`): Controls randomness in generation (0-2). Higher values make output more random.

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

**options.modelSettings.maxRetries** (`number`): Maximum number of retry attempts for failed requests.

**options.modelSettings.topP** (`number`): Nucleus sampling parameter (0-1). Controls diversity of generated text.

**options.modelSettings.topK** (`number`): Top-k sampling parameter. Limits vocabulary to k most likely tokens.

**options.modelSettings.presencePenalty** (`number`): Penalty for token presence (-2 to 2). Reduces repetition.

**options.modelSettings.frequencyPenalty** (`number`): Penalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.

**options.modelSettings.stopSequences** (`string[]`): Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.

**options.structuredOutput** (`StructuredOutputOptions`): 네트워크 결과에서 타입이 지정된 구조화 출력을 생성하기 위한 구성입니다.

**options.structuredOutput.schema** (`ZodSchema | JSONSchema7`): 출력을 검증할 스키마입니다. Zod 스키마 또는 JSON Schema를 사용할 수 있습니다.

**options.structuredOutput.model** (`MastraModelConfig`): 구조화 출력을 생성하는 데 사용할 Model입니다. 기본값은 Agent의 Model입니다.

**options.structuredOutput.instructions** (`string`): 구조화 출력을 생성하기 위한 사용자 지정 지침입니다.

**options.runId** (`string`): 이 생성 실행의 고유 ID입니다. 추적 및 디버깅에 유용합니다.

**options.requestContext** (`RequestContext`): 의존성 주입과 컨텍스트 정보를 위한 요청 컨텍스트입니다.

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

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

**options.onStepFinish** (`(event: any) => Promise<void> | void`): subagent 실행 내 각 LLM 단계 후에 실행되는 콜백입니다. 완료 이유와 토큰 사용량을 포함한 단계 세부 정보를 받습니다.

**options.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` 옵션을 사용하세요. 네트워크는 작업 완료 후 스키마와 일치하는 응답을 생성합니다.

```typescript
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)
```

### 부분 개체 스트리밍

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

```typescript
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에 저장하지 않습니다.

```typescript
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')
  }
}
```