> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viamoss.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK 옵션

> AgentProvider config를 통한 Moss 동작 구성

## 개요

SDK 설정 옵션을 사용하면 애플리케이션 코드에서 직접 Moss 동작을 사용자 정의할 수 있습니다. 이러한 설정은 지정 시 **대시보드 기본값을 재정의**하여 개발자에게 배포, 환경 또는 사용자 세그먼트별로 세밀한 제어를 제공합니다.

<Info>
  **우선순위 알림:** SDK 설정 옵션은 대시보드 설정보다 우선합니다.
  코드에서 옵션을 구성하면 대시보드에서 설정한 값을 재정의합니다. 이를
  통해 개발자는 대시보드 설정을 기본값으로 사용하면서 배포별로 동작을
  사용자 정의할 수 있습니다.
</Info>

***

## 필수 옵션

`AgentProvider` config에 다음 옵션을 제공해야 합니다:

```tsx theme={null}
import { AgentProvider, AssistantButton } from '@viamoss/moss-sdk';

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
}}>
  <AssistantButton />
</AgentProvider>
```

| 옵션              | 타입                      | 설명                 |
| --------------- | ----------------------- | ------------------ |
| `apiUrl`        | `string`                | Moss API 엔드포인트 URL |
| `applicationId` | `string`                | 대시보드의 고유 애플리케이션 ID |
| `userId`        | `string`                | 현재 사용자의 고유 식별자     |
| `getJwt`        | `() => Promise<string>` | JWT 토큰을 반환하는 함수    |

<Warning>
  `userId`는 사용자의 안정적인 식별자여야 합니다. PII(이메일, 이름)를
  직접 사용하지 마세요 - 대신 해시되거나 익명화된 식별자를 사용하세요.
</Warning>

***

## 일반 옵션

SDK 동작을 사용자 정의하는 데 자주 사용되는 옵션입니다:

### 언어

SDK 인터페이스의 UI 언어를 설정합니다.

```tsx theme={null}
<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  language: 'ko',  // 'en', 'ko' 또는 자동 감지를 위해 undefined
}}>
  <AssistantButton />
</AgentProvider>
```

**기본값:** `undefined` (브라우저 언어 자동 감지)

<Tip>
  사용자의 브라우저 언어 기본 설정을 자동으로 사용하려면 undefined로
  두세요.
</Tip>

### 비전

스크린샷 분석 기능을 활성화 또는 비활성화합니다.

```tsx theme={null}
<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  useVision: true,  // 시각적 컨텍스트 활성화
}}>
  <AssistantButton />
</AgentProvider>
```

**기본값:** `true` (대시보드에서)

### 세션 녹화

사용자 세션이 리플레이를 위해 녹화되는지 여부를 제어합니다.

```tsx theme={null}
<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  enableSessionRecording: false,  // 개인정보에 민감한 사용자를 위해 비활성화
}}>
  <AssistantButton />
</AgentProvider>
```

**기본값:** `true` (대시보드에서)

### 화면 히스토리

AI 컨텍스트에 사용자 액션 히스토리를 포함합니다.

```tsx theme={null}
<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  enableScreenHistoryRecording: true,
}}>
  <AssistantButton />
</AgentProvider>
```

**기본값:** `true` (대시보드에서)

***

## 외관 (Appearance)

Moss 어시스턴트 UI의 비주얼 테마를 사용자 정의합니다.

### 프리셋 사용

```tsx theme={null}
<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  appearance: 'blue',  // 프리셋 테마 사용
}}>
  <AssistantButton />
</AgentProvider>
```

**사용 가능한 프리셋:**

| 프리셋        | 설명                     |
| ---------- | ---------------------- |
| `'blue'`   | 글래스모피즘 효과가 있는 기본 블루 테마 |
| `'purple'` | 단색 배경의 퍼플 테마           |

### 커스텀 외관

부분 객체를 전달하여 특정 속성을 재정의합니다:

```tsx theme={null}
<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  appearance: {
    colors: {
      primary: '#3b82f6',
      primaryLight: '#60a5fa',
    },
    modal: {
      defaultPosition: { right: 20, bottom: 20 },
      defaultSize: { width: 400, height: 600 },
    },
    effects: {
      glassmorphism: true,
    },
  },
}}>
  <AssistantButton />
</AgentProvider>
```

### 사용자 정의 가능한 속성

| 카테고리          | 속성                                                                                                                                                                                   |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `colors`      | `primary`, `primaryLight`, `primaryLighter`, `userMessage`, `assistantMessage`, `headerBackground`, `inputAreaBackground`, `modalBackground`, `text.*`, `border`, `success`, `error` |
| `typography`  | `fontFamily`, `fontSize.*`, `lineHeight.*`                                                                                                                                           |
| `spacing`     | `3xs`, `2xs`, `xs`, `sm`, `md` 등                                                                                                                                                     |
| `radius`      | `sm`, `md`, `lg`, `xl`                                                                                                                                                               |
| `shadows`     | `sm`, `md`, `lg`                                                                                                                                                                     |
| `effects`     | `glassmorphism`, `glassBlur`, `glassOpacity`                                                                                                                                         |
| `inputBar`    | `roundedTop`, `topShadow`                                                                                                                                                            |
| `progressBar` | `height`                                                                                                                                                                             |
| `modal`       | `defaultPosition`, `defaultSize`                                                                                                                                                     |

<Tip>
  부분 객체는 기본 테마와 깊은 병합(deep-merge)됩니다. 재정의하려는 속성만 지정하면 됩니다.
</Tip>

***

## 세션 옵션

세션 관리 동작을 구성합니다:

