Integrar com JavaScript

Integre o serviço, sem clonar o servidor

O RAM é um serviço hospedado; seu repositório é privado. Para usar MCP, HTTP ou streaming, você não precisa clonar, compilar ou instalar o RAM. O exemplo usa fetch nativo do Node.js 24 no seu próprio aplicativo; não depende de um pacote privado.

Obtenha uma chave runner da sua conta em Meu acesso. Mantenha-a no host confiável, fora de prompts, URLs e logs. Consulte GET /api/computers, escolha o campo id de um computador próprio com state ready e availability available; GET /api/status?computer_id=ID confirma capacidades.

Delegue e guarde o identificador

Configure RAM_API_KEY e RAM_COMPUTER_ID por um mecanismo privado do seu aplicativo. O exemplo delega uma tarefa de observação, consulta estado e eventos; não executa um modelo no cliente. O Brain remoto requer provedor e limites configurados.

Uma falha de transporte na criação pode ter resultado desconhecido. Guarde os parâmetros e a chave estável antes do envio; não repita automaticamente nem invente outra chave para a mesma intenção.

const origin = 'https://ram-aws-qa.carneiro.ai';
const credential = process.env.RAM_API_KEY;
const computerId = process.env.RAM_COMPUTER_ID;
if (!credential || !computerId) throw new Error('Configure chave runner e computador');

async function request(path, input) {
  const response = await fetch(new URL(path, origin), {
    method: input ? 'POST' : 'GET',
    redirect: 'error',
    headers: {
      Authorization: `Bearer ${credential}`,
      ...(input ? { 'Content-Type': 'application/json' } : {}),
    },
    ...(input ? { body: JSON.stringify(input) } : {}),
  });
  if (!response.ok) throw new Error(`RAM HTTP ${response.status}; confira o estado antes de repetir`);
  return response.json();
}
// Persista esta chave por intenção ANTES de enviar; nunca gere outra no retry.
const requestKey = 'pedido-exemplo-estavel-001';
const { run } = await request('/api/runs', {
  objective: 'Descreva a página atualmente aberta, sem executar alterações.',
  idempotency_key: requestKey,
  runtime: 'agent', computer_id: computerId, allow_mutations: false,
  max_steps: 5, max_duration_seconds: 60, max_output_tokens: 512,
});
// Guarde run.id (UUID), sem imprimir objetivos ou resultados privados.
const current = await request(`/api/runs/${run.id}`);
const history = await request(`/api/runs/${run.id}/events?after=0`);

Apresente intervenção e viewer

waiting_for_input com result.outcome needs_input significa pausa. Consulte GET /api/runs/{id}/intervention-descriptor para apresentar a ação à pessoa sem capabilities; siga https://ram-aws-qa.carneiro.ai/docs/interventions. Após intervenção e liberação do controle humano, a continuação é um POST explícito separado com chave estável.

Na criação, consulta e continuação, viewer pode acompanhar run. O localizador HTTP GET /api/runs/{id}/viewer exige login web. Via MCP, run_start, run_continue e computer_acquire oferecem uma capability temporária quando o computador está pronto; run_viewer e computer_viewer_create emitem um novo link explicitamente. viewer.url é absoluta na origem do RAM: ofereça o link à pessoa ao iniciar a tarefa ou assumir o computador e abra somente com o consentimento dela. Confira que o link permanece na mesma origem do RAM antes de mostrá-lo; nunca aceite um destino arbitrário vindo do modelo.

Os localizadores HTTP /view exigem login web. Já a capability MCP /watch#HASH permite acompanhar sem login por 10 minutos; não concede controle. O hash é segredo temporário: não registre o link, não envie para analytics e compartilhe somente com a pessoa pretendida. Ambos mostram o computador atual, não gravação histórica. Para frames numa interface nativa, siga https://ram-aws-qa.carneiro.ai/docs/streaming; task_observer não concede tela.

Link MCP temporário sem login web

Escolha computer_id e chame computer_viewer_create. A resposta viewer contém id, computer_id, generation, url, mode observe, requires_login false, expires_at e expires_in_seconds 600. Se houver browser embutido, ofereça abrir viewer.url para a pessoa acompanhar. Verifique a mesma origem do MCP, pathname /watch, nenhuma query e fragmento aleatório de 43 caracteres base64url. Não transforme a URL em um localizador /view nem retire o fragmento antes de abrir.

Para renovar, chame computer_viewer_create novamente. O campo opcional replaces com o id anterior revoga aquele link ao emitir o novo. Após expiração, peça um novo link sem replaces. computer_viewer_revoke com id revoga um link desta mesma credencial. Expiração, revogação de chave, perda da atribuição ou mudança de geração encerram os streams; não há login nem redirecionamento como fallback.

A tela temporária é somente observação, inclusive para quem tem cookie RAM no browser. Controle humano continua exigindo o fluxo autenticado separado. O resgate faz POST sem cookies para /api/visual/links/session com token no corpo e X-RAM-Intent visual-link, depois usa ticket de uso único no WebSocket. O fragmento nunca vai em requisições HTTP; a página o remove do histórico. Não registre corpos, headers de ticket ou screenshots pessoais.

As capabilities atuais ficam somente na memória do gateway e são invalidadas por reinício. Em uma instalação com várias réplicas, um link pode ser recusado por outra réplica: peça um novo link, sem ampliar permissões. Android usa protocolo próprio e não recebe estas ferramentas de Computer. Uma MicroVM ainda creating não tem binding pronto: aguarde running e solicite computer_viewer_create; a criação não inventa um link.

Contrato do localizador HTTP autenticado

O localizador HTTP GET /api/runs/{id}/viewer retorna o objeto abaixo; a capability MCP está descrita na seção anterior. Nas respostas HTTP de criação/consulta/continuação, o localizador aparece ao lado de run. MCP computer_acquire oferece a capability temporária descrita acima. SEU_COMPUTADOR representa o ID real do computador. viewer.url já é absoluta na origem desta instalação; clientes que guardaram o formato relativo anterior devem resolvê-lo com essa mesma origem e confirmar que permanece nela.

viewer é opcional nas respostas de tarefa: uma execução simulated ou sem computador não oferece streaming. O endpoint dedicado recusa com HTTP 409 quando não há viewer autorizado. Não invente um link substituto; informe a indisponibilidade. Login expirado ao abrir a tela exige entrar no RAM e abrir o mesmo link novamente.

{
  "viewer": {
    "url": "https://ram-aws-qa.carneiro.ai/view?computer_id=SEU_COMPUTADOR",
    "computer_id": "SEU_COMPUTADOR",
    "requires_login": true,
    "mode": "observe",
    "scope": "computer"
  }
}

Perguntas frequentes

Preciso clonar ou instalar o RAM?

Não. Use o endpoint MCP ou a API HTTP autenticada do serviço hospedado. O repositório do servidor é privado.

Existe um pacote SDK público para instalar?

Não há pacote público anunciado. Este guia usa fetch nativo; o caminho /docs/sdk permanece para links existentes.