Failproof AI Observability Python SDK Agent Skill

​

계측은 작성하기 쉽지만 조용히 잘못되기도 쉽습니다

​

작동 방식, 순서대로

1. 계획. 에이전트 루프를 읽고, 오직 개발자만 답할 수 있는 두 가지 질문을 합니다: 하나의 실행이 무엇인지(session_id), 그리고 구별 가능한 행위자가 누구인지(agent_id). 코드를 작성하기 전에 이 사항들을 합의합니다. 나중에 변경하면 히스토리가 분리되고 트렌드가 깨지기 때문입니다.
2. 작성. 모든 호출 위치에 identity를 전달하는 대신 실행당 한 번만 바인딩하고, 동시성에 안전한 방식을 선택합니다. 이는 중요한 세부 사항으로, 명백해 보이는 지름길은 두 개의 겹치는 실행을 하나의 세션에 조용히 섞어버립니다.
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   ▸ 이 에이전트에 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에 직접 제출하므로
        거기서 발행된 이벤트는 드롭됩니다. 그것도 수정할까요?

​

질문할 수 있는 것들

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

​

주의할 점

​

다음 단계

• Python SDK: 이 스킬이 자동화하는 것의 배경이 되는 완전한 이벤트 레퍼런스 — 모든 이벤트 타입과 필드.
• Sessions: 이벤트가 기록된 후 계측이 생성하는 것.
• Evaluator Agent Skill: 실행이 기록되기 시작한 후 다음 단계 — 평가.
• CLI Agent Skill: 텔레메트리 결과 조회.