```tsx theme={null}
<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  sessionConfig: {
    inactivityTimeout: 60,
    maxSessionAge: 4,
    showNotification: true,
  },
}}>
  <AssistantButton />
</AgentProvider>
```

| 옵션                  | 타입        | 기본값    | 설명                |
| ------------------- | --------- | ------ | ----------------- |
| `inactivityTimeout` | `number`  | `30`   | 세션 만료 전 비활성 시간(분) |
| `maxSessionAge`     | `number`  | `2`    | 최대 세션 지속 시간(시간)   |
| `showNotification`  | `boolean` | `true` | 새 세션 시 알림 표시      |

***

## 개발자 옵션

디버깅 및 사용자 정의를 위한 고급 설정입니다:

### 스크린샷 모드

```tsx theme={null}
<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  screenshotMode: 'viewport',  // 'fullpage' 또는 'viewport'
}}>
  <AssistantButton />
</AgentProvider>
```

**기본값:** `'fullpage'`

| 값          | 설명                 |
| ---------- | ------------------ |
| `fullpage` | 전체 스크롤 가능한 페이지를 캡처 |
| `viewport` | 보이는 부분만 캡처         |

<Tip>
  페이지가 매우 긴 앱의 경우 처리 시간을 줄이기 위해 `viewport`를
  사용하세요.
</Tip>

### 로그 레벨

```tsx theme={null}
import { AgentProvider, AssistantButton, LogLevel } from '@viamoss/moss-sdk';

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  logLevel: LogLevel.DEBUG,  // DEBUG, INFO, WARN, ERROR, SILENT
}}>
  <AssistantButton />
</AgentProvider>
```

**기본값:** `LogLevel.INFO`

`logLevel`은 문자열이 아니라 SDK가 내보내는 `LogLevel` 열거형 값을 받습니다. 각 레벨은 자신보다 심각한 레벨을 모두 포함합니다 (`DEBUG`는 모든 것을 표시하고, `SILENT`은 로깅을 비활성화합니다).

### 디버그 모드

```tsx theme={null}
<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  debugMode: true,
}}>
  <AssistantButton />
</AgentProvider>
```

**기본값:** `false`

문제 해결을 위한 자세한 로깅 및 디버그 기능을 활성화합니다.

### DOM 대상 셀렉터

```tsx theme={null}
<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  observeTargetSelector: '#main-content',
}}>
  <AssistantButton />
</AgentProvider>
```

**기본값:** `'body'`

관찰할 DOM 요소의 CSS 셀렉터입니다. 페이지의 특정 부분으로 관찰을 제한하려면 이를 변경하세요.

### DOM 안정성

SDK가 페이지가 안정화되기를 기다리는 방식을 구성합니다:

```tsx theme={null}
<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  stability: {
    maxTotalWaitMs: 15000,
    layers: {
      networkIdle: true,
      domMutations: true,
      loadingIndicators: false,
      frameReadiness: true,
      resourceQuiet: true,
      layoutShift: false,
      browserIdle: true,
      finalFrame: true,
    },
    domMutations: {
      quietPeriodMs: 1000,
    },
  },
}}>
  <AssistantButton />
</AgentProvider>
```

<Tip>
  자세한 레이어별 문서는 [SDK 고급 설정](/ko/sdk/advanced#stability-tuning)
  가이드를 참조하세요.
</Tip>

***

## 전체 TypeScript 인터페이스

SDK 설정을 위한 전체 TypeScript 인터페이스입니다:

```typescript theme={null}
interface MossConfig {
  // 필수
  apiUrl: string;
  applicationId: string;
  userId: string;
  getJwt: () => Promise<string>;

  // 애플리케이션 기능
  useVision?: boolean;
  language?: 'en' | 'ko';
  appearance?: AppearanceInput;  // 'blue' | 'purple' | 커스텀 객체

  // 녹화 및 히스토리
  enableSessionRecording?: boolean;
  enableScreenHistoryRecording?: boolean;

  // 세션 관리
  sessionConfig?: {
    inactivityTimeout?: number;
    maxSessionAge?: number;
    showNotification?: boolean;
  };

  // 기술 설정
  logLevel?: LogLevel;  // 열거형: DEBUG, INFO, WARN, ERROR, SILENT
  debugMode?: boolean;
  screenshotMode?: 'fullpage' | 'viewport';
  observeTargetSelector?: string;

  // DOM 안정성
  stability?: {
    maxTotalWaitMs?: number;
    layers?: {
      networkIdle?: boolean;
      domMutations?: boolean;
      loadingIndicators?: boolean;
      frameReadiness?: boolean;
      resourceQuiet?: boolean;
      layoutShift?: boolean;
      browserIdle?: boolean;
      finalFrame?: boolean;
    };
    domMutations?: {
      quietPeriodMs?: number;
    };
  };
}
```

***

## SDK에서 사용할 수 없는 설정

다음 설정은 대시보드를 통해서만 구성할 수 있습니다:

* **AI 어시스턴트 지침** - AI를 위한 사용자 정의 지침
* **API 키** - 인증 자격 증명
* **도메인 접근 제어** - 허용 도메인 목록
* **벡터 저장소 설정** - RAG 시스템 설정

<Warning>
  이러한 설정은 보안상의 이유로 대시보드 전용입니다. 애플리케이션 전체
  동작 및 인증에 영향을 미칩니다.
</Warning>

***

## 다음 단계

<CardGroup cols={2}>
  <Card title="예시" icon="lightbulb" href="/ko/configurations/examples">
    다양한 사용 사례에 대한 전체 설정 예시 보기
  </Card>

  <Card title="대시보드 설정" icon="browser" href="/ko/configurations/dashboard-settings">
    대시보드에서 애플리케이션 기본값 구성
  </Card>
</CardGroup>