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

# AgentController

:::실험적

`AgentController` 기능은 베타 단계이며, 베타 상태를 벗어나기 전까지 마이너 버전에서 호환성을 깨뜨리는 변경이 발생할 수 있습니다. :::

`AgentController` 클래스는 하나 이상의 [`Session`](https://mastra.zisheng.pro/ko/reference/agent-controller/session) 인스턴스를 위한 공유 호스트입니다. 컨트롤러를 초기화하고 세션을 생성한 다음 `session.*` API를 사용하여 대화 상태와 실행을 제어하세요. 안내된 소개는 다음을 참조하세요.[AgentController overview](https://mastra.zisheng.pro/ko/docs/harness/agent-controller).

## 사용예

다음 예에서는 컨트롤러를 초기화하고 세션을 생성합니다. 메시지를 보내기 전에 세션 이벤트를 구독합니다.

```typescript
import { Agent } from '@mastra/core/agent'
import { AgentController } from '@mastra/core/agent-controller'
import { Workspace } from '@mastra/core/workspace'

const agent = new Agent({
  id: 'coding-agent',
  name: 'Coding agent',
  instructions: 'Help with software engineering tasks.',
  model: 'anthropic/claude-sonnet-4-6',
})

const controller = new AgentController({
  id: 'coding-controller',
  agent,
  workspace: new Workspace({ id: 'coding-workspace' }),
  modes: [{ id: 'build', name: 'Build', metadata: { default: true } }],
})

await controller.init()

const session = await controller.createSession({ resourceId: 'project-42' })
const unsubscribe = session.subscribe(event => {
  if (event.type === 'message_update') {
    console.log(event.message)
  }
})

await session.sendMessage({ content: 'Review the project structure.' })
unsubscribe()
```

## 생성자 매개변수

**id** (`string`): 고유한 컨트롤러 식별자입니다. 기본 세션 및 리소스 식별자로도 사용됩니다.

**modes** (`AgentControllerMode[]`): 모든 세션에서 사용할 수 있는 모드 정의입니다. 하나 이상의 모드가 필요합니다.

**modes.id** (`string`): Unique mode identifier.

**modes.name** (`string`): Display name.

**modes.defaultModelId** (`string`): 저장된 선택 없이 세션이 이 모드에 진입할 때 선택되는 Model입니다.

**modes.description** (`string`): Text shown in mode selectors.

**modes.instructions** (`string`): 이 모드에서 기반 Agent 지침 위에 추가되는 지침입니다.

**modes.transitionsTo** (`string`): 일시 중지된 submit\_plan이 승인된 후 진입할 모드입니다.

**modes.availableTools** (`string[]`): 노출할 Tool 이름의 허용 목록입니다. 빈 배열은 이 모드에서 모든 Tool을 숨깁니다.

**modes.metadata** (`Record<string, unknown>`): 그대로 전달되는 모드 메타데이터입니다. metadata.default: true는 기본 모드를 지정합니다.

**modes.tools** (`ToolsInput`): 모드 Tool입니다. additionalTools와 함께 사용할 수 없습니다.

**modes.additionalTools** (`ToolsInput`): 기반 Agent Tool에 추가되는 Tool입니다. tools와 함께 사용할 수 없습니다.

**modes.agent** (`Agent`): 더 이상 사용되지 않는 모드별 Agent입니다. 최상위 agent 매개변수를 사용하세요.

**modes.default** (`boolean`): 더 이상 사용되지 않는 기본 모드 표시입니다. metadata.default 또는 defaultModeId를 사용하세요.

**agent** (`Agent`): 구성된 모드에서 사용하는 공유 기반 Agent입니다.

**resourceId** (`string`): 세션 및 스레드의 기본 리소스 식별자입니다. 기본값은 id입니다.

**storage** (`MastraCompositeStore`): 영구 스레드, 메시지, 설정 및 재개 가능한 실행 데이터에 사용되는 스토리지입니다.

**stateSchema** (`PublicSchema<TState, any>`): session.state 업데이트의 유효성을 검사하는 데 사용되는 스키마입니다.

**initialState** (`Partial<TState>`): 새 세션마다 스키마 기본값과 병합되는 초기 상태입니다.

**memory** (`DynamicArgument<MastraMemory>`): 자체 Memory를 정의하지 않은 기반 Agent와 공유하는 Memory 인스턴스입니다.

**defaultModeId** (`string`): 기본 모드 식별자입니다. 모드 메타데이터보다 우선합니다.

**instructions** (`string`): 현재 모드 지침과 함께 적용되는 컨트롤러 지침입니다.

**tools** (`DynamicArgument<ToolsInput | undefined>`): 컨트롤러 실행에서 공유되며 구성된 하위 Agent가 사용할 수 있는 Tool입니다.

**workspace** (`DynamicArgument<Workspace | undefined>`): 정적 Workspace 또는 세션별 Workspace 팩토리입니다. 세션에서 유효한 Workspace를 확인할 수 있어야 합니다.

**browser** (`DynamicArgument<MastraBrowser | undefined>`): 정적 브라우저 또는 세션별 브라우저 팩토리입니다.

**channels** (`AgentControllerChannelsConfig`): 채널 스레드를 컨트롤러 세션으로 라우팅하는 데 사용되는 채팅 채널 구성입니다.

**intervalHandlers** (`IntervalHandler[]`): init()에서 시작되고 stopIntervals() 또는 destroy()에서 중지되는 주기적 핸들러입니다.

**idGenerator** (`() => string`): 스레드, 메시지 및 신호에 사용할 사용자 지정 식별자 생성기입니다.

**modelUseCountProvider** (`ModelUseCountProvider`): 사용 가능한 Model을 정렬하는 데 사용되는 Model 사용 횟수를 반환합니다.

**modelUseCountTracker** (`ModelUseCountTracker`): session.model.switch() 후 Model 선택을 기록합니다.

**subagents** (`AgentControllerSubagent[]`): 기본 제공 subagent Tool을 통해 노출되는 하위 Agent 유형입니다.

**subagents.id** (`string`): Unique subagent type identifier.

**subagents.name** (`string`): Display name.

**subagents.description** (`string`): Description used by the generated tool.

**subagents.instructions** (`DynamicArgument<AgentInstructions>`): Subagent instructions.

**subagents.tools** (`ToolsInput`): Tools owned by the subagent.

**subagents.allowedControllerTools** (`string[]`): 하위 Agent Tool에 추가되는 컨트롤러 Tool ID입니다.

**subagents.allowedWorkspaceTools** (`string[]`): 하위 Agent에 표시되는 Workspace Tool 이름입니다.

**subagents.defaultModelId** (`string`): Default subagent model.

**subagents.maxSteps** (`number`): Maximum execution steps.

**subagents.stopWhen** (`LoopOptions["stopWhen"]`): Loop stop condition.

**subagents.forked** (`boolean`): 하위 Agent가 기본적으로 복제된 상위 스레드를 상속할지 여부입니다.

**gateways** (`MastraModelGatewayInterface[]`): 기본 제공 게이트웨이와 병합되는 사용자 지정 Model 게이트웨이입니다.

**omConfig** (`AgentControllerOMConfig`): 기본 관찰 Memory Model 및 임계값입니다.

**disableBuiltinTools** (`BuiltinToolId[]`): 실행에서 제외할 기본 제공 컨트롤러 Tool입니다.

**toolCategoryResolver** (`(toolName: string) => ToolCategory | null`): Tool 이름을 권한 범주에 매핑합니다.

**pubsub** (`PubSub`): 기반 Agent에 전파되는 PubSub 구현입니다.

**threadLock** (`{ acquire: (threadId: string) => void | Promise<void>; release: (threadId: string) => void | Promise<void> }`): 스레드 소유권을 조정하는 데 사용되는 잠금 구현입니다.

**observability** (`ObservabilityEntrypoint`): 독립 실행형 컨트롤러 Mastra 인스턴스의 Observability 구성입니다.

## 속성

**id** (`string`): 생성자에 전달된 컨트롤러 식별자입니다.

## 행동 양식

### 세션

#### `createSession(options)`

`(resourceId, scope)` 쌍에 등록된 라이브 세션을 가져오거나 생성합니다. 이 메서드보다 먼저 `init()`을 호출하세요.

```typescript
const session = await controller.createSession({
  resourceId: 'project-42',
  scope: 'editor-window-1',
  threadId: 'thread-7',
})
```

동일한 `resourceId`와 `scope`는 동일한 `Session` 인스턴스를 반환합니다. 범위가 다르면 같은 리소스에 대해 격리된 세션을 생성합니다. `threadId`를 제공하면 이 메서드는 캐시된 세션을 해당 스레드로 전환하거나, 스레드가 없으면 생성합니다.

**resourceId** (`string`): Memory 리소스 및 라이브 세션 레지스트리 키입니다. 기본값은 구성된 resourceId 또는 컨트롤러 id입니다.

**scope** (`string`): 하나의 리소스에 여러 라이브 세션을 허용하는 선택적 레지스트리 네임스페이스입니다.

**threadId** (`string`): 바인딩할 정확한 스레드입니다. 누락된 스레드는 이 식별자로 생성됩니다.

**id** (`string`): 안정적인 세션 식별자입니다. 기본값은 컨트롤러 id입니다.

**ownerId** (`string`): 안정적인 세션 소유자 식별자입니다. 기본값은 id입니다.

**tags** (`Record<string, string>`): 세션에서 생성한 스레드에 복사되는 태그입니다.

**workspace** (`Workspace`): Workspace override for this session.

**browser** (`MastraBrowser`): Browser override for this session.

**requestContext** (`RequestContext`): 동적 Workspace 및 브라우저 팩토리를 확인하는 데 사용되는 컨텍스트입니다.

보고:`Promise<Session<TState>>`

#### `getSessionByResource(resourceId, scope?)`

리소스 및 선택적 범위에 등록된 라이브 세션을 반환합니다.

```typescript
const session = await controller.getSessionByResource('project-42', 'editor-window-1')
```

보고:`Promise<Session<TState> | undefined>`

#### `setResourceId(session, { resourceId })`

라이브 세션을 다른 리소스로 이동하고 활성 스레드 바인딩을 지웁니다.

```typescript
await controller.setResourceId(session, { resourceId: 'project-43' })
```

#### `getKnownResourceIds(session)`

저장된 스레드에 있는 리소스 식별자를 나열합니다.

```typescript
const resourceIds = await controller.getKnownResourceIds(session)
```

보고:`Promise<string[]>`

### 수명주기

#### `init()`

공유 스토리지, 작업 공간 서비스 및 구성된 간격 핸들러를 초기화합니다. 반복 호출은 동일한 초기화 약속을 재사용합니다.

```typescript
await controller.init()
```

#### `destroy()`

컨트롤러 소유 간격 핸들러를 중지합니다. 컨트롤러가 생성한 세션은 삭제되지 않습니다.

```typescript
await controller.destroy()
```

### 모드 및 Agent

#### `listModes()`

구성된 모드 정의를 반환합니다.

```typescript
const modes = controller.listModes()
```

보고:`AgentControllerMode[]`

#### `getCurrentAgent(session)`

세션의 활성 모드에 대한 지원 Agent를 반환합니다.

```typescript
const agent = controller.getCurrentAgent(session)
```

보고:`Agent`

### 작업공간 및 브라우저

#### `hasWorkspace()`

컨트롤러에 정적, 동적 또는 개체 기반 작업 공간 구성이 있는지 보고합니다.

```typescript
if (controller.hasWorkspace()) {
  console.log('Workspace configured')
}
```

보고:`boolean`

#### `isWorkspaceReady()`

컨트롤러 수준 작업공간이 준비되었는지 보고합니다.

```typescript
const ready = controller.isWorkspaceReady()
```

보고:`boolean`

#### `getWorkspace()`

정적 컨트롤러 작업 공간을 반환합니다. 동적 작업 공간 공장 반환`undefined` until resolved.

```typescript
const workspace = controller.getWorkspace()
```

보고:`Workspace | undefined`

#### `resolveWorkspace({ session, requestContext? })`

세션에 대한 동적 작업 공간을 확인하고 컨트롤러에서 결과를 캐시합니다.

```typescript
const workspace = await controller.resolveWorkspace({ session, requestContext })
```

보고:`Promise<Workspace | undefined>`

#### `setBrowser(browser)`

컨트롤러 브라우저를 교체하고 이를 지원 Agent에 전파합니다.

```typescript
controller.setBrowser(browser)
```

### 마스트라와 채널

#### `getMastra()`

부모 Mastra 인스턴스 또는 다음에 의해 생성된 내부 인스턴스를 반환합니다.`init()`.

```typescript
const mastra = controller.getMastra()
```

보고:`Mastra | undefined`

#### `getChannels()`

구성된 채팅 채널 통합을 반환합니다.

```typescript
const channels = controller.getChannels()
```

보고:`AgentControllerChannels | null`

### Model

#### `getCurrentModelAuthStatus(session)`

세션에서 선택한 Model에 대한 인증 상태를 반환합니다.

```typescript
const status = await controller.getCurrentModelAuthStatus(session)
```

보고:`Promise<ModelAuthStatus>`

#### `listAvailableModels()`

구성된 게이트웨이와 기본 제공 게이트웨이의 Model을 나열합니다. 결과는 잠시 캐시되며 `modelUseCountProvider`가 구성되어 있으면 사용량 데이터에 따라 정렬됩니다.

```typescript
const models = await controller.listAvailableModels()
```

보고:`Promise<AvailableModel[]>`

#### `invalidateAvailableModelsCache()`

사용 가능한 Model 캐시를 지웁니다.

```typescript
controller.invalidateAvailableModelsCache()
```

### 관찰 Memory 및 권한

#### `loadOMProgress(session)`

활성 스레드에 대해 저장된 관찰 Memory 진행 상황을 로드하고`om_status` event.

```typescript
await controller.loadOMProgress(session)
```

#### `getObservationalMemoryRecord(session)`

활성 스레드에 대한 관찰 Memory 레코드를 반환합니다.

```typescript
const record = await controller.getObservationalMemoryRecord(session)
```

보고:`Promise<ObservationalMemoryRecord | null>`

#### `getToolCategory({ toolName })`

Tool에 대한 권한 범주를 해결합니다.

```typescript
const category = controller.getToolCategory({ toolName: 'execute_command' })
```

보고:`ToolCategory | null`

### 간격

#### `registerInterval(handler)`

주기적 처리기를 시작하거나 교체합니다.

```typescript
controller.registerInterval({
  id: 'refresh',
  intervalMs: 60_000,
  handler: async () => refreshData(),
})
```

#### `removeInterval({ id })`

한 간격을 중지하고 선택적 종료 콜백을 실행합니다.

```typescript
await controller.removeInterval({ id: 'refresh' })
```

#### `stopIntervals()`

모든 간격을 중지하고 선택적 종료 콜백을 실행합니다.

```typescript
await controller.stopIntervals()
```

## 관련된

- [AgentController 가이드](https://mastra.zisheng.pro/ko/docs/harness/agent-controller)
- [세션 참조](https://mastra.zisheng.pro/ko/reference/agent-controller/session)
- [Agent](https://mastra.zisheng.pro/ko/docs/agents/overview)
- [작업공간](https://mastra.zisheng.pro/ko/docs/workspace/overview)
- [채널](https://mastra.zisheng.pro/ko/docs/capabilities/channels/overview)