Cloud Run para agentes de IA: serviço, Job ou worker pool?

Um agente que responde ao usuário e um agente que passa minutos consumindo tarefas não têm o mesmo contrato de execução. Colocar os dois atrás de uma rota HTTP pode funcionar no protótipo e criar um problema operacional assim que o loop precisa sobreviver ao fim da requisição.

Este artigo compara os três recursos do Cloud Run para essa decisão: Service, Job e worker pool. O critério não é qual nome parece mais moderno. É como o trabalho chega, quando ele termina, onde o estado fica e qual evidência permite recuperar uma execução interrompida.

Diagrama compara um agente de IA entre um serviço HTTP, um Job e um worker pool com fila.

Resultado da decisão

Use um Service quando o agente precisa de endpoint, streaming ou resposta para uma requisição.

Use um Job quando cada execução tem começo, fim e entradas bem definidas.

Use um worker pool quando o container deve consumir uma fila continuamente sem atender HTTP.

Em qualquer opção, persista estado e evidência fora do processo do agente.

A primeira pergunta é se o trabalho tem endpoint

A documentação O que é o Cloud Run separa Service, Job e worker pool pelo modo de execução. A escolha inicial é simples: se um cliente precisa chamar o agente e receber uma resposta, comece por Service; se o trabalho é puxado de uma fila sem endpoint, avalie worker pool.

Essa distinção evita um erro frequente em aplicações agentic. O agente começa dentro de uma requisição, chama ferramentas, espera uma resposta externa e continua o raciocínio. Se o processo depender de memória local ou de uma conexão HTTP aberta para guardar o progresso, uma reinicialização pode deixar a tarefa sem dono.

O agente deve devolver ao cliente apenas o que faz parte da interação. O restante precisa virar uma tarefa com identificador, estado e evidência. A orquestração multiagente com TypeScript aplica a mesma separação quando o trabalho deixa de caber em uma conversa. A introdução ao Google Cloud Run cobre o modelo geral da plataforma antes dessa escolha.

O que muda entre Service, Job e worker pool?

O documento do Google Cloud descreve Service como recurso para endpoints HTTPS e eventos, Job como execução de tarefas que terminam e worker pool como processamento contínuo baseado em pull, como consumidores de Pub/Sub, Kafka ou RabbitMQ (Google Cloud, "O que é o Cloud Run"). Essa tabela transforma a diferença em uma decisão operacional.

Recurso	Entrada principal	Fim esperado	Estado operacional	Escolha para agentes
Service	Requisição HTTP ou evento	Resposta ou entrega do evento	Estado fora da instância	Chat, API, streaming e disparo de tarefas
Job	Execução manual, agenda ou workflow	Tarefa concluída	Resultado persistido por execução	Evals, lotes, migrações e processamento finito
Worker pool	Fila consumida pelo container	Trabalho contínuo	Estado da tarefa e checkpoint	Consumidor agentic de longa duração

O worker pool não é uma versão mais lenta de um Service. Ele não tem endpoint balanceado e não faz escalonamento automático por conta própria. O time precisa decidir quantas instâncias ficam ativas e, se necessário, criar um autoscaler baseado na métrica da fila, conforme a documentação de implantação de worker pools.

Esse custo de operação pode ser correto quando a fila é a fronteira que você realmente precisa. Se o agente não tem trabalho, um Service pode escalar conforme as requisições, um Job pode esperar uma nova execução e um worker pool ainda precisa de uma política explícita para permanecer ativo. A escolha deve tornar esse comportamento visível.

Cápsula citável: No Cloud Run, Service atende HTTP e eventos, Job executa tarefas até terminar e worker pool processa trabalho contínuo sem endpoint. A escolha define como o agente recebe trabalho, como o sistema encerra uma execução e quem precisa controlar escala, estado, retry e recuperação.

Quando um agente deve ficar em um Cloud Run Service?

A documentação de como hospedar agentes no Cloud Run lista streaming HTTP e WebSockets entre os recursos úteis para interações de agentes. Service é a melhor escolha quando o cliente precisa acompanhar uma resposta, consultar o estado de uma tarefa ou iniciar uma execução por uma API autenticada.

O padrão mais seguro é separar o pedido da execução. A rota valida a entrada, cria um registro durável e publica uma mensagem. Ela pode responder com o identificador da tarefa sem manter o loop inteiro dentro da conexão do usuário.

type CreateTask = {
  taskId: string;
  prompt: string;
  repository: string;
};

async function createTask(input: CreateTask) {
  await taskStore.create({
    id: input.taskId,
    state: "queued",
    repository: input.repository,
    prompt: input.prompt,
  });

  await queue.publish({ taskId: input.taskId });

  return { taskId: input.taskId, state: "queued" };
}

