세션

:::실험적

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

Session은 하나의 리소스와 선택적 범위를 위한 격리된 런타임입니다. 자체 이벤트 버스, 스레드 바인딩, 상태, 모드 및 Model 선택, 실행 제어, 승인, 일시 중지, 후속 메시지 및 표시 상태를 소유합니다. AgentController는 공유 Agent, 구성, 스토리지, Workspace 및 서비스를 제공합니다. controller.createSession()을 통해 세션을 생성하세요. 직접 생성 및 컨트롤러 연결 메서드는 애플리케이션 API가 아닙니다. 개념 소개는 다음을 참조하세요.AgentController overview.

사용예

다음 예에서는 지원되는 컨트롤러-세션 흐름을 사용합니다.

await controller.init()

const session = await controller.createSession({ resourceId: 'project-42' })
const unsubscribe = session.subscribe(event => {
  if (event.type === 'display_state_changed') {
    render(event.displayState)
  }
})

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

속성

세션은 하위 개체로 구성되며, 각 개체는 대화별 상태의 도메인 하나를 소유합니다.

identity:

SessionIdentity

대화의 안정적인 세션, 소유자 및 리소스 식별 정보입니다. 아래의 식별 정보 메서드를 참조하세요.

thread:

SessionThread

활성 스레드 바인딩과 스레드/메시지 읽기 기능입니다. 아래의 스레드 메서드를 참조하세요.

mode:

SessionMode

활성 모드 선택입니다. 아래의 모드 메서드를 참조하세요.

model:

SessionModel

모드별 영속성을 포함한 활성 Model 선택입니다. 아래의 Model 메서드를 참조하세요.

om:

SessionOM

관찰 Memory의 관찰자 및 리플렉터 Model 설정입니다.

permissions:

SessionPermissions

세션 상태에 표현되는 Tool 및 범주 권한 정책입니다.

subagents:

SessionSubagents

전역 및 Agent 유형별 하위 Agent Model 선택입니다.

run:

SessionRun

진행 중인 실행의 실행 및 Trace 식별 정보와 중단 상태입니다. 아래의 실행 메서드를 참조하세요.

stream:

SessionStream

Agent 스레드 스트림에 대한 실시간 구독입니다. 아래의 스트림 메서드를 참조하세요.

suspensions:

SessionSuspensions

재개를 기다리며 대기 중인 대화형 Tool 호출입니다. 아래의 일시 중지 메서드를 참조하세요.

followUps:

SessionFollowUps

실행이 진행되는 동안 제출된 메시지의 대기열입니다. 아래의 후속 메시지 메서드를 참조하세요.

approval:

SessionApproval

대기 중인 Tool 승인 게이트입니다. 아래의 승인 메서드를 참조하세요.

displayState:

SessionDisplayState

UI 렌더링의 기반이 되는 표준 AgentControllerDisplayState 스냅샷입니다. 아래의 표시 상태 메서드를 참조하세요.

state:

AgentControllerRequestState<TState>

스키마 검증을 거치며 세션이 소유하는 AgentController 상태입니다. 아래의 상태 메서드를 참조하세요.

browser:

MastraBrowser | undefined

이 세션의 브라우저 자동화 인스턴스입니다. 생성 시 createSession을 통해 설정하거나 AgentController 구성 기본값에서 가져옵니다. 브라우저가 구성되지 않은 경우 undefined입니다.

행동 양식

정체성과 사건

getTags()

세션이 생성될 때 제공된 태그의 복사본을 반환합니다.

const tags = session.getTags()

보고:Record<string, string>

subscribe(listener)

이 세션의 격리된 이벤트 버스를 구독하세요. 이 메서드는 구독 취소 함수를 반환합니다.

const unsubscribe = session.subscribe(event => {
  console.log(event.type)
})

unsubscribe()

보고:() => void

메시지 및 실행 제어

sendMessage({ content, files?, requestContext? })

사용자 메시지를 보냅니다. 세션은 활성 스레드가 없을 때 먼저 스레드를 생성합니다.

await session.sendMessage({
  content: 'Summarize this file.',
  files: [{ data: fileContents, mediaType: 'text/plain', filename: 'notes.txt' }],
})

steer({ content, requestContext? })

