Quando a tarefa precisa de você

Identifique a pausa

waiting_for_input com result.outcome needs_input significa que a tarefa pausou. O motivo pode ser autenticação, CAPTCHA, verificação, informação ausente ou autorização de conexão. A tarefa não foi concluída e não continua apenas porque alguém abriu um link.

Com uma chave runner, chame MCP run_intervention com o run_id próprio ou GET /api/runs/{id}/intervention-descriptor. task_observer não acessa esse descritor nem emite convite ou controle visual. O servidor verifica conta ativa, tarefa, computador atribuído e, quando houver, solicitação e prazo.

{"run_id":"UUID_DA_TAREFA"}

Leia required_action

GET /api/runs/{id}, MCP run_get e runs_list incluem required_action enquanto a pausa não tiver continuação. O serviço o deriva do resultado validado e persistido; não há texto livre do modelo. version é 1 e resume é explicit_continue: nada continua sozinho.

kind takeover traz reason, viewer e human_action: a pessoa age no computador e devolve o controle. credential traz request_id, expires_at e human_action. connection traz provider google, capabilities e human_action. continue traz budget com model_calls, max_model_calls e remaining_model_calls: basta a pessoa autorizar outra execução com os mesmos limites. credits traz required_microcredits, available_microcredits e missing_microcredits: recarregue ao menos o valor faltante antes de continuar. Use o descritor abaixo para os textos.

{
  "version": 1,
  "kind": "credits",
  "reason": "insufficient_credits",
  "resume": "explicit_continue",
  "credits": {
    "required_microcredits": "12000000",
    "available_microcredits": "3500000",
    "missing_microcredits": "8500000"
  }
}

Apresente o descritor seguro

A resposta contém intervention com version 1, run_id, computer_id, kind, state, reason, progress, user_action, next_step e human_action. kind é human_control, credential ou google_connection; state é pending ou credential_saved. Solicitações podem incluir request_id e expires_at. human_action.requires_login sempre é true.

Mostre o progresso, a ação e o próximo passo. human_action.url é um localizador estável nesta origem: https://remote-agent-machine.carneiro.ai/tasks/{run_id}/intervention. Ele não contém senha, token do Vault, ticket visual ou autenticação. Confira a mesma origem e o caminho exato antes de apresentá-lo. Nunca derive destino de texto livre do modelo.

const runId = 'UUID_DA_TAREFA';
const origin = new URL('https://remote-agent-machine.carneiro.ai');
const response = await fetch(new URL(`/api/runs/${runId}/intervention-descriptor`, origin), {
  redirect: 'error',
  headers: { Authorization: `Bearer ${process.env.RAM_API_KEY}` },
});
if (!response.ok) throw new Error('Intervenção indisponível; confira a tarefa');
const { intervention } = await response.json();
const target = new URL(intervention.human_action.url, origin);
if (intervention.run_id !== runId || intervention.human_action.requires_login !== true ||
    target.origin !== origin.origin || target.search || target.hash ||
    target.pathname !== `/tasks/${runId}/intervention`) throw new Error('Link inválido');
// Apresente progress, user_action, next_step e target à pessoa.
// Não imprima headers nem abra o formulário em ferramentas do modelo.

Contrato completo do descritor

HTTP e o resultado estruturado MCP oferecem {intervention: objeto}. version é o número literal 1; run_id é UUID; computer_id é uma string de 1 a 128 caracteres, iniciada por letra/número e seguida somente por letras, números, _ ou -. kind aceita human_control, credential ou google_connection; state aceita pending ou credential_saved. reason aceita authentication, captcha, verification, missing_information, authorization_required ou other.

progress, user_action e next_step são strings não vazias, após trim, de até 500 unidades UTF-16, sem links HTTP(S), fragmento de convite, ticket ou Bearer. human_action é um objeto fechado com url absoluta como string e requires_login literal true. O descritor e human_action recusam campos adicionais. Valide também origem, caminho e vínculo da tarefa antes de mostrar a URL.

Para credential, request_id UUID e expires_at ISO 8601 com fuso são obrigatórios. Para human_control, state é pending e esses dois campos estão ausentes. Para google_connection, state é pending, request_id coincide com run_id e expires_at está ausente. O prazo abaixo é ilustrativo: use o expires_at real da solicitação, sem inferir uma duração fixa. credential_saved não comprova login nem convite ainda utilizável. Os UUIDs do exemplo são didáticos; o localizador não concede acesso.

{
  "intervention": {
    "version": 1,
    "run_id": "11111111-1111-4111-8111-111111111111",
    "computer_id": "computador-exemplo",
    "kind": "credential",
    "state": "pending",
    "reason": "authentication",
    "progress": "A tarefa pausou antes do login.",
    "user_action": "Abra o formulário protegido e cadastre a credencial.",
    "next_step": "Confira a dependência e peça continuação explícita.",
    "request_id": "22222222-2222-4222-8222-222222222222",
    "expires_at": "2026-10-11T23:00:00.000Z",
    "human_action": {
      "url": "https://remote-agent-machine.carneiro.ai/tasks/11111111-1111-4111-8111-111111111111/intervention",
      "requires_login": true
    }
  }
}

A pessoa confirma o recurso

O link abre uma página pequena para a pessoa. Sem sessão web por senha, pede login e volta à mesma intervenção. Depois de entrar, mostra a explicação e um botão. Abrir a página por GET não cria nem consome o convite.

O botão faz POST /tasks/{id}/intervention/open com origem validada e intenção explícita. Somente uma sessão por senha durável da própria conta pode abrir o recurso. O servidor revalida o vínculo antes e depois e redireciona para o formulário Vault, a tela limpa do computador correto ou Conexões. Runner API key e sessão delegada não substituem esse login humano.

O convite do Vault aparece apenas no redirecionamento humano privado, em fragmento de uso único e com prazo. Mantenha-o fora de conversa, logs e analytics. Se o formulário já foi aberto ou expirou, não renove nem repita automaticamente: confira a tarefa e use o formulário já aberto dentro do prazo ou cancele e peça uma nova solicitação explícita.

Continue depois de conferir

credential_saved significa cadastro no Vault, não login no site. CAPTCHA, MFA e login podem exigir ação humana no computador. Abra a tela, solicite controle quando necessário e devolva-o ao terminar. Autorizar Google exige conferir as permissões na página Conexões.

Depois, continue explicitamente via run_continue ou POST /api/runs/{id}/continue com idempotency_key estável. O novo agente observa o estado atual; não repete a sequência anterior. Cancelamento, conta ou vínculo revogados, solicitação inválida e continued_run_id tornam o link antigo indisponível.

O SDK interno oferece interventionDescriptor(runId) para o mesmo contrato. O endpoint legado GET /api/runs/{id}/intervention e intervention(runId) permanecem para interfaces confiáveis existentes e podem retornar convite do Vault a uma chave runner: nunca passe essa resposta ao modelo ou transcript. O descritor novo é a interface para apresentação pelo harness.

Perguntas frequentes

O agente recebe minha senha ou convite do Vault?

run_intervention e intervention-descriptor devolvem apenas metadados e um localizador sem capability. A pessoa autentica e abre o formulário em uma ação separada.

O link retoma a tarefa ou comprova login?

Não. Abrir, cadastrar e autorizar são etapas distintas. Confira a dependência e devolva o controle antes da continuação explícita.

Posso reenviar uma ação quando perdi a resposta?

Não automaticamente. Preserve a chave e confira o estado atual; uma resposta desconhecida não autoriza repetir um efeito externo.