Observação de Agente de Programação ao Vivo

Assista a agentes de programação trabalhando em tempo real com pausa, rollback e ramificação. Três backends suportados: Ollama para modelos locais, Anthropic API e Claude Agent SDK.

Novidade na v2.4.0

A anotação de traces estáticos diz o que um agente fez. A observação ao vivo diz o que um agente faz em resposta à orientação humana. O modo de agente de programação ao vivo do Potato permite que os anotadores assistam a um agente de programação trabalhando em tempo real -- lendo arquivos, editando código, executando testes -- e intervenham a qualquer momento. Pause o agente, envie novas instruções, faça rollback para um checkpoint anterior ou ramifique a trajetória para explorar abordagens alternativas.

Isto produz dados de anotação mais ricos do que apenas traces estáticos. Você obtém a trajetória completa com carimbos de data/hora, as intervenções do anotador, os pontos de decisão de ramificação e dados comparativos de caminhos alternativos. Esses dados são diretamente úteis para treinar modelos de recompensa de processo, modelos de preferência e avaliadores de seguimento de instruções.

Requisitos

Python 3.10+
Git (o sistema de checkpoints usa commits git)
Um dos seguintes backends de agente:
- Ollama para inferência de modelos locais (não requer chave de API)
- ANTHROPIC_API_KEY para acesso à Anthropic API
- Claude Agent SDK para a experiência completa do agente Claude Code

Backends

O Potato suporta três backends para executar agentes de programação. Cada backend executa o agente em um subprocesso e transmite suas ações para a interface de anotação em tempo real.

1. Ollama (Modelos Locais)

Execute agentes de programação localmente sem necessidade de chave de API. O Ollama oferece inferência rápida para modelos de pesos abertos. Ideal para desenvolvimento, testes e situações em que os dados não podem sair da máquina local.

Configuração:

bash

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh
 
# Pull a coding-capable model
ollama pull qwen2.5-coder:7b
 
# Or a larger model for better performance
ollama pull deepseek-coder-v2:16b

Configuração:

yaml

agentic:
  enabled: true
  display_type: coding_trace
  live_agent:
    enabled: true
    backend: ollama
    model: qwen2.5-coder:7b
 
    ollama:
      host: "http://localhost:11434"    # Ollama server URL
      temperature: 0.2
      num_ctx: 8192                     # context window size
      num_predict: 2048                 # max tokens per response
      keep_alive: "5m"                  # keep model loaded in memory
 
    # Agent capabilities
    tools:
      - read_file
      - edit_file
      - write_file
      - bash
      - glob
      - grep
    max_steps: 50
    step_timeout_seconds: 60

2. Anthropic API

Use modelos Claude via a Anthropic API. Oferece forte desempenho em programação com capacidades de uso de ferramentas. Requer uma chave de API.

Configuração:

bash

# Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."
 
# Or add to .env file
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env

Configuração:

yaml

agentic:
  enabled: true
  display_type: coding_trace
  live_agent:
    enabled: true
    backend: anthropic
    model: claude-sonnet-4-20250514
 
    anthropic:
      api_key: ${ANTHROPIC_API_KEY}
      max_tokens: 4096
      temperature: 0.2
      system_prompt: |
        You are a coding assistant working on a software project.
        Read files before editing them. Run tests after making changes.
        Explain your reasoning before each action.
 
    # Agent capabilities
    tools:
      - read_file
      - edit_file
      - write_file
      - bash
      - glob
      - grep
    max_steps: 100
    step_timeout_seconds: 120

3. Claude Agent SDK

O Claude Agent SDK oferece a experiência completa do agente Claude Code, incluindo orquestração automática de ferramentas, gerenciamento de contexto e raciocínio multiarquivo. Este é o backend mais capaz, mas requer que o SDK esteja instalado.

Configuração:

bash

# Install the Claude Agent SDK
pip install claude-agent-sdk
 
# Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."

Configuração:

yaml

agentic:
  enabled: true
  display_type: coding_trace
  live_agent:
    enabled: true
    backend: claude_agent_sdk
 
    claude_agent_sdk:
      api_key: ${ANTHROPIC_API_KEY}
      model: claude-sonnet-4-20250514
      max_turns: 100
      permission_mode: auto           # auto-approve tool use
      enable_thinking: true           # show extended thinking
 
    max_steps: 100
    step_timeout_seconds: 180

