AgentController

:::실험적

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

AgentController 클래스는 하나 이상의 Session 인스턴스를 위한 공유 호스트입니다. 컨트롤러를 초기화하고 세션을 생성한 다음 session.* API를 사용하여 대화 상태와 실행을 제어하세요. 안내된 소개는 다음을 참조하세요.AgentController overview.

사용예

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

src/mastra/agent-controller.ts

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[]

모든 세션에서 사용할 수 있는 모드 정의입니다. 하나 이상의 모드가 필요합니다.

AgentControllerMode

id:

string

Unique mode identifier.

name?:

string

Display name.

defaultModelId?:

string

저장된 선택 없이 세션이 이 모드에 진입할 때 선택되는 Model입니다.

description?:

string

Text shown in mode selectors.

instructions?:

string

이 모드에서 기반 Agent 지침 위에 추가되는 지침입니다.

transitionsTo?:

string

일시 중지된 submit_plan이 승인된 후 진입할 모드입니다.

availableTools?:

string[]

노출할 Tool 이름의 허용 목록입니다. 빈 배열은 이 모드에서 모든 Tool을 숨깁니다.

metadata?:

Record<string, unknown>

그대로 전달되는 모드 메타데이터입니다. metadata.default: true는 기본 모드를 지정합니다.

tools?:

ToolsInput

모드 Tool입니다. additionalTools와 함께 사용할 수 없습니다.

additionalTools?:

ToolsInput

기반 Agent Tool에 추가되는 Tool입니다. tools와 함께 사용할 수 없습니다.

agent?:

Agent

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

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 유형입니다.

AgentControllerSubagent

id:

string

Unique subagent type identifier.

name:

string

Display name.

description:

string

Description used by the generated tool.

instructions:

DynamicArgument<AgentInstructions>

Subagent instructions.

tools?:

ToolsInput

Tools owned by the subagent.

allowedControllerTools?:

string[]

하위 Agent Tool에 추가되는 컨트롤러 Tool ID입니다.

allowedWorkspaceTools?:

string[]

하위 Agent에 표시되는 Workspace Tool 이름입니다.

defaultModelId?:

string

Default subagent model.

maxSteps?:

number

Maximum execution steps.

stopWhen?:

LoopOptions["stopWhen"]

Loop stop condition.

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()을 호출하세요.

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?)

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

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

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

setResourceId(session, { resourceId })

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

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

getKnownResourceIds(session)

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

const resourceIds = await controller.getKnownResourceIds(session)

보고:Promise<string[]>

수명주기

init()

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

await controller.init()

destroy()

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

await controller.destroy()

모드 및 Agent

listModes()

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

const modes = controller.listModes()

보고:AgentControllerMode[]

getCurrentAgent(session)

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

const agent = controller.getCurrentAgent(session)

보고:Agent

작업공간 및 브라우저

hasWorkspace()

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

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

보고:boolean

isWorkspaceReady()

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

const ready = controller.isWorkspaceReady()

보고:boolean

getWorkspace()

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

const workspace = controller.getWorkspace()

보고:Workspace | undefined

resolveWorkspace({ session, requestContext? })

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

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

보고:Promise<Workspace | undefined>

setBrowser(browser)

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

controller.setBrowser(browser)

마스트라와 채널

getMastra()

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

const mastra = controller.getMastra()

보고:Mastra | undefined

getChannels()

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

const channels = controller.getChannels()

보고:AgentControllerChannels | null

Model

getCurrentModelAuthStatus(session)

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

const status = await controller.getCurrentModelAuthStatus(session)

보고:Promise<ModelAuthStatus>

listAvailableModels()

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

const models = await controller.listAvailableModels()

보고:Promise<AvailableModel[]>

invalidateAvailableModelsCache()

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

controller.invalidateAvailableModelsCache()

관찰 Memory 및 권한

loadOMProgress(session)

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

await controller.loadOMProgress(session)

getObservationalMemoryRecord(session)

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

const record = await controller.getObservationalMemoryRecord(session)

보고:Promise<ObservationalMemoryRecord | null>

getToolCategory({ toolName })

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

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

보고:ToolCategory | null

간격

registerInterval(handler)

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

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

removeInterval({ id })

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

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

stopIntervals()

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

await controller.stopIntervals()

관련된

• AgentController 가이드
• 세션 참조
• Agent
• 작업공간
• 채널