O trecho não transforma o agente em worker pool. Ele define uma fronteira limpa para o Service: receber, validar, persistir e encaminhar. Um consumidor separado assume o loop e atualiza a tarefa. Se o agente precisar expor streaming, o Service ainda pode acompanhar eventos já persistidos sem confiar na memória da instância.

Use Service também quando o agente funciona como uma API de ferramentas ou como um servidor MCP remoto. Nesse caso, confirme o transporte e a autenticação. A documentação do MCP hospedado no Cloud Run suporta Streamable HTTP, mas não stdio para o servidor que roda na nuvem.

Quando o Cloud Run Job é a opção mais limpa?

Job entra quando a documentação Executar Jobs descreve uma execução com argumentos, variáveis de ambiente, quantidade de tarefas e timeout específicos. Esse recurso é adequado quando o agente recebe um lote conhecido, executa a tarefa e encerra sem precisar ficar escutando uma fila.

Um eval de agente é um exemplo claro. O sistema recebe uma revisão, um conjunto de casos e uma versão do prompt ou do código. O Job roda os casos, salva resultados e termina. Uma nova execução pode usar outro conjunto de entradas sem deixar um processo permanente esperando trabalho.

gcloud run jobs execute agent-eval \
  --region=REGION \
  --update-env-vars=EVAL_RUN_ID=RUN_ID,INPUT_URI=INPUT_URI \
  --wait

O comando inicia uma execução do Job e espera a conclusão. Em produção, substitua os nomes de exemplo por valores do seu ambiente e conceda apenas a identidade que precisa executar o recurso. Para casos em que a duração ou as entradas mudam por rodada, use os overrides documentados pelo Google Cloud e registre a configuração junto do resultado.

Não use Job para fingir que existe uma fila contínua. Um scheduler ou outro serviço precisa iniciar cada execução, e o próprio agente precisa saber se uma tarefa já foi concluída. Para uma fila que recebe trabalho o tempo todo, essa camada adicional costuma indicar que o modelo de worker pool merece avaliação.

Quando o worker pool paga o custo operacional?

Worker pool entra quando a documentação de implantação de worker pools no Cloud Run descreve o recurso como uma opção para trabalho contínuo em segundo plano, sem endpoint balanceado e sem escalonamento automático. Escolha-o quando o container deve fazer pull de uma fila e continuar processando enquanto houver tarefas.

Diagrama mostra fila, estado durável, logs e retry como prova de um loop agentic.

O loop do worker não deve depender de "continuar pensando" dentro de uma chamada. Cada mensagem precisa representar uma unidade que pode ser reservada, executada, confirmada ou devolvida para retry.

async function consumeForever() {
  for await (const message of queue.pull()) {
    const lease = await taskStore.claim(message.taskId);

    if (!lease) continue;

    try {
      const result = await runAgent({
        taskId: message.taskId,
        checkpoint: lease.checkpoint,
      });

      await taskStore.complete(message.taskId, {
        result: result.summary,
        evidence: result.evidence,
      });
      await queue.ack(message);
    } catch (error) {
      await taskStore.failAttempt(message.taskId, serializeError(error));
      await queue.nack(message);
    }
  }
}

O código é um contrato de execução, não um SDK específico de fila. claim precisa impedir duas reservas simultâneas, checkpoint precisa sobreviver à reinicialização e complete deve ser idempotente. Sem isso, o retry do agente pode duplicar uma alteração ou marcar como concluída uma tarefa que só produziu texto.

O recurso não escala sozinho. A documentação do Cloud Run diz que worker pools precisam de instâncias ativas e que a equipe pode criar um autoscaler próprio para ajustar a capacidade conforme a demanda. Isso torna a métrica da fila parte do sistema, não um detalhe escondido no container.

O que a implantação precisa proteger?

A documentação de implantação exige permissões distintas para desenvolver o worker pool, usar a conta de serviço e ler a imagem no Artifact Registry (Implantar worker pools no Cloud Run). A primeira barreira é não dar ao agente uma identidade mais ampla que o trabalho exige.

Diagrama mostra um agente passando por IAM antes de acessar fila, ferramentas e logs.

Configure uma conta de serviço própria para o worker. Se o agente só lê uma fila, concede apenas a permissão de consumo e as leituras de dados necessárias. Se ele escreve em um repositório, banco ou sistema de implantação, separe essa ação em uma ferramenta estreita com autorização adicional. O processo do agente não deve ganhar acesso administrativo por conveniência.

Também trate segredo e contexto como entradas distintas. Variáveis de ambiente podem configurar o processo, mas o prompt não deve receber credenciais. A tarefa deve carregar somente o contexto necessário para o próximo passo e guardar logs, checkpoints e evidências em armazenamento apropriado.

Em loops longos, a repetição de histórico vira um custo de projeto. Quando preciso manter continuidade entre sessões de Codex e Claude Code sem reenviar o mesmo contexto, uso o RemoteCode para levar fluxos agentic mais longe com menos repetição de tokens. É uma ferramenta do próprio autor, citada aqui porque o orçamento de contexto faz parte da arquitetura do loop, não porque substitua IAM, estado ou verificação.

