Como criar agente AI com Claude no VPS

O que significa construir um agente com Claude

Construir um agente com Claude significa usar o Claude como núcleo de raciocínio, enquanto o loop, as ferramentas e os dados residem no seu próprio servidor. O Claude decide o que fazer; seu VPS executa. Você envia ao Claude a tarefa e o estado atual; o Claude responde com uma resposta ou com um pedido para usar uma de suas ferramentas; seu código executa a ferramenta e envia o resultado de volta, e o loop continua até que o trabalho seja concluído. A inteligência é um serviço que você chama via internet. Tudo ao redor dela é seu.

Essa divisão é o diferencial. Você obtém raciocínio de nível frontier sem operar um modelo, e mantém controle total sobre o que o agente pode tocar, pois as ferramentas rodam no hardware que você possui. Se você já construiu seu primeiro programa com Claude, o guia do primeiro app Claude em um VPS cobre a base sobre a qual este é construído.

Claude é o cérebro: a Messages API

Cada chamada ao Claude passa por um endpoint, a Messages API. Você envia a conversa até o momento e a lista de ferramentas que o agente pode usar; o Claude retorna sua próxima mensagem. Essa mensagem é uma resposta final ou um pedido para chamar uma ferramenta. Para o caminho de construção própria, não existe uma "agent API" separada: o uso de ferramentas é um recurso deste endpoint único, e o loop ao redor dele é de sua responsabilidade.

O Claude é stateless entre chamadas, o que significa que ele não lembra de nada por conta própria. Cada requisição carrega a conversa completa. Seu código mantém o histórico e o envia em cada turno, o que é por que cada turno em uma sessão longa custa mais tokens que o anterior. Isso não é tanto uma limitação, mas uma escolha de design: como o estado reside no seu servidor, você decide exatamente o que o Claude vê, e nada sobre a tarefa é armazenado em qualquer lugar que você não controle.

O uso de ferramentas é o loop do agente

O loop do agente com Claude é simples de descrever. Você envia uma requisição que inclui suas ferramentas. O Claude lê a tarefa e, se precisar agir, responde com um pedido de uso de ferramenta que nomeia uma ferramenta e preenche seus inputs. Seu código executa essa ferramenta e envia o resultado de volta ao Claude na próxima requisição. O Claude lê o resultado e solicita outra ferramenta ou escreve sua resposta final. Quando ele para de solicitar ferramentas, a tarefa está concluída.

Você pode escrever esse loop manualmente em poucas linhas, e muitas pessoas fazem isso, pois é fácil de visualizar e controlar. Os SDKs oficiais também fornecem um tool runner que gerencia o loop para você: você fornece as funções das ferramentas e o SDK lida com o vaivém de chamar o Claude, executar suas ferramentas e alimentar os resultados até que o Claude termine. De qualquer forma, a estrutura é a mesma. O runner apenas evita que você escreva o loop manualmente.

Três formas de construir, e quais se adequam a um VPS

Existem três formas de construir um agente Claude, e elas diferem pela quantidade de maquinário que você executa.

A primeira é seu próprio código chamando a API do Claude com suas próprias ferramentas. Você escreve o loop, ou usa o tool runner do SDK, e hospeda tudo em seu VPS. Esta é a escolha comum, pois oferece controle total sobre as ferramentas, os dados e a segurança, e roda como um programa comum em seu servidor. A maior parte deste guia assume este caminho.

A segunda é o Claude Agent SDK. Este é o Claude Code, o agente de codificação, empacotado como uma biblioteca para construção. Ele entrega um loop de agente completo e ferramentas integradas para ler e escrever arquivos, executar comandos de shell e realizar buscas, para que você não precise montá-las do zero. Ele também roda em seu próprio servidor, o que o torna ideal para um VPS quando você deseja um agente capaz de manipular arquivos e shell sem construir o harness sozinho. Um agente que lê arquivos e executa comandos de shell precisa de contenção antes de operar sem supervisão, e executar o Claude Code com segurança em um servidor aborda o sistema de permissões, o sandbox e as opções de isolamento.

A terceira são os Managed Agents, onde a Anthropic executa o loop e hospeda um sandbox no qual as ferramentas do agente são executadas. Esta é a opção sem gestão: há muito menos para você operar, mas o workspace do agente reside na infraestrutura da Anthropic em vez do seu VPS. Utilize esta opção quando quiser o mínimo de trabalho operacional e não precisar que as ferramentas rodem em sua própria máquina. Para as outras duas, seu servidor é a casa do agente, que é o foco do restante deste guia.

Conectando ferramentas com MCP

Independentemente do caminho escolhido, você desejará conectar o agente a sistemas reais, e o Model Context Protocol é a forma organizada de fazer isso. O MCP é um padrão aberto para expor ferramentas e dados a um agente. Em vez de codificar manualmente uma integração para cada serviço, você aponta o Claude para um servidor MCP que já apresenta essas capacidades como ferramentas. Você pode rodar servidores MCP como pequenos serviços no mesmo VPS, cada um com apenas o acesso necessário, o que eu cubro em executando servidores MCP em um VPS.

Escolhendo um modelo

