Python SDK

Veja exatamente o que seus agentes de IA fizeram em produção: cada execução de agente, chamada de ferramenta, requisição ao modelo, hook e intervenção humana. O Python SDK de Observabilidade do Failproof AI registra esse rastro a partir do código do seu agente para que você possa depurar, auditar e avaliar o que aconteceu. Use-o sempre que quiser que a Observabilidade do Failproof AI monitore seus agentes. Por baixo dos panos, o SDK escreve eventos estruturados em arquivos JSONL locais, e o daemon coletor os captura e os envia automaticamente para a plataforma. Você não precisa gerenciar esses arquivos diretamente.

Dica: Novo na Observabilidade do Failproof AI? Esta página é a referência completa de eventos do SDK.

Instalação

O SDK é distribuído aos clientes como um wheel privado, e não por meio de um índice de pacotes público. O processo de onboarding cobre como obtê-lo, instalá-lo e fixar sua versão — fale com seu contato do Failproof AI se precisar de acesso. Após a instalação, confirme que ele está disponível:

python -c "import agenteye; print(agenteye.__version__)"

Prefere deixar um agente de codificação fazer toda a integração? A Python SDK Agent Skill conhece o caminho de instalação, planeja os pontos de instrumentação, os implementa e verifica se os eventos chegam corretamente.

Início Rápido

import agenteye

agenteye.configure(environment="production")

agenteye.event.agent_start(session_id="run-001", agent_id="planner", goal="answer user query")

agenteye.event.tool_use(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",
    tool_call_id="toolu_01",
    input={"query": "latest AI research"},
)

agenteye.event.tool_result(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",
    tool_call_id="toolu_01",
    output={"results": ["..."]},
)

agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="success")

Instrumentando uma chamada real

Na prática, você envolve seu código de agente existente. Enquadre uma chamada ao modelo com model_request antes e model_response depois, para que os dois eventos abranjam a requisição real e a Observabilidade do Failproof AI possa correlacioná-los:

import anthropic
import agenteye

agenteye.configure(environment="production")
client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Summarise today's incidents."}]

agenteye.event.model_request(
    session_id="run-001",
    agent_id="planner",
    model="claude-sonnet-4-6",
    messages=messages,
)

reply = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=512,
    messages=messages,
)

agenteye.event.model_response(
    session_id="run-001",
    agent_id="planner",
    model=reply.model,
    stop_reason=reply.stop_reason,
    input_tokens=reply.usage.input_tokens,
    output_tokens=reply.usage.output_tokens,
    content=[block.model_dump() for block in reply.content],
)

Envolva as chamadas de ferramentas da mesma forma com tool_use e tool_result, reutilizando o mesmo tool_call_id no par. Veja como esses eventos aparecem no dashboard, com codificação de cores por tipo e filtráveis por ambiente, agente e sessão:

O stream de eventos ao vivo, com codificação de cores por tipo de evento e filtrável por ambiente, agente e sessão

configure()

agenteye.configure(
    base_dir=None,           # Path | str | None. Default: $AGENTEYE_HOME or ~/.agenteye
    flush_interval=0.5,      # float, seconds between flush cycles
    environment=None,        # str | None. Deployment environment label
)

Chame uma vez antes de qualquer chamada event.*. É seguro omitir; os valores padrão funcionam sem configuração adicional. Todos os argumentos são somente por nome de chave; passe-os pelo nome conforme mostrado acima. Quando base_dir é None (o padrão), o SDK lê $AGENTEYE_HOME se estiver definido, caso contrário recorre a ~/.agenteye. Isso corresponde à própria resolução do coletor, então uma única variável de ambiente AGENTEYE_HOME configura o spool de eventos compartilhado tanto para o SDK quanto para o coletor.

Ambiente

Rotule cada evento com um ambiente de implantação (production, staging, qa, canary, etc.). Defina uma vez; o SDK o anexa a todos os eventos automaticamente. Opção 1: via configure():

agenteye.configure(environment="production")

Opção 2: via variável de ambiente:

export AGENTEYE_ENVIRONMENT=production

