Avaliações, Red Teaming e Geração de Testes para Sistemas Agênticos

Modular, Leve, Dinâmico e Async-first

Documentação • Site • Comunidade

[!IMPORTANT] O Giskard v3 é uma reescrita completa projetada para testes dinâmicos e de múltiplas interações (multi-turn) de agentes de IA. Esta versão elimina dependências pesadas em prol de maior eficiência, ao mesmo tempo que introduz um scanner de vulnerabilidades de IA mais poderoso e uma avaliação RAG aprimorada — ambos agora disponíveis nativamente no giskard-scan (beta), sem dependência do v2. Apenas o scan legado para modelos tabulares/ML permanece exclusivo do v2. O Giskard v2 continua disponível, mas não é mais mantido ativamente. Acompanhe o progresso → Leia o anúncio do v3 · Roadmap

Instalação

pip install giskard           # checks (+ agents, llm, core)
pip install "giskard[scan]"   # + vulnerability / quality scan
pip install "giskard[openai]" # provider SDK for LLM judges / generators

Requer Python 3.12+.

Telemetria: análises agregadas opcionais via giskard-core. Nenhum prompt ou saída é enviado. Desative antes de importar o Giskard: export DO_NOT_TRACK=1 ou export GISKARD_TELEMETRY_DISABLED=1. Detalhes: giskard-core README.

O Giskard é uma biblioteca Python de código aberto para testar e avaliar sistemas agênticos. A arquitetura v3 é um conjunto modular de pacotes focados — cada um carregando apenas as dependências de que precisa — construídos do zero para envolver qualquer coisa: um LLM, um agente de caixa-preta ou um pipeline de múltiplas etapas.

Esses pacotes se baseiam em três bibliotecas fundamentais — giskard-core (utilitários compartilhados e telemetria), giskard-llm (roteamento de LLM agnóstico de provedor) e giskard-agents (orquestração de agentes e fluxos de trabalho) — que são incluídos automaticamente e raramente usados diretamente.

Giskard Checks — crie e aplique avaliações para testar agentes

pip install giskard-checks

Giskard Checks é uma biblioteca leve para criar avaliações (evals) que testam sistemas baseados em LLM — desde asserções simples até avaliações LLM-as-judge. Ao contrário dos testes de unidade tradicionais, as evals são projetadas para saídas não determinísticas, em que a mesma entrada pode produzir diferentes respostas válidas.

Use o Giskard Checks para:

• Detectar regressões — verificar se o seu sistema continua se comportando corretamente após mudanças
• Validar a qualidade do RAG — verificar se as respostas estão fundamentadas no contexto recuperado
• Aplicar regras de segurança — garantir que as saídas estejam em conformidade com suas políticas de conteúdo
• Avaliar agentes multi-turn — testar conversas completas, não apenas trocas únicas

As evals integradas incluem correspondência de strings, comparações, regex, similaridade semântica e verificações LLM-as-judge (Groundedness, Conformity, LLMJudge).

Conceitos

• Alvo — seu sistema em teste: qualquer chamável síncrono/assíncrono (inputs) -> outputs (opcionalmente com trace)
• Cenário — uma avaliação: interações + verificações
• Verificação — asserção ou juiz LLM sobre o trace
• Suíte — muitos cenários executados em conjunto

giskard.agents.Generator é um cliente LLM para fluxos de trabalho/juízes — não é o mesmo que os geradores de entrada do giskard.checks (LLMGenerator), que sintetizam mensagens de usuário.

Início rápido

import asyncio
from giskard.checks import Scenario, Groundedness


def get_answer(inputs: str) -> str:
    return "Paris"  # replace with your model / agent


async def main() -> None:
    scenario = (
        Scenario("test_france_capital")
        .interact(inputs="What is the capital of France?", outputs=get_answer)
        .check(
            Groundedness(
                name="answer is grounded",
                context="France is in Western Europe. Its capital is Paris.",
            )
        )
    )
    result = await scenario.run()
    result.print_report()


asyncio.run(main())

Groundedness é um juiz LLM — instale um extra de provedor (ex.: pip install "giskard[openai]") e defina a chave de API correspondente. Modelo padrão: openai/gpt-4o-mini.

Consulte a documentação completa para Suites, LLMJudge, cenários multi-turn e muito mais.

