Agentes customizados

O que cada configuração, método e campo faz. Se você está instrumentando pela primeira vez, comece pelo guia — esta página é para consulta.

Guia de agentes customizados

Instalação, instrumentação, métodos de evento, um exemplo completo e problemas comuns.

Usando um framework?

LangChain, CrewAI, LlamaIndex e Pydantic AI se instrumentam com uma única chamada.

Python 3.10 ou superior. Sem dependências de runtime.

Instalação

pip install failproofai-sdk

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 estão incluídos no pacote base.

Conectar o daemon do Failproof

Dashboard
CLI

Acesse Admin → Keys e crie uma chave com events:add.
Conecte o daemon do Failproof à Cloud na máquina do agente.
Execute uma sessão instrumentada e encontre o ID exato em Observe → Events.
Acesse Observe → Sessions, selecione o mesmo ambiente e abra o trace reconstruído.

failproofai config \
  --connect https://app.befailproof.ai \
  --token <events-add-key>
failproofai config --status

Configuração

import failproofai_sdk

failproofai_sdk.configure(
    base_dir=None,
    flush_interval=0.5,
    environment="production",
)

Argumento	O que faz
`environment`	O rótulo em cada evento — `production`, `staging`, `prod-eu`. Padrão: `dev`.
`flush_interval`	Com que frequência a thread em segundo plano grava no disco, em segundos. Padrão: `0.5`.
`base_dir`	Onde gravar. Padrão: o spool do daemon, que é o desejado a menos que você saiba o contrário.

Configurar via variável de ambiente:

Variável	O que faz
`AGENTEYE_ENVIRONMENT`	Define `environment` sem alterar o código, para quando o rótulo pertence ao deployment e não à aplicação. Um argumento de `configure()` tem precedência sobre ela.
`FAILPROOFAI_HOME`	Move a raiz do Failproof AI que contém o spool.
`FAILPROOFAI_SDK_STRICT`	`1` faz com que erros de instrumentação sejam lançados em vez de apenas registrados.
`FAILPROOFAI_SDK_STRICT_INTEGRATIONS`	`1` faz com que um problema de compatibilidade com framework seja lançado em vez de apenas avisar e continuar.

Sem vírgulas em environment. O ingest divide esse campo por vírgulas para construir seus filtros e ignora qualquer evento cujo rótulo contenha uma — fazendo com que toda uma execução desapareça silenciosamente. Escreva prod-eu, não prod,eu.configure(environment="prod,eu") lança um erro imediatamente. AGENTEYE_ENVIRONMENT não pode lançar — não há quem o chame — então emite um aviso uma vez e usa dev como fallback.

Os eventos são enfileirados em memória e gravados em segundo plano a cada flush_interval segundos, com um flush final ao encerrar o interpretador. Um processo encerrado abruptamente perde tudo que ainda não havia sido gravado.

Identidade

Todo evento pertence a uma sessão e a um agente. Os escopos preenchem ambos automaticamente, então raramente você precisa passá-los:

with failproofai_sdk.session():
    with failproofai_sdk.agent("planner"):
        failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1")

Passar session_id ou agent_id explicitamente ainda funciona e tem precedência. Se nem um estiver vinculado nem passado, a chamada lança TypeError em vez de emitir um evento que a Cloud descartaria silenciosamente.

A identidade usa variáveis de contexto. Ela segue tasks asyncio automaticamente, mas não novas threads — envolva um worker com failproofai_sdk.propagate() ou seus eventos serão emitidos sem vínculo.

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.

	Abre	Fecha
Agentes	`agent_start`	`agent_end`
	`agent_pause`	`agent_resume`
Modelos	`model_request`	`model_response`
Ferramentas	`tool_use`	`tool_result`
Hooks	`hook_triggered`	`hook_completed`
Humanos	`human_wait`	`human_input`

Três são independentes: error, human_pause, human_interrupt.

Todos os campos por método

Todo 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 todo método retorna None.

Método	Obrigatório	Opcional
`agent_start`	—	`goal`, `parent_id`
`agent_end`	—	`outcome`, `summary`
`agent_pause`	`pause_id`	`reason`, `user_id`
`agent_resume`	`pause_id`	`reason`, `user_id`
`model_request`	—	`model`, `messages`, `system`, `tools`, `request_id`
`model_response`	—	`model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role`, `request_id`, `duration_ms`
`tool_use`	`tool_name`, `tool_call_id`	`input`
`tool_result`	`tool_name`, `tool_call_id`	`output`, `error`
`hook_triggered`	`hook_name`, `hook_id`	`trigger_event`, `input`
`hook_completed`	`hook_name`, `hook_id`	`outcome`, `output`, `error`
`error`	`error_type`, `message`	`traceback`
`human_wait`	`input_id`	`prompt`, `options`, `reason`
`human_input`	`input_id`	`response`
`human_pause`	—	`reason`, `user_id`
`human_interrupt`	—	`reason`, `user_id`, `at_step`

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" — é tratado como sucesso.