Prioridade: configure(environment=...) tem precedência sobre a variável de ambiente. Se nenhum dos dois for definido, o padrão é "dev". O valor do ambiente aparece como um filtro de primeira classe no dashboard e é armazenado no servidor para consultas rápidas.

Aviso: Os valores de ambiente não devem conter uma vírgula , literal. Os filtros do dashboard usam seleção múltipla separada por vírgulas na requisição (?environment=prod,staging), então um ambiente chamado prod,blue seria dividido em dois valores. Eventos com ambientes contendo vírgulas são rejeitados no momento da ingestão.

Dados e privacidade

O SDK registra apenas os campos que você passa explicitamente. Prompts, mensagens, entradas e saídas de ferramentas e conteúdo do modelo são capturados somente porque você os entrega a uma chamada event.*. Nada é lido do seu processo ou capturado implicitamente. Qualquer campo que você deixar sem definir é omitido do evento completamente; ele não é gravado em disco. Isso torna a redação sua escolha e sua responsabilidade. Se um prompt ou payload de ferramenta contiver PII ou segredos que você prefere não armazenar, filtre ou mascare-os antes de passá-los ao método de evento.

Referência de Eventos

A maioria dos eventos vem em pares início/fim que compartilham um ID de correlação: tool_use e tool_result compartilham um tool_call_id, hook_triggered e hook_completed compartilham um hook_id, e human_wait e human_input compartilham um input_id. Emita o evento de início, execute o trabalho e então emita o evento de fim com o mesmo ID. A Observabilidade do Failproof AI correlaciona o par e calcula duration_ms para você, então você nunca passa duration_ms diretamente.

O grafo de execução no estilo git de uma sessão ao lado de sua linha do tempo de eventos, reconstruído a partir dos eventos pareados, com o painel de detalhamento ferramenta/modelo/hook

Todos os métodos de evento requerem estes dois campos:

Campo	Tipo	Descrição
`session_id`	`str`	Identifica a execução de agente de nível superior
`agent_id`	`str`	Identifica qual agente dentro da sessão emitiu o evento

Todos os métodos também aceitam **kwargs arbitrários para metadados personalizados (consulte Campos Personalizados).

`event.agent_start()`

Emitido quando um agente começa a trabalhar.

agenteye.event.agent_start(
    session_id="run-001",
    agent_id="planner",
    goal="answer user query",   # str | None
    parent_id=None,             # str | None - parent agent_id for nested agents
)

`event.agent_end()`

Emitido quando um agente termina seu trabalho.

agenteye.event.agent_end(
    session_id="run-001",
    agent_id="planner",
    outcome="success",          # str | None
    summary="Answered query",   # str | None
)

`event.tool_use()`

Emitido quando um agente invoca uma ferramenta. Pareie com tool_result; o SDK calcula duration_ms automaticamente.

agenteye.event.tool_use(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",     # str, required
    tool_call_id="toolu_01",    # str, required - correlation key for the matching tool_result
    input={"query": "..."},     # dict | None
)

`event.tool_result()`

Emitido quando uma ferramenta retorna. Correlaciona com tool_use via tool_call_id.

agenteye.event.tool_result(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",
    tool_call_id="toolu_01",        # must match the prior tool_use
    output={"results": ["..."]},    # Any | None
    error=None,                     # str | None - set if the tool raised
    # duration_ms is computed automatically - do not pass it
)

`event.model_request()`

Emitido imediatamente antes de enviar um prompt a um LLM.

agenteye.event.model_request(
    session_id="run-001",
    agent_id="planner",
    model="claude-sonnet-4-6", # str | None - any provider/model string; not validated
    messages=[                   # list[dict] | None - conversation turns
        {"role": "user", "content": "..."},
    ],
    system="You are helpful.",   # Any | None - str or list of content blocks
    tools=[                      # list[dict] | None - tool schemas offered to the model
        {"name": "search", "input_schema": {"type": "object"}},
    ],
)

As entradas de messages aceitam tanto uma content como string simples quanto content no estilo Anthropic como lista de blocos. Parâmetros de amostragem (temperature, max_tokens, etc.) podem ser passados como kwargs extras.