Controles

A interface de anotação oferece quatro ações de controle que permitem aos anotadores orientar o comportamento do agente.

Pausar / Retomar

Clique em Pause para interromper o agente entre os passos. O agente conclui o passo atual e aguarda. O anotador pode revisar o estado atual, examinar arquivos e decidir se deixa o agente continuar ou intervém. Clique em Resume para deixar o agente prosseguir.

yaml

live_agent:
  controls:
    pause_resume:
      enabled: true
      auto_pause_on_error: true      # pause when a command fails
      auto_pause_after_steps: 0      # pause after N steps (0 = disabled)
      keyboard_shortcut: "Space"

Enviar Instruções

Enquanto o agente está pausado, os anotadores podem enviar novas instruções que redirecionam o agente. Isto é útil quando o agente está seguindo o caminho errado ou quando o anotador quer testar como o agente responde à orientação.

yaml

live_agent:
  controls:
    send_instructions:
      enabled: true
      placeholder: "Type instructions for the agent..."
      inject_as: system_message      # "system_message" or "user_message"
      keyboard_shortcut: "Enter"
      presets:
        - "Try a different approach"
        - "Read the error message more carefully"
        - "Check the test file for expected behavior"
        - "Revert your last change and try again"

As instruções são injetadas no contexto da conversa do agente. A opção inject_as controla se elas aparecem como uma mensagem de sistema (instrução autoritativa) ou uma mensagem de usuário (orientação conversacional).

Rollback

O rollback reverte o projeto para um checkpoint git anterior. Cada alteração de arquivo que o agente faz é automaticamente commitada, de modo que o anotador pode clicar em qualquer passo anterior na linha do tempo e fazer rollback para aquele estado exato. O contexto da conversa do agente também é truncado para corresponder.

yaml

live_agent:
  controls:
    rollback:
      enabled: true
      show_checkpoint_diff: true     # show what will be undone
      require_confirmation: true     # "Are you sure?" dialog
      keyboard_shortcut: "Ctrl+Z"

Ramificar e Repetir

A ramificação e repetição combina rollback com o envio de instruções. O anotador faz rollback para um checkpoint e envia instruções diferentes, criando uma trajetória ramificada. Isto é poderoso para coletar dados de preferência: você pode explorar duas abordagens diferentes a partir do mesmo ponto inicial e comparar os resultados.

yaml

live_agent:
  controls:
    branch:
      enabled: true
      max_branches: 5                # maximum branches from any checkpoint
      branch_naming: auto            # "auto" or "manual"
      compare_view: true             # side-by-side branch comparison
      keyboard_shortcut: "Ctrl+B"

A visualização de comparação de ramos mostra dois ramos lado a lado, destacando onde eles divergem. Os anotadores podem avaliar qual ramo produziu melhores resultados, gerando pares de preferência para treinamento DPO.

Sistema de Checkpoints Git

O modo de agente ao vivo usa git para rastrear cada alteração de arquivo. Isto oferece rollback confiável, ramificação e histórico completo de alterações.

Como funciona

Antes de o agente iniciar, o Potato cria um novo branch git chamado potato-session-{session_id}
Após cada alteração de arquivo (editar, escrever, criar, excluir), o Potato commita automaticamente com uma mensagem descritiva
Cada commit é marcado como um checkpoint que aparece na linha do tempo
O rollback usa git checkout para restaurar o diretório de trabalho a qualquer checkpoint
A ramificação cria um novo branch git a partir do commit do checkpoint

Configuração

yaml

live_agent:
  git_checkpoints:
    enabled: true
    branch_prefix: "potato-session"
    commit_message_format: "Step {step}: {tool} {file_path}"
    auto_commit: true
    cleanup_on_complete: false       # delete session branches when done
    require_clean_working_dir: true  # fail if there are uncommitted changes

Gerenciamento Manual de Checkpoints

bash

# List all Potato session branches
git branch | grep potato-session
 
# View checkpoints for a session
git log potato-session-abc123 --oneline
 
# Clean up old session branches
python -m potato.cleanup_sessions --older-than 7d

