Anotação Agêntica

Novo na v2.3.0

Os agentes de IA são cada vez mais implantados para tarefas complexas de múltiplas etapas: navegar na web, escrever código, chamar APIs e orquestrar subagentes. Mas avaliar se um agente realmente fez a coisa certa exige julgamento humano com uma granularidade que as ferramentas de anotação tradicionais não conseguem oferecer. Um único traço de agente pode conter dezenas de etapas, chamadas de ferramentas, raciocínio intermediário, capturas de tela e decisões de ramificação. Os anotadores precisam ver todo esse contexto, navegá-lo de forma eficiente e fornecer avaliações estruturadas tanto no nível do traço quanto no nível de cada etapa individual.

O sistema de anotação agêntica do Potato resolve isso com quatro capacidades:

1. 13 conversores de formato de traços que normalizam logs de agentes de qualquer framework principal para um formato unificado
2. 5 tipos de exibição especializados otimizados para diferentes modalidades de agente (tool-use, navegação web, coding, chat, observação ao vivo)
3. 9 esquemas de anotação prontos que cobrem as dimensões de avaliação de agentes mais comuns
4. 4 tipos de anotação feitos sob medida para avaliação avançada: avaliação de trajetória, avaliação por rubrica, comparação pareada e anotação de recompensa de processo

Conversores de Formato de Traços

Os traços de agentes vêm em formatos bastante diferentes dependendo do framework. O Potato traz 13 conversores que os normalizam em uma representação interna unificada. Você especifica o conversor na sua configuração, ou deixa o Potato detectar o formato automaticamente.

Referência de Conversores

Configuração

Especifique o conversor na configuração do seu projeto:

agentic:
  enabled: true
  trace_converter: react
  trace_file: "data/agent_traces.jsonl"

Cada linha do arquivo de traços deve ser um objeto JSON contendo o traço bruto do agente. O conversor cuida do resto.

Para traços multiagente em que diferentes agentes usam diferentes frameworks, você pode especificar conversores por agente:

agentic:
  enabled: true
  trace_converter: multi_agent
  trace_file: "data/multi_agent_traces.jsonl"
  multi_agent:
    agent_converters:
      planner: react
      coder: anthropic
      reviewer: openai

Detecção Automática

Se você não tiver certeza de qual conversor usar, defina trace_converter: auto:

agentic:
  enabled: true
  trace_converter: auto
  trace_file: "data/traces.jsonl"

O Potato inspeciona os 10 primeiros traços e seleciona o conversor que melhor corresponde com base nas assinaturas dos campos. Um aviso é registrado se a confiança ficar abaixo de 80%, caso em que você deve especificar o conversor explicitamente.

Conversores Personalizados

Se o seu framework de agente não estiver na lista, você pode escrever um conversor em Python:

# converters/my_converter.py
from potato.agentic.base_converter import BaseTraceConverter
 
class MyConverter(BaseTraceConverter):
    name = "my_framework"
 
    def convert(self, raw_trace: dict) -> dict:
        steps = []
        for entry in raw_trace["log"]:
            steps.append({
                "type": entry.get("kind", "action"),
                "content": entry["text"],
                "timestamp": entry.get("ts"),
                "metadata": entry.get("extra", {}),
            })
        return {"steps": steps}

Registre-o na configuração:

agentic:
  trace_converter: custom
  custom_converter: "converters/my_converter.py:MyConverter"

Tipos de Exibição

Depois que os traços são convertidos, o Potato os renderiza usando um dos cinco tipos de exibição especializados. Cada um é otimizado para uma modalidade de agente diferente.

1. Exibição de Traço de Agente

A exibição padrão para agentes que usam ferramentas (OpenAI function calling, Anthropic tool_use, ReAct, LangChain, etc.). Renderiza cada etapa como um cartão com codificação por cores conforme o tipo de etapa.

agentic:
  enabled: true
  trace_converter: openai
  display_type: agent_trace
 
  agent_trace_display:
    # Color coding for step types
    colors:
      thought: "#6E56CF"
      action: "#3b82f6"
      observation: "#22c55e"
      error: "#ef4444"
      system: "#6b7280"
 
    # Collapsible sections
    collapse_observations: true
    collapse_threshold: 500    # characters before auto-collapsing
 
    # Step numbering
    show_step_numbers: true
    show_timestamps: true
 
    # Tool call rendering
    render_json: true          # pretty-print JSON arguments
    syntax_highlight: true     # highlight code in observations

Recursos:

• Cartões de etapa com borda esquerda colorida indicando o tipo (pensamento, ação, observação, erro)
• Seções recolhíveis para observações longas ou saídas de ferramentas (limiar configurável)
• Formatação de JSON para argumentos de chamadas de ferramentas e respostas estruturadas
• Realce de sintaxe para blocos de código nas observações
• Linha do tempo de etapas na barra lateral mostrando o traço completo de relance
• Navegação salto-para-etapa para traços longos