O Claude possui vários modelos, e escolher um é um equilíbrio entre capacidade, velocidade e custo. Na data de escrita deste texto, as escolhas principais são o Claude Opus 4.8 (claude-opus-4-8), o padrão capaz para raciocínio complexo e execuções longas de agentes; o Claude Sonnet 5 (claude-sonnet-5), uma opção equilibrada que é mais barata e rápida, mantendo-se próximo ao Opus em muitas tarefas; e o Claude Haiku 4.5 (claude-haiku-4-5), o mais rápido e barato, para etapas simples de alto volume. Acima deles está o Claude Fable 5 (claude-fable-5), o modelo mais capaz, para o trabalho mais exigente. Use o identificador exato do modelo em seu código, sem adicionar datas a ele.

Um padrão prático é misturá-los. Deixe um modelo mais barato lidar com chamadas de ferramentas rotineiras e um mais forte lidar com as decisões difíceis. Como o modelo é apenas uma string em sua requisição, a troca é uma mudança de uma linha, portanto, comece com um padrão capaz e ajuste para baixo onde a velocidade ou o custo importem mais que a última fração de qualidade.

Rode como um serviço endurecido em seu VPS

Um agente só é útil se permanecer rodando, e só é seguro se estiver contido. Em um VPS, ambos os fatores vêm de rodar o agente como um serviço de sistema endurecido (hardened), em vez de um programa iniciado manualmente em um terminal. Como serviço, ele inicia no boot, reinicia se falhar e gera logs no journal. Endurecido, ele roda como um usuário sem privilégios com apenas o acesso necessário, de modo que um bug ou uma instrução incorreta tenha um limite.

A regra mais importante é manter sua chave da API do Claude no lado do servidor. A chave paga e autoriza cada chamada, portanto, ela deve ficar em um arquivo legível apenas pelo usuário do agente, carregado no serviço como uma variável de ambiente, e nunca colocada no código, em um repositório ou em qualquer lugar que um navegador possa alcançar. Gere uma unit de serviço completa e endurecida para seu agente aqui:

Depois, finalize o servidor. Configure o SSH apenas para chaves e restrinja a conta que você administra, como em SSH hardening em um VPS. Se preferir operar o agente em uma sessão interativa enquanto o constrói, executando o Claude Code em um VPS com tmux é um bom complemento. E se você quiser os conceitos por trás de tudo isso, sem vinculá-los a um modelo específico, o guia complementar sobre construindo seu próprio agente de IA em um VPS apresenta os fundamentos.

Se o que você deseja é um assistente de codificação via terminal, executando um agente de IA de codificação em um VPS aborda o Aider e o Goose.

FAQ

Qual modelo Claude devo usar para construir um agente?

Comece com o Claude Opus 4.8 (claude-opus-4-8), o padrão capaz, e ajuste a partir daí. O Claude Sonnet 5 (claude-sonnet-5) é mais barato e rápido para a maioria dos trabalhos, o Claude Haiku 4.5 (claude-haiku-4-5) é melhor para etapas simples de alto volume, e o Claude Fable 5 (claude-fable-5) é o mais capaz para as tarefas mais difíceis. Um padrão comum é usar um modelo mais barato para etapas rotineiras e um mais forte para as decisões difíceis, já que a troca é uma mudança de uma linha.

Eu rodo o agente inteiro no meu VPS, ou a Anthropic roda?

Depende da abordagem. Se você escrever seu próprio loop contra a API do Claude, ou usar o Claude Agent SDK, o agente roda inteiramente no seu VPS e apenas as chamadas do modelo saem para a Anthropic. Se você usar Managed Agents, a Anthropic roda o loop e hospeda o sandbox onde as ferramentas são executadas, então menos partes residem no seu servidor. Para um agente que roda em sua própria máquina, use uma das duas primeiras opções.

Qual é a diferença entre a Claude API e o Claude Agent SDK?

A Claude API é o endpoint Messages bruto: você envia uma conversa e ferramentas, e escreve o loop do agente ao redor dele, ou usa o tool runner do SDK para conduzi-lo. O Claude Agent SDK é uma biblioteca de nível superior, o Claude Code empacotado para construção, que entrega um loop completo e ferramentas integradas de arquivo, shell e busca. Use a API quando quiser definir tudo você mesmo, e o Agent SDK quando quiser um agente capaz sem montar o harness.

Como mantenho minha chave da API do Claude segura em um servidor?

Mantenha-a no lado do servidor e fora do seu código. Armazene-a em um arquivo legível apenas pela conta na qual o agente roda, carregue-a no serviço como uma variável de ambiente e nunca a faça commit em um repositório ou a exponha a um navegador. Como cada requisição ao Claude parte do seu servidor, a chave nunca precisa chegar ao dispositivo de um usuário, o que torna um agente rodando em servidor mais fácil de proteger do que um embutido em um app cliente.

Eu preciso hospedar um modelo localmente para construir um agente com Claude?

Não. Com o Claude, o modelo é um serviço hospedado que você chama via API, portanto não há nada para rodar em uma GPU. Seu VPS roda o loop do agente, as ferramentas e os dados, e o raciocínio acontece no lado da Anthropic. Isso é o que permite que um servidor modesto rode um agente capaz. Se você preferir um modelo totalmente local, esse é o caminho de self-hosting abordado no guia complementar sobre construção de seu próprio agente de IA.