Pular para o conteúdo
Pular para o conteúdo

Docs / Guias

Página traduzida automaticamente

Esta página foi traduzida automaticamente, então pode ter erros ou soar um pouco estranha. A versão em inglês é a fonte da verdade. Ler o original em inglês.

Operar o Studio com um agente de navegador

Registre as ações de revisão do Verbatra Studio como ferramentas WebMCP para que um agente de IA no navegador trabalhe na aba aberta e autenticada do painel.

Use esta página para deixar um agente de IA no navegador, como o Gemini ou o Claude no Chrome, verificar divergências, percorrer a fila de revisão (no Studio, Review queue) e corrigir entradas na aba do Studio que você deixou aberta. Ela não serve para configurar o projeto nem para acesso remoto.

Você precisa de:

  • o Studio em execução sobre o seu projeto (Revisar no Studio);
  • o Chrome 149 ou mais recente com chrome://flags/#enable-webmcp-testing ativado, ou um navegador com suporte nativo a WebMCP, em uma janela normal, não no modo headless.

Experimental

O WebMCP é um recurso novo do navegador, atrás de uma flag, e a interface dele ainda pode mudar.

Ativar as ferramentas

verbatra studio --expose-agent-tools

VERBATRA_STUDIO_AGENT_TOOLS=1 faz o mesmo; Gastos e ferramentas de agente mostra como a flag e a variável são resolvidas. Abra a URL impressa no navegador com WebMCP, e o agente daquela aba encontra as ferramentas.

Para deixar o agente chamar o seu provedor, inicie o Studio também com --allow-spend.

O agente lê todo valor sem ocultação, como a página o mostra, porque um agente na aba pode ler a página de qualquer forma. As exceções são as ferramentas de glossário e verbatra_history_keyRevisions: os valores delas passam pela ocultação de segredos, então um valor com o formato de uma chave de API volta substituído por [REDACTED]. Para manter valores longe de um agente, use o servidor MCP com --redact-values; para um projeto sob NDA (acordo de confidencialidade), veja Studio e MCP.

Saber o que o agente pode chamar

Cada ferramenta é uma ação do Studio com o prefixo verbatra_. As ferramentas de leitura são marcadas como somente leitura, as de escrita alteram apenas os seus arquivos locais e as ferramentas pagas só são registradas com --allow-spend.

Ferramentas de leitura

FerramentaO que faz
verbatra_project_snapshota configuração carregada, as capabilities e, em capabilities.limits, os limites de taxa de retranslate, reviewDecision e dos dois métodos de substituição de valores
verbatra_status_checkcobertura por locale
verbatra_status_diffchaves ausentes, alteradas e órfãs por locale
verbatra_glossary_geto glossário resolvido, com os segredos ocultados
verbatra_lock_stateo estado do arquivo de lock por locale
verbatra_history_listcommits recentes nos arquivos de locale, com o nome do autor (nunca o e-mail)
verbatra_history_keyRevisionsos commits de uma chave em um locale, com diffs por palavra e chaves de API removidas novo
verbatra_key_integrityverificações de placeholder, marcação e ICU de uma chave, nos locales em que a origem dela mudou
verbatra_review_queuetodo valor escrito por máquina que ninguém aprovou, a partir dos arquivos versionados
verbatra_key_valuea origem e o destino de uma chave, com quem escreveu o destino
verbatra_key_contexta descrição, os termos do glossário e o maxLength de uma chave, e a verificação de um draft opcional
verbatra_locale_valuesvalores de chaves por locale de destino, 200 por página por padrão, filtrados por locales, keys ou query
verbatra_locale_integritytoda tradução que falha nas verificações de integridade
verbatra_translation_estimateo que uma chamada para traduzir as pendências enviaria e quanto custaria, sem chamar um provedor
verbatra_usage_summaryo uso de tokens da última execução, o orçamento e, se algum locale falhou ou parou no meio, incomplete novo
verbatra_usage_historyexecuções registradas, das mais recentes às mais antigas, com tokens, custo e cobertura, apenas como contagens novo

Ferramentas de escrita

FerramentaO que faz
verbatra_glossary_writealtera um termo de um glossário baseado em arquivo
verbatra_review_approveregistra a aprovação de um valor por uma pessoa identificada
verbatra_review_rejectregistra a rejeição por uma pessoa identificada, removendo o valor
verbatra_translation_editEntrygrava um valor pela barreira de integridade

Ferramentas pagas

FerramentaO que faz
verbatra_translation_retranslateEntryretraduz uma chave em um locale
verbatra_translation_translatePendingtraduz tudo o que está pendente, opcionalmente para alguns locales sob um teto maxTokens