콘텐츠를 활성 실행으로 큐에 넣습니다.

await session.steer({ content: 'Focus on the failing tests.' })

followUp({ content, requestContext? })

실행이 활성화된 동안 후속 작업을 대기열에 추가하거나 유휴 상태에서 즉시 보냅니다.

await session.followUp({ content: 'Then propose a fix.' })

getCurrentRunId()

활성 스트림 실행 식별자, 추적된 실행 식별자를 반환합니다.null while idle.

const runId = session.getCurrentRunId()

보고:string | null

abort()

활성 실행을 중단하고 보류 중인 정지 표시 상태를 지웁니다.

session.abort()

작업공간

getWorkspace()

이 세션에 대해 해결된 작업공간을 반환합니다. 이렇게 하면 세션 범위에서 선택된 세션 수준 재정의 및 작업 공간이 유지됩니다.

const workspace = session.getWorkspace()
const skill = await workspace.skills?.get('code-review')

보고:Workspace

세션 부여

세션 범위는 메시지를 표시하지 않고 자동 승인 Tool을 부여합니다. 부여는 일시적입니다. 세션이 다시 시작되면 재설정되고 지속되지 않습니다.

grantCategory(category)

현재 세션에 Tool 범주를 부여합니다. 이 카테고리의 Tool은 자동 승인됩니다.

session.grantCategory('edit')

grantTool(toolName)

현재 세션에 특정 Tool을 부여합니다.

session.grantTool('mastra_workspace_execute_command')

getGrants()

현재 부여된 카테고리와 Tool을 반환합니다.

const grants = session.getGrants()
// { categories: string[], tools: string[] }

hasCategoryGrant(category)

카테고리에 인Memory 세션 부여가 있는지 여부를 반환합니다.

const allowed = session.hasCategoryGrant('edit')

보고:boolean

hasToolGrant(toolName)

Tool에 Memory 내 세션 부여가 있는지 여부를 반환합니다.

const allowed = session.hasToolGrant('write_file')

보고:boolean

Tool 승인

resolveToolApproval(toolName)

명시적인 Tool 규칙, 세션 부여 및 카테고리 규칙을 적용한 후 유효한 정책을 반환합니다.

const policy = session.resolveToolApproval('execute_command')

보고:PermissionPolicy

respondToToolApproval({ decision, toolCallId?, requestContext?, declineContext? })

tool_approval_required 이벤트의 대기 중인 Tool 승인 요청에 응답합니다. 세션의 나머지 기간 동안 해당 Tool의 전체 범주도 허용하려면 always_allow_category를 전달하세요.

session.respondToToolApproval({ decision: 'approve' })
session.respondToToolApproval({ decision: 'decline' })
session.respondToToolApproval({ decision: 'always_allow_category' })

respondToToolSuspension({ resumeData, toolCallId?, requestContext? })

애플리케이션이 제공한 데이터로 일시 중지된 Tool을 재개합니다. 여러 Tool 호출이 일시 중지된 경우 toolCallId를 제공하세요.

await session.respondToToolSuspension({
  toolCallId: event.toolCallId,
  resumeData: ['src'],
})

submit_plan의 경우 { action: 'approved' } 또는 { action: 'rejected', feedback }을 전달하세요. 승인이 완료되면 Tool이 재개되기 전에 transitionsTo로 구성된 모드로 전환할 수 있습니다.

토큰 사용

getTokenUsage()

활성 스레드에 대해 실행 중인 토큰 사용량 집계의 복사본을 반환합니다.

const usage = session.getTokenUsage()
// { promptTokens, completionTokens, totalTokens, ... }

신원

session.identity는 대화의 안정적인 식별자, 즉 리소스 ID, 세션 id, ownerId를 소유합니다. id와 ownerId는 세션의 수명 동안 유지되며 리소스 ID가 전환되어도 변경되지 않습니다. 이는 스토리지의 SessionRecord에 있는 id 및 ownerId 필드와 동일합니다.

session.identity.getId()

안정적인 세션 식별자를 반환합니다.

const sessionId = session.identity.getId()

session.identity.getOwnerId()

세션의 안정적인 소유자 식별자를 반환합니다.

const ownerId = session.identity.getOwnerId()

