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

# 다음에서 마이그레이션`.network()`감독 Agent에게

`Agent.stream()` 및 `Agent.generate()`를 사용하는 감독자 Agent는 여러 Agent를 조정하고 기존 Agent `.network()` API를 대체하는 데 권장되는 접근 방식입니다. 이 가이드에서는 마이그레이션의 각 단계를 안내합니다. :::warning\[.network() 지원 중단]

`.network()`더 이상 사용되지 않으며 향후 릴리스에서 제거될 예정입니다. 기존 코드는 그때까지 계속 작동하지만 현재 개발은 감독자 Agent에 중점을 두고 있습니다. 가능한 한 빨리 감독 Agent으로 마이그레이션하세요.

:::

## `.network()`를 `.stream()` 또는 `.generate()`로 교체

핵심 변경 사항은 `.network()` 호출을 `.stream()`(스트리밍) 또는 `.generate()`(비스트리밍)로 교체하는 것입니다. Agent 구성은 그대로 유지됩니다. 계속해서 Agent에 `agents`, `workflows`, `tools`, `memory`를 정의합니다. 차이점은 호출 방법과 결과 처리 방법입니다. `.network()`에서는 `network-execution-event-step-finish`와 같은 사용자 지정 이벤트 타입을 순회했습니다. `.stream()`에서는 표준 `textStream` 또는 `fullStream` 반복자를 사용합니다. **전에:**

```typescript
const result = await routingAgent.network('Research AI in education')

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

**후에:**

```typescript
const stream = await supervisorAgent.stream('Research AI in education', {
  maxSteps: 10,
})

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk)
}
```

`maxSteps` 옵션은 감독자가 수행할 수 있는 반복 횟수를 제한합니다. 이 옵션은 `.network()`의 암시적 반복 제한을 대체합니다. 비스트리밍 사용 사례에서는 동일한 옵션과 함께 `generate()`를 사용하세요.

```typescript
const result = await supervisorAgent.generate('Research AI in education', {
  maxSteps: 10,
})

console.log(result.text)
```

## 명확한 감독자 지침 작성

`.network()`에서는 라우팅 Agent가 일반적인 지침과 프리미티브 설명을 바탕으로 호출 대상을 결정했습니다. 감독자 Agent도 같은 방식으로 작동하지만, 명확하고 구체적인 지침을 제공하면 위임 정확도가 높아집니다. 감독자의 `instructions`에는 사용 가능한 리소스와 각 리소스를 사용해야 하는 시점을 명시해야 합니다. 또한 이러한 리소스를 조정하는 방법과 작업 완료 여부를 판단하는 방법도 설명해야 합니다. **전에:**

```typescript
const routingAgent = new Agent({
  id: 'routing-agent',
  instructions: 'You are a network of researchers and writers...',
  agents: { researchAgent, writingAgent },
  memory: new Memory(),
})
```

**후에:**

```typescript
const supervisorAgent = new Agent({
  id: 'supervisor-agent',
  instructions: `You coordinate research and writing tasks using specialized agents.

Available resources:
- researchAgent: Gathers factual data and sources (returns bullet points)
- writingAgent: Transforms research into narrative content (returns full paragraphs)

Delegation strategy:
1. For research requests: Delegate to researchAgent first
2. For writing requests: Delegate to writingAgent (provide research if available)
3. For complex requests: Delegate to researchAgent first, then writingAgent

Success criteria:
- All user questions are fully answered
- Response is well-formatted and complete
- If information is incomplete, continue iterating`,
  agents: { researchAgent, writingAgent },
  memory: new Memory(),
})
```

## 하위 Agent에 설명 추가

각 하위 Agent에는 목적과 반환 형식을 설명하는 `description` 필드가 필요합니다. 설명에는 하위 Agent를 사용해야 하는 시점도 명시해야 합니다. 감독자는 이러한 설명을 사용하여 위임할 Agent를 결정합니다.

```typescript
const researchAgent = new Agent({
  id: 'research-agent',
  description: `Specializes in gathering factual information and data on any topic.
    Returns concise bullet-point summaries with key facts and sources.
    Does not write full articles or narrative content.`,
})

