Como criar um agente de IA com Claude em um VPS

O que significa criar um agente com Claude

Criar um agente com Claude significa usar o Claude como núcleo de raciocínio, enquanto o ciclo, as ferramentas e os dados ficam no seu próprio servidor. O Claude decide o que fazer; o seu VPS executa as ações. Você envia a tarefa e o estado atual ao Claude. O Claude responde com uma resposta ou com um pedido para usar uma das suas ferramentas. O seu código executa a ferramenta e envia o resultado de volta. O ciclo continua até o trabalho terminar. A inteligência é um serviço que você chama pela Internet. Tudo o que está à volta é seu.

Esta separação é a principal vantagem. Você obtém raciocínio de nível avançado sem operar um modelo e mantém controlo total sobre aquilo a que o agente pode aceder, porque as ferramentas são executadas em hardware que você controla. Se já criou um primeiro programa com Claude, o guia para criar a primeira aplicação Claude num VPS explica os fundamentos usados neste tutorial.

O Claude é o cérebro: a Messages API

Todas as chamadas ao Claude passam por um único endpoint, a Messages API. Envia a conversa até ao momento e a lista de ferramentas que o agente pode utilizar; o Claude devolve a mensagem seguinte. Essa mensagem é uma resposta final ou um pedido para chamar uma ferramenta. No percurso de implementação própria, não existe uma "agent API" separada: a utilização de ferramentas é uma funcionalidade deste endpoint único, e o ciclo à sua volta é executado pelo seu código.

O Claude não mantém estado entre chamadas, o que significa que não memoriza nada por si só. Cada pedido inclui a conversa completa. O seu código mantém o histórico e envia-o a cada turno, o que explica por que motivo cada turno de uma sessão longa custa mais tokens do que o anterior. Isto não é tanto uma limitação como uma opção de conceção: como o estado fica no seu servidor, decide exatamente o que o Claude vê, e nada relacionado com a tarefa é armazenado fora do seu controlo. Isto faz com que o prompt continue a crescer. Embora a janela de contexto do Claude suporte esse crescimento sem problemas, um modelo local no mesmo ciclo não o fará. Por isso, é necessário aumentar num_ctx no Ollama antes de este deixar de truncar prompts longos.

As ferramentas fazem parte do ciclo do agente

O ciclo do agente com Claude é simples de descrever. Envia um pedido que inclui as suas ferramentas. Claude lê a tarefa e, se precisar de agir, responde com um pedido de utilização de ferramenta que identifica uma ferramenta e preenche os respetivos argumentos. O seu código executa essa ferramenta e envia o resultado de volta para Claude no pedido seguinte. Claude lê o resultado e pede outra ferramenta ou escreve a resposta final. Quando deixa de pedir ferramentas, a tarefa está concluída.

Pode escrever esse ciclo manualmente em poucas linhas, e muitas pessoas fazem isso porque é fácil de ver e controlar. Os SDK oficiais também fornecem um executor de ferramentas que conduz o ciclo por si: fornece as funções das ferramentas, e o SDK trata da comunicação entre as partes, da chamada a Claude, da execução das ferramentas e do envio dos resultados de volta até Claude terminar. Em ambos os casos, a estrutura é a mesma. O executor apenas evita que tenha de escrever o ciclo. Se o ciclo ainda parecer abstrato, escreva primeiro um ciclo mínimo antes de usar um executor. Esse é o passo de que tudo o resto depende em neste percurso faseado para aprender agentes de IA do zero.

Três formas de criar um agente e quais se adequam a um VPS

Existem três formas de criar um agente Claude. Elas diferem na quantidade de componentes que você precisa executar.

A primeira é usar o seu próprio código para chamar a API do Claude com as suas próprias ferramentas. Você implementa o loop ou usa o executor de ferramentas do SDK e aloja todo o sistema no seu VPS. Esta é a opção mais comum, porque oferece controlo total sobre as ferramentas, os dados e a segurança. O sistema é executado como um programa normal no seu servidor. A maior parte deste guia pressupõe este caminho.

