failproofai 1.0.1-beta.0 → 1.0.1

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

@@ -0,0 +1,433 @@
+---
+title: "Python SDK"
+description: "AI 에이전트가 프로덕션에서 수행한 모든 작업을 확인하세요: 모든 에이전트 실행, 툴 호출, 모델 요청, hook, 그리고 사람의 개입까지."
+---
+
+
+AI 에이전트가 프로덕션에서 수행한 모든 작업을 확인하세요: 모든 에이전트 실행, 툴 호출, 모델 요청, hook, 그리고 사람의 개입까지. Failproof AI Observability Python SDK는 에이전트 코드 내부에서 그 기록을 남겨 디버깅, 감사, 평가에 활용할 수 있게 해줍니다. 에이전트를 Failproof AI Observability로 관찰하고 싶을 때마다 사용하세요.
+
+내부적으로 SDK는 구조화된 이벤트를 로컬 JSONL 파일에 기록하며, 콜렉터 데몬이 이를 감지해 플랫폼으로 자동 전송합니다. 파일을 직접 관리할 필요가 없습니다.
+
+> **팁:** Failproof AI Observability가 처음이신가요? 이 페이지는 SDK 이벤트의 완전한 레퍼런스입니다.
+
+<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>
+
+---
+
+## 설치
+
+SDK는 공개 패키지 인덱스가 아닌 프라이빗 휠로 고객에게 배포됩니다. 온보딩 과정에서 취득, 설치, 버전 고정 방법을 안내받게 됩니다. 접근 권한이 필요하면 Failproof AI 담당자에게 문의하세요.
+
+설치 후 다음 명령으로 확인하세요:
+
+```bash
+python -c "import agenteye; print(agenteye.__version__)"
+```
+
+코딩 에이전트가 전체 통합을 처리하게 하고 싶으신가요? [Python SDK Agent Skill](/ko/agenteye/python-sdk-skill)은 설치 경로를 파악하고, 계측 지점을 계획·작성하며, 이벤트가 정상적으로 수신되는지 검증합니다.
+
+---
+
+## 빠른 시작
+
+```python
+import agenteye
+
+agenteye.configure(environment="production")
+
+agenteye.event.agent_start(session_id="run-001", agent_id="planner", goal="answer user query")
+
+agenteye.event.tool_use(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",
+    tool_call_id="toolu_01",
+    input={"query": "latest AI research"},
+)
+
+agenteye.event.tool_result(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",
+    tool_call_id="toolu_01",
+    output={"results": ["..."]},
+)
+
+agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="success")
+```
+
+### 실제 호출 계측하기
+
+실제로는 기존 에이전트 코드를 감싸는 방식으로 사용합니다. 모델 호출 앞에 `model_request`를, 뒤에 `model_response`를 배치하면 두 이벤트가 실제 요청을 감싸게 되어 Failproof AI Observability가 두 이벤트를 서로 연결할 수 있습니다:
+
+```python
+import anthropic
+import agenteye
+
+agenteye.configure(environment="production")
+client = anthropic.Anthropic()
+
+messages = [{"role": "user", "content": "Summarise today's incidents."}]
+
+agenteye.event.model_request(
+    session_id="run-001",
+    agent_id="planner",
+    model="claude-sonnet-4-6",
+    messages=messages,
+)
+
+reply = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=512,
+    messages=messages,
+)
+
+agenteye.event.model_response(
+    session_id="run-001",
+    agent_id="planner",
+    model=reply.model,
+    stop_reason=reply.stop_reason,
+    input_tokens=reply.usage.input_tokens,
+    output_tokens=reply.usage.output_tokens,
+    content=[block.model_dump() for block in reply.content],
+)
+```
+
+툴 호출도 동일한 방식으로 `tool_use`와 `tool_result`를 감싸되, 동일한 `tool_call_id`를 쌍으로 재사용하세요.
+
+아래는 이벤트가 대시보드에 도달했을 때의 모습입니다. 이벤트 유형별로 색상이 구분되며 환경, 에이전트, 세션별로 필터링할 수 있습니다:
+
+![이벤트 유형별로 색상이 구분되고 환경, 에이전트, 세션별로 필터링 가능한 라이브 이벤트 스트림](/agenteye/images/events-stream.png)
+
+---
+
+## configure()
+
+```python
+agenteye.configure(
+    base_dir=None,           # Path | str | None. Default: $AGENTEYE_HOME or ~/.agenteye
+    flush_interval=0.5,      # float, seconds between flush cycles
+    environment=None,        # str | None. Deployment environment label
+)
+```
+
+`event.*` 호출 전에 한 번 호출하세요. 생략해도 안전하며, 기본값만으로도 바로 사용할 수 있습니다. 모든 인수는 키워드 전용이므로 위와 같이 이름으로 전달하세요.
+
+`base_dir`가 `None`(기본값)인 경우, SDK는 `$AGENTEYE_HOME`이 설정되어 있으면 해당 값을 사용하고, 그렇지 않으면 `~/.agenteye`로 폴백합니다. 이는 콜렉터 자체의 경로 결정 방식과 동일하므로, `AGENTEYE_HOME` 환경 변수 하나로 SDK와 콜렉터가 공유하는 이벤트 스풀을 설정할 수 있습니다.
+
+---
+
+## 환경
+
+모든 이벤트에 배포 환경을 나타내는 레이블(`production`, `staging`, `qa`, `canary` 등)을 지정하세요. 한 번만 설정하면 SDK가 모든 이벤트에 자동으로 첨부합니다.
+
+**방법 1: `configure()`를 통해 설정:**
+
+```python
+agenteye.configure(environment="production")
+```
+
+**방법 2: 환경 변수를 통해 설정:**
+
+```bash
+export AGENTEYE_ENVIRONMENT=production
+```
+
+**우선순위:** `configure(environment=...)`가 환경 변수보다 우선합니다. 둘 다 설정되지 않은 경우 기본값은 `"dev"`입니다.
+
+환경 값은 대시보드의 1급 필터로 표시되며, 빠른 쿼리를 위해 서버에 저장됩니다.
+
+> **경고:** 환경 값에는 리터럴 `,` 쉼표를 포함할 수 없습니다. 대시보드 필터는 와이어에서 쉼표로 구분된 다중 선택 방식을 사용(`?environment=prod,staging`)하므로, `prod,blue`라는 이름의 환경은 두 개의 값으로 분리됩니다. 쉼표가 포함된 환경의 이벤트는 수집 시 거부됩니다.
+
+---
+
+## 데이터 및 개인정보 보호
+
+SDK는 명시적으로 전달한 필드만 기록합니다. 프롬프트, 메시지, 툴 입출력, 모델 콘텐츠는 `event.*` 호출에 전달할 때만 캡처됩니다. 프로세스에서 암묵적으로 읽거나 캡처하는 정보는 없습니다. 설정하지 않은 필드는 이벤트에서 완전히 제외되며 디스크에도 기록되지 않습니다.
+
+따라서 데이터 삭제는 전적으로 여러분의 선택이자 책임입니다. 프롬프트나 툴 페이로드에 저장하고 싶지 않은 개인정보나 비밀이 포함된 경우, 이벤트 메서드에 전달하기 전에 제거하거나 마스킹하세요.
+
+---
+
+## 이벤트 레퍼런스
+
+대부분의 이벤트는 상관 ID를 공유하는 시작/종료 쌍으로 구성됩니다: `tool_use`와 `tool_result`는 `tool_call_id`를 공유하고, `hook_triggered`와 `hook_completed`는 `hook_id`를 공유하며, `human_wait`와 `human_input`은 `input_id`를 공유합니다. 시작 이벤트를 발행하고 작업을 수행한 뒤, 동일한 ID로 종료 이벤트를 발행하세요. Failproof AI Observability가 쌍을 매칭하고 `duration_ms`를 자동으로 계산하므로 직접 전달할 필요가 없습니다.
+
+![페어드 이벤트로 재구성된 실행 그래프 및 타임라인과 툴/모델/hook 분류 패널이 나란히 표시된 세션 상세 화면](/agenteye/images/session-detail.png)
+
+모든 이벤트 메서드에는 다음 두 필드가 필요합니다:
+
+| 필드 | 타입 | 설명 |
+|---|---|---|
+| `session_id` | `str` | 최상위 에이전트 실행을 식별합니다 |
+| `agent_id` | `str` | 세션 내에서 이벤트를 발행한 에이전트를 식별합니다 |
+
+모든 메서드는 커스텀 메타데이터를 위한 임의의 `**kwargs`도 허용합니다([커스텀 필드](#custom-fields) 참고).
+
+---
+
+### `event.agent_start()`
+
+에이전트가 작업을 시작할 때 발행됩니다.
+
+```python
+agenteye.event.agent_start(
+    session_id="run-001",
+    agent_id="planner",
+    goal="answer user query",   # str | None
+    parent_id=None,             # str | None - parent agent_id for nested agents
+)
+```
+
+---
+
+### `event.agent_end()`
+
+에이전트가 작업을 완료할 때 발행됩니다.
+
+```python
+agenteye.event.agent_end(
+    session_id="run-001",
+    agent_id="planner",
+    outcome="success",          # str | None
+    summary="Answered query",   # str | None
+)
+```
+
+---
+
+### `event.tool_use()`
+
+에이전트가 툴을 호출할 때 발행됩니다. `tool_result`와 쌍을 이루며 SDK가 `duration_ms`를 자동 계산합니다.
+
+```python
+agenteye.event.tool_use(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",     # str, required
+    tool_call_id="toolu_01",    # str, required - correlation key for the matching tool_result
+    input={"query": "..."},     # dict | None
+)
+```
+
+---
+
+### `event.tool_result()`
+
+툴이 결과를 반환할 때 발행됩니다. `tool_call_id`를 통해 `tool_use`와 연결됩니다.
+
+```python
+agenteye.event.tool_result(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",
+    tool_call_id="toolu_01",        # must match the prior tool_use
+    output={"results": ["..."]},    # Any | None
+    error=None,                     # str | None - set if the tool raised
+    # duration_ms is computed automatically - do not pass it
+)
+```
+
+---
+
+### `event.model_request()`
+
+LLM에 프롬프트를 전송하기 직전에 발행됩니다.
+
+```python
+agenteye.event.model_request(
+    session_id="run-001",
+    agent_id="planner",
+    model="claude-sonnet-4-6", # str | None - any provider/model string; not validated
+    messages=[                   # list[dict] | None - conversation turns
+        {"role": "user", "content": "..."},
+    ],
+    system="You are helpful.",   # Any | None - str or list of content blocks
+    tools=[                      # list[dict] | None - tool schemas offered to the model
+        {"name": "search", "input_schema": {"type": "object"}},
+    ],
+)
+```
+
+`messages` 항목은 일반 문자열 `content` 또는 Anthropic 스타일의 블록 리스트 `content`를 모두 허용합니다. 샘플링 파라미터(`temperature`, `max_tokens` 등)는 추가 kwargs로 전달할 수 있습니다.
+
+---
+
+### `event.model_response()`
+
+LLM이 응답을 반환할 때 발행됩니다.
+
+```python
+agenteye.event.model_response(
+    session_id="run-001",
+    agent_id="planner",
+    model="claude-sonnet-4-6", # str | None - any provider/model string; not validated
+    stop_reason="end_turn",     # str | None
+    input_tokens=1024,          # int | None
+    output_tokens=256,          # int | None
+    content=[                    # Any | None - str, or list of content blocks
+        {"type": "text", "text": "..."},
+    ],
+    role="assistant",            # str | None
+)
+```
+
+`content`는 일반 문자열(일반 프로바이더) 또는 Anthropic 스타일의 콘텐츠 블록 리스트를 모두 허용합니다. 툴 호출은 별도의 `tool_calls` 필드 없이 `{"type": "tool_use", ...}` 블록 형태로 `content` 안에 포함됩니다.
+
+---
+
+### `event.hook_triggered()`
+
+hook이 실행될 때 발행됩니다. `hook_completed`와 쌍을 이루며 SDK가 `duration_ms`를 자동 계산합니다.
+
+```python
+agenteye.event.hook_triggered(
+    session_id="run-001",
+    agent_id="planner",
+    hook_name="pre_tool_use",   # str, required
+    hook_id="hook-abc",         # str, required - correlation key
+    trigger_event="tool_use",   # str | None
+    input={"tool": "search"},   # Any | None
+)
+```
+
+---
+
+### `event.hook_completed()`
+
+hook이 완료될 때 발행됩니다. `hook_id`를 통해 `hook_triggered`와 연결됩니다.
+
+```python
+agenteye.event.hook_completed(
+    session_id="run-001",
+    agent_id="planner",
+    hook_name="pre_tool_use",
+    hook_id="hook-abc",         # must match the prior hook_triggered
+    outcome="allow",            # str | None
+    output=None,                # Any | None
+    error=None,                 # str | None
+    # duration_ms is computed automatically - do not pass it
+)
+```
+
+---
+
+### `event.error()`
+
+처리되지 않은 오류가 발생할 때 발행됩니다.
+
+```python
+agenteye.event.error(
+    session_id="run-001",
+    agent_id="planner",
+    error_type="TimeoutError",  # str, required
+    message="timed out",        # str, required
+    traceback="Traceback...",   # str | None
+)
+```
+
+---
+
+## 사람 개입(Human-in-the-Loop) 이벤트
+
+사람 개입 이벤트는 에이전트 실행 중 사람이 개입하는 순간(승인 대기, 입력 제공, 일시 중지, 에이전트 중단)에 대한 감시를 제공합니다. 이를 통해 사람이 응답하는 데 걸리는 시간을 측정하고(SDK가 페어드 이벤트에서 `duration_ms`를 자동 계산), 에이전트를 일시 중지하거나 중단한 사람을 감사하며, 대시보드에 표시되는 승인 및 감독 워크플로를 구축할 수 있습니다.
+
+### `event.human_wait()`
+
+에이전트가 사람의 입력을 기다리기 위해 실행을 일시 중지할 때 발행됩니다. `human_input`과 쌍을 이루며 SDK가 `duration_ms`(사람이 응답하는 데 걸린 시간)를 자동 계산합니다.
+
+```python
+agenteye.event.human_wait(
+    session_id="run-001",
+    agent_id="planner",
+    input_id="inp-abc",                          # str, required - correlation key for the matching human_input
+    prompt="Do you approve this action?",        # str | None - the question shown to the human
+    options=["approve", "reject", "defer"],      # list[str] | None - choices presented to the human
+    reason="approval_required",                  # str | None - why the agent is waiting
+)
+```
+
+### `event.human_input()`
+
+사람이 입력을 제공하고 에이전트가 재개될 때 발행됩니다. `input_id`를 통해 `human_wait`와 연결됩니다. `duration_ms`는 자동으로 계산되므로 호출자가 전달해서는 안 됩니다.
+
+```python
+agenteye.event.human_input(
+    session_id="run-001",
+    agent_id="planner",
+    input_id="inp-abc",    # str, required - must match the prior human_wait
+    response="approve",    # str | None - the human's answer (free text or selected option)
+    # duration_ms is computed automatically - do not pass it
+)
+```
+
+### `event.human_pause()`
+
+사람이 능동적으로 에이전트를 일시 중지할 때(예: 대시보드 컨트롤을 통해) 발행됩니다. 에이전트는 종료되지 않고 일시 중단됩니다.
+
+```python
+agenteye.event.human_pause(
+    session_id="run-001",
+    agent_id="planner",
+    reason="user_requested",  # str | None
+    user_id="usr_42",         # str | None - who paused the agent
+)
+```
+
+### `event.human_interrupt()`
+
+사람이 에이전트를 실행 중에 능동적으로 중단시킬 때 발행됩니다. `human_pause`와 달리 에이전트의 작업이 일시 중단이 아닌 종료됩니다.
+
+```python
+agenteye.event.human_interrupt(
+    session_id="run-001",
+    agent_id="planner",
+    reason="output_incorrect",       # str | None
+    user_id="usr_42",                # str | None - who interrupted the agent
+    at_step="tool_use:web_search",   # str | None - what the agent was doing when stopped
+)
+```
+
+---
+
+## 커스텀 필드
+
+추가 키워드 인수는 표준 필드 뒤에 이벤트에 추가됩니다:
+
+```python
+agenteye.event.tool_use(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="db_query",
+    tool_call_id="toolu_02",
+    tenant_id="acme",           # custom field
+    region="us-east-1",         # custom field
+)
+```
+
+`timestamp`, `type`, `environment`는 예약된 이름으로, 커스텀 필드로 전달하면 `ValueError`(`Reserved field names cannot be used as custom fields: [...]`)가 발생합니다. `session_id`와 `agent_id`는 모든 이벤트 메서드의 필수 파라미터이므로 두 번 제공할 수 없으며, 그렇게 하면 Python이 `TypeError`를 발생시킵니다. 환경은 `configure(environment=...)`(또는 `AGENTEYE_ENVIRONMENT` 변수)로 설정하세요.
+
+필드를 쿼리하고 싶다면 페이로드를 구조화된 JSON으로 유지하세요. JSON이 기본적으로 지원하지 않는 값(datetime, UUID, decimal, set, bytes, 모델 객체 등)은 기록이 안전하게 계속될 수 있도록 문자열로 변환됩니다.
+
+---
+
+## 이벤트 기록 방식
+
+이벤트는 프로세스 내에 버퍼링되었다가 `flush_interval`초마다(기본값 500ms) 디스크에 플러시됩니다. 각 플러시는 하나의 JSONL 파일을 작성합니다:
+
+```text
+~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl
+```
+
+콜렉터는 이 디렉터리를 감시하고 파일을 자동으로 업로드합니다. 파일을 직접 관리할 필요가 없습니다.
+
+각 파일은 원자적으로 작성됩니다: SDK가 임시 파일에 쓴 다음 제자리로 이름을 변경하므로 콜렉터가 절반만 쓰인 파일을 볼 일이 없습니다. 프로세스가 종료될 때도 최종 플러시가 실행되므로 마지막 인터벌에 버퍼링된 이벤트가 유실되지 않습니다. 콜렉터가 오프라인 상태인 경우 이벤트는 디스크에 파일로 쌓여 있다가 콜렉터가 복구되면 전송됩니다.
+
+---
+
+## 다음 단계
+
+- [이벤트 스트림](/ko/agenteye/event-stream): 이벤트 유형별로 색상이 구분되고 환경, 에이전트, 세션별로 필터링 가능한 라이브 이벤트 스트림을 확인하세요.
+- [세션](/ko/agenteye/sessions): 페어드 이벤트가 각 에이전트 실행을 실행 그래프 및 타임라인으로 어떻게 재구성하는지 확인하세요.

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

@@ -0,0 +1,56 @@
+---
+title: "쿼리"
+description: "에이전트 데이터에 어떤 질문이든 던지고 몇 초 안에 답을 얻으세요."
+---
+
+
+에이전트 데이터에 어떤 질문이든 던지고 몇 초 안에 답을 얻으세요. Failproof AI Observability는 이벤트와 평가 데이터에 대한 저장된 실행 가능 쿼리 라이브러리를 제공합니다. 빈 SQL 편집기 대신 이미 동작하는 예제에서 바로 시작할 수 있습니다.
+
+![저장된 쿼리 라이브러리: 기본 제공 프리셋과 사용자 지정 쿼리가 함께 표시된 그리드](/agenteye/images/queries.png)
+
+*`/<org-slug>/queries`에 있는 저장된 쿼리 라이브러리: 기본 제공 프리셋과 팀이 저장한 쿼리가 나란히 배치됩니다.*
+
+## 빈 페이지가 아닌 프리셋에서 시작하세요
+
+테이블 이름을 외우거나 SQL을 처음부터 작성할 필요가 없습니다. 라이브러리는 팀이 가장 자주 묻는 질문에 맞춘 기본 제공 프리셋과 함께 열리며, 팀이 저장하고 이름을 붙인 쿼리도 바로 옆에 표시됩니다. 원하는 내용에 가까운 것을 선택하면 이미 답의 절반에 도달한 셈입니다.
+
+모든 저장된 쿼리는 조직 단위로 범위가 지정되고 공유되므로, 팀원이 작성한 유용한 쿼리가 나의 것이 되기도 합니다. 쿼리에 이름과 설명을 한 번만 붙여두면 조직 내 누구든 찾아서 실행하거나, 나중에 대시보드에 결과를 고정할 수 있습니다.
+
+`/<org-slug>/queries`에서 찾을 수 있습니다.
+
+## SQL 작성기에서 수정하고 실행하세요
+
+쿼리를 열면 SQL 작성기로 이동하며, 여기서 바로 수정하고 즉시 결과를 확인할 수 있습니다. 내보내기도, 왕복 요청도, 다른 사람을 기다릴 필요도 없습니다.
+
+![저장된 쿼리를 실행 중인 SQL 작성기 — 스키마 사이드바와 실시간 결과 그리드 포함](/agenteye/images/query-lab.png)
+
+*SQL 작성기: 왼쪽에 쿼리, 컬럼 이름을 추측하지 않아도 되는 스키마 사이드바, 아래에 실시간 결과 그리드.*
+
+- **스키마 사이드바**는 분석 테이블과 해당 컬럼을 정리하여 보여주므로, 필드 이름을 찾아 헤매지 않고도 쿼리를 작성할 수 있습니다.
+- **실시간 결과 그리드**는 실행하는 즉시 행을 반환하므로, 반복 작업을 추측 없이 몇 초 만에 처리할 수 있습니다.
+- **읽기 전용 설계.** 쿼리는 이벤트 저장소에 대해 실행되며 서버에서 검증됩니다. `SELECT`와 `WITH` 구문만 허용되며, 구문 타임아웃과 행 수 제한이 적용됩니다. 탐색용 쿼리가 데이터를 수정하는 일은 절대 없으며, 과부하 쿼리는 자동으로 중단됩니다.
+
+결과가 마음에 드시나요? 팀 전체가 활용할 수 있도록 라이브러리에 저장하거나, 결과를 라인, 막대, 영역, 파이 타일 형태로 대시보드에 고정하세요.
+
+## 터미널에서 실행하거나 AI 어시스턴트에게 작성을 맡기세요
+
+저장된 쿼리는 어디서 작업하든 따라옵니다.
+
+- **터미널에서.** `agenteye` CLI로 동일한 쿼리를 목록 조회, 실행, 저장할 수 있습니다. 결과를 스크립트에 넣거나, CI에 연결하거나, 코딩 에이전트에 전달하는 것도 가능합니다.
+
+```bash
+agenteye query list                 # 터미널에서 동일한 저장된 쿼리 확인
+agenteye query run errs --arg prod  # 실행하고 행 출력 (파이프 연결 시 --json 추가)
+```
+
+  전체 명령어 목록은 [CLI and agents](/ko/agenteye/cli-and-agents)를 참조하세요.
+
+- **AI 어시스턴트에서.** SQL 표현이 어렵다면? 대시보드 내 [AI 어시스턴트](/ko/agenteye/assistant)에게 평범한 언어로 질문하면 쿼리를 작성하고 라이브러리에 저장해 드립니다.
+
+저장된 쿼리 실행은 `queries:run` 권한으로 제어되며, 쿼리 생성 및 삭제 권한과 별도로 분리되어 있습니다. 따라서 라이브러리 수정 권한 없이 읽기 전용 접근만 부여할 수 있습니다.
+
+## 관련 문서
+
+- [Dashboards](/ko/agenteye/dashboards): 쿼리 결과를 조직 전체가 공유하는 차트에 고정합니다.
+- [AI assistant](/ko/agenteye/assistant): 평범한 언어로 질문하고 쿼리를 받아보세요.
+- [CLI and agents](/ko/agenteye/cli-and-agents): 터미널에서 동일한 쿼리를 실행하고 저장합니다.

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

@@ -0,0 +1,68 @@
+---
+title: "보안"
+description: "Failproof AI Observability는 프로덕션 에이전트 가까이에서 동작하도록 설계되어 있으며, 프롬프트, 도구 입력값, 출력값을 모두 처리합니다."
+---
+
+
+Failproof AI Observability는 프로덕션 에이전트 가까이에서 동작하도록 설계되어 있으며, 프롬프트, 도구 입력값, 출력값을 모두 처리합니다. 이 페이지에서는 해당 데이터를 격리하고, 통제하며, 여러분의 손에 유지하는 방법을 설명합니다. 보안 검토를 위해 Failproof AI Observability를 평가 중이라면 여기서 시작하세요.
+
+---
+
+## 데이터는 여러분의 환경에 보관됩니다
+
+Failproof AI Observability는 자체 호스팅 방식입니다. 이벤트, 프롬프트, 모델 응답, 분석 데이터는 모두 여러분 자신의 환경에 있는 데이터베이스에 저장됩니다. 서드파티 SaaS에 데이터가 전송되거나 저장되지 않으며, 모든 데이터는 여러분의 클라우드 계정 내에 유지됩니다.
+
+---
+
+## 테넌트 격리
+
+하나의 Failproof AI Observability 인스턴스에서 여러 조직을 호스팅할 수 있으며, 각 조직은 스토리지 계층에서 격리됩니다. 이 격리는 UI가 아닌 데이터베이스 수준에서 강제됩니다.
+
+- 조직의 운영 데이터(사용자, 키, 대시보드, 저장된 쿼리)는 해당 조직 범위로 한정되며, 조직 간 데이터 읽기는 데이터베이스 자체에서 차단됩니다.
+- 수집된 모든 이벤트에는 소유 조직 정보가 기록되므로, 한 조직의 이벤트를 다른 조직에서 절대 읽을 수 없습니다.
+
+모든 대시보드 라우트는 org 슬러그(`/<org-slug>/…`) 하위에 범위가 지정됩니다.
+
+---
+
+## 로그인
+
+Failproof AI Observability는 비밀번호 없는 이메일 기반 로그인을 사용합니다. 피싱하거나 유출될 비밀번호 자체가 없습니다. 사용자가 일회용 코드(또는 원클릭 매직 링크)를 요청하면 이메일로 전송되며, 짧은 시간 내에 만료됩니다. 로그인은 **허용 목록**으로 제한됩니다. 여러분이 허용한 이메일 주소(또는 도메인)만 인증할 수 있습니다.
+
+![이메일로 일회용 코드를 전송하는 Failproof AI Observability 로그인 화면](/agenteye/images/login.png)
+
+---
+
+## API 키를 이용한 범위 기반 접근 제어
+
+모든 클라이언트는 세분화된 최소 권한을 가진 API 키로 인증합니다. 수집기는 `events:add` 권한만 필요하고, 대시보드 또는 어시스턴트 키는 읽기 전용으로 설정할 수 있습니다. 삭제, 재생성과 같은 파괴적인 작업은 별도의 권한으로 관리하며, 여러분이 직접 부여 여부를 결정합니다.
+
+![각 키의 권한 부여 현황을 읽기, 쓰기, 파괴적 범위별로 색상 구분하여 표시하는 API 키 페이지](/agenteye/images/api-keys.png)
+
+관리자 부트스트랩 키는 설정용으로만 보관하고, 그 외 모든 용도에는 제한된 키를 발급하세요. [API 키](/ko/agenteye/api-keys) 문서를 참고하세요.
+
+---
+
+## 읽기 전용, 승인 기반 어시스턴트
+
+대시보드 내 [AI 어시스턴트](/ko/agenteye/assistant)는 여러분의 데이터를 기반으로 질문에 답변하지만, 설계상 다음과 같은 제약이 있습니다.
+
+- **기본적으로 읽기 전용**입니다. 어시스턴트의 SQL은 `SELECT`/`WITH` 쿼리만 허용하고, 단일 구문으로 제한되며, 행 수 상한이 적용되는 가드를 통해 실행됩니다.
+- 어시스턴트가 생성하는 모든 것(저장된 쿼리, 대시보드)은 **승인 기반**으로 처리됩니다. 모든 쓰기 작업은 실행 전에 여러분이 검토하고 승인해야 합니다.
+- 어시스턴트는 **절대 삭제할 수 없습니다**.
+
+따라서 팀원이 "이번 주에 가장 많이 오류가 발생한 에이전트는 무엇인가요?"라고 묻고 결과를 활용하더라도, 어시스턴트가 스스로 데이터를 변경하거나 삭제하는 것은 불가능합니다.
+
+---
+
+## 전송 중 보안
+
+모든 트래픽은 HTTPS를 통해 전송됩니다. 여러분이 직접 인증서로 TLS를 종료하므로, 수집기-서버 간 및 브라우저-서버 간 트래픽은 전송 중 암호화됩니다.
+
+---
+
+## 다음 단계
+
+- [개요](/ko/agenteye/overview): Failproof AI Observability의 전체 구조를 확인하세요.
+- [API 키](/ko/agenteye/api-keys): 수집기, 대시보드, 어시스턴트에 대한 접근 범위를 설정하세요.
+- [관찰 가능성](/ko/agenteye/observability): Failproof AI Observability가 에이전트에서 수집하는 정보를 확인하세요.

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

@@ -0,0 +1,57 @@
+---
+title: "세션 & 실행 그래프"
+description: "한 번의 실행에서 발생한 모든 이벤트를 하나의 읽기 쉬운 행으로 정리하고, 몇 초 만에 파악할 수 있는 git 스타일의 실행 그래프로 시각화합니다."
+---
+
+
+실행이 실패한 이유를 더 이상 추측할 필요가 없습니다. Failproof AI Observability는 한 번의 실행에서 발생한 모든 이벤트를 하나의 읽기 쉬운 행으로 정리하고, 전체 실행 흐름을 몇 초 만에 파악할 수 있는 git 스타일의 그림으로 그려냅니다. 에이전트가 단계별로 정확히 무엇을 했는지 한눈에 확인할 수 있습니다.
+
+![세션 목록: 환경과 에이전트 전반에 걸쳐 실행별로 한 행씩 표시되며, 상태 뱃지와 평가 점수 뱃지가 함께 표시됩니다](/agenteye/images/sessions-list.png)
+
+*실행당 한 행: 상태 뱃지를 통해 실행 결과를 한눈에 파악할 수 있으며, 평가자를 연결하면 점수 뱃지도 함께 표시됩니다.*
+
+<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>
+
+*에이전트 트레이싱: 목표부터 도구 사용, 최종 답변까지 단일 실행을 단계별로 추적합니다.*
+
+---
+
+## 모든 실행을 한눈에 파악하기
+
+원시 이벤트 트레일은 모든 단계의 실제 기록이지만, 수십 번의 실행에 걸쳐 수천 개의 단계가 쌓이면 개별 단계가 아닌 실행 전체를 파악해야 합니다. 세션 페이지는 한 번의 실행에서 발생한 모든 이벤트를 하나의 행으로 집약하여, 하루치 활동을 쏟아지는 로그 대신 스캔 가능한 목록으로 만들어 줍니다.
+
+각 행에는 상태 뱃지가 표시되므로, 클릭하기 전에도 실패한 실행과 정상 실행을 바로 구분할 수 있습니다. 날짜 범위, 환경, 에이전트, 세션으로 필터링하면 몇 번의 클릭만으로 "전체"에서 "내가 찾는 실행"으로 범위를 좁힐 수 있습니다.
+
+평가자를 연결하면 완료된 모든 실행이 자동으로 점수를 받고, 최신 점수가 뱃지 형태로 해당 행에 표시됩니다. 점수 범위로 필터링할 수 있으므로 "이번 주 프로덕션에서 점수가 낮은 실행만 보기"가 수동 검토가 아닌 필터 하나로 해결됩니다. 평가자를 설정하기 전에도 세션은 전체 실행을 캡처하지만, 점수 뱃지는 아직 표시되지 않습니다.
+
+---
+
+## 전체 실행을 그림으로 읽기
+
+![이벤트 타임라인 옆에 표시된 세션의 git 스타일 실행 그래프와 도구, 모델, 훅 분석 패널](/agenteye/images/session-detail.png)
+
+*실행 그래프(왼쪽)가 이벤트 타임라인 옆에 표시되며, 오른쪽 패널에서는 실행에 사용된 도구, 모델, 훅, 토큰 소비량을 상세히 확인할 수 있습니다.*
+
+세션을 클릭하면 실행 그래프가 열립니다. 에이전트, 도구, 훅, 모델 호출이 시간 순서에 따라 어떻게 전개되었는지를 git 스타일로 보여줍니다. 병렬 서브 에이전트는 각각 별도의 레인으로 분기되므로, 어떤 작업이 동시에 실행되었는지, 어떤 서브 에이전트가 지연되었는지, 실행이 어디서 잘못되었는지를 로그 더미를 머릿속으로 다시 재생하지 않고도 파악할 수 있습니다.
+
+오른쪽 패널에서는 실행별 세부 내역을 확인할 수 있습니다. 어떤 도구와 모델이 실행되었는지, 어떤 훅이 실행되었는지, 해당 실행에서 토큰을 얼마나 소비했는지가 그래프 바로 옆에 표시됩니다. "이 실행은 왜 이렇게 비쌌지?" 또는 "느린 도구가 뭐지?"에 대한 답이 바로 거기 있습니다.
+
+개별 이벤트에는 고유 링크가 있으므로, "세션에서 3분의 2 지점쯤"이라고 설명하는 대신 특정 순간의 링크를 바로 공유할 수 있습니다. 이벤트에서 링크를 복사하거나, [감사](/ko/agenteye/audits) 결과나 오류에서 링크를 따라가면 해당 이벤트가 선택되고 스크롤된 상태로 세션이 열립니다. 매우 긴 실행에서도 마찬가지입니다. 타임라인은 브라우저 성능을 위해 제한된 범위를 로드하지만, 해당 범위를 벗어난 이벤트를 가리키는 링크도 시작 지점으로 떨어지지 않고 해당 이벤트를 정확히 찾아줍니다. 이벤트가 보존 기간을 초과한 경우, 페이지는 아무것도 선택하지 않고 넘어가는 대신 그 사실을 명시적으로 알려줍니다.
+
+---
+
+## 찾는 방법
+
+모든 대시보드 페이지는 조직 단위(`/<org-slug>/…`)로 범위가 지정됩니다. 세션은 왼쪽 사이드바의 **Observe** 메뉴 아래, Events 옆에 위치하며, 목록 상단에 날짜 범위, 환경, 에이전트, 세션 필터가 제공됩니다. 모든 행에서 클릭 한 번으로 전체 실행 그래프를 확인할 수 있습니다.
+
+점수 뱃지와 점수 범위 필터링을 활성화하려면 평가자를 연결하세요: [평가](/ko/agenteye/evaluations)를 참고하세요.
+
+---
+
+## 관련 문서
+
+- [이벤트 스트림](/ko/agenteye/event-stream): 각 세션이 집약되는 원시 단계별 트레일.
+- [평가](/ko/agenteye/evaluations): 각 실행에 필터링 가능한 점수 뱃지를 부여하기 위한 평가자 연결 방법.
+- [텔레메트리](/ko/agenteye/telemetry): 에이전트의 실행 결과가 세션으로 전달되는 방식.