failproofai 1.0.1-beta.1 → 1.0.2-beta.0

package/.next/standalone/docs-old/ko/agenteye/hermes-capture.mdx

@@ -0,0 +1,53 @@
+---
+title: "Hermes 세션 캡처"
+description: "팀의 Hermes 게이트웨이 세션 — Slack, Telegram, CLI, 예약 실행 — 을 일반 세션 및 이벤트로 AgentEye에 가져옵니다."
+---
+
+[Hermes](https://hermes-agent.nousresearch.com)는 팀원들이 이미 사용하는 어떤 채널에서든 — Slack, Telegram, CLI, 예약 실행 — 응답을 제공합니다. Hermes 세션 캡처는 이 모든 것을 AgentEye에 일반 세션 및 이벤트로 가져오므로, 팀이 매일 대화하는 어시스턴트도 직접 작성한 에이전트만큼 관찰 가능해집니다.
+
+소형 백그라운드 수집기가 Hermes의 로컬 세션 저장소를 작성 즉시 읽어 AgentEye로 전송합니다. 동작 방식은 [Codex](/ko/agenteye/codex-capture) 및 [OpenClaw](/ko/agenteye/openclaw-capture) 캡처와 동일하며, 하나의 수집기로 여러 에이전트를 동시에 캡처할 수 있습니다.
+
+---
+
+## 캡처 항목
+
+머신의 모든 Hermes 세션은 어느 채널에서 시작되었든 캡처됩니다. 각 세션은 AgentEye [세션](/ko/agenteye/sessions)이 되고, 사용자 및 어시스턴트 메시지, 도구 호출, 도구 결과는 해당하는 [이벤트](/ko/agenteye/event-stream)가 됩니다.
+
+세션이 시작된 채널 — Slack, Telegram, CLI, 예약 실행 — 은 세션에 기록되므로 구분하거나 하나씩 필터링할 수 있습니다. 함께 기록되는 정보로는 세션이 실행된 모델, 세션이 시작된 채팅 및 사용자, 그리고 세션이 다른 세션을 생성한 경우 부모 세션으로의 링크가 있습니다.
+
+세션은 Hermes가 시작하는 즉시 표시되며, 아직 아무 말도 나누지 않은 상태여도 마찬가지입니다. 한 턴의 응답과 도구 호출은 실제로 발생한 순서대로 유지됩니다. 세션이 종료되면 종료 이유, 비용, 사용된 토큰 수도 함께 확인할 수 있습니다.
+
+---
+
+## 활성화 방법
+
+캡처는 활성화하기 전까지 비활성 상태입니다. `events:add` 권한이 있는 API 키([API 키](/ko/agenteye/api-keys) 참조)로 수집기를 설치하고 Hermes 캡처를 활성화합니다.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \
+  | sh -s -- --key <YOUR_API_KEY> --hermes-enabled
+```
+
+이 명령으로 수집기가 설치되고, 백그라운드 서비스로 등록되며, 캡처가 시작됩니다. 실행 여부를 확인합니다.
+
+```bash
+agenteye-collector health
+```
+
+동일한 머신에서 여러 에이전트를 캡처하려면? 같은 명령에 각 에이전트의 플래그를 추가하면 됩니다 — 예: `--hermes-enabled --codex-enabled`.
+
+첫 실행 시 기존 Hermes 세션이 한 번 백필되고, 이후 새로운 활동은 몇 초 이내에 스트리밍됩니다. Hermes의 데이터는 읽기만 할 뿐 수정하거나 삭제하지 않으며, 각 메시지는 재시작이 있더라도 한 번만 전송됩니다.
+
+`health` 명령은 수집기가 캡처한 모든 데이터가 실제로 AgentEye에 도달했는지도 알려줍니다. 배치 전송에 실패한 경우 삭제되지 않고 보존되어 재시도되며, 미전송 데이터가 남아 있는 동안은 비정상 상태로 보고됩니다 — 따라서 "정상"은 단순히 프로세스가 살아있다는 의미가 아니라 데이터가 실제로 도착했음을 의미합니다.
+
+---
+
+## 확인 위치
+
+캡처된 세션은 **Sessions**에, 이벤트는 **Events** 스트림에 표시되며, 다른 에이전트와 동일하게 취급됩니다 — 따라서 [세션 재생](/ko/agenteye/sessions), [검색](/ko/agenteye/queries), [평가](/ko/agenteye/evaluations), [알림](/ko/agenteye/alerts) 모두 이 세션에 적용됩니다. Hermes 에이전트로 필터링하면 해당 세션만 볼 수 있습니다.
+
+---
+
+## 개인정보 보호
+
+Hermes 세션에는 전체 대화 내용 — 명령 출력, 파일 내용, 에이전트가 읽거나 쓴 모든 것 — 이 포함되며, 비밀 정보가 담길 수 있습니다. 캡처된 세션은 있는 그대로 전송되므로, AgentEye에 해당 콘텐츠를 중앙화하는 것이 적절한 환경에서만 캡처를 활성화하고, 수집기에는 `events:add` 권한만 있는 키를 부여하세요. 데이터가 격리되어 보관되는 방식은 [보안](/ko/agenteye/security)을 참조하세요.

package/.next/standalone/docs-old/ko/agenteye/incidents.mdx

@@ -0,0 +1,50 @@
+---
+title: "인시던트"
+description: "알림이 발생하면, 누구나 인시던트가 열려 있는지, 담당자가 누구인지, 지금까지 무슨 일이 있었는지를 하나의 귀속 타임라인에서 확인할 수 있습니다."
+---
+
+
+알림이 발생했을 때 가장 먼저 드는 질문은 언제나 "누가 담당하고 있나요?"입니다. 인시던트가 그 답을 제공합니다. 무언가 임계값을 초과하는 순간, 누구나 인시던트가 열려 있다는 사실, 담당자가 누구인지, 지금까지 정확히 어떤 일이 있었는지를 확인할 수 있습니다. 사후 검토(post-mortem)에 바로 활용할 수 있는 깔끔하고 귀속된 기록과 함께요.
+
+![인시던트 인박스: 알림과 연결되거나 수동으로 생성된 인시던트 카드들이 상태별로 그룹화되어 있으며, 각각에는 심각도 배지와 담당자가 표시됩니다](/agenteye/images/incidents.png)
+*인박스는 열린 인시던트를 상태별로 그룹화하고 심각도 및 담당자로 필터링하므로, 지금 즉시 사람이 처리해야 할 것이 무엇인지 바로 확인할 수 있습니다.*
+
+## 담당자를 한눈에 파악하세요
+
+채팅 스레드에서 "누가 보고 있나요?"라고 묻는 일은 이제 없습니다. 임계값이 초과되면 인시던트가 자동으로 열리고 공유 인박스에 상태별로 그룹화되어 추가됩니다. 인시던트를 확인(acknowledge)하면 여러분의 이름이 붙어 나머지 팀원들이 처리되고 있다는 것을 알 수 있습니다. 확인은 공유 방식으로 이루어집니다. 여러 명의 운영자가 동일한 인시던트를 확인할 수 있으며, 각각이 개별적으로 기록되기 때문에 대규모 대응 상황에서도 서로 겹치지 않고 이름별로 표시됩니다. 트리아지(triage)를 위한 단일 담당자를 지정하고, 심각도 또는 담당자로 인박스를 필터링해서 자신이 처리해야 할 항목만 볼 수 있습니다.
+
+## 전체 경과를 하나의 타임라인으로
+
+인시던트가 종료되면 이미 보고서가 완성되어 있습니다. 인시던트를 열면 임계값 초과 증거, 담당자 및 구독자, 현장에서 협업을 위한 댓글 스레드, 그리고 추가 전용(append-only) 활동 타임라인을 확인할 수 있습니다.
+
+![인시던트 상세 보기: 상위 알림 및 임계값 초과 요약, 담당자 및 구독자, 귀속된 활동 타임라인, 댓글 스레드](/agenteye/images/incident-detail.png)
+*발생한 모든 일이 순서대로 기록되며, 각 항목마다 실행한 담당자의 서명이 붙습니다.*
+
+모든 액션(열림, 확인, 해결 등)은 해당 타임라인에 기록되며 절대 수정되거나 삭제되지 않습니다. 각 항목은 귀속됩니다. 액션을 취한 운영자의 이메일로, 또는 임계값 초과 시 인시던트를 여는 것처럼 Failproof AI Observability가 자체적으로 수행한 작업에는 **automated**로 표시됩니다. 익명 처리되거나 손실되는 것은 없으므로, 사후 검토가 거의 자동으로 완성됩니다.
+
+## 인시던트의 상태 전환
+
+```mermaid
+stateDiagram-v2
+    [*] --> firing
+    firing --> acknowledged: an operator acks
+    firing --> resolved: an operator resolves
+    acknowledged --> resolved: an operator resolves
+    resolved --> [*]
+```
+
+- **열림(firing):** 임계값 초과 시 인시던트가 열리고 채널에 한 번 알림이 전송됩니다. 반복적인 임계값 초과는 동일한 인시던트에 통합되며, 반복 알림 대신 증거만 갱신됩니다.
+- **확인됨(acknowledged):** 운영자가 인시던트를 담당합니다. 인시던트는 열린 상태를 유지하며, 이후 임계값 초과 발생 시 증거가 조용히 업데이트됩니다.
+- **해결됨(resolved):** 운영자가 인시던트를 종료합니다. 조건이 해소될 때 자동으로 해결되는 기능은 계획 중이지만 아직 활성화되지 않았습니다. 따라서 인시던트는 사람이 해결할 때까지 열린 상태로 유지되어, 실제로 무엇이 해소되었는지에 대한 책임이 명확히 유지됩니다. 이후 동일한 알림에서 새로운 인시던트가 다시 열릴 수 있습니다.
+
+하나의 알림에는 최대 하나의 열린 인시던트만 존재할 수 있으므로, 불안정하게 반복되는 규칙으로 인해 중복 인시던트가 쌓이는 일은 없습니다. `incidents:write` 권한이 있다면 수동으로 인시던트를 열 수도 있습니다. 어떤 알림도 감지하지 못한 상황을 위한 독립 인시던트, 또는 기존 알림에 연결된 인시던트를 생성할 수 있습니다.
+
+## 위치
+
+인시던트는 `/<org-slug>/incidents`에 있습니다. 조회에는 **`incidents:read`**, 수동 인시던트 생성에는 **`incidents:write`**, 확인·담당자 지정·댓글·해결에는 **`incidents:ack`** 권한이 필요합니다. 이전에 발급된 키로 부여된 `alerts:ack` 권한은 `incidents:ack`와 동일하게 처리되므로, 온콜 로테이션을 위해 키를 재발급할 필요가 없습니다.
+
+## 관련 항목
+
+- [알림](/ko/agenteye/alerts): 임계값이 초과될 때 인시던트를 여는 규칙입니다.
+- [오류 추적](/ko/agenteye/error-tracking): 모든 장애를 한 곳에서 확인하고 알림으로 승격시킵니다.
+- [감사](/ko/agenteye/audits): 어떤 규칙도 감지하지 못한 장애를 찾아내는 예약된 분석기입니다.

package/.next/standalone/docs-old/ko/agenteye/observability.mdx

@@ -0,0 +1,23 @@
+---
+title: "관찰"
+description: "관찰 화면은 에이전트가 지금 무엇을 하고 있는지 실시간으로 확인하고 특정 실행을 상세히 살펴볼 수 있는 공간입니다."
+---
+
+
+관찰 화면은 에이전트가 지금 무엇을 하고 있는지 실시간으로 확인하고 특정 실행을 상세히 살펴볼 수 있는 공간입니다. 이곳의 모든 정보는 실시간이며 조직 범위로 제공되고, 날짜 범위·환경·에이전트·세션 기준으로 필터링할 수 있어 "뭔가 이상한데"라는 느낌에서 정확한 실행 기록까지 수초 안에 도달할 수 있습니다.
+
+![환경, 에이전트, 세션 기준으로 필터링 가능하고 유형별로 색상이 구분된 실시간 이벤트 스트림](/agenteye/images/events-stream.png)
+
+각각의 페이지로 구성된 네 가지 화면:
+
+- **[이벤트 스트림](/ko/agenteye/event-stream)**: 모든 에이전트의 모든 실행에 대한 실시간 단계별 기록으로, 최신순으로 정렬됩니다. 조직의 홈 화면이자 트리아지의 첫 번째 출발점입니다.
+- **[세션 및 실행 그래프](/ko/agenteye/sessions)**: 이벤트를 실행 단위 한 행으로 집계하고, 각 실행이 어떻게 전개되었는지를 git 스타일의 그림으로 보여줍니다.
+- **[성능 메트릭](/ko/agenteye/telemetry)**: 모델, 도구, 훅에 대한 지연 시간 히트맵과 p50/p95/p99 지표를 제공하여 꼬리 스파이크가 중앙값과 어떻게 다른지 한눈에 파악할 수 있습니다.
+- **[오류 추적](/ko/agenteye/error-tracking)**: 문제가 발생한 모든 항목을 한 화면에서 트리아지하고, 알림 발생에서 해당 실행까지 클릭 한 번으로 이동합니다.
+
+## 관련 항목
+
+- [평가](/ko/agenteye/evaluations): 모든 실행의 품질을 점수화합니다.
+- [알림](/ko/agenteye/alerts): 임의의 임계값을 호출 규칙으로 전환합니다.
+- [감사](/ko/agenteye/audits): Failproof AI Observability가 자동으로 세션 전반의 실패 패턴을 찾아드립니다.
+- [CLI 및 에이전트](/ko/agenteye/cli-and-agents): 터미널에서도 동일한 관찰 기능을 사용할 수 있습니다.

package/.next/standalone/docs-old/ko/agenteye/openclaw-capture.mdx

@@ -0,0 +1,49 @@
+---
+title: "OpenClaw 세션 캡처"
+description: "팀의 로컬 OpenClaw 세션을 AgentEye로 가져와 일반 세션 및 이벤트로 확인하세요 — OpenClaw 실행 방식은 전혀 변경할 필요가 없습니다."
+---
+
+팀이 [OpenClaw](https://docs.openclaw.ai)를 사용하고 있다면, OpenClaw 세션 캡처를 통해 해당 세션들을 AgentEye의 일반 세션 및 이벤트로 가져올 수 있습니다. 이를 통해 다른 관찰 데이터와 함께 검색, 재생, 평가가 가능합니다. 이 기능은 [Python SDK](/ko/agenteye/python-sdk)를 보완합니다. SDK는 직접 작성한 에이전트를 계측하는 반면, 이 기능은 팀이 이미 수행하는 OpenClaw 작업을 캡처합니다 — 실행 방식은 전혀 바꿀 필요가 없습니다.
+
+소규모 백그라운드 수집기가 OpenClaw의 로컬 세션 트랜스크립트를 작성 즉시 읽어 AgentEye로 전송합니다. [Codex 캡처](/ko/agenteye/codex-capture)와 동일한 방식으로 동작하며, 하나의 수집기로 두 가지를 동시에 캡처할 수 있습니다.
+
+---
+
+## 캡처되는 내용
+
+머신의 OpenClaw 설정에 구성된 모든 에이전트는 해당 머신의 수집기에 의해 캡처됩니다 — 에이전트별 별도 설정은 필요하지 않습니다.
+
+각 OpenClaw 세션은 AgentEye [세션](/ko/agenteye/sessions)이 되고, 사용자 및 어시스턴트 메시지, 툴 호출, 툴 결과는 대응하는 [이벤트](/ko/agenteye/event-stream)가 됩니다.
+
+---
+
+## 활성화 방법
+
+캡처는 기본적으로 비활성화 상태입니다. `events:add` 권한이 있는 API 키([API 키](/ko/agenteye/api-keys) 참고)로 수집기를 설치하고 OpenClaw 캡처를 활성화하세요:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \
+  | sh -s -- --key <YOUR_API_KEY> --openclaw-enabled
+```
+
+이 명령은 수집기를 설치하고, 백그라운드 서비스로 등록하며, 캡처를 시작합니다. 정상 동작 여부를 확인하려면:
+
+```bash
+agenteye-collector health
+```
+
+동일한 머신에서 여러 에이전트를 캡처하려면? 각 에이전트의 플래그를 동일한 명령에 추가하면 됩니다 — 예: `--openclaw-enabled --codex-enabled`.
+
+최초 실행 시 기존 OpenClaw 세션이 한 번 백필되고, 이후 새 활동은 수 초 내에 스트리밍됩니다. OpenClaw의 파일은 읽기만 할 뿐 — 수정, 이동, 삭제는 절대 하지 않습니다 — 각 세션은 재시작이 있더라도 정확히 한 번만 전송됩니다.
+
+---
+
+## 확인 위치
+
+캡처된 세션은 **Sessions**에 표시되고, 이벤트는 **Events** 스트림에 표시됩니다 — 다른 에이전트 관찰 데이터와 동일합니다. 따라서 [세션 재생](/ko/agenteye/sessions), [검색](/ko/agenteye/queries), [평가](/ko/agenteye/evaluations), [알림](/ko/agenteye/alerts) 모두 해당 데이터에 적용됩니다. OpenClaw 에이전트로 필터링하면 해당 세션만 볼 수 있습니다.
+
+---
+
+## 개인정보 보호
+
+OpenClaw 트랜스크립트에는 커맨드 출력, 파일 내용, 에이전트가 읽거나 쓴 모든 내용을 포함한 전체 세션이 담겨 있으며, 비밀 정보가 포함될 수 있습니다. 캡처된 세션은 있는 그대로 전송되므로, AgentEye에 해당 내용을 중앙화하는 것이 적절한 머신 및 팀에 대해서만 캡처를 활성화하고, 수집기에는 `events:add` 권한만 가진 키를 사용하세요. 데이터 격리 방식에 대해서는 [보안](/ko/agenteye/security)을 참고하세요.

package/.next/standalone/docs-old/ko/agenteye/overview.mdx

@@ -0,0 +1,108 @@
+---
+title: "Failproof AI: 에이전트 장애 관측"
+description: "Failproof AI Observability는 프로덕션 환경에서 AI 에이전트를 관측, 평가, 개선하기 위한 자체 호스팅 플랫폼입니다."
+---
+
+
+Failproof AI Observability는 프로덕션 환경에서 AI 에이전트를 관측, 평가, 개선하기 위한 자체 호스팅 플랫폼입니다. 에이전트의 모든 동작(모든 도구 호출, 모델 요청, 훅, 오류)을 기록하고, 각 실행의 품질을 점수화하며, 미처 발견하지 못했던 장애를 찾아내 여러분의 인프라 내에서 직접 운영하는 대시보드에 표시합니다.
+
+AI 에이전트를 운영 중이고 실행이 왜 잘못됐는지 계속 추측하는 데 지쳤다면, 여기서 시작하세요. 이 문서는 설치 전에 Failproof AI Observability가 제공하는 것과 각 구성 요소가 어떻게 연결되는지 설명합니다.
+
+> **Failproof AI Observability는 Failproof AI의 엔터프라이즈 제품입니다.** 실제 동작을 보고 싶으신가요? 데모를 요청하세요: [nikita@befailproof.ai](mailto:nikita@befailproof.ai)로 이메일 보내주세요.
+
+![git 스타일의 실행 그래프와 이벤트 타임라인이 나란히 표시된 Failproof AI Observability 세션, 오른쪽 패널에는 도구·모델·훅의 실행별 분석 정보 표시](/agenteye/images/session-detail.png)
+
+*모든 에이전트 실행은 git 스타일의 실행 그래프(왼쪽)와 이벤트 타임라인이 나란히 표시됩니다. 병렬 서브 에이전트는 각각 별도의 레인을 가지며, 오른쪽 패널에서 해당 실행의 도구, 모델, 훅, 토큰 사용량을 상세히 확인할 수 있습니다.*
+
+---
+
+## 실제 동작 보기
+
+두 편의 짧은 영상에서 팀들이 가장 먼저 찾는 두 가지 기능을 보여줍니다: 실행 추적과 자동 장애 탐지.
+
+<div style={{ position: "relative", width: "100%", paddingBottom: "56.25%", height: 0, overflow: "hidden", borderRadius: "12px", margin: "1.5rem 0" }}>
+  <iframe src="https://www.youtube.com/embed/VWxukZc5k7s?autoplay=1&mute=1&loop=1&playlist=VWxukZc5k7s&rel=0&playsinline=1" title="Watch: Agent Tracing by Failproof AI (2 min)" allow="autoplay; encrypted-media; picture-in-picture; fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}></iframe>
+</div>
+
+*에이전트 추적: 목표에서 도구 사용, 최종 응답까지 단일 실행을 단계별로 따라가기.*
+
+<div style={{ position: "relative", width: "100%", paddingBottom: "56.25%", height: 0, overflow: "hidden", borderRadius: "12px", margin: "1.5rem 0" }}>
+  <iframe src="https://www.youtube.com/embed/C5nHKGQIqZQ?autoplay=1&mute=1&loop=1&playlist=C5nHKGQIqZQ&rel=0&playsinline=1" title="Watch: Automatically find where your agent is failing (2 min)" allow="autoplay; encrypted-media; picture-in-picture; fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}></iframe>
+</div>
+
+*Failproof 감사: Failproof AI Observability가 세션 전반의 로그를 분석해 수정이 필요한 사항을 알려줍니다.*
+
+---
+
+## 팀이 이 도구를 사용하는 이유
+
+- **에이전트가 실제로 무엇을 했는지 확인하세요.** 모든 실행이 읽기 쉬운 git 스타일의 실행 그래프로 변환됩니다: 어떤 도구가 병렬로 실행됐는지, 어떤 서브 에이전트가 분기했는지, 어디서 멈췄는지, 무엇을 사용했는지 한눈에 볼 수 있습니다.
+- **품질 저하를 자동으로 감지하세요.** 소규모 점수화 서비스를 연결하면 Failproof AI Observability가 완료된 모든 실행을 점수화하여, 유용성 하락이나 환각 급증을 자동으로 감지합니다.
+- **미리 규칙을 작성하지 않아도 장애를 찾아냅니다.** 반복 감사가 세션 전반의 로그에서 오류 클러스터, 지연 이상값, 낮은 점수, 중단된 실행을 발굴하고, 증거가 뒷받침된 우선순위 결과를 제시합니다.
+- **중요한 순간에 알림을 받으세요.** 오류율, 지연 시간, 비용, 또는 평가 점수에 대한 임계값 규칙이 발동되면 인시던트가 생성되어 확인, 담당자 지정, 해결까지 처리할 수 있습니다.
+- **일반 언어로 질문하세요.** 대시보드 내 AI 어시스턴트가 여러분의 데이터를 기반으로 "이번 주 프로덕션에서 품질 트렌드는 어떤가요?" 같은 질문에 답합니다. 어시스턴트가 변경하는 모든 사항은 승인이 필요합니다.
+- **데이터를 직접 관리하세요.** Failproof AI Observability는 자체 호스팅 방식으로, 이벤트, 프롬프트, 분석 데이터가 여러분이 제어하는 인프라 안에 머뭅니다.
+
+---
+
+## 제공 기능
+
+Failproof AI Observability는 세 가지 개념(**관측**, **분석**, **관리**)을 중심으로 구성되며, 이는 대시보드 왼쪽 사이드바에 그대로 반영됩니다.
+
+**관측** (실제로 무슨 일이 있었는지의 원본 데이터):
+
+- **[이벤트 스트림](/ko/agenteye/event-stream)**: 모든 실행의 단계별 실시간 기록 (도구 호출, 모델 호출, 훅, 오류).
+- **[세션](/ko/agenteye/sessions)**: 실행별로 집계된 이벤트로, 각 실행은 점수화 준비가 된 한 행으로 표시되며 git 스타일의 실행 그래프를 포함합니다.
+- **[성능 메트릭](/ko/agenteye/telemetry)**: 표면별 지연 시간 히트맵과 모델, 도구, 훅에 대한 p50/p95/p99 지표로, 꼬리 구간의 급증을 중앙값과 비교해 식별합니다.
+- **[오류 추적](/ko/agenteye/error-tracking)**: 발생한 모든 문제를 한 곳에서 트리아지하고, 발동된 알림에서 한 번의 클릭으로 접근할 수 있습니다.
+
+![도구 관측 페이지: 24개의 시간 구간에 걸친 지연 시간 히트맵, 백분위수 밴드, 도구 분포 바](/agenteye/images/tools.png)
+
+*각 관측 화면은 스파크라인과 p50/p95/p99 지표를 지연 시간 히트맵 및 백분위수 밴드와 함께 표시합니다. 여기서는 도구(Tools) 화면을 보여줍니다.*
+
+**분석** (활동을 인사이트로 전환):
+
+- **[쿼리](/ko/agenteye/queries)** 및 **[대시보드](/ko/agenteye/dashboards)**: 이벤트와 평가 데이터에 대해 저장된 SQL을 실행하고, 조직 범위의 공유 대시보드로 시각화합니다.
+- **[평가](/ko/agenteye/evaluations)**: 자체 평가 서비스가 생성하는 품질 점수와 점수별 근거.
+- **[감사](/ko/agenteye/audits)**: 세션 전반에서 장애 패턴을 발굴하는 반복 조사.
+- **[알림](/ko/agenteye/alerts)** 및 **[인시던트](/ko/agenteye/incidents)**: 알림을 발송하는 임계값 규칙과, 이를 트리아지할 수 있는 인시던트 워크플로우.
+
+**인터페이스** (원하는 방식으로 데이터에 접근):
+
+- **[CLI](/ko/agenteye/cli-and-agents)**: 터미널이나 스크립트에서 전체 배포를 제어하고, 코딩 에이전트가 일반 언어로 대신 처리하도록 할 수 있습니다.
+- **[AI 어시스턴트](/ko/agenteye/assistant)**: 대시보드 내에서 일반 언어로 에이전트에 대해 질문하세요.
+- **REST API**: 대시보드와 CLI의 모든 기능은 범위가 지정된 [API 키](/ko/agenteye/api-keys)로 직접 호출할 수 있는 REST API로 지원됩니다 — 이벤트 수집, 세션 및 평가 쿼리, 대시보드·알림·감사·사용자·키 관리까지 가능하여, Failproof AI Observability를 자체 도구와 연동할 수 있습니다.
+
+**관리** (팀을 위한 운영):
+
+- **[API 키](/ko/agenteye/api-keys)**: 수집기, 대시보드, 어시스턴트용 범위 지정 토큰.
+- **사용자**: 허용 목록 기반의 이메일 패스워드리스 로그인.
+- **설정**: 모델 컨텍스트 윈도우 재정의를 포함한 조직별 구성.
+
+---
+
+## 구성 요소의 연결 방식
+
+데이터는 에이전트 코드에서 대시보드까지 단방향으로 흐릅니다: 에이전트(Python SDK를 통해)가 이벤트를 agenteye-collector로 전송하고, collector가 서버로 전달하며, 서버가 대시보드를 제공합니다. 두 개의 선택적 서비스로 구성이 완성됩니다 — 점수화 서비스(평가)와 AI 어시스턴트 서비스(대시보드 내 채팅).
+
+- **Python SDK**: 에이전트에 몇 가지 `agenteye.event.*` 호출을 추가하면, 이벤트가 로컬에서 버퍼링됩니다.
+- **agenteye-collector**: 각 에이전트 머신에서 실행되는 경량 데몬으로, 이벤트를 일괄 처리하여 서버로 전송합니다.
+- **서버**: 이벤트를 수집하고, 자체 데이터베이스에서 운영 상태를 유지하며, 대시보드·CLI·자체 통합에서 모두 사용하는 REST API를 제공합니다.
+- **대시보드**: 모든 것을 탐색하는 공간.
+- **선택적 서비스**: 점수화 서비스(평가)와 AI 어시스턴트 서비스(대시보드 내 채팅).
+
+문서 전반에서 사용하는 용어(*이벤트, 세션, 평가, 감사, 결과, 인시던트*)에 대해서는 [개념](/ko/agenteye/concepts)을 참고하세요.
+
+---
+
+## Failproof AI Observability 도입하기
+
+Failproof AI Observability는 Failproof AI의 엔터프라이즈 제품으로, Failproof AI 브랜드 아래 정책 및 가드레일 제품인 Failproof AI Enforcement와 함께 동작합니다. 완전히 여러분의 환경에서 실행됩니다. 아직 패키지에 대한 접근 권한이 없다면, 데모를 요청해 주세요: [nikita@befailproof.ai](mailto:nikita@befailproof.ai)로 이메일을 보내주시면 시작을 도와드리겠습니다.
+
+---
+
+## 다음 단계
+
+- [개념](/ko/agenteye/concepts): Failproof AI Observability 용어를 한 곳에서 정리한 문서.
+- [Observability](/ko/agenteye/observability): 에이전트의 동작을 실행별로 추적하기.
+- [보안](/ko/agenteye/security): Failproof AI Observability가 데이터를 격리하고 여러분의 통제 하에 유지하는 방법.

package/.next/standalone/docs-old/ko/agenteye/python-sdk-skill.mdx

@@ -0,0 +1,130 @@
+---
+title: "Failproof AI Observability Python SDK Agent Skill"
+description: "계측되지 않은 에이전트에서 가시적인 이벤트로: 코딩 에이전트가 계측 지점을 찾아내고, 작성하고, 정상적으로 반영됐음을 검증합니다."
+---
+
+코딩 에이전트에게 *"이 에이전트에 Failproof AI Observability를 추가해줘"* 라고 말하면, 에이전트가 루프를 읽고, 계측 위치를 파악하고, 코드를 작성하고, 작업을 완료로 선언하기 전에 이벤트를 검증합니다.
+
+**Python SDK 스킬** (`agenteye-python-sdk`)은 *Agent Skill*입니다. 이는 Claude Code나 Codex 같은 코딩 에이전트가 작업이 일치할 때 온디맨드로 로드하는 명령어 폴더입니다. 이 스킬은 에이전트에게 [Python SDK](/ko/agenteye/python-sdk) 사용법을 가르쳐줍니다. 라이브러리가 아니며 SDK의 작동 방식을 변경하지 않습니다.
+
+## 계측은 작성하기 쉽지만 조용히 잘못되기도 쉽습니다
+
+SDK는 작습니다: 키워드 전용 인수를 사용하는 이벤트 메서드 13개가 전부입니다. 코딩 에이전트는 [Python SDK](/ko/agenteye/python-sdk) 레퍼런스를 읽고 1분 안에 그럴듯한 계측 코드를 만들어낼 수 있습니다.
+
+문제는 이 SDK가 잘못 사용해도 오류를 발생시키지 않는다는 점이며, 잘못된 계측은 대시보드를 열었을 때 비어 있다는 걸 발견하기 전까지는 올바른 계측과 완전히 똑같아 보입니다. 실제로 시간을 낭비하게 만드는 실수들은 모두 침묵입니다:
+
+| 실수 | 보이는 것 |
+|---|---|
+| `agent_start` 없음 | 모든 이벤트가 기록됨. 세션은 0. |
+| 환경 설정 안 됨 | 모든 것이 동작하지만 `dev`에 기록됨. |
+| `outcome="failure"` | 실행이 성공으로 표시됨 — `failed`, `error`, `timeout`, `rejected`만 집계됨. |
+| 오타가 있는 필드 이름 | 새 필드로 저장됨. |
+| 스레드 풀에서 이벤트 발행 | 조용히 드롭됨. |
+
+이 중 어떤 것도 오류를 발생시키지 않습니다. 어떤 것도 테스트에서 나타나지 않습니다. 모두 스킬에 포함되어 있으며, 이를 잡아내는 검사와 함께 명세로 기술되어 있습니다.
+
+## 작동 방식, 순서대로
+
+스킬은 신중한 엔지니어라면 수행할 세 단계를 동일하게 실행합니다:
+
+1. **계획.** 에이전트 루프를 읽고, 오직 개발자만 답할 수 있는 두 가지 질문을 합니다: 하나의 실행이 무엇인지(`session_id`), 그리고 구별 가능한 행위자가 누구인지(`agent_id`). 코드를 작성하기 전에 이 사항들을 합의합니다. 나중에 변경하면 히스토리가 분리되고 트렌드가 깨지기 때문입니다.
+2. **작성.** 모든 호출 위치에 identity를 전달하는 대신 실행당 한 번만 바인딩하고, 동시성에 안전한 방식을 선택합니다. 이는 중요한 세부 사항으로, 명백해 보이는 지름길은 두 개의 겹치는 실행을 하나의 세션에 조용히 섞어버립니다.
+3. **검증.** 에이전트를 실행하고 결과 이벤트 파일을 읽어 `agent_start`가 존재하는지, 환경이 올바른지, 하나의 실행이 하나의 세션을 생성했는지 확인합니다.
+
+세 번째 단계가 사람들이 건너뛰는 단계입니다. SDK는 이벤트를 로컬 파일에 기록하므로, 완전한 통합은 서버, API 키, 네트워크 없이 노트북에서 검증할 수 있습니다. 바로 이것이 스킬이 이 단계를 고집하는 이유입니다.
+
+## 다른 스킬들과의 관계
+
+세 가지 스킬, 명확한 역할 분담:
+
+| 스킬 | 사용 시점 | 영향 범위 |
+|---|---|---|
+| **Python SDK 스킬** (이 페이지) | 에이전트가 텔레메트리를 *발행*하게 하려고 할 때 — "observability 추가", "내 에이전트가 왜 안 보이지?" | 에이전트 레포에 코드를 작성. 아무것도 읽지 않음. |
+| **[Evaluator 스킬](/ko/agenteye/evaluator-skill)** | 실행을 *평가*하려고 할 때 — "무엇을 측정해야 하지?" | 레포에 코드 작성, 텔레메트리 읽기 |
+| **[CLI 스킬](/ko/agenteye/cli-skill)** | 발생한 일을 *조회*하거나 배포를 운영하려고 할 때 | 사용자 권한으로 CLI 실행, 변경 포함 |
+
+이 순서로 연결됩니다: 이 스킬이 이벤트를 흐르게 하고, evaluator가 점수를 매기고, CLI가 결과를 읽습니다. 에이전트가 세션을 발행하기 전까지는 평가할 것도, 읽을 것도 없습니다. 처음부터 시작한다면 여기서 시작하세요.
+
+## 사전 요구 사항
+
+1. **Python 3.10+** 및 계측하려는 에이전트 코드베이스.
+2. **SDK.** 공개 패키지 인덱스가 아닌 프라이빗 wheel로 고객에게 배포됩니다. 온보딩 과정에서 SDK를 획득하고 설치하는 방법을 안내합니다. 스킬은 설치 경로를 알고 있으며, 찾을 수 없는 경우 추측 대신 직접 물어봅니다.
+3. **그 외 없음.** 대시보드 로그인, API 키, 네트워크가 필요 없습니다. 스킬은 SDK가 기록하는 이벤트 파일을 기준으로 검증하므로 오프라인에서도 작업을 완료하고 증명할 수 있습니다.
+
+## 스킬 가져오는 방법
+
+스킬은 공개 [`FailproofAI/skills`](https://github.com/FailproofAI/skills) 컬렉션에 있습니다:
+
+```bash
+npx skills add FailproofAI/skills --skill agenteye-python-sdk -a claude-code
+```
+
+현재 프로젝트 대신 모든 프로젝트에 설치하려면 `-g`를 추가하고, 환경이 심볼릭 링크를 지원하지 않으면 `--copy`를 사용하세요. Codex의 경우 `-a codex`를 전달하세요.
+
+## 수동 설치
+
+Agent Skills는 `SKILL.md`와 참조 파일들을 포함하는 폴더입니다. 설치 도구를 사용하지 않으려면:
+
+- **Claude Code**: `agenteye-python-sdk/` 폴더를 `~/.claude/skills/`(모든 프로젝트) 또는 `<your-repo>/.claude/skills/`(해당 레포만)에 복사합니다. Claude Code가 자동으로 인식합니다 — `/skills` 목록을 확인하거나, 일치하는 내용을 질문해보세요.
+- **Codex**: Codex는 동일한 `SKILL.md`를 읽습니다. 번들된 `agents/openai.yaml`이 `allow_implicit_invocation: true`로 설정되어 있어 작업이 일치하면 자동 선택됩니다. 그렇지 않으면 `$agenteye-python-sdk`로 호출하세요.
+
+계측하려는 코드가 있는 **레포지토리에서** 에이전트를 실행하세요 — 스킬은 무엇을 제안하기 전에 에이전트 루프를 먼저 읽습니다.
+
+## 세션 예시
+
+```text
+you   ▸ 이 에이전트에 Failproof AI Observability를 추가해줘.
+
+agent ▸ 루프를 확인했습니다 — tools.py에 도구 디스패처 하나, llm.py에
+        Anthropic 래퍼 하나. 코드 작성 전에 두 가지 질문이 있습니다.
+
+        하나의 실행이란 무엇인가요? 요청을 동시에 처리하므로 ctx.request_id에
+        이미 있는 요청 id를 사용하는 게 좋을 것 같습니다 — 그러면 여기서의
+        세션과 로그의 요청이 동일한 문자열이 됩니다.
+
+        그리고 행위자는 누구인가요? planner 경로와 researcher 경로가 보입니다.
+        별도로 레이블링할까요, 아니면 하나의 에이전트로 볼까요?
+
+you   ▸ 요청 id가 맞아. 하나의 에이전트야, "assistant"로 불러.
+
+agent ▸ 완료했습니다. 디스패처와 LLM 클라이언트를 래핑했고, agent_start와
+        agent_end가 에러 경로를 포함해 handle_request를 감쌉니다.
+        Identity에는 컨텍스트 로컬을 사용했습니다 — 디스패처가 도구를 스레드
+        풀에서 실행하는데, 더 간단한 방법을 쓰면 동시 실행 결과가 하나의 세션에
+        섞여도 아무 경고가 없었을 겁니다.
+
+        실제 실행으로 검증했습니다: 4개 파일에 걸쳐 11개 이벤트 —
+        agent_start, model_request/response, tool_use/tool_result x3,
+        agent_end (outcome=success). environment=production, 요청당 하나의
+        세션, 지속 시간 짝 맞춤.
+
+        하지 않은 것 하나: batch.py의 워커 풀이 executor에 직접 제출하므로
+        거기서 발행된 이벤트는 드롭됩니다. 그것도 수정할까요?
+```
+
+주목할 패턴: 제안하기 전에 코드를 먼저 읽었고, 개발자만 답할 수 있는 질문만 했으며, 이미 갖고 있던 id를 재사용하고, 스레드 풀을 확인했기 때문에 동시성에 안전한 방식을 선택했고, 성공을 선언하는 대신 **실제 이벤트를 읽어 검증**한 뒤 — 조용히 실패할 것을 알고 있는 곳을 표시했습니다.
+
+## 질문할 수 있는 것들
+
+- *"내 에이전트가 왜 대시보드에 안 보이지?"* → 단계적으로 확인합니다: 이벤트가 기록되고 있는지, `agent_start`가 있는지, 환경이 올바른지, 수집기가 같은 위치를 읽고 있는지.
+- *"모든 것이 dev에 기록되고 있어."* → 환경이 설정되지 않았거나, 이후 호출에서 재설정되었습니다.
+- *"토큰 추적을 추가해줘."* → LLM 래퍼를 찾아 모델, 중지 이유, 사용량을 기록합니다.
+- *"서브 에이전트도 계측해줘."* → 하나의 세션, 구별되는 에이전트 레이블, 부모 아래 중첩됩니다.
+- *"계측 테스트를 작성해줘."* → SDK가 임시 디렉터리를 가리키게 하고 기록된 이벤트를 어서트합니다.
+
+## 주의할 점
+
+**검증 단계를 실행하게 하세요.** 이 스킬을 가치 있게 만드는 단계는 마지막 단계입니다 — 에이전트를 실행하고 이벤트를 다시 읽는 것. 계측을 작성하고 멈추는 에이전트는 쉬운 절반만 한 것이며, 조용히 실패하는 절반이 나머지입니다.
+
+**코드 전에 이름을 합의하세요.** `session_id`와 `agent_id`는 모든 화면이 그룹화하는 기준 축입니다. 나중에 이름을 바꾸면 히스토리가 분리됩니다: 이전 실행은 옛 레이블을 유지하고 트렌드가 깨집니다. 스킬이 질문할 것이고, 답변은 잠깐의 생각을 충분히 투자할 가치가 있습니다.
+
+**에이전트가 공개 인덱스에서 SDK를 설치하자고 제안한다면, 스킬이 로드되지 않은 것입니다.** SDK는 프라이빗으로 배포됩니다. 그 제안은 코딩 에이전트가 스킬을 따르지 않고 추측하고 있다는 확실한 신호입니다 — 거기서 멈추고 스킬이 설치됐는지 확인하세요.
+
+그 외에는 영향 범위가 작습니다: 작업 디렉터리에 코드를 작성하고 지정한 위치에 이벤트 파일을 작성합니다. 배포에서는 아무것도 읽지 않고 변경하지도 않습니다.
+
+## 다음 단계
+
+- **[Python SDK](/ko/agenteye/python-sdk)**: 이 스킬이 자동화하는 것의 배경이 되는 완전한 이벤트 레퍼런스 — 모든 이벤트 타입과 필드.
+- **[Sessions](/ko/agenteye/sessions)**: 이벤트가 기록된 후 계측이 생성하는 것.
+- **[Evaluator Agent Skill](/ko/agenteye/evaluator-skill)**: 실행이 기록되기 시작한 후 다음 단계 — 평가.
+- **[CLI Agent Skill](/ko/agenteye/cli-skill)**: 텔레메트리 결과 조회.