kpi-agentes 0.1.0

SDK para monitoramento e observabilidade de agentes de IA — KPI Agentes

kpi-agentes

SDK Python para monitoramento e observabilidade de agentes de IA.

Integre qualquer agente LLM em segundos e acompanhe Faithfulness, Relevancy, latência, custo por token e muito mais no painel KPI Agentes.

Instalação

pip install kpi-agentes

Início rápido

import time
import asyncio
from kpi_agentes import KPIReporter

# Inicialize uma vez (após as configs globais do seu app)
kpi = KPIReporter(
    agent_id = "uuid-do-seu-agente",   # obtido no painel KPI Agentes
    base_url = "https://seu-servidor.com",
)

# No endpoint de chat — fire-and-forget, não atrasa a resposta
@app.post("/chat")
async def chat(request):
    _t0 = time.monotonic()
    result = await run_agent(request.message)

    asyncio.create_task(kpi.report(
        question         = request.message,
        answer           = result["reply"],
        context_chunks   = result.get("context_chunks", []),   # habilita RAG metrics
        provider         = "gemini",
        model            = "gemini-2.5-flash",
        total_latency_ms = int((time.monotonic() - _t0) * 1000),
        status           = "completed",
    ))

    return result

Parâmetros do KPIReporter

Parâmetro	Tipo	Obrigatório	Descrição
agent_id	str	✅	UUID do agente no painel KPI
agent_version_id	str	❌	UUID da versão (para comparação A/B)
base_url	str	❌	URL do backend KPI (padrão: http://localhost:8001)
timeout	float	❌	Timeout HTTP em segundos (padrão: 8.0)
enabled	bool	❌	False desativa sem remover código (padrão: True)

Parâmetros do kpi.report()

Parâmetro	Tipo	Descrição
question	str	Pergunta do usuário
answer	str	Resposta do agente
context_chunks	list[str]	Trechos do RAG (habilita Faithfulness/Relevancy)
provider	str	Ex: "gemini", "openai", "groq"
model	str	Ex: "gemini-2.5-flash", "gpt-4o-mini"
total_latency_ms	int	Latência total em ms
ttft_ms	int	Time to First Token em ms
prompt_tokens	int	Tokens de entrada
completion_tokens	int	Tokens de saída
tool_results	list[dict]	Resultados de tool calls
user_guid	str	ID do usuário (anonimizado)
session_id	str	ID da sessão
status	str	"completed" | "error" | "timeout"
metadata	dict	Dados adicionais livres

KPIs monitorados

• Faithfulness — fidelidade da resposta ao contexto RAG
• Relevancy — relevância da resposta à pergunta
• Latência — p50, p95, p99 e média
• TTFT — Time to First Token
• Custo por interação — baseado em token usage
• Success Rate — taxa de resoluções bem-sucedidas
• Error Rate — taxa de erros
• Tool Calls — rastreamento de chamadas de ferramentas

Requisitos

• Python 3.10+
• httpx (instalado automaticamente)
• Backend KPI Agentes rodando e acessível

Licença

MIT