A segunda é o Claude Agent SDK. Trata-se do Claude Code, o agente de programação, empacotado como uma biblioteca sobre a qual você pode criar. Ele inclui um loop de agente completo e ferramentas integradas para ler e escrever ficheiros, executar comandos shell e fazer pesquisas. Assim, você não precisa de montar esses componentes do zero. Também é executado no seu próprio servidor, o que o torna adequado para um VPS quando você quer um agente capaz de trabalhar com ficheiros e shell sem criar o harness por conta própria. Um agente que lê ficheiros e executa comandos shell precisa de contenção antes de funcionar sem supervisão. A secção executar o Claude Code com segurança num servidor aborda o sistema de permissões, o sandbox e as opções de isolamento.

A terceira é Managed Agents, em que a Anthropic executa o loop e aloja um sandbox onde as ferramentas do agente são executadas. Esta é a opção que exige menos intervenção: há muito menos componentes para operar, mas o espaço de trabalho do agente fica na infraestrutura da Anthropic, e não no seu VPS. Escolha esta opção quando quiser reduzir ao mínimo o trabalho operacional e não precisar de executar as ferramentas na sua própria máquina. Nas outras duas opções, o seu servidor é o local onde o agente é executado. É disso que trata o restante deste guia.

Conectar ferramentas com MCP

Independentemente do caminho escolhido, vai querer ligar o agente a sistemas reais, e o Model Context Protocol é a forma organizada de o fazer. O MCP é um padrão aberto para expor ferramentas e dados a um agente. Em vez de programar manualmente uma integração para cada serviço, aponta o Claude para um servidor MCP que já apresenta essas capacidades como ferramentas. Pode executar servidores MCP como pequenos serviços no mesmo VPS, cada um com apenas o acesso de que necessita. Explico isto em executar servidores MCP num VPS.

Escolher um modelo

O Claude está disponível em vários modelos, e a escolha envolve um compromisso entre capacidade, velocidade e custo. No momento da redação, as opções principais são o Claude Opus 4.8 (claude-opus-4-8), a opção padrão mais capaz para raciocínio complexo e execuções longas de agentes; o Claude Sonnet 5 (claude-sonnet-5), uma opção equilibrada, mais barata e rápida, que permanece próxima do Opus em muitas tarefas; e o Claude Haiku 4.5 (claude-haiku-4-5), o mais rápido e barato, para etapas simples e de elevado volume. Acima deles está o Claude Fable 5 (claude-fable-5), o modelo mais capaz, destinado às tarefas mais exigentes. Use no código o identificador exato do modelo, sem acrescentar uma data.

Um padrão prático é combinar os modelos. Deixe um modelo mais barato tratar as chamadas de ferramentas rotineiras e use um modelo mais potente para as decisões difíceis. Como o modelo é apenas uma string no pedido, a troca requer uma alteração de uma linha. Comece com uma opção padrão capaz e reduza o modelo quando a velocidade ou o custo forem mais importantes do que o último nível de qualidade.

Execute-o como um serviço protegido no seu VPS

Um agente só é útil se continuar em execução, e só é seguro se estiver contido. Num VPS, essas duas condições são obtidas ao executar o agente como um serviço de sistema protegido, em vez de iniciar um programa manualmente num terminal. Como serviço, ele inicia no boot, reinicia se falhar e escreve os logs no journal. Protegido, é executado por um utilizador sem privilégios e com apenas os acessos necessários, o que limita o impacto de um bug ou de uma instrução maliciosa. Uma unidade de serviço só consegue limitar aquilo em que o processo pode tocar. O restante deve ser aplicado dentro do próprio harness do agente. É esse o objetivo dos plugins DeepSeek Harness que vale a pena instalar noutra stack: limites de gastos, regras de permissões por ferramenta e análise de prompt injection.

