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://remote-agent-machine.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://remote-agent-machine.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. GET /api/runs/{id}/viewer, MCP run_viewer e MCP computer_acquire também o oferecem. 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.

A tela limpa começa observando e exige login web da própria conta. O link não contém credencial, não é acesso anônimo nem gravação histórica. Para frames numa interface nativa, siga https://remote-agent-machine.carneiro.ai/docs/streaming; task_observer não concede tela.

Contrato da resposta de viewer

GET /api/runs/{id}/viewer e MCP run_viewer retornam o objeto abaixo. Na criação/consulta/continuação, o mesmo viewer aparece ao lado de run; computer_acquire o inclui ao lado da concessão. 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://remote-agent-machine.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.