Failproof AI Observability Python SDK Agent Skill

​

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

​

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

1. 계획. 에이전트 루프를 읽고, 오직 당신만 답할 수 있는 두 가지 질문을 합니다. 무엇을 한 번의 실행으로 볼 것인가(session_id), 그리고 구별 가능한 행위자는 누구인가(agent_id). 코드를 작성하기 전에 이 합의를 먼저 받아냅니다. 나중에 변경하면 히스토리가 분리되고 트렌드가 깨지기 때문입니다.
2. 작성. 매 실행마다 한 번만 ID를 바인딩하고(모든 콜 사이트에 전달하는 대신), 동시성에 안전한 방식을 선택합니다. 간단해 보이는 지름길이 겹치는 두 실행을 하나의 세션으로 조용히 혼합할 수 있기 때문에 중요한 세부 사항입니다.
3. 검증. 에이전트를 실행하고 생성된 이벤트 파일을 읽어, agent_start가 존재하는지, 환경이 올바른지, 한 번의 실행이 하나의 세션을 생성했는지 확인합니다.

​

다른 스킬들과의 관계

​

사전 요구 사항

1. Python 3.10 이상 그리고 계측하려는 에이전트 코드베이스.
2. SDK. 공개 인덱스가 아닌 프라이빗 wheel로 고객에게 배포됩니다. 온보딩 과정에서 SDK를 받고 설치하는 방법을 안내받게 됩니다. 스킬은 설치 경로를 알고 있으며, 찾지 못하면 추측하는 대신 물어봅니다.
3. 그 외에는 없습니다. 대시보드 로그인도, API 키도, 네트워크도 필요 없습니다. 스킬은 SDK가 기록한 이벤트 파일을 기준으로 검증하므로 오프라인에서 작업을 완료하고 증명할 수 있습니다.

​

스킬 설치 방법

npx skills add FailproofAI/skills --skill agenteye-python-sdk -a claude-code

​

직접 설치하기

• 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를 사용합니다.

​

세션의 실제 모습

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?

​

요청할 수 있는 것들

• “에이전트가 대시보드에 왜 안 보이나요?” → 단계별로 확인합니다. 이벤트가 기록되고 있는지, agent_start가 있는지, 환경이 올바른지, collector가 같은 위치를 읽고 있는지.
• “모든 것이 dev 아래로 들어가요.” → 환경이 설정되지 않았거나 이후 호출에서 재설정된 경우입니다.
• “토큰 추적을 추가해줘.” → LLM 래퍼를 찾아 모델, 중지 이유, 사용량을 기록합니다.
• “서브 에이전트도 계측해줘.” → 하나의 세션, 구별되는 에이전트 레이블, 상위 에이전트 아래에 중첩됩니다.
• “계측에 대한 테스트를 작성해줘.” → SDK가 임시 디렉터리를 가리키게 하고 기록된 이벤트를 검증합니다.

​

주의할 점

​

다음 단계

• Python SDK: 이 스킬이 자동화하는 것의 배후에 있는 완전한 이벤트 레퍼런스 — 모든 이벤트 타입과 필드.
• Sessions: 이벤트가 도착하면 계측이 만들어내는 것.
• Evaluator Agent Skill: 실행이 도착한 이후의 다음 단계 — 점수화.
• CLI Agent Skill: 텔레메트리를 다시 읽기.