verbatra_key_integrity retorna apenas os locales em que a origem da chave mudou, então uma lista vazia significa que nada precisava ser verificado. As linhas dela são mais planas que as do key.integrity do servidor MCP. Só o servidor MCP tem project.doctor e report.provenance. verbatra_locale_values pagina como o locale.values do servidor MCP, com os mesmos limit e cursor (Mais entradas e resultados).

Conhecer as regras que as ferramentas seguem

Toda chamada passa pelo próprio RPC de loopback autenticado do painel, com a mesma validação de entrada e a mesma barreira de integridade (veja Segurança da tradução): um valor que falha em uma verificação é recusado, não gravado.

Regras por chamada

  • Procedência: a edição de um agente é registrada com origin agent e permanece na fila de revisão; uma edição no painel é human. As ferramentas de leitura informam quem escreveu cada valor (O arquivo de lock e a procedência).
  • Trabalho humano: retraduzir recusa o valor de uma pessoa com KEY_PROTECTED (exceto com humanEdits: "overwrite") e uma chave fixada com KEY_PINNED, e editar recusa uma chave fixada (Manter traduções humanas).
  • Decisões de revisão: aprovar e rejeitar apenas repassam a sua decisão. Ambas exigem reviewer, o nome da pessoa, e expectedValue, o texto revisado; um valor alterado é recusado com REVIEW_VALUE_CHANGED.
  • Sem ferramentas em massa: Approve selected (aprovar selecionados), Reject selected (rejeitar selecionados), Retranslate selected (retraduzir selecionados), Approve all in (aprovar tudo em) e Search and replace (buscar e substituir) continuam exclusivos de pessoas.
  • Estimar primeiro: um locale desconhecido é recusado com UNKNOWN_LOCALE antes de qualquer gasto, e vale o menor entre o maxTokens da chamada e o da configuração (Estimar o custo antes de uma execução).
  • Limites de taxa: em qualquer janela de um minuto, 20 retraduções, 20 edições, 20 gravações no glossário, 60 decisões de revisão e 5 chamadas para traduzir as pendências, uma de cada vez.

Ler uma chamada com falha

Toda ferramenta retorna o envelope do painel (o objeto JSON da resposta), então uma falha aparece como { "ok": false, "error": { "code": ..., "message": ... } }. Além dos códigos do próprio SDK, a camada de RPC adiciona:

CódigoSignificado
REQUEST_INVALIDa requisição ou a resposta não era um envelope legível
METHOD_UNKNOWNo método não existe nesta versão do Studio
SPEND_DISABLEDum método pago enquanto os gastos estão desativados: o Studio está em execução sem --allow-spend, ou o provedor é none; a mensagem diz qual dos dois
PARAMS_INVALIDum parâmetro falhou na validação; issues nomeia cada campo
METHOD_RATE_LIMITEDacima do limite de taxa; retryAfterSeconds diz quando a chamada volta a caber no limite
BATCH_TOO_LARGEum lote excede uma janela inteira do limite de taxa; envie menos entradas
ALREADY_IN_PROGRESSuma segunda chamada para uma entrada ainda em andamento (HTTP 409)
SESSION_EXPIREDo Studio reiniciou com um novo token; abra a URL que ele imprimiu
INTERNALum handler falhou com um erro inesperado (HTTP 500); a mensagem é genérica

Corrigir ferramentas degradadas

Se o navegador rejeita o registro das ferramentas, toda visualização mostra um alerta como:

Agent tools degraded: 2 of the agent tool registrations failed with SecurityError. The dashboard itself is unaffected. The browser console lists every failing tool.

O console tem uma linha que nomeia cada falha:

Saída
Verbatra agent tools: 2 of 20 tool registrations failed. verbatra_status_diff (SecurityError: ...); verbatra_key_value (SecurityError: ...)

Leia primeiro o nome do erro ali e depois recarregue a aba, o que registra as ferramentas de novo. Uma flag ausente ou um navegador sem WebMCP nunca mostra esse aviso: nesses casos nada é registrado, sem nenhuma mensagem. Uma sessão sem --allow-spend tenta registrar duas ferramentas a menos, o que não é uma falha.

Avaliar o risco de gastos

As ferramentas não adicionam nenhuma exposição de rede: o Studio continua escutando apenas em 127.0.0.1, toda requisição leva o token da sessão, e as ferramentas que retornam texto do projeto o marcam como não confiável, para que o agente o trate como dados.

Atenção

Com --allow-spend e --expose-agent-tools juntos, um agente pode gastar no seu provedor sem uma confirmação por chamada, até os limites de taxa. O Studio não distingue a chamada de um agente do seu clique, então não adiciona nenhum diálogo de aprovação. Para apenas ler e editar, deixe --allow-spend desativado.

Veja também

Editar no GitHub

Nesta página