Formato de dados

Os dados de entrada para tarefas de agente de programação ao vivo especificam a descrição da tarefa e, opcionalmente, um arquivo ou diretório inicial:

json

{
  "id": "task_001",
  "task_description": "Fix the bug in src/parser.py where empty input causes a crash",
  "project_dir": "/path/to/project",
  "start_file": "src/parser.py",
  "test_command": "python -m pytest tests/test_parser.py -v",
  "context_files": [
    "src/parser.py",
    "tests/test_parser.py"
  ]
}

Campo	Obrigatório	Descrição
`id`	Sim	Identificador único da tarefa
`task_description`	Sim	O que o agente deve fazer
`project_dir`	Sim	Caminho para o diretório do projeto
`start_file`	Não	Arquivo a mostrar inicialmente ao agente
`test_command`	Não	Comando para verificar a correção
`context_files`	Não	Arquivos a pré-carregar no contexto do agente

Referência de configuração

Configuração completa para uma tarefa de observação de agente de programação ao vivo:

yaml

task_name: "Live Coding Agent Observation"
task_dir: "."
 
data_files:
  - "data/coding_tasks.jsonl"
 
item_properties:
  id_key: id
  text_key: task_description
 
agentic:
  enabled: true
  display_type: coding_trace
 
  coding_trace_display:
    diff_style: unified
    diff_context_lines: 3
    syntax_highlight: true
    show_line_numbers: true
    terminal_theme: dark
    file_tree:
      enabled: true
      position: left
      click_to_navigate: true
 
  live_agent:
    enabled: true
    backend: anthropic
    model: claude-sonnet-4-20250514
 
    anthropic:
      api_key: ${ANTHROPIC_API_KEY}
      max_tokens: 4096
      temperature: 0.2
 
    tools:
      - read_file
      - edit_file
      - write_file
      - bash
      - glob
      - grep
 
    max_steps: 100
    step_timeout_seconds: 120
 
    controls:
      pause_resume:
        enabled: true
        auto_pause_on_error: true
        keyboard_shortcut: "Space"
      send_instructions:
        enabled: true
        inject_as: system_message
        presets:
          - "Try a different approach"
          - "Read the error message carefully"
          - "Run the tests first"
      rollback:
        enabled: true
        require_confirmation: true
      branch:
        enabled: true
        max_branches: 5
        compare_view: true
 
    git_checkpoints:
      enabled: true
      branch_prefix: "potato-session"
      auto_commit: true
      cleanup_on_complete: false
 
annotation_schemes:
  # Per-step ratings during observation
  - annotation_type: per_turn_rating
    name: step_quality
    description: "Rate each agent step as you observe it"
    target: agentic_steps
    rating_type: radio
    labels:
      - "Good"
      - "Acceptable"
      - "Unnecessary"
      - "Incorrect"
 
  # Overall task completion after agent finishes
  - annotation_type: radio
    name: task_completion
    description: "Did the agent complete the task?"
    labels:
      - "Fully Complete"
      - "Partially Complete"
      - "Failed"
 
  # Branch comparison (when branching is used)
  - annotation_type: radio
    name: branch_preference
    description: "Which branch produced a better result?"
    labels:
      - "Branch A"
      - "Branch B"
      - "Both Equal"
      - "Both Failed"
 
  # Notes on the observation
  - annotation_type: text
    name: observation_notes
    description: "Describe what you observed and any interventions you made"
    label_requirement:
      required: false
 
output_annotation_dir: "output/"
output_annotation_format: "jsonl"

Exportação de Trajetória Ramificada

Quando os anotadores usam ramificar e repetir, a saída inclui a árvore de ramificação completa. Este formato foi projetado para treinar modelos de preferência e modelos de recompensa de processo a partir de trajetórias comparativas.

json

