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

# Failproof AI Observability Python SDK Agent Skill

> 계측되지 않은 에이전트에서 눈으로 확인할 수 있는 이벤트까지 — 코딩 에이전트가 계측 지점을 찾고, 작성하고, 정상적으로 반영됐음을 증명합니다.

코딩 에이전트에게 *"이 에이전트에 Failproof AI Observability를 추가해줘"* 라고 말하면, 에이전트가 루프를 읽고 계측 위치를 파악하고 코드를 작성한 뒤, 작업 완료를 선언하기 전에 이벤트를 직접 검증합니다.

**Python SDK 스킬** (`agenteye-python-sdk`)은 *Agent Skill*입니다. 코딩 에이전트(Claude Code나 Codex 등)가 작업이 해당 스킬과 일치할 때 온디맨드로 로드하는 지침 폴더입니다. 이 스킬은 에이전트가 [Python SDK](/ko/agenteye/python-sdk)를 사용하는 방법을 가르쳐 줍니다. 라이브러리가 아니며, SDK의 동작 방식에는 어떠한 변경도 가하지 않습니다.

## 계측은 작성하기 쉬우면서도 조용히 틀리기 쉽습니다

SDK는 작습니다. 열세 개의 이벤트 메서드, 모두 키워드 전용입니다. 코딩 에이전트는 [Python SDK](/ko/agenteye/python-sdk) 레퍼런스를 읽고 그럴듯한 계측 코드를 1분 안에 만들어낼 수 있습니다.

문제는 이 SDK가 잘못 사용해도 예외를 발생시키지 않으며, 잘못된 계측은 누군가 대시보드를 열어보고 텅 빈 화면을 발견하기 전까지는 올바른 계측과 똑같아 보인다는 점입니다. 실제로 시간을 잡아먹는 실수들은 모두 '침묵'의 형태를 띱니다.

| 실수                  | 확인되는 증상                                                           |
| ------------------- | ----------------------------------------------------------------- |
| `agent_start` 누락    | 이벤트는 모두 기록됨. 세션은 0.                                               |
| 환경 미설정              | 모든 것이 작동하지만 `dev` 아래에 저장됨.                                        |
| `outcome="failure"` | 실행이 정상으로 표시됨 — `failed`, `error`, `timeout`, `rejected`만 집계에 포함됨. |
| 필드명 오타              | 허용되어 새 필드로 저장됨.                                                   |
| 스레드 풀에서 이벤트 발생      | 조용히 드롭됨.                                                          |

이 중 어떤 것도 예외를 발생시키지 않습니다. 어떤 것도 테스트에서 드러나지 않습니다. 모든 사례가 스킬 안에 포함되어 있으며, 이를 잡아내는 검사와 함께 계약 형태로 명시되어 있습니다.

## 스킬이 수행하는 작업, 순서대로

스킬은 신중한 엔지니어라면 밟을 동일한 세 단계를 실행합니다.

1. **계획.** 에이전트 루프를 읽고, 오직 당신만 답할 수 있는 두 가지 질문을 합니다. 무엇을 한 번의 실행으로 볼 것인가(`session_id`), 그리고 구별 가능한 행위자는 누구인가(`agent_id`). 코드를 작성하기 전에 이 합의를 먼저 받아냅니다. 나중에 변경하면 히스토리가 분리되고 트렌드가 깨지기 때문입니다.
2. **작성.** 매 실행마다 한 번만 ID를 바인딩하고(모든 콜 사이트에 전달하는 대신), 동시성에 안전한 방식을 선택합니다. 간단해 보이는 지름길이 겹치는 두 실행을 하나의 세션으로 조용히 혼합할 수 있기 때문에 중요한 세부 사항입니다.
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 theme={null}
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 theme={null}
you   ▸ Add Failproof AI Observability to this agent.

agent ▸ Read your loop — one tool dispatcher in tools.py, one Anthropic
        wrapper in llm.py. Two questions before I write anything.

        What counts as one run? You handle requests concurrently, so I'd
        use the request id you already have in ctx.request_id — then a
        session here and a request in your logs are the same string.

        And who are the actors? I see a planner path and a researcher
        path. Label them separately, or is that one agent to you?

you   ▸ Request id is right. They're one agent, call it "assistant".

agent ▸ Done. Wrapped the dispatcher and the LLM client; agent_start and
        agent_end bracket handle_request, including the error path. Used
        a context-local for identity — your dispatcher runs tools in a
        thread pool, and the simpler approach would have mixed concurrent
        runs into one session without complaining.

        Verified against a real run: 11 events across 4 files —
        agent_start, model_request/response, tool_use/tool_result x3,
        agent_end (outcome=success). environment=production, one session
        per request, durations paired.

        One thing I did NOT do: your worker pool in batch.py submits
        straight to the executor, so events from there would be dropped.
        Want me to fix those too?
```

주목할 패턴: 제안 전에 코드를 읽었고, 오직 당신만 답할 수 있는 질문만 했으며, 이미 갖고 있던 ID를 재사용했고, 스레드 풀을 발견했기 *때문에* 동시성에 안전한 방식을 선택했으며, 성공을 선언하는 대신 **실제 이벤트를 읽어 검증했고**, 조용히 실패할 것을 알고 있는 곳 하나를 별도로 표시했습니다.

## 요청할 수 있는 것들

* *"에이전트가 대시보드에 왜 안 보이나요?"* → 단계별로 확인합니다. 이벤트가 기록되고 있는지, `agent_start`가 있는지, 환경이 올바른지, collector가 같은 위치를 읽고 있는지.
* *"모든 것이 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)**: 텔레메트리를 다시 읽기.