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. Envia a tarefa e o estado atual ao Claude, que 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 chama através da internet. Tudo o que está à volta é seu.

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

Claude é o cérebro: a Messages API

Todas as chamadas para 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; 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.

Claude não mantém estado entre chamadas, o que significa que não se lembra de nada por si só. Cada pedido inclui a conversa completa. O seu código mantém o histórico e envia-o em cada interação, o que explica por que cada interação numa sessão longa custa mais tokens do que a anterior. Isto não é tanto uma limitação, mas uma opção de conceção: como o estado fica no seu servidor, decide exatamente o que Claude vê, e nenhuma informação sobre a tarefa é armazenada num local que não controla. Isso faz com que o prompt continue a crescer. Embora a janela de contexto do Claude lide com esse crescimento sem problemas, um modelo local no mesmo ciclo não o fará. Por isso, é necessário aumentar num_ctx no Ollama antes que ele deixe de truncar prompts longos.

Uso de ferramentas é o ciclo do agente

O ciclo do agente com Claude é simples de descrever. Envia-se um pedido que inclui as 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-no porque é fácil de ver e controlar. Os SDK oficiais também fornecem um executor de ferramentas que gere o ciclo por si: fornece as funções das ferramentas, e o SDK trata da comunicação entre pedidos, da chamada de 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 manualmente. Se o ciclo ainda parecer abstrato, escreva primeiro um ciclo mínimo antes de usar um executor. Esse é o passo de que depende todo o resto em este percurso faseado para aprender agentes de IA desde o início.

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 ficam sob a sua responsabilidade.

A primeira consiste em usar o seu próprio código para chamar a Claude API com as suas próprias ferramentas. Pode escrever o loop ou usar o executor de ferramentas do SDK. Nesse caso, aloja tudo no seu VPS. Esta é a opção mais comum porque oferece controlo total sobre as ferramentas, os dados e a segurança. O agente é executado como um programa normal no seu servidor. A maior parte deste guia pressupõe este modelo.

A segunda opção é o Claude Agent SDK. Trata-se do Claude Code, o agente de programação, disponibilizado como uma biblioteca sobre a qual pode construir. O SDK inclui um loop de agente completo e ferramentas integradas para ler e escrever ficheiros, executar comandos de shell e fazer pesquisas. Assim, não precisa de criar esses componentes de raiz. O agente também é executado no seu próprio servidor, o que torna esta opção adequada para um VPS quando precisa de um agente capaz de trabalhar com ficheiros e shell sem criar o harness. Um agente que lê ficheiros e executa comandos de shell precisa de contenção antes de poder trabalhar 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 opção é Managed Agents, em que a Anthropic executa o loop. Por predefinição, as ferramentas do agente são executadas num sandbox alojado pela Anthropic. Por isso, o workspace do agente fica na infraestrutura da Anthropic, e não no seu VPS. Em 11 de outubro de 2026, uma opção de sandbox self-hosted, ainda em beta, permite que um processo worker no seu próprio servidor execute as chamadas das ferramentas, enquanto o loop permanece na Anthropic. Escolha Managed Agents quando quiser reduzir ao mínimo o trabalho operacional e não precisar de executar o próprio loop na sua máquina. Nas outras duas opções, o seu servidor aloja o agente completo. É esse o modelo abordado no restante deste guia.

Ligar 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 precisa, como explico 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. Em 11 de outubro de 2026, a linha atual inclui o Claude Opus 5.5 (claude-opus-5-5), que a Anthropic recomenda como ponto de partida para a maioria das cargas de trabalho e disponibiliza para programação agêntica de longa duração e trabalho com conhecimento; o Claude Sonnet 5.5 (claude-sonnet-5-5), uma opção equilibrada, mais barata e mais rápida; e o Claude Haiku 5.5 (claude-haiku-5-5), o mais rápido e barato, para etapas simples e de grande volume. Acima deles está o Claude Fable 5.1 (claude-fable-5-1), o modelo mais capaz disponível para todos os clientes, destinado a raciocínio exigente e trabalho agêntico de longo horizonte. Os modelos mais antigos, como o Claude Opus 4.8 e o Claude Fable 5, continuam disponíveis, mas agora estão classificados como legados. Use no código o identificador exato do modelo, sem acrescentar uma data.