session.identity.getResourceId()

현재 리소스 ID를 반환합니다.

const resourceId = session.identity.getResourceId()

session.identity.getDefaultResourceId()

세션이 생성된 리소스 ID를 반환합니다.

const defaultResourceId = session.identity.getDefaultResourceId()

리소스 ID를 변경하려면 controller.setResourceId()를 사용하세요. 이 메서드는 활성 스레드도 지웁니다. 세션 id와 ownerId는 리소스 전환의 영향을 받지 않습니다.

실

session.thread활성 스레드 바인딩 및 리소스 범위 스레드 작업을 소유합니다. 저장된 스레드와 메시지는 저장소가 구성될 때 컨트롤러 재생성 후에도 유지될 수 있습니다. 라이브 세션과 해당 이벤트 버스는 그렇지 않습니다.

session.thread.create({ title?, id? })

스레드를 생성하고 세션을 바인딩하고 해당 이벤트 스트림을 엽니다.

const thread = await session.thread.create({
  id: 'thread-7',
  title: 'Investigate login failure',
})

보고:Promise<AgentControllerThread>

session.thread.rename({ title })

활성 저장 스레드의 이름을 바꿉니다.

await session.thread.rename({ title: 'Fix login failure' })

session.thread.clone({ sourceThreadId?, title?, resourceId? })

소유한 스레드와 해당 메시지를 복제한 다음 세션을 복제본에 바인딩합니다.

const clone = await session.thread.clone({
  sourceThreadId: 'thread-7',
  title: 'Alternative approach',
})

보고:Promise<AgentControllerThread>

session.thread.switch({ threadId, emitEvent? })

소유된 저장된 스레드로 전환하고 해당 스레드의 모드, Model 및 관찰 Memory 설정을 수화합니다.

await session.thread.switch({ threadId: 'thread-8' })

session.thread.delete({ threadId })

소유한 스레드를 삭제합니다. 활성 스레드를 삭제하면 현재 바인딩도 지워집니다.

await session.thread.delete({ threadId: 'thread-8' })

session.thread.getId()

활성 스레드 ID를 반환하며 바인딩된 스레드가 없으면 null을 반환합니다.

const threadId = session.thread.getId()

session.thread.list(options?)

저장소의 스레드를 나열합니다. 기본적으로 현재 리소스에 대한 스레드만 반환되며 일시적으로 분기된 하위 Agent 스레드는 숨겨집니다.

const threads = await session.thread.list()
const allThreads = await session.thread.list({ allResources: true })
const everything = await session.thread.list({ includeForkedSubagents: true })

session.thread.getById({ threadId })

ID에 해당하는 단일 스레드를 반환하며, 존재하지 않으면 null을 반환합니다.

const thread = await session.thread.getById({ threadId: 'thread-abc123' })

session.thread.listActiveMessages(options?)

활성 스레드에 대한 메시지를 검색합니다. 스레드가 바인딩되지 않은 경우 빈 배열을 반환합니다.

const messages = await session.thread.listActiveMessages({ limit: 50 })

session.thread.listMessages({ threadId, limit? })

특정 스레드에 대한 메시지를 검색합니다.

const messages = await session.thread.listMessages({ threadId: 'thread-abc123' })

메시지 읽기 메서드 listActiveMessages, listMessages, firstUserMessage는 MastraDBMessage 객체를 반환하고, firstUserMessages는 스레드 ID를 키로 하는 Map<string, MastraDBMessage>를 반환합니다. 각 메시지에는 role, id, createdAt과 content.format 및 content.parts 배열을 포함하는 content 객체가 있습니다. content.parts에서 텍스트, 추론, Tool 호출 및 첨부 파일을 읽으세요. 시스템 알림 및 알림 메시지와 같은 신호는 role: 'signal'이 지정된 별도 메시지로 반환됩니다.

session.thread.firstUserMessage({ threadId })

스레드의 첫 번째 사용자 메시지를 가져오며, 없으면 null을 반환합니다.

const firstMsg = await session.thread.firstUserMessage({
  threadId: 'thread-abc123',
})

session.thread.firstUserMessages({ threadIds })

여러 스레드에 대한 첫 번째 사용자 메시지를 한 번에 검색하여 맵으로 반환합니다.