{
  "id": "task_001",
  "annotator": "observer_01",
  "root_branch": {
    "branch_id": "main",
    "steps": [
      {"step": 0, "type": "file_read", "file": "src/parser.py", "rating": "Good"},
      {"step": 1, "type": "edit", "file": "src/parser.py", "rating": "Incorrect"}
    ],
    "children": [
      {
        "branch_id": "branch_1",
        "branch_point": 1,
        "instruction": "Try a different approach -- use a try/except block instead",
        "steps": [
          {"step": 2, "type": "edit", "file": "src/parser.py", "rating": "Good"},
          {"step": 3, "type": "terminal", "command": "pytest", "rating": "Good"}
        ],
        "outcome": "Fully Complete",
        "children": []
      },
      {
        "branch_id": "branch_2",
        "branch_point": 1,
        "instruction": "Read the test file first to understand expected behavior",
        "steps": [
          {"step": 2, "type": "file_read", "file": "tests/test_parser.py", "rating": "Good"},
          {"step": 3, "type": "edit", "file": "src/parser.py", "rating": "Good"},
          {"step": 4, "type": "terminal", "command": "pytest", "rating": "Good"}
        ],
        "outcome": "Fully Complete",
        "children": []
      }
    ]
  },
  "branch_preference": "Branch B",
  "observation_notes": "Both branches solved the problem, but branch B produced cleaner code by reading the tests first."
}

Exporte trajetórias ramificadas para aprendizado de preferências:

bash

# Export as DPO preference pairs from branch comparisons
python -m potato.export \
  -i output/ \
  -f branching_dpo \
  -o results/branch_preferences.jsonl
 
# Export full trajectory trees
python -m potato.export \
  -i output/ \
  -f trajectory_tree \
  -o results/trajectory_trees.jsonl

Segurança

O agente ao vivo é executado no diretório do projeto especificado nos dados da tarefa. Ele tem acesso para ler, escrever e executar arquivos dentro desse diretório. Considere as seguintes práticas de segurança:

Sandboxing: Para código não confiável ou modelos de agente não confiáveis, execute o Potato dentro de um contêiner Docker ou VM. O agente pode executar comandos shell arbitrários, então o isolamento é importante.
Modo somente leitura: Desative as ferramentas bash e write_file se você quiser apenas que o agente analise o código sem modificá-lo.
Restrições de rede: Use a flag --network none do Docker para impedir que o agente faça requisições de rede.
Limites de recursos: Defina max_steps e step_timeout_seconds para evitar agentes descontrolados.

yaml

# Restricted tool set for analysis-only tasks
live_agent:
  tools:
    - read_file
    - glob
    - grep
  # No edit_file, write_file, or bash

Solução de problemas

Ollama Não Está Executando

text

Error: Connection refused at http://localhost:11434

Inicie o servidor Ollama:

bash

ollama serve

Verifique se está em execução:

bash

ollama list

Chave de API Ausente

text

Error: ANTHROPIC_API_KEY environment variable not set

Defina a variável de ambiente:

bash

export ANTHROPIC_API_KEY="sk-ant-..."

Ou adicione-a ao arquivo .env do seu projeto. O Potato carrega arquivos .env automaticamente.

Git Não Inicializado

text

Error: Project directory is not a git repository

O sistema de checkpoints requer git. Inicialize um repositório no diretório do projeto:

bash

cd /path/to/project
git init
git add -A
git commit -m "Initial commit"

Agente Preso em um Loop

Se o agente repetir a mesma ação várias vezes, ele pode estar preso. O Potato detecta loops quando a mesma chamada de ferramenta com os mesmos argumentos é repetida 3 vezes e pausa o agente automaticamente. Você pode configurar esse limite:

yaml

live_agent:
  loop_detection:
    enabled: true
    threshold: 3                     # pause after N identical consecutive steps
    action: pause                    # "pause" or "terminate"

Limpeza de Branches de Sessão

Com o tempo, os branches de sessão se acumulam. Limpe-os periodicamente:

bash

# Remove branches older than 7 days
python -m potato.cleanup_sessions --older-than 7d
 
# Remove all session branches
python -m potato.cleanup_sessions --all
 
# Dry run (show what would be deleted)
python -m potato.cleanup_sessions --older-than 7d --dry-run

Veja também

Anotação de Agente de Programação -- anote traces estáticos de agentes de programação
Anotação de Recompensa de Processo -- colete sinais de recompensa por passo para treinamento de PRM
Anotação de Revisão de Código -- revisão inline ao estilo de PR do GitHub para alterações de código
Anotação Agêntica -- anotação de traces de agente de propósito geral

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