const writingAgent = new Agent({
  id: 'writing-agent',
  description: `Transforms research material into well-structured written content.
    Produces full paragraphs and complete articles.
    Best used after research has been gathered.`,
})
```

## 이벤트 처리 업데이트

특정 `.network()` 이벤트를 처리하고 있다면 표준 스트림 청크 타입을 사용하도록 업데이트하세요.

| `.network()` 이벤트                      | 감독자 Agent 청크                           |
| ------------------------------------- | -------------------------------------- |
| `routing-agent-start`                 | `step-start`                           |
| `routing-agent-end`                   | `step-finish`                          |
| `agent-execution-start`               | `step-start`(위임 시)                     |
| `agent-execution-event-text-delta`    | `text-delta`                           |
| `agent-execution-event-finish`        | `step-finish`                          |
| `network-execution-event-step-finish` | `step-finish` + `finishReason: 'stop'` |
| `network-object`                      | `object-delta`(구조화된 출력 사용)             |
| `network-object-result`               | `object`(구조화된 출력 사용)                   |

## 위임 후크 추가

감독 Agent를 사용하면 위임 수명 주기에 연결하여 위임을 모니터링하거나 수정하거나 거부할 수 있습니다. 이러한 후크는 Agent의 `defaultOptions`에서 설정하거나 호출별로 전달할 수 있습니다. `onDelegationStart`감독자가 하위 Agent에게 위임하기 전에 호출됩니다. Prompt를 수정하거나 하위 Agent의 단계를 제한할 수 있습니다. 후크는 위임을 완전히 거부할 수도 있습니다.

```typescript
const stream = await supervisorAgent.stream('Research AI in education', {
  maxSteps: 10,
  delegation: {
    onDelegationStart: async context => {
      console.log(`Delegating to: ${context.primitiveId}`)

      if (context.primitiveId === 'research-agent') {
        return {
          proceed: true,
          modifiedPrompt: `${context.prompt}\n\nFocus on 2024-2025 data.`,
          modifiedMaxSteps: 5,
        }
      }

      if (context.iteration > 8) {
        return {
          proceed: false,
          rejectionReason: 'Max iterations reached. Synthesize current findings.',
        }
      }

      return { proceed: true }
    },
  },
})
```

`onDelegationComplete`는 위임이 완료된 후 호출됩니다. 결과를 검사하고 감독자 루프를 중지해야 할 때 `context.bail()`을 호출하세요. 감독자의 Memory에 저장될 피드백을 반환할 수도 있습니다.

```typescript
const stream = await supervisorAgent.stream('Research AI in education', {
  maxSteps: 10,
  delegation: {
    onDelegationComplete: async context => {
      if (context.error) {
        context.bail() // Stop further delegations
        return {
          feedback: `Delegation to ${context.primitiveId} failed: ${context.error}. Try a different approach.`,
        }
      }
    },
  },
})
```

## 메시지 필터링 추가

기본적으로 하위 Agent는 감독자로부터 전체 대화 컨텍스트를 받습니다. 공유할 메시지를 제어하려면 `messageFilter`를 사용하세요. 예를 들어 민감한 데이터를 제거하거나 메시지 수를 제한할 수 있습니다.

```typescript
const stream = await supervisorAgent.stream('Research AI in education', {
  maxSteps: 10,
  delegation: {
    messageFilter: ({ messages, primitiveId, prompt }) => {
      return messages
        .filter(msg => {
          const content =
            typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content)
          return !content.includes('confidential')
        })
        .slice(-10)
    },
  },
})
```

## 반복 모니터링 추가

`onIterationComplete`감독자 루프가 반복될 때마다 호출됩니다. 이를 사용하여 진행 상황을 기록하거나 상담사를 안내하는 피드백을 제공하세요. 후크는 실행을 조기에 중지할 수도 있습니다.

```typescript
const stream = await supervisorAgent.stream('Research AI in education', {
  maxSteps: 10,
  onIterationComplete: async context => {
    console.log(`Iteration ${context.iteration}/${context.maxIterations}`)

    if (!context.text.includes('recommendations')) {
      return {
        continue: true,
        feedback: 'Please include specific recommendations in your analysis.',
      }
    }

    if (context.text.length > 1000 && context.finishReason === 'stop') {
      return { continue: false }
    }

    return { continue: true }
  },
})
```

## 작업 완료 점수 추가

작업 완료 채점자는 작업이 완료되었는지 자동으로 확인합니다. 검증이 실패하면 감독자는 계속해서 반복합니다. 실패한 득점자의 피드백이 대화 컨텍스트에 포함되어 하위 Agent가 누락된 내용을 확인할 수 있습니다.

```typescript
import { createScorer } from '@mastra/core/evals'

const taskCompleteScorer = createScorer({
  id: 'task-complete',
  name: 'Task Completeness',
}).generateScore(async context => {
  const text = (context.run.output || '').toString()
  const hasAnalysis = text.includes('analysis')
  const hasRecommendations = text.includes('recommendation')
  return hasAnalysis && hasRecommendations ? 1 : 0
})

const stream = await supervisorAgent.stream('Research AI in education', {
  maxSteps: 10,
  isTaskComplete: {
    scorers: [taskCompleteScorer],
    strategy: 'all',
    onComplete: async result => {
      console.log('Task complete:', result.complete)
    },
  },
})
```

## 또한보십시오

- [감독자 Agent](https://mastra.zisheng.pro/ko/docs/capabilities/subagents)
- [Agent 네트워크](https://mastra.zisheng.pro/ko/docs/agents/networks)
- [Agent.stream() 참조](https://mastra.zisheng.pro/ko/reference/streaming/agents/stream)
- [Agent.generate() 참조](https://mastra.zisheng.pro/ko/reference/agents/generate)
- [대리인 승인](https://mastra.zisheng.pro/ko/docs/agents/agent-approval)
- [가이드: 연구 코디네이터](https://mastra.zisheng.pro/ko/guides/guide/research-coordinator)