Um padrão prático consiste em combiná-los. Deixe um modelo mais barato tratar das chamadas de ferramentas rotineiras e use um modelo mais forte para as decisões difíceis. Como o modelo é apenas uma string no pedido, a troca exige uma alteração de uma linha. Comece com um modelo padrão capaz e reduza a capacidade quando a velocidade ou o custo forem mais importantes do que o último nível de qualidade.

Execute como um serviço protegido no seu VPS

Um agente só é útil se permanecer em execução, e só é seguro se estiver contido. Num VPS, ambos os objetivos são alcançados 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 regista os eventos no journal. Com proteção reforçada, é executado por um utilizador sem privilégios e tem apenas o acesso de que precisa. Assim, um bug ou uma instrução maliciosa fica limitado. Uma unidade de serviço pode restringir os recursos que o processo pode aceder, bem como a memória, o CPU e o número de tarefas que pode utilizar. No entanto, não consegue avaliar o que o agente decide fazer com esse acesso. Essa proteção deve ficar no próprio harness do agente. É essa a função dos plugins DeepSeek Harness que vale a pena instalar numa stack diferente: limites de despesas, regras de permissão 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 colocada no 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 restrinja a conta a partir da qual administra o servidor, 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 utilizar um assistente de programação no terminal, executar um agente de IA para programação num VPS aborda o Aider e o Goose.

FAQ

Que modelo Claude devo usar para criar um agente?

Comece com Claude Opus 5.5 (claude-opus-5-5), que a Anthropic recomenda para a maioria das cargas de trabalho, e ajuste a partir daí. Claude Sonnet 5.5 (claude-sonnet-5-5) é mais barato e rápido para a maioria das tarefas, Claude Haiku 5.5 (claude-haiku-5-5) é a melhor opção para etapas simples e de elevado volume, e Claude Fable 5.1 (claude-fable-5-1) é o mais capaz para as tarefas mais difíceis. Um padrão comum é usar um modelo mais barato nas etapas rotineiras e um modelo mais potente nas decisões difíceis, porque a mudança exige apenas uma alteração numa linha.

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

Depende da abordagem. Se escrever o seu próprio ciclo contra a Claude API, ou usar o Claude Agent SDK, o agente é executado inteiramente no seu VPS e apenas as chamadas ao modelo são enviadas para a Anthropic. Se usar Managed Agents, a Anthropic executa o ciclo e, por predefinição, aloja o sandbox onde as ferramentas são executadas, pelo que uma parte menor do agente fica no seu servidor; uma opção de sandbox self-hosted, em beta desde October 11, 2026, transfere a execução das ferramentas para a sua própria máquina, enquanto o ciclo permanece na Anthropic. Para um agente executado inteiramente na 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: envia uma conversa e ferramentas, e escreve o ciclo do agente à volta disso, ou usa o tool runner do SDK para o conduzir. O Claude Agent SDK é uma biblioteca de nível superior, com o Claude Code empacotado para servir de base a novos projetos, que inclui um ciclo completo e ferramentas integradas para ficheiros, shell e pesquisa. Use a API quando quiser definir tudo por conta própria, e o Agent SDK quando quiser um agente capaz sem montar toda a infraestrutura de suporte.

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

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

Preciso de fazer self-hosting de um modelo para criar um agente com Claude?

Não. Com Claude, o modelo é um serviço alojado que chama através da API, por isso não há nada para executar numa GPU. O seu VPS executa o ciclo do agente, as ferramentas e gere os dados, enquanto o raciocínio ocorre do lado da Anthropic. É isso que permite a um servidor modesto executar um agente capaz. Se quiser usar um modelo totalmente local, esse é o caminho self-hosted abordado no guia complementar sobre como criar o seu próprio agente de IA.