Agent Skill Python SDK de Observabilidade do Failproof AI

​

Instrumentação é fácil de escrever e fácil de errar silenciosamente

​

O que ela faz, em ordem

1. Planejar. Ela lê seu loop de agente e faz as duas perguntas que só você pode responder: o que conta como uma execução (seu session_id) e quem são os atores distinguíveis (seu agent_id). Ela obtém essas respostas antes de escrever código, porque mudá-las depois divide seu histórico e quebra as tendências.
2. Escrever. Ela vincula a identidade uma vez por execução em vez de passá-la por todos os pontos de chamada, e escolhe uma forma segura para concorrência — um detalhe que importa, porque o atalho óbvio silenciosamente mistura duas execuções sobrepostas em uma única sessão.
3. Verificar. Ela executa seu agente e lê os arquivos de eventos resultantes, verificando se agent_start está presente, se o ambiente está correto e se uma execução produziu uma sessão.

​

Como ela se relaciona com as outras skills

​

Pré-requisitos

1. Python 3.10+ e a base de código do agente que você deseja instrumentar.
2. O SDK. Ele é distribuído aos clientes como um wheel privado, não de um índice público — seu onboarding cobre como obtê-lo e instalá-lo. A skill conhece o caminho de instalação e perguntará a você em vez de adivinhar, caso não consiga encontrá-lo.
3. Nada mais. Sem login no dashboard, sem chave de API, sem rede. A skill verifica contra os arquivos de eventos que o SDK grava, portanto pode concluir e provar seu trabalho offline.

​

Onde encontrá-la

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

​

Instalando manualmente

• Claude Code: copie a pasta agenteye-python-sdk/ para ~/.claude/skills/ (todos os projetos) ou <seu-repositório>/.claude/skills/ (somente aquele repositório). Claude Code a descobre automaticamente — verifique a lista /skills, ou simplesmente pergunte algo que corresponda a ela.
• Codex: o Codex lê o mesmo SKILL.md. O arquivo agents/openai.yaml incluído define allow_implicit_invocation: true, então ela é selecionada automaticamente quando uma tarefa corresponde; caso contrário, invoque-a como $agenteye-python-sdk.

​

Como uma sessão se parece

você  ▸ Adicione Observabilidade do Failproof AI a este agente.

agente▸ Li seu loop — um dispatcher de ferramentas em tools.py, um
        wrapper do Anthropic em llm.py. Duas perguntas antes de
        escrever qualquer coisa.

        O que conta como uma execução? Você lida com requisições
        concorrentemente, então eu usaria o id de requisição que você
        já tem em ctx.request_id — assim uma sessão aqui e uma
        requisição nos seus logs são a mesma string.

        E quem são os atores? Vejo um caminho de planejador e um
        caminho de pesquisador. Rotulo-os separadamente, ou é um único
        agente para você?

você  ▸ O id de requisição está certo. São um único agente, chame de
        "assistant".

agente▸ Pronto. Envolvi o dispatcher e o cliente LLM; agent_start e
        agent_end delimitam handle_request, incluindo o caminho de erro.
        Usei um context-local para identidade — seu dispatcher executa
        ferramentas em um thread pool, e a abordagem mais simples teria
        misturado execuções concorrentes em uma única sessão sem
        reclamar.

        Verificado contra uma execução real: 11 eventos em 4 arquivos —
        agent_start, model_request/response, tool_use/tool_result x3,
        agent_end (outcome=success). environment=production, uma sessão
        por requisição, durações pareadas.

        Uma coisa que eu NÃO fiz: seu worker pool em batch.py submete
        diretamente ao executor, então eventos de lá seriam descartados.
        Quer que eu corrija esses também?

​

O que você pode pedir

• “Por que meu agente não está aparecendo no dashboard?” → percorre a escada: os eventos estão sendo gravados, agent_start está lá, o ambiente está correto, o collector está lendo o mesmo lugar.
• “Tudo está chegando como dev.” → o ambiente nunca foi definido, ou foi redefinido por uma chamada posterior.
• “Adicione rastreamento de tokens.” → encontra seu wrapper LLM e registra modelo, motivo de parada e uso.
• “Instrumente os sub-agentes também.” → uma sessão, rótulos de agentes distintos, aninhados sob seu pai.
• “Escreva testes para a instrumentação.” → aponta o SDK para um diretório temporário e faz asserções sobre os eventos que ele gravou.

​

O que observar

​

Próximos passos

• Python SDK: a referência completa de eventos — cada tipo de evento e campo — por trás do que esta skill automatiza.
• Sessions: o que sua instrumentação produz quando os eventos chegam.
• Evaluator Agent Skill: o próximo passo quando as execuções estiverem chegando — pontuá-las.
• CLI Agent Skill: lendo sua telemetria de volta.