Pareamento e duração

Uma regra: passe o mesmo id ao evento de fechamento que foi usado no evento de abertura. É isso que os emparelha e permite ao SDK medir o intervalo.

Par	Correspondência por
`tool_use` → `tool_result`	`tool_call_id`
`hook_triggered` → `hook_completed`	`hook_id`
`agent_pause` → `agent_resume`	`pause_id`
`human_wait` → `human_input`	`input_id`
`model_request` → `model_response`	`request_id`

Não passe duration_ms manualmente. O SDK o mede, 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 erro, pois a coluna é um inteiro de 32 bits e ficaria vazia caso contrário.

Casos extremos

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 rodando ao mesmo tempo podem reutilizar os mesmos ids sem conflito.
Eles não têm escopo por agente. Um par aberto em um agente e fechado em outro ainda é emparelhado corretamente — o que é o caso normal em código multi-agente.
request_id é opcional, mas recomendado. Sem ele, os 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 Cloud, mas o SDK não consegue medir o tempo — nenhum dos processos viu ambas as metades.
No máximo 10.000 abridores aguardam um fechador ao mesmo tempo. Além disso, o mais antigo é descartado, evitando que um vazamento cresça indefinidamente.

Campos próprios

Qualquer palavra-chave extra que você passar é armazenada junto ao evento:

failproofai_sdk.event.tool_use(
    tool_name="search", tool_call_id="c1",
    fw_tenant="acme", fw_region="eu-west-1",     # seus próprios
)

Prefira tipos JSON se quiser consultá-los depois. Qualquer outro tipo — UUID, datetime, Decimal, set, bytes, objeto de modelo — é armazenado como string.

Prefixe seus nomes de campo. Os extras são aplicados por último, então um campo chamado model, tool_name ou outcome sobrescreve silenciosamente o valor real. Os adaptadores de framework usam fw_; faça o mesmo e não haverá conflitos.É também por isso que um campo opcional com nome errado nunca gera erro — ele simplesmente se torna um novo campo customizado. Se um campo padrão estiver ausente na Cloud, verifique a ortografia primeiro.

Estes cinco nomes são reservados e rejeitados diretamente: timestamp, session_id, agent_id, type, environment.

Entrega e verificação

Dashboard
CLI

Em Observe → Events, verifique se agent_start existe primeiro e agent_end existe por último. Em seguida, abra Observe → Sessions e confirme se os eventos de modelo, ferramenta, humano, hook e erro aparecem na ordem esperada. Use o ID da sessão como chave principal de troubleshooting.

failproofai flush --wait --timeout 60
failproofai config --status
fp sessions --since 1h --env production --session-id <session-id>
fp events --since 1h --session-id <session-id> --full

Se a Cloud estiver vazia, inspecione $FAILPROOFAI_HOME/custom-agents/events, caso contrário ~/.failproofai/custom-agents/events. Arquivos JSONL comprovam a emissão pelo SDK; um spool crescendo indica problema de configuração ou entrega do daemon, 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 está em execução, ele coleta e exclui cada lote em milissegundos, então uma listagem de diretório disputa com o coletor e mostra muito menos eventos do que foram emitidos.

Prevenir falhas em um runtime customizado

Use os achados de auditoria e os traces vinculados para definir a ação insegura, as evidências necessárias e a resposta pretendida. Uma integração de enforcement customizada 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 ajudá-lo a mapear os limites de modelo, ferramenta e ciclo de vida do seu runtime para hooks de política e, em seguida, validar a integração com você.

Connect your agents

Reference

Guia de agentes customizados

Usando um framework?

Instalação

Conectar o daemon do Failproof

Configuração

Identidade

Catálogo de eventos

Pareamento e duração

Campos próprios

Entrega e verificação

Prevenir falhas em um runtime customizado

Guia de agentes customizados

Usando um framework?

​Instalação

​Conectar o daemon do Failproof

​Configuração

​Identidade

​Catálogo de eventos

​Pareamento e duração

​Campos próprios

​Entrega e verificação

​Prevenir falhas em um runtime customizado

Instalação

Conectar o daemon do Failproof

Configuração

Identidade

Catálogo de eventos

Pareamento e duração

Campos próprios

Entrega e verificação

Prevenir falhas em um runtime customizado