`event.model_response()`

Emitido quando o LLM retorna uma resposta.

agenteye.event.model_response(
    session_id="run-001",
    agent_id="planner",
    model="claude-sonnet-4-6", # str | None - any provider/model string; not validated
    stop_reason="end_turn",     # str | None
    input_tokens=1024,          # int | None
    output_tokens=256,          # int | None
    content=[                    # Any | None - str, or list of content blocks
        {"type": "text", "text": "..."},
    ],
    role="assistant",            # str | None
)

content aceita tanto uma string simples (provedores genéricos) quanto uma lista de blocos de conteúdo no estilo Anthropic. Chamadas de ferramentas ficam dentro de content como blocos {"type": "tool_use", ...}, sem um campo separado tool_calls.

`event.hook_triggered()`

Emitido quando um hook é acionado. Pareie com hook_completed; o SDK calcula duration_ms automaticamente.

agenteye.event.hook_triggered(
    session_id="run-001",
    agent_id="planner",
    hook_name="pre_tool_use",   # str, required
    hook_id="hook-abc",         # str, required - correlation key
    trigger_event="tool_use",   # str | None
    input={"tool": "search"},   # Any | None
)

`event.hook_completed()`

Emitido quando um hook termina. Correlaciona com hook_triggered via hook_id.

agenteye.event.hook_completed(
    session_id="run-001",
    agent_id="planner",
    hook_name="pre_tool_use",
    hook_id="hook-abc",         # must match the prior hook_triggered
    outcome="allow",            # str | None
    output=None,                # Any | None
    error=None,                 # str | None
    # duration_ms is computed automatically - do not pass it
)

`event.error()`

Emitido quando ocorre um erro não tratado.

agenteye.event.error(
    session_id="run-001",
    agent_id="planner",
    error_type="TimeoutError",  # str, required
    message="timed out",        # str, required
    traceback="Traceback...",   # str | None
)

Eventos de Humano no Ciclo

Os eventos de humano no ciclo (human-in-the-loop) oferecem supervisão sobre os momentos em que uma pessoa intervém na execução do agente (aguardando aprovação, fornecendo entrada, pausando ou interrompendo o agente). Eles permitem medir quanto tempo os humanos levam para responder (o SDK calcula duration_ms automaticamente nos eventos pareados), auditar quem pausou ou interrompeu um agente, e construir fluxos de trabalho de aprovação e supervisão que aparecem no dashboard.

`event.human_wait()`

Emitido quando o agente pausa a execução para aguardar que um humano forneça entrada. Pareie com human_input; o SDK calcula duration_ms automaticamente (quanto tempo o humano levou para responder).

agenteye.event.human_wait(
    session_id="run-001",
    agent_id="planner",
    input_id="inp-abc",                          # str, required - correlation key for the matching human_input
    prompt="Do you approve this action?",        # str | None - the question shown to the human
    options=["approve", "reject", "defer"],      # list[str] | None - choices presented to the human
    reason="approval_required",                  # str | None - why the agent is waiting
)

`event.human_input()`

Emitido quando um humano fornece entrada e o agente retoma a execução. Correlaciona com human_wait via input_id. duration_ms é calculado automaticamente e não deve ser passado pelo chamador.

agenteye.event.human_input(
    session_id="run-001",
    agent_id="planner",
    input_id="inp-abc",    # str, required - must match the prior human_wait
    response="approve",    # str | None - the human's answer (free text or selected option)
    # duration_ms is computed automatically - do not pass it
)

`event.human_pause()`

Emitido quando um humano pausa ativamente o agente (por exemplo, via controle no dashboard). O agente é suspenso, mas não encerrado.

agenteye.event.human_pause(
    session_id="run-001",
    agent_id="planner",
    reason="user_requested",  # str | None
    user_id="usr_42",         # str | None - who paused the agent
)

`event.human_interrupt()`

Emitido quando um humano para ativamente o agente durante a execução. Diferente de human_pause, o trabalho do agente é encerrado em vez de suspenso.