const firstByThread = await session.thread.firstUserMessages({
  threadIds: ['thread-a', 'thread-b'],
})

session.thread.getSetting({ key })

활성 스레드 메타데이터에서 설정을 읽습니다.

const value = await session.thread.getSetting({ key: 'omThreshold' })

session.thread.setSetting({ key, value })

활성 스레드 메타데이터에 설정을 씁니다.

await session.thread.setSetting({ key: 'omThreshold', value: 0.8 })

session.thread.deleteSetting({ key })

활성 스레드 메타데이터에서 설정을 제거합니다.

await session.thread.deleteSetting({ key: 'omThreshold' })

방법

session.mode활성 모드 선택을 소유합니다.

session.mode.get()

활성 모드 ID를 반환합니다.

const modeId = session.mode.get()

session.mode.resolve()

컨트롤러에 구성된 모드를 기준으로 확인한 활성 모드의 전체 AgentControllerMode 객체를 반환합니다.

const mode = session.mode.resolve()

session.mode.switch({ modeId })

다른 모드로 전환합니다. 세션은 활성 스레드에 새 모드를 유지하기 전에 나가는 모드의 Model을 저장합니다. 그런 다음 진입하는 모드에서 선택한 Model 또는 기본 Model을 복원합니다. 세션은 즉시 mode_changed를 내보내고 Model 확인 후 model_changed를 내보냅니다.

await session.mode.switch({ modeId: 'build' })

Model

session.model모드별 Model Memory를 포함하여 활성 Model 선택을 소유합니다.

session.model.get()

활성 Model ID를 반환합니다.

const modelId = session.model.get()

session.model.displayName()

활성 Model ID의 마지막 세그먼트를 짧은 표시 이름으로 반환합니다. 선택된 Model이 없으면 'unknown'을 반환합니다.

const name = session.model.displayName()

session.model.hasSelection()

현재 선택된 Model이 있는지 확인하세요.

if (session.model.hasSelection()) {
  // Ready to send messages
}

session.model.switch({ modelId, scope?, modeId? })

활성 Model을 전환합니다. scope가 'thread'(기본값)이면 Model ID가 모드별 Model로 유지되므로 해당 모드로 다시 전환할 때 복원됩니다. 선택을 컨트롤러의 modelUseCountTracker에 보고하고 model_changed 이벤트를 내보냅니다.

// Set for the current session only
await session.model.switch({
  modelId: 'anthropic/claude-sonnet-4-6',
  scope: 'global',
})

// Persist to the current thread (default)
await session.model.switch({ modelId: 'anthropic/claude-sonnet-4-6' })

관찰 기억

관찰 Memory Model 선택은 session.om.observer와 session.om.reflector의 역할별로 그룹화됩니다. 두 역할은 동일한 메서드를 제공합니다. 값을 읽을 때 세션 상태에 설정된 값이 있으면 이를 반환하고, 없으면 컨트롤러의 omConfig 기본값을 사용합니다.

session.om.observer.modelId() / session.om.reflector.modelId()

역할의 Model ID를 반환하며, 세션 상태와 omConfig 모두 값을 제공하지 않으면 undefined를 반환합니다.

const observer = session.om.observer.modelId()
const reflector = session.om.reflector.modelId()

session.om.observer.threshold() / session.om.reflector.threshold()

역할의 임계값을 토큰 단위로 반환합니다(관찰자는 관찰 임계값, 리플렉터는 반영 임계값). 설정되지 않은 경우 undefined를 반환합니다.

const observationThreshold = session.om.observer.threshold()
const reflectionThreshold = session.om.reflector.threshold()

session.om.observer.switchModel({ modelId }) / session.om.reflector.switchModel({ modelId })

역할의 Model을 전환합니다. 스레드 메타데이터에 대한 설정을 유지하고om_model_changed event.

await session.om.observer.switchModel({
  modelId: 'anthropic/claude-haiku-4-5',
})
await session.om.reflector.switchModel({
  modelId: 'anthropic/claude-haiku-4-5',
})

session.om.observer.resolvedModel() / session.om.reflector.resolvedModel()

