Skip to main content
O que cada configuração, método e campo faz. Se você está instrumentando pela primeira vez, comece pelo guia — esta página serve como referência.

Guia de agentes personalizados

Instalação, instrumentação, métodos de evento, exemplo prático e problemas comuns.

Usando um framework?

LangChain, CrewAI, LlamaIndex e Pydantic AI se instrumentam automaticamente com uma única chamada.
Python 3.10 ou superior. Sem dependências em tempo de execução.

​
Instalação

O pacote é instalado como failproofai-sdk e importado no Python como failproofai_sdk. Extras de framework como failproofai-sdk[langgraph] instalam o próprio framework; os adaptadores sempre vêm incluídos no pacote base.

​
Conectar o daemon do Failproof

  1. Acesse Admin → Keys e crie uma chave com events:add.
  2. Conecte o daemon do Failproof à nuvem na máquina do agente.
  3. Execute uma sessão instrumentada e encontre o ID exato em Observe → Events.
  4. Acesse Observe → Sessions, selecione o mesmo ambiente e abra o trace reconstruído. Uma sessão de agente Python personalizado reconstruída como grafo de execução e trace de eventos ordenados.

​
Configuração

Configuração via variável de ambiente:
Sem vírgulas em environment. O sistema de ingestão divide esse campo por vírgulas para construir seus filtros e ignora qualquer evento cujo rótulo contenha uma — fazendo uma execução inteira desaparecer silenciosamente. Use prod-eu, não prod,eu.configure(environment="prod,eu") lança uma exceção para que você perceba imediatamente. AGENTEYE_ENVIRONMENT não pode lançar exceção — nada está te chamando — então ela emite um aviso uma vez e usa dev como fallback.
Os eventos são enfileirados na memória e gravados em segundo plano a cada flush_interval segundos, com um flush final na saída do interpretador. Um processo encerrado abruptamente perde tudo o que ainda não foi gravado.

​
Identidade

Todo evento pertence a uma sessão e a um agente. Os escopos preenchem ambos automaticamente, então raramente é necessário passá-los:
Passar session_id ou agent_id explicitamente ainda funciona e tem precedência. Se nenhum estiver vinculado nem passado, a chamada lança TypeError em vez de emitir um evento que a nuvem descartaria silenciosamente.
A identidade é transportada por variáveis de contexto. Ela segue tarefas asyncio automaticamente, mas não novas threads — encapsule um worker com failproofai_sdk.propagate() ou os eventos dele ficarão sem associação.

​
Catálogo de eventos

Quinze métodos. A maioria vem em pares — você chama o abridor e depois o fechador, e o SDK mede o intervalo entre eles. Três são independentes: error, human_pause, human_interrupt.
Cada método também aceita session_id e agent_id, que os escopos preenchem automaticamente. Qualquer campo deixado como None é descartado em vez de enviado como null no JSON, e todos os métodos retornam None.
Para marcar uma execução como falha, outcome deve ser um dos valores: failed, error, timeout ou rejected. Qualquer outro valor — incluindo o quase-correto "failure" — é contado como sucesso.

​
Pareamento e duração

Uma regra: dê ao evento de fechamento o mesmo id do seu abridor. É isso que os emparelha e permite ao SDK medir o intervalo. Não passe duration_ms manualmente. O SDK o mede automaticamente, e passá-lo lança ValueError. A única exceção é model_response, onde somente você conhece a latência real do provedor. Passe um número inteiro de milissegundos — um float lança exceção, pois a coluna é um inteiro de 32 bits e ficaria vazia caso contrário.
  • Os ids precisam ser únicos apenas por tipo e por sessão. Uma chamada de ferramenta e um hook podem compartilhar o mesmo id; duas sessões em execução simultânea podem reutilizar os mesmos ids sem conflito.
  • Eles não são escopados por agente. Um par aberto sob um agente e fechado sob outro ainda é emparelhado corretamente — o que é o caso normal em código multi-agente.
  • request_id é opcional, mas recomendado. Sem ele, eventos de modelo são emparelhados na ordem de chegada, então duas chamadas concorrentes no mesmo agente podem ser emparelhadas incorretamente.
  • Um par dividido entre processos ainda é emparelhado na nuvem, mas o SDK não consegue medir o tempo — nenhum dos processos viu as duas metades.
  • No máximo 10.000 abridores aguardam um fechador ao mesmo tempo. Além disso, o mais antigo é descartado, então um vazamento não pode crescer indefinidamente.

​
Seus próprios campos

Qualquer palavra-chave extra que você passar é armazenada junto ao evento:
Prefira tipos JSON se quiser consultá-los posteriormente. Qualquer outro tipo — UUID, datetime, Decimal, set, bytes, objeto de modelo — é armazenado como string.
Use prefixo nos nomes dos seus campos. Os extras são aplicados por último, então um campo chamado model, tool_name ou outcome sobrescreve silenciosamente o campo original. Os adaptadores de framework usam fw_; faça o mesmo e não haverá conflito.É também por isso que um campo opcional com erro de ortografia nunca gera erro — ele simplesmente se torna um novo campo personalizado. Se um campo padrão estiver ausente na nuvem, verifique a ortografia primeiro.
Estes cinco nomes são reservados e rejeitados diretamente: timestamp, session_id, agent_id, type, environment.

​
Entrega e verificação

Em Observe → Events, verifique se agent_start existe primeiro e agent_end existe por último. Em seguida, abra Observe → Sessions e confirme que os eventos de modelo, ferramenta, humano, hook e erro aparecem na ordem esperada. Use o ID de sessão como chave principal de diagnóstico.
Se a nuvem estiver vazia, inspecione $FAILPROOFAI_HOME/custom-agents/events; caso contrário, ~/.failproofai/custom-agents/events. Arquivos JSONL confirmam a emissão pelo SDK; um spool crescendo aponta para configuração do daemon ou entrega, enquanto um spool vazio aponta para instrumentação ou tempo de vida do processo.
Inspecione o spool somente quando o daemon estiver parado. Enquanto ele executa, coleta e exclui cada lote em milissegundos, então uma listagem de diretório disputa com o coletor e exibe muito menos eventos do que foram emitidos.

​
Prevenir falhas em um runtime personalizado

Use descobertas de auditoria e traces vinculados para definir a ação insegura, as evidências necessárias e a resposta pretendida. Uma integração de enforcement personalizada deve expor a ação antes da execução, passar sua entrada estruturada ao motor de políticas e aplicar a decisão resultante de allow, instruct ou deny. Entre em contato com o Failproof AI e iremos ajudar a mapear os limites de modelo, ferramenta e ciclo de vida do seu runtime para hooks de política, e então validar a integração junto com você.