2. Exibição de Traço de Agente Web

Feita sob medida para agentes de navegação web (WebArena, VisualWebArena, gravações brutas de navegador). Renderiza capturas de tela com sobreposições SVG mostrando onde o agente clicou, digitou ou rolou.

agentic:
  enabled: true
  trace_converter: webarena
  display_type: web_agent
 
  web_agent_display:
    # Screenshot rendering
    screenshot_max_width: 900
    screenshot_quality: 85
 
    # SVG overlay for agent actions
    overlay:
      enabled: true
      click_marker: "circle"       # circle, crosshair, or arrow
      click_color: "#ef4444"
      click_radius: 20
      type_highlight: "#3b82f6"    # highlight for text input fields
      scroll_indicator: true
 
    # Filmstrip view
    filmstrip:
      enabled: true
      thumbnail_width: 150
      show_action_labels: true
 
    # DOM snapshot display
    show_dom_snapshot: false        # optional raw DOM view
    show_url_bar: true
    show_action_description: true

Recursos:

• Galeria de capturas de tela com visualização em tamanho real e zoom
• Sobreposições SVG mostrando alvos de clique (círculos vermelhos), regiões de entrada de texto (destaques azuis) e direções de rolagem
• Visão em tira de filme na parte inferior mostrando todas as capturas como miniaturas para navegação rápida
• Descrição da ação abaixo de cada captura (ex.: "Clicar no botão 'Add to Cart'")
• Barra de URL mostrando a URL da página atual em cada etapa
• Comparação antes/depois para etapas que modificam o conteúdo da página

3. Exibição de Chat Interativo

Para avaliar agentes conversacionais e chatbots. Suporta dois submodos: chat ao vivo, em que os anotadores interagem com o agente em tempo real, e revisão de traço, em que os anotadores avaliam uma conversa gravada.

agentic:
  enabled: true
  display_type: interactive_chat
 
  interactive_chat_display:
    mode: trace_review         # or "live_chat"
 
    # Trace review settings
    trace_review:
      show_system_prompt: false
      show_token_counts: true
      show_latency: true
      message_grouping: turn    # "turn" or "message"
 
    # Live chat settings (when mode: live_chat)
    live_chat:
      proxy: openai             # agent proxy to use
      max_turns: 20
      timeout_seconds: 60
      show_typing_indicator: true
      allow_regenerate: true
 
    # Common settings
    show_role_labels: true
    role_colors:
      user: "#3b82f6"
      assistant: "#6E56CF"
      system: "#6b7280"
      tool: "#22c55e"

O modo de revisão de traço renderiza uma conversa gravada com contagem de tokens e latência por mensagem opcionais. Os anotadores podem avaliar turnos individuais ou a conversa inteira.

O modo de chat ao vivo conecta os anotadores a um agente em execução por meio do Sistema de Proxy de Agente (veja abaixo). Os anotadores conversam com o agente e, em seguida, anotam a conversa resultante.

4. Exibição de Traço de Coding

Feita sob medida para sessões de agentes de coding (Claude Code, Aider, SWE-Agent). Renderiza diffs de código com realce de sintaxe, saída de terminal em blocos escuros e leituras de arquivos com números de linha.

agentic:
  enabled: true
  trace_converter: claude_code
  display_type: coding_trace
 
  coding_trace_display:
    diff_style: unified           # unified or split
    terminal_theme: dark
    show_file_tree: true
    collapse_long_output: true
    collapse_threshold: 50        # lines
    show_line_numbers: true
    syntax_highlight: true

Recursos:

• Visão de diff unificada com realce vermelho/verde para operações de edição
• Blocos de terminal escuros para a saída de comandos bash/shell
• Blocos de código com numeração de linha para operações de leitura de arquivos
• Barra lateral com árvore de arquivos mostrando todos os arquivos tocados durante a sessão
• Saídas longas recolhíveis para conteúdo verboso de terminal ou de arquivo

Veja Anotação de Agente de Coding para a referência completa.

5. Exibição de Agente ao Vivo

Observação em tempo real de agentes de IA com controles para intervenção humana. Suporta agentes de navegação web e agentes de coding.

agentic:
  enabled: true
  display_type: live_agent

Recursos:

• Streaming em tempo real das ações do agente via Server-Sent Events
• Pausar/Retomar o agente entre etapas
• Enviar instruções para redirecionar o agente no meio da tarefa
• Assumir o controle manual
• Reverter para qualquer ponto de verificação anterior (agentes de coding usam pontos de verificação baseados em git)
• Ramificar e reproduzir a partir de qualquer ponto de verificação com instruções diferentes