O acervo sobre observabilidade de agentes no CI ajuda a definir os eventos que precisam sair do worker: tarefa recebida, reserva, chamada de ferramenta, checkpoint, erro, retry e conclusão. Logs sem identificador de tarefa são difíceis de usar quando várias instâncias trabalham em paralelo.

Como verificar se a escolha funciona?

O início rápido oficial de worker pools verifica o resultado pelos logs do container, e a documentação de Cloud Run aponta Cloud Logging e Error Reporting como integrações operacionais. A verificação precisa confirmar mais que a implantação: ela deve provar que a mensagem foi processada e que o estado pode ser recuperado.

Faça um teste pequeno com uma tarefa descartável e confira esta sequência:

O Service ou produtor cria uma tarefa com identificador único.
A fila entrega a mensagem ao worker.
O armazenamento registra a reserva e o checkpoint.
O agente produz uma evidência curta; o resumo sozinho não basta.
O estado muda para concluído e a mensagem é confirmada.
Uma falha entre o checkpoint e a confirmação permite retry sem duplicar o efeito.

Depois, interrompa uma execução em um ponto conhecido. O worker deve reiniciar, encontrar a tarefa não concluída e continuar a partir de um estado explícito. Se a única prova estiver no log de uma instância que morreu, a arquitetura ainda não está pronta.

Use gcloud run worker-pools list para verificar que o recurso existe e consulte os logs por tarefa. Para Jobs, guarde o identificador da execução e seus resultados. Para Services, teste o endpoint e o caminho assíncrono separadamente. A validação de tool calls em TypeScript cobre a mesma disciplina na fronteira entre o agente e o código.

Cápsula citável: Um agente de longa duração só está operacionalmente verificado quando a tarefa tem identificador, o worker registra um checkpoint, a saída contém evidência e um retry pode continuar sem duplicar o efeito. Uma implantação bem-sucedida prova que o container iniciou. Não prova que o loop sobreviveu a falha, redelivery ou reinicialização.

Erros comuns e limites da comparação

O primeiro erro é escolher worker pool porque o agente parece "autônomo". Autonomia do modelo não define o contrato de execução. Se existe um pedido HTTP claro e uma resposta curta, Service é mais simples. Se existe uma entrada finita, Job reduz a superfície de operação.

O segundo é assumir que worker pool significa escalonamento automático pronto. A documentação atual diz o contrário. Você precisa definir instâncias, métrica, política de aumento e redução, além do comportamento quando a fila está vazia. Se não quer manter esse mecanismo, use uma combinação de Service, Pub/Sub push, Cloud Tasks ou Jobs que corresponda ao fluxo.

O terceiro é guardar estado no disco local ou na memória. Instâncias são descartáveis, e uma revisão nova pode substituir a antiga. Salve progresso em banco, fila, armazenamento de objetos ou outro sistema que o processo de recuperação consiga ler.

Há também um limite de produto. Worker pools são uma capacidade recente e a documentação pode mudar enquanto os comandos e integrações amadurecem. Fixe a revisão da imagem, teste a configuração em um projeto descartável e confirme a região, as permissões e os termos de disponibilidade antes de acoplar o recurso a uma operação crítica.

Perguntas frequentes sobre agentes no Cloud Run

Um agente de IA precisa de worker pool para tarefas longas?

Não. Um Service pode iniciar a tarefa e devolver um identificador, enquanto um Job pode executar um lote até o fim. Worker pool faz sentido quando o container deve consumir uma fila continuamente sem endpoint. A decisão depende da chegada do trabalho e da política de recuperação, não da duração isolada do prompt.

Cloud Run worker pool tem URL pública?

Não. A documentação de worker pools descreve o recurso sem endpoint balanceado. Isso reduz a superfície HTTP, mas exige outro caminho para entregar trabalho, como uma fila pull. O agente ainda precisa de identidade de serviço, permissões estreitas, logs e um mecanismo para atualizar o estado da tarefa.

Quando Cloud Run Job é melhor que worker pool?

Job é melhor quando a entrada pode ser definida no início e a execução deve terminar. Evals, lotes e migrações são exemplos. Worker pool é melhor quando o processo precisa permanecer consumindo uma fila. Se o scheduler precisa disparar Jobs continuamente apenas para imitar um consumidor, reavalie a arquitetura.

Como impedir que um retry do agente duplique efeitos?

Use um identificador idempotente por tarefa, reserve a mensagem com lease e grave checkpoint antes de repetir uma chamada que produz efeito. A confirmação da fila deve acontecer depois do estado durável. Para ferramentas de escrita, inclua uma chave de idempotência ou uma etapa de aprovação antes da operação irreversível.

Agentes de IA de longa duração no Cloud Run: serviço ou worker pool?