구성된 Model 게이트웨이를 통해 역할의 Model ID를 Model 인스턴스로 확인합니다. 설정된 Model ID가 없거나 리졸버가 구성되지 않은 경우 undefined를 반환합니다.

const observerModel = session.om.observer.resolvedModel()
const reflectorModel = session.om.reflector.resolvedModel()

권한

session.permissions는 session.state에서 Tool 승인 정책, 즉 승인 확인 중 참조되는 범주별 및 Tool별 규칙을 소유합니다. 이는 세션 권한 부여에 설명된 인메모리 권한 부여와는 별개입니다. 권한 부여는 라이브 세션과 함께 초기화됩니다. 호스트가 해당 세션 상태를 복원하지 않으면 권한 규칙은 영구적으로 유지되지 않습니다.

session.permissions.getRules()

현재 권한 규칙을 반환하며, 설정된 규칙이 없으면 빈 규칙({ categories: {}, tools: {} })을 반환합니다.

const rules = session.permissions.getRules()
// { categories: { execute: 'ask' }, tools: { dangerous_tool: 'deny' } }

session.permissions.setForCategory({ category, policy })

Tool 범주에 대한 승인 정책('allow' | 'ask' | 'deny')을 설정합니다. 변경 사항이 세션 상태에 유지되면 완료됩니다.

await session.permissions.setForCategory({ category: 'execute', policy: 'ask' })

session.permissions.setForTool({ toolName, policy })

특정 Tool에 대한 승인 정책을 설정합니다. Tool별 정책은 카테고리 정책보다 우선합니다. 한 번 지속되면 해결됩니다.

await session.permissions.setForTool({ toolName: 'dangerous_tool', policy: 'deny' })

하위 Agent

session.subagents하위 Agent 구성을 소유합니다. 현재 하위 Agent Model 선택이 표시됩니다.session.subagents.model.

session.subagents.model.get({ agentType? })

agentType 값이 제공된 경우 해당 하위 Agent Model ID를 반환한 다음 전역 하위 Agent Model을 반환하며, 둘 다 설정되지 않았으면 null을 반환합니다.

const modelId = session.subagents.model.get({ agentType: 'explore' })

session.subagents.model.set({ modelId, agentType? })

하위 Agent Model ID를 설정합니다. 유형별 재정의를 설정하려면 agentType을 전달하고, 전역 기본값을 설정하려면 생략하세요. 스레드 설정에 유지하고 subagent_model_changed 이벤트를 내보냅니다.

// Set the global subagent model
await session.subagents.model.set({ modelId: 'anthropic/claude-sonnet-4-6' })

// Set a per-type override
await session.subagents.model.set({
  modelId: 'anthropic/claude-haiku-4-5',
  agentType: 'explore',
})

달리다

session.run실행 및 추적 ID와 진행 중인 실행에 대한 중단 상태를 소유합니다.

session.run.getRunId() / getTraceId()

현재 실행에 저장된 실행 ID와 Trace ID를 반환하며, 유휴 상태이면 null을 반환합니다.

const runId = session.run.getRunId()
const traceId = session.run.getTraceId()

session.run.isRunning()

현재 실행이 진행 중인지 여부를 반환합니다.

if (session.run.isRunning()) {
  // A run is active
}

개울

session.streamAgent 스레드 스트림 및 해당 중복 제거 키에 대한 실시간 구독을 소유합니다.

session.stream.activeRunId()

라이브 스트림에서 활성화된 실행 ID를 반환하며, 열린 스트림이 없으면 null을 반환합니다.

const runId = session.stream.activeRunId()

session.stream.isActive()

스트림에 현재 활성 실행이 있는지 여부를 반환합니다.

if (session.stream.isActive()) {
  // The current thread's stream is producing output
}

정지

session.suspensions는 재개를 기다리며 대기 중인 대화형 Tool 호출(예: ask_user 및 request_access)을 소유합니다.

session.suspensions.hasPending()

현재 일시 중단된 Tool이 있는지 여부를 반환합니다.

if (session.suspensions.hasPending()) {
  // At least one interactive tool is waiting for a response
}

session.suspensions.has({ toolCallId })

특정 Tool 호출이 일시 중단되었는지 여부를 반환합니다.

const waiting = session.suspensions.has({ toolCallId: event.toolCallId })

