@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/ko-KR/observability.md

@@ -0,0 +1,294 @@
+---
+title: "관측성"
+description: "에이전트 추적, 평가, 피드백, A/B 실험 및 내장 대시보드 — 모두 구성이 필요하지 않습니다."
+---
+
+# 에이전트 관찰 가능성
+
+모든 에이전트 기반 앱은 즉시 관찰이 가능합니다. 추적, 자동화된 평가, 사용자 피드백 및 A/B 실험은 구성 없이 작동합니다. 모든 데이터는 앱의 자체 SQL 데이터베이스에 있습니다.
+
+이 페이지에서는 데이터베이스에 저장된 추적, 비용, 평가 및 피드백과 같은 _에이전트 품질_ 지표를 다룹니다. _product_ 분석(PostHog/Mixpanel/Amplitude로 흐르는 앱 이벤트)에 대해서는 [Tracking](/docs/tracking)를 참조하세요.
+
+## "평가"/"관찰 가능성"이라는 세 가지 — 내가 원하는 것은 무엇인가요? {#which}
+
+이 세 페이지는 혼동하기 쉽습니다. 질문하고 있는 항목을 선택하세요.
+
+| 페이지                                                 | 답변하는 질문                                              | 실행시                            | 우려        |
+| ------------------------------------------------------ | ---------------------------------------------------------- | --------------------------------- | ----------- |
+| **관측 가능성 평가**(이 페이지, _Evals_ 탭)            | "실제 생산은 어떻게 진행되었나요?"                         | 수동, 매 실행 후(LLM-판사 샘플링) | 품질        |
+| **[CI Eval Gate](/docs/evals)** (`*.eval.ts`)          | "에이전트가 이 고정 입력에 대해 올바른 작업을 수행합니까?" | 활성, 결정적, CI/배포 게이트      | 품질        |
+| **[Observational Memory](/docs/observational-memory)** | "이 긴 스레드가 저렴하고 창 안에 남아 있습니까?"           | 긴 스레드의 배경 압축             | 비용 / 상황 |
+
+관찰 가능성과 CI 평가 게이트는 둘 다 _품질_ 점수를 매기지만 반대쪽 끝, 즉 실제 트래픽의 수동적 사후 점수와 고정 입력에 대한 활성 통과/실패 확인의 점수를 매깁니다. 관찰 기억은 품질과 관련이 없습니다. 토큰 비용과 컨텍스트 창 압박에 관한 것입니다.
+
+## 자동으로 캡처되는 내용 {#captured}
+
+사용자가 메시지를 보내면 프레임워크는 자동으로 다음을 기록합니다.
+
+- **토큰 사용** — 입력, 출력, 캐시 읽기, 캐시 쓰기
+- **비용** — 토큰 수 및 모델 가격으로 계산
+- **대기 시간** — 도구 호출당 총 지속 시간 및 시간
+- **도구 호출** — actions가 호출된, 성공/오류 상태, 기간
+- **자동 평가** — 매 실행 후 5개의 품질 점수가 계산됩니다.
+
+코드 변경이 필요하지 않습니다. 계측기는 `production-agent.ts`에 투명하게 연결됩니다.
+
+```an-diagram title="Every run feeds the loop" summary="One agent run produces a trace, automated scores, and a feedback hook — all stored in the app's own SQL and surfaced on the dashboard. Experiments split traffic across config variants."
+{
+  "html": "<div class=\"obs-loop\"><div class=\"diagram-node\">Agent run<br><small class=\"diagram-muted\">production-agent.ts</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Captured automatically</span><small class=\"diagram-muted\">tokens &middot; cost &middot; latency &middot; tool calls</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">Traces &amp; spans</div><div class=\"diagram-box\">Evals (5 scorers + LLM judge)</div><div class=\"diagram-box\">Feedback &amp; frustration index</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node ok\">Dashboard<br><small class=\"diagram-muted\">scoped to the signed-in user</small></div></div>",
+  "css": ".obs-loop{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.obs-loop .diagram-col{display:flex;flex-direction:column;gap:8px}.obs-loop .diagram-arrow{font-size:22px;line-height:1}.obs-loop .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## 대시보드 {#dashboard}
+
+단일 경로를 사용하여 모든 템플릿에 대시보드를 추가하세요.
+
+```tsx
+// app/routes/observability.tsx
+import { ObservabilityDashboard } from "@agent-native/core/client";
+
+export default function ObservabilityPage() {
+  return (
+    <div className="min-h-screen bg-background p-6">
+      <ObservabilityDashboard />
+    </div>
+  );
+}
+```
+
+모든 데이터의 범위는 로그인한 사용자로 제한됩니다. 현재는 교차 사용자 관리 보기가 없습니다.
+
+대시보드에는 5개의 탭이 있습니다:
+
+| 탭         | 표시 내용                                                                    |
+| ---------- | ---------------------------------------------------------------------------- |
+| **개요**   | 주요 지표 — 실행, 비용, 대기 시간, 도구 성공률, 만족도, 평가 점수            |
+| **대화**   | 개별 범위에 대한 드릴다운이 포함된 추적 목록(agent_run, llm_call, tool_call) |
+| **평가**   | 기준별 자동 평가 점수, 시간 경과에 따른 추세                                 |
+| **실험**   | 상태 배지가 포함된 A/B 테스트 목록, 신뢰 구간이 포함된 변형 결과             |
+| **피드백** | 좋아요/비추천 스트림, 카테고리 분류, 불만 점수                               |
+
+## 사용자 피드백 {#feedback}
+
+### 명시적인 피드백
+
+좋아요/아래 버튼은 채팅 UI의 모든 에이전트 메시지에서 인라인으로 렌더링됩니다. 아래로 내리면 카테고리 팝오버가 열립니다(부정확함, 도움이 되지 않음, 잘못된 도구, 너무 느림). 이는 `AssistantChat.tsx`에 자동으로 연결됩니다.
+
+### 암묵적 피드백(좌절지수)
+
+프레임워크는 대화 신호에서 좌절 지수(0-100)를 계산합니다.
+
+| 신호        | 무게 | 탐지 내용                             |
+| ----------- | ---- | ------------------------------------- |
+| 다른 표현   | 30%  | 사용자가 비슷한 메시지를 반복함       |
+| 재시도 패턴 | 20%  | "다시 시도하세요", "아니요, 틀렸어요" |
+| 포기        | 20%  | 응답 직후 세션이 종료됩니다           |
+| 감정        | 15%  | 부정적인 언어 패턴                    |
+| 길이 추세   | 15%  | 메시지 길이 감소                      |
+
+점수 해석: 0-20 = 정상, 20-40 = 마찰, 40-60 = 불만족, 60+ = 세션 중단.
+
+## 자동 평가 {#evals}
+
+매 에이전트 실행 후 5개의 결정론적 득점자가 실행됩니다.
+
+| 기준                | 측정 대상                                                | 점수 범위 |
+| ------------------- | -------------------------------------------------------- | --------- |
+| `tool_success_rate` | 오류가 없는 도구 호출 비율                               | 0-1       |
+| `step_efficiency`   | 도구 사용 실행에 대해 과도한 LLM 반복에 불이익을 줍니다. | 0-1       |
+| `latency_score`     | 10초/도구 기준선에 대해 정규화됨                         | 0-1       |
+| `cost_efficiency`   | 비용 기준에 대해 정규화됨                                | 0-1       |
+| `error_recovery`    | 에이전트가 도구 오류를 복구했습니까?                     | 0 또는 1  |
+
+### LLM-판사(선택)
+
+`evalSampleRate`를 설정하여 샘플링된 LLM 기반 평가를 활성화합니다.
+
+```ts
+import { putSetting } from "@agent-native/core/settings";
+
+await putSetting("observability-config", {
+  enabled: true,
+  evalSampleRate: 0.05, // 5% of runs
+});
+```
+
+맞춤 기준은 자연어 루브릭을 사용합니다.
+
+```ts
+const criteria = {
+  name: "helpfulness",
+  description: "Was the response helpful and complete?",
+  rubric: "0.0 = unhelpful, 0.5 = partially helpful, 1.0 = fully resolved",
+};
+```
+
+## A/B 실험 {#experiments}
+
+다양한 모델, 온도 또는 에이전트 구성을 테스트하세요.
+
+```ts
+// Create via API
+POST /_agent-native/observability/experiments
+{
+  "name": "model-a-vs-b",
+  "variants": [
+    { "id": "control", "weight": 50, "config": { "model": "<your-model-id>" } },
+    { "id": "treatment", "weight": 50, "config": { "model": "<other-model-id>" } }
+  ],
+  "metrics": ["cost", "latency", "satisfaction"]
+}
+
+// Start the experiment
+PUT /_agent-native/observability/experiments/:id
+{ "status": "running" }
+```
+
+`<your-model-id>` / `<other-model-id>` 대신 엔진에서 허용하는 실제 모델 식별자를 사용하십시오(모델 이름은 자주 변경됩니다. 현재 ID는 공급자/엔진을 확인하세요). 에이전트 루프는 자동으로 사용자의 변형을 확인하고 구성 재정의를 적용합니다. 할당에서는 일관된 해싱을 사용합니다. 동일한 사용자는 항상 동일한 변형을 얻습니다.
+
+```an-diagram title="Consistent-hash variant assignment" summary="Each user hashes to a stable variant, the loop applies that variant's config override, and results roll up per variant with confidence intervals."
+{
+  "html": "<div class=\"exp\"><div class=\"diagram-node\">User id<br><small class=\"diagram-muted\">consistent hash</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-card\"><span class=\"diagram-pill\">control &middot; 50%</span><small class=\"diagram-muted\">config override A</small></div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">treatment &middot; 50%</span><small class=\"diagram-muted\">config override B</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Results per variant<br><small class=\"diagram-muted\">cost &middot; latency &middot; satisfaction</small></div></div>",
+  "css": ".exp{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.exp .diagram-col{display:flex;flex-direction:column;gap:8px}.exp .diagram-card{display:flex;flex-direction:column;gap:2px;padding:8px 12px}.exp .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## 구성 {#config}
+
+모든 설정은 `observability-config` 키에 저장됩니다:
+
+```ts
+{
+  enabled: true,           // Master switch
+  capturePrompts: false,   // Store prompt content in traces
+  captureToolArgs: false,  // Store action input arguments
+  captureToolResults: false, // Store action results
+  evalSampleRate: 0,       // 0-1, fraction of runs to LLM-judge
+  exporters: []            // OTLP export targets
+}
+```
+
+```an-callout
+{
+  "tone": "info",
+  "body": "Content is **redacted by default** — only token counts, costs, and timing are stored. `capturePrompts`, `captureToolArgs`, and `captureToolResults` are opt-in; turn them on only when you need prompt/argument content for debugging."
+}
+```
+
+## API 엔드포인트 {#api}
+
+`/_agent-native/observability/`에 모두 자동 마운트됨:
+
+| 방법 | 경로                       | 목적                       |
+| ---- | -------------------------- | -------------------------- |
+| GET  | `/`                        | 개요 통계                  |
+| GET  | `/traces`                  | 추적 요약 나열             |
+| GET  | `/traces/:runId`           | 추적 세부정보(요약 + 범위) |
+| GET  | `/traces/:runId/evals`     | 실행 평가                  |
+| POST | `/feedback`                | 의견 제출                  |
+| GET  | `/feedback`                | 피드백 나열                |
+| GET  | `/feedback/stats`          | 피드백 집계                |
+| GET  | `/satisfaction`            | 만족도 점수                |
+| GET  | `/evals/stats`             | 평가 통계                  |
+| POST | `/experiments`             | 실험 만들기                |
+| GET  | `/experiments`             | 실험 나열                  |
+| GET  | `/experiments/:id`         | 실험 세부정보 가져오기     |
+| PUT  | `/experiments/:id`         | 실험 업데이트              |
+| POST | `/experiments/:id/results` | 계산 결과                  |
+| GET  | `/experiments/:id/results` | 결과 얻기                  |
+
+모든 엔드포인트는 `?since=N`(ms 타임스탬프) 및 `?limit=N` 쿼리 매개변수를 지원합니다.
+
+## 외부 플랫폼으로 내보내기 {#export}
+
+Langfuse, Datadog, Grafana 또는 모든 OTel 호환 백엔드로 추적을 보냅니다.
+
+```ts
+await putSetting("observability-config", {
+  enabled: true,
+  exporters: [
+    {
+      type: "otlp",
+      endpoint: "https://cloud.langfuse.com/api/public/otel",
+      headers: { Authorization: "Bearer sk-..." },
+    },
+  ],
+});
+```
+
+프레임워크는 OpenTelemetry GenAI 사양과 호환되는 `gen_ai.*` 의미 체계 규칙 범위를 내보냅니다.
+
+## OpenTelemetry 범위 {#otel}
+
+위의 `exporters` 구성(OTLP 엔드포인트에 사내 추적을 제공)과 별도로 에이전트 루프는 모든 실행, 모델 호출 및 도구 호출에 대해 **실시간 OpenTelemetry 범위**를 내보낼 수도 있습니다. 따라서 이미 OTel 수집기를 실행하는 호스트는 나머지 분산 추적과 함께 에이전트 활동을 볼 수 있습니다.
+
+이 레이어는 **선택 사항이며 기본적으로 작동하지 않습니다**:
+
+- `@opentelemetry/api`는 **선택적 종속성**입니다. 설치되지 않은 경우 도우미는 자동 무작동 상태로 저하됩니다. 여기서는 에이전트 루프에 어떤 것도 발생하지 않습니다.
+- API 패키지가 _is_ 존재하는 경우에도 기본 무작동 추적 프로그램이 제공됩니다. 스팬은 **호스트가 `TracerProvider`**(`@opentelemetry/sdk-node` 또는 이와 유사한 방법을 통해)를 등록한 후에만 현실이 됩니다. 프레임워크는 의도적으로 무거운 SDK/exporter 패키지에 의존하거나 공급자 자체를 등록하지 **않습니다**. 계측은 임베딩 앱에 의해 선택됩니다.
+
+따라서 OTel을 연결하지 않았을 때의 비용은 호출당 몇 번의 캐시된 속성 읽기입니다. 이 기능을 켜려면 api 패키지와 SDK를 설치하고 다른 Node 서비스와 동일한 방식으로 서버 시작 시 공급자를 등록하세요.
+
+에이전트 루프는 세 가지 범위 종류를 내보냅니다.
+
+| 스팬        | 언제                  | 속성                                                              |
+| ----------- | --------------------- | ----------------------------------------------------------------- |
+| `agent.run` | 에이전트 실행당 한 번 | `agent.run_id`, `agent.thread_id`, `agent.user_id`, `agent.model` |
+| `tool.call` | 액션 호출당 한 번     | `tool.name` 및 성공/오류 상태                                     |
+| `llm.call`  | 모델 호출당           | 타이밍 + 정상/오류 상태                                           |
+
+스팬은 OK/ERROR 상태로 완료되고 실패 시 오류 메시지를 기록합니다. 0/감시 속성 값은 정리되어 범위가 노이즈로 인해 복잡해지지 않습니다. 이 OTel 레이어는 위의 대시보드를 구동하는 내부 `agent_trace_spans`/`agent_trace_summaries` 테이블에 순전히 추가됩니다. 둘 다 동일한 실행 이벤트에서 생성됩니다.
+
+## 오류 보고(Sentry) {#sentry}
+
+DSN가 구성되면 Nitro 경로 핸들러를 이스케이프하는 서버측 오류가 Sentry에 보고됩니다. 이것이 없으면 SDK는 자동으로 작동하지 않으므로 dev에서 환경 변수를 설정하지 않은 상태로 두는 것이 안전합니다. 브라우저 및 서버 이벤트는 동일한 Sentry 프로젝트로 이동할 수 있습니다. 소유권, 볼륨, 할당량 또는 경고 라우팅에 대한 운영 분리를 원하는 경우에만 이를 별도의 프로젝트로 분할하세요.
+
+| 표면               | SDK               | 환경 변수                                                       | 참고                                                                 |
+| ------------------ | ----------------- | --------------------------------------------------------------- | -------------------------------------------------------------------- |
+| 브라우저 / SPA     | `@sentry/browser` | `VITE_SENTRY_CLIENT_DSN`, `SENTRY_CLIENT_DSN` 또는 `SENTRY_DSN` | 클라이언트에서 처리되지 않은 오류와 경로 변경 탐색경로를 캡처합니다. |
+| Nitro 서버         | `@sentry/node`    | `SENTRY_SERVER_DSN` 또는 `SENTRY_DSN`                           | 5xx 응답 및 Nitro 수명 주기 오류를 캡처합니다. 요청별 사용자.        |
+| `agent-native` CLI | `@sentry/node`    | _하드코드_                                                      | 게시된 CLI 바이너리의 충돌 보고서. 사용자가 구성할 수 없습니다.      |
+
+### 서버측 구성 {#sentry-config}
+
+배포 환경(Netlify 대시보드, Cloudflare 비밀 등)에서 `SENTRY_SERVER_DSN` 또는 공유 `SENTRY_DSN`를 설정합니다. 프레임워크는 다음과 같은 Nitro 플러그인을 자동 마운트합니다:
+
+1. 시작 시 `Sentry.init`를 한 번 호출합니다(멱등성 - 여러 플러그인에서 호출해도 안전함).
+2. 모든 API/프레임워크 요청에서 `getSession(event)`를 통해 사용자를 확인하고 `id` / `email` / `username`와 `orgId` 태그를 Sentry의 요청별 격리 범위에 연결합니다. 추가 DB 적중을 방지하기 위해 정적 자산 경로를 건너뜁니다.
+3. 검색 가능한 `route`, `method` 및 `userAgent` 태그를 사용하여 모든 프레임워크 경로 5xx를 캡처합니다.
+
+선택적 손잡이:
+
+- `SENTRY_SERVER_TRACES_SAMPLE_RATE`(float `0`–`1`) — 성능 추적을 선택합니다. 기본값은 `0`입니다(오류만 해당). 잘못된 값은 `0`에 고정됩니다.
+- `AGENT_NATIVE_RELEASE` — `release` 태그를 재정의합니다. 기본값은 `agent-native-server@<core-version>`입니다.
+
+### 템플릿
+
+모든 템플릿은 이를 자동으로 상속하므로 가져올 항목이 없습니다. SSR 앱의 경우 `SENTRY_CLIENT_DSN`, `VITE_SENTRY_CLIENT_DSN` 또는 공유 `SENTRY_DSN`를 런타임에 사용할 수 있을 때 서버는 작은 브라우저 구성 스크립트를 삽입하므로 브라우저 캡처는 Vite 빌드 시간 환경으로 제한되지 않습니다. 사용자 정의 동작(추가 태그, 템플릿당 다른 DSN, 하드 비활성화 Sentry)을 원하는 템플릿은 `server/plugins/sentry.ts`에서 자체 플러그인을 내보내 재정의할 수 있습니다.
+
+```ts
+// server/plugins/sentry.ts
+import { createSentryPlugin } from "@agent-native/core/server";
+export default createSentryPlugin();
+```
+
+CLI의 하드코딩된 DSN는 의도적입니다. 게시된 바이너리는 실행되는 환경에 관계없이 전화 홈 충돌이 발생해야 합니다. 서버 모듈은 오류가 Sentry에 도달해야 하는지 여부를 운영자가 결정하는 고객 환경 내에서 실행되므로 DSN를 하드코딩하지 않습니다.
+
+### 개인정보 보호 및 PII {#privacy}
+
+서버와 CLI 모두 다음을 제거하는 `sendDefaultPii: false` 및 `beforeSend` 후크로 초기화합니다.
+
+- `request.headers.authorization`, `cookie`, `set-cookie`, `proxy-authorization`
+- `request.cookies`
+- `user.ip_address` (동의 없이 자동 수집)
+- `contexts.runtime_env`(프로세스 환경 스냅샷)
+- 최상위 예외 유형이 `ValidationError`인 모든 이벤트(버그가 아닌 예상된 사용자 입력 거부로 처리됨)
+
+`setUser({ id, email, username })`를 통해 명시적으로 설정된 ID 필드는 유지됩니다.
+
+## 다음 단계
+
+- [**Tracking**](/docs/tracking) — 앱 자체 이벤트에 대한 제품 분석(PostHog, Mixpanel, Amplitude)
+- [**Actions**](/docs/actions) — 추적에서 도구 호출로 나타나는 작업
+- [**Security**](/docs/security) — 데이터 범위 지정 및 자격 증명 처리

package/docs/content/locales/ko-KR/observational-memory.md

@@ -0,0 +1,77 @@
+---
+title: "관찰 기억"
+description: "짧은 대화를 건드리지 않고도 긴 에이전트 스레드를 저렴하고 프롬프트 캐시 안정성을 유지하는 배경 3계층 압축(최근 원시 → 관찰 → 반사)"
+---
+
+# 관찰 기억
+
+장기 실행 에이전트 스레드는 모든 메시지, 모든 도구 호출, 모든 결과 등 거대한 기록을 축적합니다. 매 턴마다 전체 기록을 모델로 재생하는 것은 비용이 많이 들고 결국 컨텍스트 창을 날려버립니다. **관찰 메모리(OM)**는 긴 스레드의 오래된 부분을 날짜가 기록된 계층화된 요약으로 압축하므로 모델은 토큰 비용의 일부만으로도 무슨 일이 일어났는지 알 수 있으며 가장 최근의 내용은 그대로 유지됩니다.
+
+OM은 완전히 자동이며 소유자 범위입니다. **짧은 스레드는 영향을 받지 않습니다**: 스레드가 첫 번째 압축 임계값을 넘을 때까지 OM은 작동하지 않으며 컨텍스트는 OM이 없을 때와 마찬가지로 바이트 단위입니다.
+
+## 3개 계층 {#tiers}
+
+OM은 긴 스레드를 가장 최근의 것부터 가장 최근의 것까지 3개의 레이어로 나타냅니다.
+
+| 등급                 | 무엇인가요                                                                                                |
+| -------------------- | --------------------------------------------------------------------------------------------------------- |
+| **반영**             | 최고 레벨, 일단 커지면 관찰 로그에서 요약됩니다. 장호형 요약                                              |
+| **관찰**             | 일자가 기록된 조밀한 항목으로, 일련의 원시 메시지를 무슨 일이 일어났는지에 대한 압축된 기록으로 접습니다. |
+| **최근 원시 메시지** | 마지막 N 턴은 **그대로** 유지되며 절대 접히지 않으므로 에이전트는 항상 최신 컨텍스트를 볼 수 있습니다.    |
+
+```an-diagram title="Three tiers, distilled to recent" summary="The older prefix folds into dated observations and a long-arc reflection; only the most recent turns stay verbatim."
+{
+  "html": "<div class=\"om\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Reflections</span><small class=\"diagram-muted\">long-arc summary, condensed from the observation log</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&uarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Observations</span><small class=\"diagram-muted\">dense, dated entries folding stretches of raw messages</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&uarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill ok\">Recent raw messages</span><small class=\"diagram-muted\">last N turns, kept <strong>verbatim</strong> — never folded</small></div></div>",
+  "css": ".om{display:flex;flex-direction:column-reverse;align-items:stretch;gap:8px}.om .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px}.om .diagram-arrow{text-align:center;font-size:20px;line-height:1}"
+}
+```
+
+각 차례마다 읽기 측은 이를 원시 이전 접두사를 대체하고 최근 원시 창을 그대로 유지하며 압축된 레코드를 신뢰할 수 있는 것으로 처리하도록 모델에 지시하는 자체 레이블이 지정된 단일 `[Observational Memory]` 블록으로 이를 조립합니다(완료된 작업을 다시 실행하지 말고 기록된 결정, 이름, 날짜 및 상태를 신뢰하십시오).
+
+## 압축 실행 방법 {#compaction}
+
+두 번의 패스는 깔끔한 턴 _후에_ **실행 후 잊어버리는 최선의 노력** 단계로 실행되므로 사용자에게 표시되는 응답에 지연 시간을 추가하지 않으며 모든 실패는 무시됩니다.
+
+1. **관찰자** — 스레드의 _unobserved_ 메시지가 관찰 토큰 임계값을 초과하면 해당 메시지를 하나의 조밀한 관찰 항목으로 접습니다.
+2. **리플렉터** — 지속 관찰 로그 자체가 반사 토큰 임계값을 초과하면 관찰을 더 높은 수준의 반영으로 압축합니다.
+
+```an-diagram title="Two best-effort passes after a clean turn" summary="Each pass no-ops below its threshold, so running the compactor every turn is cheap. Failures are swallowed and never add latency."
+{
+  "html": "<div class=\"om-pass\"><div class=\"diagram-node\">Clean turn ends<br><small class=\"diagram-muted\">fire-and-forget</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Observer</span><small class=\"diagram-muted\">unobserved tokens &gt; 30k? &rarr; fold into one observation</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Reflector</span><small class=\"diagram-muted\">observation log &gt; 40k? &rarr; condense into a reflection</small></div></div>",
+  "css": ".om-pass{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.om-pass .diagram-node,.om-pass .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.om-pass .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+둘 다 임계값 아래에서 무작동을 통과하므로 매 회전 후에 압축기를 호출하는 것이 저렴합니다. OM은 휘발성 원시 접두사를 안정적인 압축 텍스트로 대체하기 때문에 긴 스레드가 반복되는 동안 프롬프트 **캐시 안정성**을 유지합니다.
+
+OM 데이터는 소유자(및 존재하는 경우 조직)로 범위가 지정된 앱 자체 SQL 데이터베이스에 있습니다. 이는 프레임워크의 나머지 부분과 동일한 범위 지정 모델입니다. 사용자 간에 공유되지 않습니다.
+
+## 구성 {#config}
+
+기본값은 보수적입니다. 운영자는 `AGENT_NATIVE_OM_*` 환경 변수를 사용하여 배포 시 압축을 다이얼할 수 있습니다(앱 코드를 다시 배포할 필요 없음). 유효하지 않거나 누락된 값은 항상 명명된 기본값으로 대체됩니다.
+
+| 환경 변수                                     | 기본값  | 제어 대상                                                                |
+| --------------------------------------------- | ------- | ------------------------------------------------------------------------ |
+| `AGENT_NATIVE_OM_OBSERVATION_TOKEN_THRESHOLD` | `30000` | 관찰자가 이를 하나의 관찰로 접도록 트리거하는 관찰되지 않은 메시지 토큰. |
+| `AGENT_NATIVE_OM_REFLECTION_TOKEN_THRESHOLD`  | `40000` | Reflector가 반사로 압축되도록 트리거하는 관찰 로그 토큰.                 |
+| `AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT`    | `12`    | 가장 최근 메시지 중 그대로 유지되는 메시지의 수(관찰에 포함되지 않음)    |
+
+관찰자 및 반사기 출력 한도(4000/2000 토큰)는 단일 압축 패스 자체가 예산을 초과하는 것을 방지합니다. `resolveObservationalMemoryConfig({ ... })`를 통해 코드에서 조정할 수 있지만 환경에 노출되지는 않습니다.
+
+> [!TIP]
+> 더 빨리 압축하려면 임계값을 낮추십시오(더 저렴한 긴 스레드, 약간 더 많은 요약). 압축하기 전에 더 많은 원시 기록을 컨텍스트에 유지하도록 설정하세요. 워크플로에 더 긴 축어적 꼬리가 필요한 경우 `AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT`를 더 높게 설정하세요.
+
+## 시작할 때 {#when}
+
+OM은 적어도 하나의 관찰 또는 반영을 생성할 만큼 충분히 긴 스레드의 동작만 변경합니다. 구체적으로:
+
+- 새롭거나 짧은 스레드: 아직 OM 항목이 없습니다 → 컨텍스트는 변경되지 않은 일반 성적표입니다.
+- 관찰 임계값을 초과한 긴 스레드: 이전 접두사는 압축된 `[Observational Memory]` 블록으로 대체되고, 최근 원시 테일은 그대로 유지되며, 토큰 사용량이 크게 감소합니다.
+
+주입은 최선의 노력이며 경계 안전합니다. 안전한 다듬기 지점을 찾을 수 없는 경우(예: 보류 중인 도구 사용/결과 쌍이 창 가장자리에 있는 경우) OM은 보류 중인 도구 결과를 삭제할 위험을 감수하는 대신 다듬기 없이 메모리 블록을 _추가적으로_ 삽입합니다.
+
+## 관련
+
+- [**Using Your Agent**](/docs/using-your-agent) — 앱 옆에 도킹된 에이전트로 작업하는 일상적인 루프입니다.
+- [**Observability**](/docs/observability) — OM의 절감액이 표시되는 실행당 토큰 및 비용 측정항목입니다.
+- [**Custom Agents & Teams**](/docs/agent-teams) — 긴 하위 에이전트 실행은 동일한 압축의 이점을 얻습니다.

package/docs/content/locales/ko-KR/onboarding.md

@@ -0,0 +1,216 @@
+---
+title: "온보딩 및 API 키"
+description: "최초 실행 구성을 위한 설정 체크리스트 — API 키, OAuth 및 공급자 연결"
+---
+
+# 온보딩
+
+에이전트 네이티브 프레임워크에 구축된 앱을 처음 열면 다음이 표시됩니다.
+**설정** 상담원 사이드바의 체크리스트. 첫 실행 구성을 닫아 둡니다
+에이전트 채팅: AI 엔진을 연결하고 선택적으로 앱을 공유 위치로 지정
+인프라를 구축하고 필요할 때만 공급자를 추가하세요.
+
+```an-diagram title="The setup checklist" summary="Only Connect an AI engine is required. The panel tracks completion and auto-hides once everything required is done."
+{
+  "html": "<div class=\"ob\"><div class=\"diagram-card\"><span class=\"diagram-pill warn\">required</span><strong>Connect an AI engine</strong><small class=\"diagram-muted\">Connect Builder (one click) or paste an LLM key</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">optional</span><strong>Database</strong><small class=\"diagram-muted\">set <code>DATABASE_URL</code></small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">optional</span><strong>Authentication</strong><small class=\"diagram-muted\">OAuth / access token</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">optional</span><strong>Email delivery</strong><small class=\"diagram-muted\">Resend / SendGrid</small></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box ok\">all required done &rarr; panel auto-hides</div></div>",
+  "css": ".ob{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.ob .diagram-card{display:flex;flex-direction:column;gap:3px;padding:12px 14px}.ob .diagram-arrow{font-size:22px}"
+}
+```
+
+## 최종 사용자용
+
+### 볼 내용
+
+- 'AI 연결'과 같은 체크리스트가 포함된 상담원 채팅 위의 **설정** 패널
+  엔진', '이메일 전달' 등
+- 상단의 카운터(예: "1/4")는 준비된 단계 수를 보여줍니다.
+- 현재 단계가 확장되었습니다. 완료된 단계에는 녹색 확인 표시가 표시되고 그대로 유지됩니다.
+  열면 읽을 수 있습니다.
+- 필수 단계에는 작은 빨간색 **필수** 알약이 표시됩니다. 패널은 계속 표시됩니다.
+  모든 필수 단계가 완료될 때까지
+- 필요한 모든 작업이 완료되면 패널이 자동으로 숨겨집니다.
+- 오른쪽 상단에 있는 갈매기 모양으로 전체 패널을 접을 수 있습니다. 또는
+  하단의 **Hide setup**으로 완전히 숨겨졌습니다.
+
+### 각 단계를 완료하는 방법
+
+단계는 하나 이상의 **방법**을 제공합니다 — 동일한 사항을 만족시키는 다양한 방법
+요구 사항. 기본 경로가 먼저 표시됩니다. 보조 경로는 컴팩트하게 유지됩니다.
+단계에 여러 동등한 제공자가 있는 경우 선택기 또는 공개 뒤에
+
+- **서비스 연결(한 번의 클릭)** — 예: _관리 대상에 Builder_ 연결
+  AI 게이트웨이. 버튼을 클릭하면 창이 열리고 로그인하면 창이 닫힙니다.
+  단계가 완료로 표시됩니다. 복사할 키가 없습니다.
+- **API 키를 붙여넣거나 양식을 작성하세요** — 예: LLM 공급자, 데이터베이스를 선택하세요.
+  OAuth 제공업체 또는 이메일 제공업체인 경우 값을 붙여넣고 **저장**을 클릭하세요.
+  비밀 필드는 비밀번호 입력을 사용하므로 값이 화면에 표시되지 않습니다. 저장됨
+  값은 로컬 `.env`(또는 작업 공간 설정)에 적용됩니다.
+  [Security](/docs/security)는 그들이 사는 곳입니다.
+- **링크 열기** — 일부 단계는 로그인 페이지 또는 문서를 가리킵니다. 클릭
+  **계속**하고 새 탭에서 흐름을 완료하세요.
+- **상담원에게 문의** — 몇 단계를 거치면 "상담원이 설정하도록 허용" 옵션이 제공됩니다.
+  클릭하면 상담원이 채팅을 통해 안내해 드립니다.
+  외부 설정(OAuth 자격 증명 생성 등)
+
+### 일반적으로 표시되는 기본 제공 단계
+
+- **AI 엔진 연결**(필수) - 유일한 필수 단계입니다. 연결
+  원클릭 관리 게이트웨이의 경우 Builder 또는 보조 공급자 키 열기
+  자신의 LLM 키를 선택하여 붙여넣으세요.
+- **데이터베이스** (선택 사항) — 특정 데이터베이스를 사용하려면 `DATABASE_URL`를 설정하세요.
+  SQL 데이터베이스 연결 문자열.
+- **인증** (선택 사항) — 내장된 이메일/비밀번호 계정은
+  기본값. 해당 경로를 원할 때만 OAuth 또는 액세스 토큰 로그인을 추가하세요.
+- **이메일 전달**(선택 사항) — 비밀번호 재설정을 위해 배포하기 전에 유용합니다.
+  팀 초대 및 알림 공유. 이미 사용하고 있는 제공업체를 이용하세요.
+  로컬 개발은 그것 없이 실행될 수 있습니다.
+
+템플릿은 이 위에 자체 단계를 추가할 수 있습니다. CRM 템플릿은
+"Connect Gmail"를 추가하면 문서 템플릿에 "기본 작업 공간 선택"이 추가될 수 있습니다. 참조
+로그인 설정 세부정보는 [Authentication](/docs/authentication)를 참조하세요.
+
+### 체크리스트로 돌아가기
+
+**설정 숨기기**를 누르면 해당 브라우저 세션에 대한 패널이 사라집니다.
+아직 완료되지 않은 필수 단계는 다음 로드 시 다시 표시됩니다. 한 번
+필요한 모든 작업이 완료되었으며 패널은 영원히 자동으로 숨겨집니다. 아무것도 없습니다.
+할 일이 남았습니다.
+
+## 개발자용
+
+템플릿을 작성하는 경우 온보딩 단계를 등록하여 표시되도록 합니다.
+사용자의 사이드바 체크리스트. 프레임워크는 렌더링, 완료를 처리합니다.
+추적 및 해제 - 단계가 무엇인지, 어떻게 진행되는지 선언하면 됩니다.
+만족합니다.
+
+시스템이 **자동 마운트**됩니다. 템플릿을 얻기 위해 아무것도 연결할 필요가 없습니다.
+4가지 기본 제공 단계(LLM, 데이터베이스, 인증, 이메일). 특정 앱을 추가하려면
+단계(Gmail, Slack, Notion 등), a에서 `registerOnboardingStep()`를 호출
+서버 플러그인.
+
+### 자동 마운트된 경로
+
+모든 경로는 `/_agent-native/onboarding/`에 속합니다:
+
+| 경로                                                | 목적                           |
+| --------------------------------------------------- | ------------------------------ |
+| `GET /_agent-native/onboarding/steps`               | 완료 상태가 포함된 단계 나열   |
+| `POST /_agent-native/onboarding/steps/:id/complete` | 단계 완료 표시(재정의)         |
+| `POST /_agent-native/onboarding/dismiss`            | 온보딩 배너 닫기               |
+| `POST /_agent-native/onboarding/reopen`             | 해제 해제(패널 다시 표시)      |
+| `GET /_agent-native/onboarding/dismissed`           | 읽기 취소 + allComplete 플래그 |
+
+```an-api title="List onboarding steps"
+{
+  "method": "GET",
+  "path": "/_agent-native/onboarding/steps",
+  "summary": "List all registered steps with their completion status",
+  "description": "Drives the sidebar checklist — returns each step's id, title, methods, required flag, and whether `isComplete` currently passes.",
+  "responses": [
+    { "status": "200", "description": "Array of steps with completion status for the current user/app." }
+  ]
+}
+```
+
+### 템플릿에서 단계 추가
+
+```an-annotated-code title="Registering a custom onboarding step"
+{
+  "filename": "server/plugins/my-onboarding.ts",
+  "language": "ts",
+  "code": "import { defineNitroPlugin } from \"@agent-native/core/server\";\nimport { registerOnboardingStep } from \"@agent-native/core/onboarding\";\nimport { listOAuthAccounts } from \"@agent-native/core/oauth-tokens\";\n\nexport default defineNitroPlugin(() => {\n  registerOnboardingStep({\n    id: \"gmail\",\n    order: 100,\n    title: \"Connect Gmail\",\n    description: \"Grant read/send access so the agent can work with email.\",\n    methods: [\n      {\n        id: \"oauth\",\n        kind: \"link\",\n        primary: true,\n        label: \"Sign in with Google\",\n        payload: { url: \"/_agent-native/google/auth-url?scope=mail\", external: false },\n      },\n      {\n        id: \"delegate\",\n        kind: \"agent-task\",\n        label: \"Let the agent set it up\",\n        badge: \"beta\",\n        payload: { prompt: \"Walk me through connecting Gmail. Set env vars as needed.\" },\n      },\n    ],\n    isComplete: async () => {\n      const accounts = await listOAuthAccounts(\"google\");\n      return accounts.length > 0;\n    },\n  });\n});",
+  "annotations": [
+    { "lines": "5", "label": "Auto-mounted", "note": "Register from a Nitro plugin — the framework handles rendering, completion tracking, and dismissal." },
+    { "lines": "7", "label": "Stable id", "note": "Re-registering with the same `id` after defaults load overrides a built-in step." },
+    { "lines": "12-19", "label": "Primary method", "note": "`primary: true` marks the big CTA. `kind: \"link\"` sends the user into the OAuth flow." },
+    { "lines": "20-26", "label": "Delegate path", "note": "`kind: \"agent-task\"` hands the setup to the agent chat with a prompt." },
+    { "lines": "28-31", "label": "Completion check", "note": "`isComplete` runs server-side. OAuth tokens live in the `oauth_tokens` store — check it, not `process.env.GMAIL_REFRESH_TOKEN`." }
+  ]
+}
+```
+
+### 온보딩에서 작업공간 연결 확인
+
+외부 서비스(예: Slack, Google Workspace, GitHub 또는 HubSpot)와 상호작용하는 템플릿을 구축할 때 작업공간이 이미 연결되어 있고 해당 공급자 연결을 애플리케이션에 부여했는지 확인해야 합니다. 이렇게 하면 중앙 관리 연결이 존재할 때 사용자가 로컬 환경 변수에 자격 증명(예: API 키 또는 새로 고침 토큰)을 복제할 필요가 없습니다.
+
+연결 카탈로그 APIs를 사용하여 `isComplete` 콜백에서 연결 준비 상태를 확인할 수 있습니다.
+
+```ts
+import { listWorkspaceConnectionProviderCatalogForApp } from "@agent-native/core/workspace-connections";
+
+// Inside registerOnboardingStep:
+isComplete: async () => {
+  // Check if a managed workspace connection exists and is ready
+  const catalog = await listWorkspaceConnectionProviderCatalogForApp({
+    appId: "mail",
+    templateUse: "mail",
+    provider: "gmail",
+  });
+  const connection = catalog.providers[0];
+
+  if (
+    connection?.readiness.status === "ready" &&
+    connection.workspaceConnection.grantState === "granted"
+  ) {
+    return true;
+  }
+
+  // Fall back to local environment variable check
+  return !!process.env.GMAIL_REFRESH_TOKEN;
+};
+```
+
+연결 공급자 카탈로그 방법의 전체 목록은 [Workspace Connections](/docs/workspace-connections) 문서를 참조하세요.
+
+### 메소드 종류
+
+| 종류               | 페이로드                                              | 사용                                          |
+| ------------------ | ----------------------------------------------------- | --------------------------------------------- |
+| `link`             | `{ url, external? }`                                  | 사용자를 OAuth 흐름 또는 문서 페이지로 보내기 |
+| `form`             | `{ fields, writeScope? }`                             | 환경 변수(키, 비밀, URL) 수집                 |
+| `builder-cli-auth` | `{ scope: "llm" \| "browser" \| "image-generation" }` | Connect Builder (unlocks shared infra)        |
+| `agent-task`       | `{ prompt }`                                          | 처리할 상담원 채팅에 메시지를 보냅니다.       |
+
+`primary: true` 플래그는 메서드를 해당 단계의 큰 CTA로 표시합니다.
+설정 경로가 표시되어야 하는 경우 `badge: "soon"`와 `disabled: true`를 사용하세요.
+사용 가능하기 전에
+
+### 내장 단계
+
+| 아이디     | 필수       | 설명                                      |
+| ---------- | ---------- | ----------------------------------------- |
+| `llm`      | 그렇습니다 | Builder 연결 또는 공급자 LLM 키           |
+| `database` | 아니요     | 기본 데이터베이스 또는 SQL `DATABASE_URL` |
+| `auth`     | 아니요     | 내장 계정, 선택적 OAuth 또는 액세스 토큰  |
+| `email`    | 아니요     | 거래 이메일을 위한 재전송 또는 SendGrid   |
+
+이들 중 하나는 동일한 `id`에 다시 등록하여 재정의할 수 있습니다.
+기본 로드.
+
+### 클라이언트 사용량
+
+패널이 이미 `<AgentPanel>` 내부에 있습니다. 사용자 정의 레이아웃을 구축하려면:
+
+```tsx
+import {
+  OnboardingPanel,
+  OnboardingBanner,
+  useOnboarding,
+} from "@agent-native/core/client/onboarding";
+
+function MySidebar() {
+  const { allComplete, dismissed, currentStepId } = useOnboarding();
+  if (allComplete || dismissed) return <Chat />;
+  return (
+    <>
+      <OnboardingPanel />
+      <Chat />
+    </>
+  );
+}
+```
+
+단계 값이 저장되는 위치와 비밀이 처리되는 방법에 대한 배경 정보는
+[Security](/docs/security)를 참조하세요. 최종 사용자 메시지 터치포인트(초대,
+비밀번호 재설정) **이메일 전달** 단계에 따라 다릅니다.
+[Messaging](/docs/messaging).