A regra mais importante é manter a sua chave da API Claude no servidor. A chave paga e autoriza cada chamada. Por isso, deve ficar num ficheiro legível apenas pelo utilizador do agente, ser carregada no serviço como uma variável de ambiente e nunca ser incluída em código, num repositório ou em qualquer local acessível por um browser. Gere aqui uma unidade de serviço completa e protegida para o seu agente:

Depois, proteja o próprio servidor. Configure o SSH para aceitar apenas chaves e proteja a conta a partir da qual administra o sistema, conforme descrito em Proteção do SSH num VPS. Se preferir controlar o agente a partir de uma sessão interativa enquanto o configura, executar o Claude Code num VPS com tmux é um bom complemento. Depois de abrir uma segunda sessão na mesma máquina, os dois podem transferir trabalho entre si, em vez de ter de transportar cada instrução de um painel para o outro. Se quiser compreender os conceitos subjacentes, sem os associar a um único modelo, o guia relacionado sobre criar o seu próprio agente de IA num VPS apresenta os fundamentos.

Se pretende um assistente de programação num terminal, executar um agente de IA para programação num VPS aborda o Aider e o Goose.

FAQ

Que modelo Claude devo utilizar para criar um agente?

Comece com Claude Opus 4.8 (claude-opus-4-8), a opção predefinida mais capaz, e ajuste a partir daí. Claude Sonnet 5 (claude-sonnet-5) é mais barato e rápido para a maioria das tarefas, Claude Haiku 4.5 (claude-haiku-4-5) é mais indicado para etapas simples e de grande volume, e Claude Fable 5 (claude-fable-5) é o mais capaz para as tarefas mais difíceis. Um padrão comum é utilizar um modelo mais barato para as etapas rotineiras e um modelo mais potente para as decisões complexas, porque a troca requer apenas uma alteração de uma linha.

Executo o agente inteiro no meu VPS ou a Anthropic trata dessa parte?

Depende da abordagem. Se escrever o seu próprio loop com a Claude API ou utilizar o Claude Agent SDK, o agente é executado inteiramente no seu VPS e apenas as chamadas ao modelo são enviadas para a Anthropic. Se utilizar Managed Agents, a Anthropic executa o loop e aloja o sandbox onde as ferramentas são executadas, pelo que uma parte menor fica no seu servidor. Para um agente executado na sua própria máquina, utilize uma das primeiras duas opções.

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

A Claude API é o endpoint Messages de baixo nível: envia uma conversa e ferramentas, e escreve o loop do agente à volta disso, ou utiliza o tool runner do SDK para o controlar. O Claude Agent SDK é uma biblioteca de nível superior, baseada no Claude Code para permitir a sua utilização na criação de aplicações, que fornece um loop completo e ferramentas integradas para ficheiros, shell e pesquisa. Utilize a API quando quiser definir tudo manualmente, e o Agent SDK quando quiser um agente capaz sem montar todo o suporte de execução.

Como mantenho a minha chave da Claude API segura num servidor?

Mantenha-a no servidor e fora do código. Guarde-a num ficheiro legível apenas pela conta sob a qual o agente é executado, carregue-a no serviço como uma variável de ambiente e nunca a confirme num repositório nem a exponha a um browser. Como todos os pedidos para a Claude partem do seu servidor, a chave nunca precisa de chegar ao dispositivo do utilizador. Isso torna mais fácil proteger um agente executado no servidor do que um agente integrado numa aplicação cliente.

Preciso de alojar um modelo localmente para criar um agente com Claude?

Não. Com Claude, o modelo é um serviço alojado que contacta através da API, pelo que não há nada para executar numa GPU. O seu VPS executa o loop do agente, as ferramentas e gere os dados; o raciocínio ocorre do lado da Anthropic. É isso que permite a um servidor modesto executar um agente capaz. Se quiser utilizar um modelo totalmente local, esse é o caminho de alojamento próprio abordado no guia complementar sobre a criação do seu próprio agente de IA.