다음을 사용하여 일시 중단된 Tool을 재개합니다.session.respondToToolSuspension().

후속 조치

session.followUps실행이 진행되는 동안 제출된 메시지의 FIFO 대기열을 소유합니다.

session.followUps.count()

대기 중인 후속 작업 수를 반환합니다.

const queued = session.followUps.count()

session.followUps.isEmpty()

후속 큐가 비어 있는지 여부를 반환합니다.

if (!session.followUps.isEmpty()) {
  // Messages are waiting to be processed
}

승인

session.approval보류 중인 Tool 승인 게이트를 소유하고 있습니다.

session.approval.isArmed()

Tool이 현재 승인 결정을 기다리고 있는지 여부를 반환합니다.

if (session.approval.isArmed()) {
  // Show the approval prompt
}

다음으로 응답session.respondToToolApproval().

표시 상태

session.displayState는 UI 렌더링의 기반이 되는 표준 AgentControllerDisplayState 스냅샷과, 모든 세션 이벤트에 맞춰 이를 동기화하는 리듀서를 소유합니다.

session.displayState.get()

UI 렌더링을 위한 현재 AgentControllerDisplayState 스냅샷을 반환합니다.

const displayState = session.displayState.get()

session.displayState.restoreTasks(tasks)

UI가 지속된 작업 Tool 기록을 재생한 후 스냅샷의 작업 부분을 복원합니다. 이는 스냅샷의 순수한 업데이트이며 이벤트를 발생시키지 않으므로 호출한 후 명시적으로 다시 렌더링됩니다.

session.displayState.restoreTasks(replayedTasks)

모든 이벤트가 끝날 때마다 세션은 최신 스냅샷과 함께 display_state_changed를 내보냅니다. session.subscribe()로 구독하거나 session.displayState.get()에서 현재 값을 읽으세요.

상태

session.state는 대화의 스키마 검증된 AgentController 상태를 소유합니다. 현재 스냅샷을 보관하며 AgentController에 전달된 stateSchema를 기준으로 업데이트의 유효성을 검사합니다. 업데이트는 직렬화되며 변경될 때마다 state_changed 이벤트를 내보냅니다.

session.state.get()

현재 상태 스냅샷의 읽기 전용 복사본을 반환합니다.

const state = session.state.get()

session.state.set(updates)

부분 업데이트를 상태에 병합합니다. 업데이트가 대기열에 추가되므로 동시 호출이 순서대로 적용되고 스키마에 대한 유효성 검사를 거친 후 변경된 키와 함께 state_changed를 내보냅니다.

await session.state.set({ yolo: true })

session.state.update(updater)

현재 스냅샷을 대상으로 업데이터를 실행하고 쓰기 대기열 내에서 결과를 원자적으로 적용합니다. 최신 상태를 확인해야 하는 읽기-수정-쓰기 변경에 사용하세요. 업데이터는 병합할 updates, 내보낼 선택적 events, 그리고 update()가 확인하는 result 값을 반환합니다.

const added = await session.state.update(current => ({
  updates: { count: (current.count ?? 0) + 1 },
  result: (current.count ?? 0) + 1,
}))

지속성 경계

Session은 라이브 런타임 객체입니다. 이벤트 버스, 임의의 session.state, 권한 규칙, 권한 부여, 대기 중인 승인, 일시 중지, 후속 메시지, 실행 상태 및 스트림 상태는 컨트롤러나 프로세스를 다시 생성할 때 자동으로 유지되지 않습니다. 세션을 다시 생성할 때 호스트가 이러한 상태를 복원해야 합니다. 구성된 스토리지를 사용하면 스레드, 메시지 및 토큰 사용량이 유지됩니다. 스레드 설정은 모드 및 Model 선택을 복원합니다. 관찰 Memory 설정과 Agent 유형별 재정의를 포함한 하위 Agent Model 선택도 복원할 수 있습니다. 채팅 채널은 저장된 스레드에 다시 매핑될 수 있지만, 채널 간 상태와 자동 승인 상태를 관리하는 AgentControllerChannels는 메모리에 유지됩니다.

관련된

• AgentController 클래스
• AgentController 개요
• 스레드와 상태
• Tool 승인