Veja Avaliação de Agente ao Vivo e Agente de Coding ao Vivo para detalhes de configuração.

Tipos de Anotação Avançados

Além das avaliações por turno e dos esquemas prontos, o Potato inclui quatro tipos de anotação feitos sob medida para avaliação estruturada de agentes.

Avaliação de Trajetória (trajectory_eval)

Localização de erros por etapa com taxonomias de erros hierárquicas e pontuação de severidade. Cada etapa recebe uma nota de correção, um tipo de erro, um nível de severidade e uma justificativa opcional. Um contador de pontuação corrente é decrementado conforme a severidade.

annotation_schemes:
  - annotation_type: trajectory_eval
    name: step_eval
    error_taxonomy:
      reasoning:
        - logical_error
        - incorrect_assumption
      action:
        - wrong_tool
        - wrong_arguments
        - premature_termination
    severity_weights:
      minor: -1
      major: -5
      critical: -10

Veja a publicação de blog sobre avaliação de trajetória para um guia completo.

Avaliação por Rubrica (rubric_eval)

Avaliação multicritério em grade no estilo MT-Bench. Defina critérios personalizados e uma escala de avaliação. Os anotadores avaliam cada critério de forma independente.

annotation_schemes:
  - annotation_type: rubric_eval
    name: agent_rubric
    criteria:
      - name: correctness
        description: "Did the agent produce the correct result?"
      - name: efficiency
        description: "Did the agent take an efficient path?"
      - name: safety
        description: "Did the agent avoid unsafe actions?"
    scale: 5
    scale_labels:
      1: "Very Poor"
      3: "Acceptable"
      5: "Excellent"

Veja o tutorial de avaliação por rubrica para instruções de configuração.

Comparação Pareada

Compare dois traços de agente lado a lado com três modos:

• Binário: clique para selecionar A ou B (com empate opcional)
• Escala: controle deslizante de "A muito melhor" a "B muito melhor"
• Multidimensão: A/B/empate independentes por dimensão, com justificativa obrigatória

annotation_schemes:
  - annotation_type: pairwise
    name: agent_comparison
    mode: multi_dimension
    dimensions:
      - correctness
      - efficiency
      - safety
    require_justification: true
    allow_tie: true

Veja o guia de comparação pareada para os três modos.

Anotação de Recompensa de Processo

Anotação binária de correção por etapa, otimizada para treinar modelos de recompensa de processo. Dois modos: primeiro-erro (clique na primeira etapa errada, o restante é marcado automaticamente) e por etapa (avalie cada uma de forma independente).

annotation_schemes:
  - annotation_type: process_reward
    name: prm
    mode: first_error    # or per_step

Veja Anotação de Recompensa de Processo para a referência completa.

Avaliações por Turno

Para avaliações de diálogo e de múltiplas etapas, muitas vezes você precisa de avaliações em turnos individuais em vez de (ou além de) o traço geral. O Potato suporta anotação por turno para qualquer tipo de exibição.

annotation_schemes:
  # Overall trace rating
  - annotation_type: likert
    name: overall_quality
    description: "Rate the overall quality of this agent trace"
    min: 1
    max: 5
    labels:
      1: "Very Poor"
      5: "Excellent"
 
  # Per-turn ratings
  - annotation_type: per_turn_rating
    name: step_correctness
    description: "Was this step correct?"
    target: agentic_steps        # binds to trace steps
    rating_type: radio
    labels:
      - "Correct"
      - "Partially Correct"
      - "Incorrect"
      - "Unnecessary"
 
  - annotation_type: per_turn_rating
    name: step_explanation
    description: "Explain any issues with this step"
    target: agentic_steps
    rating_type: text
    conditional:
      show_when:
        step_correctness: ["Partially Correct", "Incorrect", "Unnecessary"]

As avaliações por turno aparecem em linha ao lado de cada cartão de etapa. O bloco conditional permite exibir perguntas de acompanhamento apenas quando certas avaliações são selecionadas, mantendo a interface limpa.

Formato de Saída por Turno

As anotações por turno são salvas com índices de etapa:

{
  "id": "trace_042",
  "annotations": {
    "overall_quality": 3,
    "step_correctness": {
      "0": "Correct",
      "1": "Correct",
      "2": "Incorrect",
      "3": "Correct"
    },
    "step_explanation": {
      "2": "The agent searched for the wrong product name"
    }
  }
}

Sistema de Proxy de Agente

Para tarefas de avaliação ao vivo em que os anotadores interagem com um agente em tempo real, o Potato fornece uma camada de proxy de agente. O proxy fica entre a interface de anotação e o backend do agente, registrando a conversa completa para revisão posterior.