agenteye.event.human_interrupt(
    session_id="run-001",
    agent_id="planner",
    reason="output_incorrect",       # str | None
    user_id="usr_42",                # str | None - who interrupted the agent
    at_step="tool_use:web_search",   # str | None - what the agent was doing when stopped
)

Campos Personalizados

Quaisquer argumentos de palavra-chave extras são acrescentados ao evento após os campos padrão:

agenteye.event.tool_use(
    session_id="run-001",
    agent_id="planner",
    tool_name="db_query",
    tool_call_id="toolu_02",
    tenant_id="acme",           # custom field
    region="us-east-1",         # custom field
)

timestamp, type e environment são reservados e geram ValueError (Reserved field names cannot be used as custom fields: [...]) se passados como campos personalizados. session_id e agent_id são parâmetros obrigatórios em todos os métodos de evento e não podem ser fornecidos uma segunda vez; o Python gera TypeError se você tentar. Defina o ambiente com configure(environment=...) (ou a variável AGENTEYE_ENVIRONMENT) em vez disso. Mantenha os payloads como JSON estruturado quando quiser consultar seus campos. Valores que o JSON não suporta nativamente — como datetimes, UUIDs, decimais, sets, bytes ou objetos de modelo — são convertidos para strings para que o registro continue com segurança.

Como os Eventos São Gravados

Os eventos são armazenados em buffer no processo e descarregados em disco a cada flush_interval segundos (padrão: 500 ms). Cada descarga grava um arquivo JSONL:

~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl

O coletor monitora este diretório e faz o upload dos arquivos automaticamente. Você não precisa gerenciar esses arquivos diretamente. Cada arquivo é gravado atomicamente: o SDK escreve em um arquivo temporário e então o renomeia para o local final, de modo que o coletor nunca veja um arquivo gravado pela metade. Uma descarga final também é executada quando seu processo sai, para que os eventos armazenados em buffer no último intervalo não sejam perdidos. Se o coletor estiver offline, os eventos simplesmente se acumulam como arquivos em disco e são enviados assim que ele voltar.

Próximos passos

Stream de eventos: acompanhe esses eventos chegando ao vivo, com codificação de cores e filtrável por ambiente, agente e sessão.
Sessões: veja como os eventos pareados reconstroem cada execução de agente como um grafo de execução e linha do tempo.

Overview

Features

SDK and CLI

Administration

Instalação

Início Rápido

Instrumentando uma chamada real

configure()

Ambiente

Dados e privacidade

Referência de Eventos

`event.agent_start()`

`event.agent_end()`

`event.tool_use()`

`event.tool_result()`

`event.model_request()`

`event.model_response()`

`event.hook_triggered()`

`event.hook_completed()`

`event.error()`

Eventos de Humano no Ciclo

`event.human_wait()`

`event.human_input()`

`event.human_pause()`

`event.human_interrupt()`

Campos Personalizados

Como os Eventos São Gravados

Próximos passos

​Instalação

​Início Rápido

​Instrumentando uma chamada real

​configure()

​Ambiente

​Dados e privacidade

​Referência de Eventos

​event.agent_start()

​event.agent_end()

​event.tool_use()

​event.tool_result()

​event.model_request()

​event.model_response()

​event.hook_triggered()

​event.hook_completed()

​event.error()

​Eventos de Humano no Ciclo

​event.human_wait()

​event.human_input()

​event.human_pause()

​event.human_interrupt()

​Campos Personalizados

​Como os Eventos São Gravados

​Próximos passos

Instalação

Início Rápido

Instrumentando uma chamada real

configure()

Ambiente

Dados e privacidade

Referência de Eventos

`event.agent_start()`

`event.agent_end()`

`event.tool_use()`

`event.tool_result()`

`event.model_request()`

`event.model_response()`

`event.hook_triggered()`

`event.hook_completed()`

`event.error()`

Eventos de Humano no Ciclo

`event.human_wait()`

`event.human_input()`

`event.human_pause()`

`event.human_interrupt()`

Campos Personalizados

Como os Eventos São Gravados

Próximos passos