Giskard Scan — scanner de vulnerabilidades para agentes de IA

pip install "giskard[scan]"   # or: pip install giskard-scan

O Giskard Scan é a camada de red teaming e varredura de vulnerabilidades para sistemas agênticos. Ele gera suítes de testes adversários automaticamente a partir de uma descrição em linguagem simples do seu agente, cobrindo injeção de prompt, conteúdo nocivo, estereótipos, desinformação e muito mais.

Use o Giskard Scan para:

• Fazer red team no seu agente — gerar automaticamente entradas adversárias nas categorias de ameaças do OWASP LLM Top-10
• Executar sondas de injeção de prompt — conjunto de dados integrado de payloads de injeção pronto para uso
• Estender com geradores personalizados — passe suas próprias instâncias de ScenarioGenerator para generate_suite, ou registre-as em vulnerability_suite_generator_registry

Início rápido

import asyncio
from giskard.scan import vulnerability_scan


async def my_agent(inputs: str) -> str:
    # Replace with your agent / model call
    return f"Echo: {inputs}"


async def main() -> None:
    await vulnerability_scan(
        target=my_agent,
        description="A customer support chatbot for an e-commerce platform.",
        languages=["en"],
    )


asyncio.run(main())

Os geradores de scan também precisam de um extra de provedor LLM e de uma chave de API (assim como os juízes do Checks acima).

Procurando pelo Giskard v2?

O Giskard v2 incluía o Scan (detecção automática de vulnerabilidades) e o RAGET (geração de conjuntos de teste para avaliação de RAG).

Para agentes LLM, ambos são substituídos no v3 pelo giskard-scan: use o vulnerability_scan no lugar do scan LLM do v2, e o quality_scan (com KnowledgeBase) no lugar do RAGET.

O v3 também funciona com modelos de ML — envolva um como alvo e avalie-o com giskard-checks ou giskard-scan. O que os exemplos abaixo abordam é o scan tabular automático exclusivo do v2 — a suíte de detectores que inspeciona um giskard.Model + giskard.Dataset para detectar automaticamente problemas de desempenho, viés e robustez — além da suíte de testes de ML giskard.testing e do Giskard Hub. Esses recursos não estão planejados para o v3.

pip install "giskard[llm]>2,<3"

Scan — detecte automaticamente problemas de desempenho, viés e segurança

Envolva seu modelo e execute o scan:

import giskard
import pandas as pd


# Replace my_llm_chain with your actual LLM chain or model inference logic
def model_predict(df: pd.DataFrame):
    """The function takes a DataFrame and must return a list of outputs (one per row)."""
    return [my_llm_chain.run({"query": question}) for question in df["question"]]


giskard_model = giskard.Model(
    model=model_predict,
    model_type="text_generation",
    name="My LLM Application",
    description="A question answering assistant",
    feature_names=["question"],
)

scan_results = giskard.scan(giskard_model)
display(scan_results)

RAGET — gere conjuntos de dados de avaliação para aplicações RAG

Gere automaticamente perguntas, respostas de referência e contexto a partir da sua base de conhecimento:

import pandas as pd
from giskard.rag import generate_testset, KnowledgeBase

# Load your knowledge base documents
df = pd.read_csv("path/to/your/knowledge_base.csv")
knowledge_base = KnowledgeBase.from_pandas(df, columns=["column_1", "column_2"])

testset = generate_testset(
    knowledge_base,
    num_questions=60,
    language="en",
    agent_description="A customer support chatbot for company X",
)

Documentação completa do v2

👋 Comunidade

Recebemos contribuições da comunidade de IA! Leia este guia para começar e junte-se à nossa próspera comunidade no Discord.

Acompanhe o progresso e compartilhe feedback: Anúncio do v3 · Roadmap

🌟 Deixe-nos uma estrela; isso ajuda o projeto a ser descoberto por outras pessoas e nos mantém motivados a construir ferramentas de código aberto incríveis! 🌟

❤️ Se você achar nosso trabalho útil, considere nos patrocinar no GitHub. Com um patrocínio mensal, você pode obter um selo de patrocinador, exibir sua empresa neste readme e ter seus relatórios de bugs priorizados. Também oferecemos patrocínio pontual se você quiser que nos envolvamos em um projeto de consultoria, ministremos um workshop ou façamos uma apresentação na sua empresa.