Usar a API HTTP

Autenticação e seleção

A API HTTP autenticada permanece disponível para aplicativos e integrações da suíte. MCP é a interface principal para harnesses; os dois caminhos usam serviços do mesmo núcleo independente de protocolo. Os objetivos do Agent usam uma VM atribuída hoje; a composição com MicroVM ainda é planejada.

A origem desta instalação é https://remote-agent-machine.carneiro.ai. Forneça Authorization: Bearer com uma chave da sua conta nas chamadas da API. Fora de desenvolvimento em loopback, use HTTPS.

Para executar, use uma chave runner, selecione computer_id e confirme que o Brain está configurado. Uma task_observer acessa somente GET /api/runs, GET /api/runs/{id} e GET /api/runs/{id}/events. Consultar status do computador não faz parte desse propósito.

Descubra seu computador

Antes de enviar a tarefa, consulte GET /api/computers com a chave runner. A resposta contém computers, uma lista de computadores próprios. Use o campo id do computador escolhido como computer_id; não use o nome label como identificador.

Confira state e availability: state ready é cadastro persistido, enquanto availability available indica disponibilidade atual. in_use significa ocupado e unavailable ou not_ready não comprova computador utilizável. Uma lista vazia exige atribuição pelo administrador. GET /api/status?computer_id=ID confere as capacidades da seleção; a execução agent ainda depende de provedor configurado.

Enviar um objetivo

POST /api/runs recebe o mesmo objeto ilustrado na página MCP, com runtime agent explícito. Guarde a idempotency_key e os parâmetros do pedido antes de enviar. A resposta contém run; queued não significa que o navegador já esteja pronto.

allow_mutations false limita alterações pelas ferramentas; true amplia o alcance existente e não substitui autorização específica para compras ou efeitos sensíveis. Um texto de prompt não é uma política independente de segurança.

Consultar sem executar

O exemplo lê tarefas. Defina RAM_API_KEY por um mecanismo privado do seu host. O heredoc fornece a configuração ao curl por stdin, sem inserir a chave literalmente no exemplo. Não execute com tracing de shell nem registre headers.

• GET /api/runs — tarefas próprias; limit (1–100, padrão 30), before, status e computer_id. Use next_before para continuar.
• GET /api/runs/{id} — estado e resultado da tarefa própria.
• GET /api/runs/{id}/events?after=0 — eventos após o cursor; conserve o último id recebido.
• GET /api/runs/{id}/viewer — link opcional para a tela web limpa do computador; usuário ainda precisa entrar na conta.
• POST /api/runs/{id}/cancel com {} — solicitar cancelamento.
• POST /api/runs/{id}/continue com idempotency_key — continuação explícita ligada à tarefa anterior.

curl --silent --show-error --fail-with-body --config - <<EOF
url = "https://remote-agent-machine.carneiro.ai/api/runs"
header = "Authorization: Bearer ${RAM_API_KEY}"
EOF

Quando a execução precisa da pessoa

waiting_for_input com result.outcome needs_input é uma pausa, não uma tarefa concluída. A intervenção pode ser controle humano, cadastro de credencial ou autorização de uma conexão Google.

Nessas pausas, a consulta da tarefa e runs_list incluem required_action, derivado pelo serviço: takeover (agir no computador), credential, connection, continue (limite de chamadas atingido) ou credits (créditos insuficientes para a próxima chamada ao modelo). resume é sempre explicit_continue; veja https://remote-agent-machine.carneiro.ai/docs/interventions.

O harness usa MCP run_intervention ou GET /api/runs/{id}/intervention-descriptor para obter explicação e um link estável sem credencial. A pessoa entra na própria conta e confirma a abertura do recurso protegido; veja https://remote-agent-machine.carneiro.ai/docs/interventions. Depois da intervenção e da liberação do controle humano, a pessoa pode pedir continuação com uma chave estável.

preparing indica uma intenção durável de preparo. Um preparo unknown ou dispatch ativo não deve ser reenviado automaticamente. A conferência de preparo é explícita e limitada à evidência persistida; não significa navegador pronto.

Perguntas frequentes

Fechar o cliente cancela o objetivo delegado?

Não por si só. Use a rota de cancelamento quando quiser cancelar. Efeitos externos que já ocorreram não são desfeitos.

A API de criação pode ser repetida automaticamente?

Não crie outro pedido às cegas após perda de resposta. Preserve a mesma chave e parâmetros, consulte as tarefas e reconcilie a intenção. Deduplicação da tarefa não garante efeito externo exatamente uma vez.

Uma conexão Google ausente dispara login sozinha?

Não. O pedido estruturado pausa a tarefa para uma ação humana na página Conexões. A continuação verifica uma conexão própria, ativa e com as permissões necessárias.