> For the complete documentation index, see [llms.txt](https://rws.gitbook.io/rws/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rws.gitbook.io/rws/index-public-articles.md).

# Guia Didático do Framework Ragas: Avaliação e Métricas de RAG e Agentes

## Abstract

Este artigo é um guia didático e prático sobre o **Ragas** (v0.4 Stable), a principal referência científica em código aberto para avaliação qualitativa e quantitativa de sistemas generativos. O documento explica o paradigma de avaliação baseada em LLM (*AI-as-a-Judge*), detalha a clássica **Tríade de RAG** (Fidelidade, Relevância, Revocação e Precisão) com diagramas de fluxo, explora a nova fronteira de **Avaliação de Agentes Inteligentes** (acurácia de ferramentas e aderência a tópicos) e fornece exemplos completos e funcionais de código em Python para implementação imediata em pipelines de CI/CD.

***

## 1. O Desafio de Avaliar Sistemas Probabilísticos

No desenvolvimento de software tradicional, os testes de código são determinísticos: se uma função recebe `soma(2, 2)`, esperamos exatamente `4`. Na engenharia de IA generativa, as saídas são probabilísticas. A mesma entrada pode gerar infinitas variações de texto corretas, erradas ou, pior, alucinações extremamente convincentes.

Para resolver isso de forma escalável e evitar revisões manuais humanas exaustivas e caras, o Ragas utiliza o padrão **AI-as-a-Judge (IA como Juiz)**. Usando modelos de linguagem poderosos calibrados por prompts científicos (com suporte a Rastreabilidade e *Reasoning*), o framework destrincha o pipeline e avalia de forma quantitativa cada componente da experiência cognitiva.

***

## 2. A Tríade de RAG (v0.4 Stable)

Avaliar apenas a resposta final do usuário esconde problemas silenciosos. Por exemplo: se a resposta for ruim, a culpa foi do banco vetorial (*retriever*) que trouxe documentos irrelevantes ou do modelo de linguagem (*generator*) que ignorou os documentos certos?

O Ragas soluciona este isolamento metodológico dividindo a avaliação em três pilares principais (Tríade de RAG), gerando 4 métricas core:

```mermaid
graph TD
    subgraph "A Tríade de RAG"
        Q["Pergunta do Usuário (Query)"] -->|1 - Busca Semântica| R["Contexto Recuperado (Contexts)"]
        R -->|2 - Prompt Aumentado| G["Resposta Gerada (Answer)"]
        
        %% Métricas de Ingestão e Recuperação
        Q -.->|Context Precision & Recall| R
        
        %% Métricas de Geração
        R -.->|Faithfulness| G
        Q -.->|Answer Relevancy| G
    end

    style Q fill:#cce5ff,stroke:#004085,stroke-width:2px
    style R fill:#fff3cd,stroke:#856404,stroke-width:2px
    style G fill:#d4edda,stroke:#28a745,stroke-width:2px
```

### Detalhamento das Métricas Core:

#### A. Context Precision (Precisão do Contexto)

* **O que mede**: Os chunks de informação altamente relevantes foram colocados nas primeiras posições de busca pelo retriever?
* **Como funciona**: O Ragas avalia a ordenação semântica e atribui notas mais baixas caso a resposta certa esteja "escondida" no final de uma lista longa de chunks irrelevantes.

#### B. Context Recall (Revocação do Contexto)

* **O que mede**: A informação necessária para responder à pergunta estava de fato presente no contexto recuperado?
* **Como funciona**: O Ragas compara as alegações da resposta de referência (*reference*) contra os chunks recuperados, garantindo que o banco de dados trouxe o que era esperado.

#### C. Faithfulness (Fidelidade / Groundedness)

* **O que mede**: A resposta final gerada se baseia estritamente no contexto recuperado, ou a IA "alucinou" trazendo informações externas?
* **Como funciona**: A resposta gerada é dividida em proposições lógicas atômicas, e cada uma é checada contra o contexto. É uma métrica que não necessita de resposta de referência humana (*reference-free*).

#### D. Answer Relevancy (Relevância da Resposta)

* **O que mede**: A resposta gerada realmente responde ao que o usuário perguntou, ou ela é vaga/incompleta?
* **Como funciona**: O Ragas gera perguntas hipotéticas a partir da resposta e compara a similaridade semântica destas perguntas geradas com a pergunta original do usuário.

***

## 3. Avaliação de Agentes Inteligentes (Multi-Turn & Traces)

À medida que os sistemas evoluem de prompts simples para agentes autônomos que tomam decisões e acionam ferramentas (ex: MCP Servers ou APIs SAP), a avaliação tradicional de turno único se torna obsoleta. Avaliar agentes exige focar no **Trace de Execução (Rastro de Spans)**.

O Ragas intercepta os passos lógicos executados e avalia:

```mermaid
sequenceDiagram
    autonumber
    participant U as Usuário
    participant A as Loop do Agente
    participant T as Execução de Ferramenta
    participant R as Ragas Evaluator

    U->>A: Pergunta: "Quanto sobrou no caixa de vendas?"
    A->>T: Invoca: run_bigquery_sql()
    T-->>A: Retorna: "Saldo: $54,000"
    A->>U: Resposta: "O caixa atual é de R$ 54.000."
    
    Note over A,R: Trace de Execução capturado pelo Ragas
    R->>R: Compara ferramentas usadas contra referências esperadas (ToolCallAccuracy)
    R->>R: Analisa se o agente manteve a coerência sem desviar do assunto (TopicAdherence)
```

* **Tool Call Accuracy (Acurácia de Chamadas de Ferramenta)**: Mede a exatidão das ferramentas invocadas pelo agente em termos de ordem e parâmetros, comparando-a com uma sequência ideal.
* **Topic Adherence (Aderência ao Tópico)**: Garante que o agente permaneça no escopo da conversa e não seja desviado por *prompt injections* ou loops degenerados de raciocínio.
* **Agent Goal Accuracy (Acurácia da Meta final)**: Avalia se o agente concluiu com sucesso o objetivo principal traçado na instrução inicial.

***

## 5. Integração no Pipeline de CI/CD (Poka-Yoke)

Avaliações sistemáticas não devem ocorrer apenas em notebooks locais. A melhor prática de engenharia de software é acoplá-las em barreiras automáticas de integração contínua (CI/CD):

```mermaid
graph LR
    A[Pull Request] --> B{Executar Ragas Suite}
    B -->|Score >= 0.85| C[Aprovar PR & Deploy]
    B -->|Score < 0.85| D[Bloquear PR - Alucinação Detectada]
    
    style B fill:#fff3cd,stroke:#856404,stroke-width:2px
    style C fill:#d4edda,stroke:#28a745,stroke-width:2px
    style D fill:#f8d7da,stroke:#721c24,stroke-width:2px
```

Ao acoplar o Ragas nos testes automáticos com ferramentas como Pytest e GitHub Actions, o time garante um mecanismo robusto de **Poka-Yoke (Mistake-Proofing)**, impedindo que código que gere alucinações ou perdas de precisão em produção seja integrado no branch principal.

***

## Conexões e Links Relacionados

* **Conceito**: \[\[Systematic-Evaluation-Pipeline]]
* **Conceito**: \[\[Ragas-Agent-Performance-Evaluation]]
* **Conceito**: \[\[Poka-Yoke]]
* **Resumos**: \[\[Ragas-Framework]]
* **Resumos**: \[\[Ragas-Agent-Performance-Evaluation]]

***

\[\[Index-Public-Articles]]

***

\[\[index]]


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://rws.gitbook.io/rws/index-public-articles.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.