agentic:
  enabled: true
  display_type: interactive_chat
 
  agent_proxy:
    type: openai                 # openai, http, or echo
 
    # OpenAI proxy
    openai:
      model: "gpt-4o"
      api_key: ${OPENAI_API_KEY}
      system_prompt: "You are a helpful customer service agent."
      temperature: 0.7
      max_tokens: 1024

Tipos de Proxy

O proxy OpenAI encaminha mensagens para uma API compatível com OpenAI:

agent_proxy:
  type: openai
  openai:
    model: "gpt-4o"
    api_key: ${OPENAI_API_KEY}
    system_prompt: "You are a helpful assistant."
    temperature: 0.7

O proxy HTTP encaminha mensagens para qualquer endpoint HTTP (seu próprio servidor de agente):

agent_proxy:
  type: http
  http:
    url: "https://my-agent.example.com/chat"
    method: POST
    headers:
      Authorization: "Bearer ${AGENT_API_KEY}"
    request_template:
      messages: "{{messages}}"
      session_id: "{{session_id}}"
    response_path: "response.content"
    timeout_seconds: 30

O proxy echo devolve a mensagem do usuário (útil para testes e desenvolvimento de UI):

agent_proxy:
  type: echo
  echo:
    prefix: "[Echo] "
    delay_ms: 500

Esquemas de Anotação Prontos

O Potato traz 9 esquemas de anotação projetados especificamente para avaliação de agentes. Use-os diretamente ou como ponto de partida para seus próprios esquemas.

Carregue um esquema pronto pelo nome:

annotation_schemes:
  - preset: agent_task_success
  - preset: agent_step_correctness
  - preset: agent_error_taxonomy

Ou combine presets com esquemas personalizados:

annotation_schemes:
  - preset: agent_task_success
  - preset: agent_step_correctness
 
  # Custom schema alongside presets
  - annotation_type: text
    name: evaluator_notes
    description: "Any additional observations about this agent trace"
    label_requirement:
      required: false

Exemplo Completo: Avaliando um Agente ReAct

Aqui está uma configuração completa para avaliar traços de agente no estilo ReAct com avaliações por etapa:

# project config
task_name: "ReAct Agent Evaluation"
task_dir: "."
 
data_files:
  - "data/react_traces.jsonl"
 
item_properties:
  id_key: trace_id
  text_key: task_description
 
agentic:
  enabled: true
  trace_converter: react
  display_type: agent_trace
 
  agent_trace_display:
    colors:
      thought: "#6E56CF"
      action: "#3b82f6"
      observation: "#22c55e"
      error: "#ef4444"
    collapse_observations: true
    collapse_threshold: 300
    show_step_numbers: true
    render_json: true
 
annotation_schemes:
  - preset: agent_task_success
  - preset: agent_step_correctness
  - preset: agent_efficiency
 
  - annotation_type: text
    name: failure_reason
    description: "If the agent failed, describe what went wrong"
    label_requirement:
      required: false
 
output_annotation_dir: "output/"
output_annotation_format: "jsonl"

Dados de entrada de exemplo (data/react_traces.jsonl):

{
  "trace_id": "react_001",
  "task_description": "Find the population of Tokyo and compare it to New York City",
  "trace": [
    {"type": "thought", "content": "I need to find the population of both cities. Let me search for Tokyo first."},
    {"type": "action", "content": "search", "action_input": "Tokyo population 2024"},
    {"type": "observation", "content": "Tokyo has a population of approximately 13.96 million in the city proper..."},
    {"type": "thought", "content": "Now I need to find New York City's population."},
    {"type": "action", "content": "search", "action_input": "New York City population 2024"},
    {"type": "observation", "content": "New York City has a population of approximately 8.34 million..."},
    {"type": "thought", "content": "Tokyo (13.96M) has about 67% more people than NYC (8.34M)."},
    {"type": "action", "content": "finish", "action_input": "Tokyo has ~13.96 million people vs NYC's ~8.34 million, making Tokyo about 67% larger by population."}
  ]
}

Inicie o servidor:

potato start config.yaml -p 8000

Leitura Adicional

• Anotação de Agente de Coding — renderização de diffs, saída de terminal, árvore de arquivos para agentes de coding
• Anotação de Recompensa de Processo — dados de treinamento de PRM com modos primeiro-erro e por etapa
• Anotação de Revisão de Código — comentários em linha e veredictos no estilo de PR do GitHub
• Agente de Coding ao Vivo — observação em tempo real de agentes de coding com reversão e ramificação
• Avaliação de Agente ao Vivo — observação em tempo real de agentes web
• Anotação de Agente Web — revisão de traços de agentes web pré-gravados
• Avaliando Agentes de IA: Um Guia Completo — passo a passo de um projeto completo de avaliação de agentes
• Formatos de Exportação — exportar dados de avaliação de agentes

Para detalhes de implementação, consulte a documentação fonte.