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

# 세션

:::실험적

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

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

## 사용예

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

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

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

```typescript
const tags = session.getTags()
```

보고:`Record<string, string>`

#### `subscribe(listener)`

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

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

unsubscribe()
```

보고:`() => void`

### 메시지 및 실행 제어

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

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

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

#### `steer({ content, requestContext? })`

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

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

#### `followUp({ content, requestContext? })`

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

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

#### `getCurrentRunId()`

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

```typescript
const runId = session.getCurrentRunId()
```

보고:`string | null`

#### `abort()`

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

```typescript
session.abort()
```

### 작업공간

#### `getWorkspace()`

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

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

보고:`Workspace`

### 세션 부여

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

#### `grantCategory(category)`

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

```typescript
session.grantCategory('edit')
```

#### `grantTool(toolName)`

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

```typescript
session.grantTool('mastra_workspace_execute_command')
```

#### `getGrants()`

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

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

#### `hasCategoryGrant(category)`

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

```typescript
const allowed = session.hasCategoryGrant('edit')
```

보고:`boolean`

#### `hasToolGrant(toolName)`

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

```typescript
const allowed = session.hasToolGrant('write_file')
```

보고:`boolean`

### Tool 승인

#### `resolveToolApproval(toolName)`

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

```typescript
const policy = session.resolveToolApproval('execute_command')
```

보고:`PermissionPolicy`

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

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

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

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

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

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

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

### 토큰 사용

#### `getTokenUsage()`

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

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

## 신원

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

### `session.identity.getId()`

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

```typescript
const sessionId = session.identity.getId()
```

### `session.identity.getOwnerId()`

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

```typescript
const ownerId = session.identity.getOwnerId()
```

### `session.identity.getResourceId()`

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

```typescript
const resourceId = session.identity.getResourceId()
```

### `session.identity.getDefaultResourceId()`

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

```typescript
const defaultResourceId = session.identity.getDefaultResourceId()
```

리소스 ID를 변경하려면 [`controller.setResourceId()`](https://mastra.zisheng.pro/ko/reference/agent-controller/agent-controller-class)를 사용하세요. 이 메서드는 활성 스레드도 지웁니다. 세션 `id`와 `ownerId`는 리소스 전환의 영향을 받지 않습니다.

## 실

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

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

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

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

보고:`Promise<AgentControllerThread>`

### `session.thread.rename({ title })`

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

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

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

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

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

보고:`Promise<AgentControllerThread>`

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

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

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

### `session.thread.delete({ threadId })`

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

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

### `session.thread.getId()`

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

```typescript
const threadId = session.thread.getId()
```

### `session.thread.list(options?)`

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

```typescript
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`을 반환합니다.

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

### `session.thread.listActiveMessages(options?)`

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

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

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

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

```typescript
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`을 반환합니다.

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

### `session.thread.firstUserMessages({ threadIds })`

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

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

### `session.thread.getSetting({ key })`

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

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

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

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

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

### `session.thread.deleteSetting({ key })`

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

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

## 방법

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

### `session.mode.get()`

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

```typescript
const modeId = session.mode.get()
```

### `session.mode.resolve()`

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

```typescript
const mode = session.mode.resolve()
```

### `session.mode.switch({ modeId })`

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

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

## Model

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

### `session.model.get()`

활성 Model ID를 반환합니다.

```typescript
const modelId = session.model.get()
```

### `session.model.displayName()`

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

```typescript
const name = session.model.displayName()
```

### `session.model.hasSelection()`

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

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

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

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

```typescript
// 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`를 반환합니다.

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

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

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

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

```typescript
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`를 반환합니다.

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

## 권한

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

### `session.permissions.getRules()`

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

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

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

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

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

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

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

```typescript
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`을 반환합니다.

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

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

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

```typescript
// 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`을 반환합니다.

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

### `session.run.isRunning()`

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

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

## 개울

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

### `session.stream.activeRunId()`

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

```typescript
const runId = session.stream.activeRunId()
```

### `session.stream.isActive()`

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

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

## 정지

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

### `session.suspensions.hasPending()`

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

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

### `session.suspensions.has({ toolCallId })`

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

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

다음을 사용하여 일시 중단된 Tool을 재개합니다.[`session.respondToToolSuspension()`](#tool-approvals).

## 후속 조치

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

### `session.followUps.count()`

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

```typescript
const queued = session.followUps.count()
```

### `session.followUps.isEmpty()`

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

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

## 승인

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

### `session.approval.isArmed()`

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

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

다음으로 응답[`session.respondToToolApproval()`](#tool-approvals).

## 표시 상태

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

### `session.displayState.get()`

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

```typescript
const displayState = session.displayState.get()
```

### `session.displayState.restoreTasks(tasks)`

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

```typescript
session.displayState.restoreTasks(replayedTasks)
```

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

## 상태

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

### `session.state.get()`

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

```typescript
const state = session.state.get()
```

### `session.state.set(updates)`

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

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

### `session.state.update(updater)`

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

```typescript
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 클래스](https://mastra.zisheng.pro/ko/reference/agent-controller/agent-controller-class)
- [AgentController 개요](https://mastra.zisheng.pro/ko/docs/harness/agent-controller)
- [스레드와 상태](https://mastra.zisheng.pro/ko/docs/harness/agent-controller)
- [Tool 승인](https://mastra.zisheng.pro/ko/docs/harness/agent-controller)