Como aprender agentes de IA do zero em seis etapas

O percurso em seis etapas

Para aprender sobre agentes de IA desde o início, avance por seis etapas, nesta ordem: conceitos, o primeiro loop, ferramentas, memória, conceção do loop e segurança. Em cada etapa, constrói uma coisa com as próprias mãos. Avançar demasiado cedo é o motivo mais comum para as pessoas ficarem bloqueadas, porque um framework esconde exatamente a parte que precisava de ver.

Um agente de IA é um loop à volta de um modelo de linguagem ao qual é permitido chamar ferramentas. Essa frase resume todo o assunto. Tudo o que vem depois são detalhes sobre o que entra no loop, aquilo em que as ferramentas podem tocar e como interromper o loop quando algo corre mal. Se consegue explicar o loop a outra pessoa, aprendeu o essencial. Se só consegue enumerar frameworks, ainda não aprendeu.

O plano abaixo pressupõe que aprende construindo. Leia uma etapa, construa a pequena coisa, provoque uma falha de propósito e avance depois. Uma etapa que apenas leu é uma etapa que ainda não executou.

O que realmente precisa antes da etapa 1

A lista honesta de pré-requisitos é curta e mais curta do que a sugerida pela maioria das páginas de cursos.

• Consegue ler e escrever Python ou TypeScript ao nível de um script com cinquenta linhas.
• Sente-se à vontade numa shell Linux: instalar um pacote, editar um ficheiro e ler um log.
• Tem uma API key para um modelo alojado ou uma máquina que consiga executar um modelo local.

Essa é a lista completa. Não precisa de teoria de machine learning nem de ter treinado um modelo. O trabalho com agentes não envolve gradientes nem dados de treino. Uma placa gráfica só é relevante se decidir executar o modelo por sua conta. Essa é uma competência separada que pode adquirir mais tarde em alojar o Ollama numa VPS para alojar um LLM por sua conta.

O que as pessoas subestimam é a parte da shell. Os agentes falham por causa de permissões, caminhos, variáveis de ambiente e processos que terminam silenciosamente. Se um stack trace sobre PATH ou um modo de ficheiro o fizer fechar o terminal, passe primeiro um fim de semana a estudar os fundamentos de Linux. Isso vai poupar-lhe um mês mais tarde.

Etapa 1: o que é um agente e o que não é

Comece com uma chamada à API e sem um loop. Envie um prompt, mostre a resposta e observe as contagens de tokens na resposta. Agora entende a unidade de custo e a unidade de latência.

Depois, aprenda a usar ferramentas. Esta é a única ideia realmente nova em todo o campo. Descreva uma função para o modelo usando um nome, uma descrição e um esquema JSON (JavaScript Object Notation) para as respetivas entradas. O modelo não executa nada. Responde com um pedido estruturado: chamar run_command com estes argumentos. O seu código executa a função, envia o resultado de volta como uma mensagem e pergunta novamente ao modelo. O modelo é um planeador que lê texto e escreve texto. O seu código é o componente que executa as ações. O código do seu lado dessa interação recebe um nome quando começa a comparar arquiteturas: é o harness do agente, o ciclo, as ferramentas e as permissões associados a um modelo que não possui nada disso.

Um chatbot termina depois de uma resposta. Um agente repete essa troca até o modelo deixar de pedir ferramentas. Essa repetição é toda a diferença e também explica por que os modos de falha são diferentes. Um chatbot dá uma resposta errada uma vez. Um agente age com base numa resposta errada várias vezes antes de alguém perceber.

Etapa 2: escreva o loop uma vez, por conta própria

Não comece com um framework. Escreva cerca de trinta linhas de Python para definir a estrutura por si mesmo.

sudo apt update && sudo apt install -y python3-venv
python3 -m venv ~/agent
source ~/agent/bin/activate
pip install anthropic
export ANTHROPIC_API_KEY=your-key-here

import subprocess
import anthropic

client = anthropic.Anthropic()

tools = [{
    "name": "run_command",
    "description": "Run a read only shell command and return its output.",
    "input_schema": {
        "type": "object",
        "properties": {"command": {"type": "string"}},
        "required": ["command"],
    },
}]

messages = [{"role": "user", "content": "How much disk space is free here?"}]

while True:
    response = client.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        tools=tools,
        messages=messages,
    )
    if response.stop_reason != "tool_use":
        break
    messages.append({"role": "assistant", "content": response.content})
    results = []
    for block in response.content:
        if block.type == "tool_use":
            done = subprocess.run(
                block.input["command"], shell=True,
                capture_output=True, text=True, timeout=10,
            )
            results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": done.stdout or done.stderr,
            })
    messages.append({"role": "user", "content": results})

print(next(b.text for b in response.content if b.type == "text"))

Execute-o com python3 agent.py. Uma execução correta imprime um parágrafo com os seus sistemas de ficheiros e o espaço livre disponível, porque o modelo pediu df -h, o seu código executou-o e a segunda passagem transformou essa tabela numa frase. Se não imprimir nada, o loop terminou antes de receber um bloco de texto. Adicione print(response.stop_reason) dentro do loop e observe os valores a mudar.

Agora provoque uma falha de propósito. Apague a linha tool_use_id e leia o erro, porque a API rejeita um resultado de ferramenta sem um ID correspondente, e esse é o erro mais comum de quem está a começar. Faça uma pergunta que exija dois comandos e observe o loop executar-se duas vezes. Faça uma pergunta impossível e observe se ele desiste ou fica num loop infinito.

Um aviso sobre este exemplo. Ele envia diretamente a saída do modelo para uma shell com shell=True. Isto é aceitável numa máquina de teste que possa reinstalar, mas está errado em qualquer outro contexto. A Etapa 6 corrige esse problema. Os conceitos subjacentes ao loop são explicados com mais detalhe em como criar o seu próprio agente de IA num VPS.

Etapa 3: ferramentas que o agente ainda não tinha

A sua ferramenta run_command funciona, mas um agente real precisa de ferramentas que acedam a recursos externos ao sistema: um sistema de tickets, uma base de dados ou um repositório. Escrever um wrapper específico para cada serviço e para cada agente não é escalável.

O Model Context Protocol (MCP) é a solução adotada pela indústria. Um servidor MCP expõe um conjunto de ferramentas através de um transporte padrão, e qualquer agente compatível com MCP pode utilizá-lo sem código de integração específico. O servidor de referência do sistema de ficheiros é um único comando:

npx -y @modelcontextprotocol/server-filesystem /home/you/projects

Isto requer que o Node esteja instalado, e o argumento do diretório é o único caminho que o servidor pode aceder. Este é o modelo de segurança em termos simples: o servidor define o limite, não o modelo. Aponte um cliente para esse servidor e o agente passa a poder ler e escrever ficheiros sem que tenha de programar essas operações. A execução correta destes servidores, com uma conta de serviço e com as opções de transporte explicadas, é abordada em executar servidores MCP num VPS para agentes de programação com IA. Para um segundo servidor que aponta para dados reais, em vez de um diretório temporário, alojar o openGym, um monitor de treinos disponibiliza um servidor apenas de leitura. Assim, pode praticar perguntas sobre o seu histórico de treinos sem dar ao agente nada que ele possa alterar.

A lição desta etapa é que o verdadeiro trabalho está no desenho das ferramentas. Uma descrição vaga faz o modelo adivinhar. Uma ferramenta que devolve quarenta mil caracteres contamina a janela de contexto. Uma ferramenta que pode eliminar dados acabará por eliminá-los.

Etapa 4: memória, que é principalmente composta por ficheiros

Os principiantes recorrem aqui a uma base de dados vetorial. Não o faça, pelo menos ainda não.

Um agente não tem memória entre chamadas. A cada chamada, envia novamente toda a conversa. Por isso, uma sessão longa custa mais por interação do que uma sessão curta. Assim, a memória divide-se em dois problemas. O primeiro é saber o que cabe na janela de contexto neste momento. Pode geri-lo resumindo a conversa, removendo resultados antigos de ferramentas e colocando em cache o prefixo estável do prompt, para pagar apenas uma fração do preço desse conteúdo. O segundo é saber o que permanece depois de um reinício. Isso é armazenamento.

Para o segundo problema, um ficheiro Markdown simples que o agente possa ler e escrever é melhor do que uma base de dados vetorial na maioria dos primeiros projetos. Dê-lhe um ficheiro, indique o formato, diga-lhe para ler esse ficheiro antes de começar e para o atualizar quando aprender algo. Terá a maior parte do benefício e poderá abrir o ficheiro para ver aquilo em que o agente acredita. Recorra a embeddings e retrieval quando as notas deixarem de caber na janela de contexto, e não antes disso.

Etapa 5: o loop é o produto

Nesta fase, já consegue criar um agente que funciona enquanto o observa. A Etapa 5 consiste em fazê-lo funcionar quando não está a observá-lo.

Quatro perguntas determinam se é seguro deixar um agente autónomo sem supervisão. O que o aciona, para que não seja executado sem motivo. Dentro de que limite funciona, para que um erro tenha consequências reduzidas. Como o resultado é verificado, porque um agente que avalia o próprio trabalho dá sempre aprovação. Que orçamento o limita, em tokens ou em tempo de relógio. Conceber estes quatro elementos de forma deliberada é a disciplina descrita em engenharia de loops e o que essa definição abrange.

O exercício: pegue no agente da etapa 2, atribua-lhe uma tarefa que exija quatro ou cinco passos e adicione um limite rígido de iterações. Depois remova o limite e observe o efeito de um loop sem limites na sua fatura de tokens. Faça isso uma vez com um orçamento pequeno, para nunca o fazer por acidente com um orçamento grande.

Etapa 6: segurança, segredos e custos

Esta etapa não é opcional. Fica por último apenas porque não é possível sentir o risco antes de criar algo que funcione.

Execute o agente com um utilizador próprio sem privilégios. Nunca o execute como root nem com a sua própria conta. Assim, o impacto fica limitado a um diretório, e não à máquina inteira. Mantenha as credenciais fora do alcance do modelo. Qualquer conteúdo presente na janela de contexto pode ser devolvido através de uma chamada a uma ferramenta. A solução é usar tokens de curta duração, com escopo limitado, por trás de um helper, conforme descrito em mantenha os segredos fora dos seus agentes de IA. Defina um limite rígido para os custos. Um loop sem supervisão gera custos em cada iteração sem ninguém a monitorizá-lo. Os limites e o processamento em lote que mantêm esses custos sob controlo estão descritos em controlo de custos de agentes de IA numa VPS sempre ligada.

Se o agente for executado dentro de um harness, em vez de um script escrito por si, parte desta etapa será configuração e não código. os plugins do DeepSeek Harness que vale a pena instalar cobrem grande parte dos mesmos requisitos, com limites de orçamento, regras de permissões para ferramentas e verificação de injeções.

Os custos merecem um número concreto. Em julho de 2026, o Claude Opus 5 cobra $5 por milhão de tokens de entrada e $25 por milhão de tokens de saída. Um agente muito comunicativo que reenvia uma conversa cada vez maior pode processar algumas centenas de milhares de tokens numa única tarefa. O prompt caching e a utilização de um modelo menor para tarefas rotineiras alteram esses cálculos muito mais do que qualquer ajuste ao prompt.

A injeção de prompts também pertence a esta etapa. Se o agente ler uma página Web, um sistema de gestão de issues ou uma caixa de entrada, a pessoa que escreveu esse texto também está a escrever instruções para o agente. A pesquisa na Web é normalmente a ferramenta que abre esta porta primeiro. apontar um agente para a sua própria instância SearXNG mostra, lado a lado, a configuração e a superfície de injeção criada. A defesa não é um system prompt mais elaborado. É a fronteira de permissões. Um agente que não pode apagar um repositório não pode ser convencido a apagá-lo.

Que mapa deve seguir?

Escolha um currículo e conclua-o em vez de experimentar seis. O repositório Microsoft ai-agents-for-beginners é o recurso gratuito mais completo: um curso de dezoito lições que ultrapassou 70,000 estrelas em julho de 2026 e corresponde diretamente às etapas anteriores. As listas de repositórios de agentes em tendência são úteis para perceber o que existe, mas são muito menos úteis como programa de estudo, porque uma lista ordenada por estrelas é ordenada por popularidade, não por sequência pedagógica.

Quando quiser praticar num projeto real, um agente de programação é o melhor primeiro alvo: o feedback é imediato, as ferramentas são claras e é fácil desfazer os erros. Executar um agente de IA para programação num VPS apresenta um exemplo completo, do início ao fim. Se preferir estudar sistemas funcionais em vez de construir um do zero, a comparação em os melhores agentes de IA self-hosted mostra como vários projetos implementam o mesmo ciclo de formas diferentes.

Quanto tempo demora?

Para quem já programa, as etapas 1 e 2 ocupam uma noite. A etapa 3 ocupa um fim de semana, quase todo dedicado à descrição das ferramentas, e não ao protocolo. As etapas 4 e 5 exigem algumas semanas de utilização real, porque só se aprende o que o agente esquece observando-o esquecer. A etapa 6 nunca termina completamente, porque cada nova capacidade concedida reabre essa etapa.

Dois meses de noites dedicadas de forma consistente são suficientes para a maioria das pessoas criar um agente funcional, delimitado e útil. Quem demora um ano costuma ser quem continuou a ler em vez de construir.

FAQ

Preciso de conhecer machine learning para criar um agente de IA?

Não. Criar um agente consiste em chamar um modelo através de uma API e ligar os pedidos de ferramentas a funções reais. Isto é programação de aplicações comum. Não precisa de lidar com treino, gradientes ou conjuntos de dados. As competências que determinam se o agente funciona são o desenho dos esquemas das ferramentas, o tratamento de erros e as permissões do Linux. A teoria de machine learning só se torna relevante se avançar para o fine-tuning de um modelo. Esse é um trabalho diferente, com pré-requisitos diferentes.

Devo começar com um framework como LangChain ou CrewAI?

Escreva primeiro um loop sem framework e só depois adote um. Um framework substitui as trinta linhas da etapa 2 por um objeto de configuração. Isto é conveniente quando já sabe o que foi substituído, mas causa confusão antes disso. Quando o agente apresenta um comportamento incorreto, precisa de analisar diretamente a lista de mensagens e os resultados das ferramentas. Isto é muito mais difícil se nunca os viu. Depois de escrever um loop próprio, um framework poupa tempo em vez de ocultar o mecanismo.

Quanto custa aprender sobre agentes de IA?

Menos do que a maioria das pessoas espera, se definir limites. Uma chave de API alojada e um pequeno VPS são suficientes para estas seis etapas. O risco real não é o custo por hora. É um loop sem limite que cobra cada iteração enquanto dorme. Defina um limite rígido de gastos na conta da API logo no primeiro dia, adicione um limite de iterações a todos os loops que escrever e use um modelo mais barato para as etapas de rotina. Executar o modelo localmente elimina o custo dos tokens, mas exige hardware adequado.

Qual é a diferença entre um agente de IA e um chatbot?

Um chatbot responde uma vez. Um agente repete um ciclo: o modelo pede uma ferramenta, o seu código executa-a, o resultado é devolvido e o modelo decide o que fazer a seguir. Essa repetição permite que um agente conclua uma tarefa com várias etapas. É também por isso que os agentes precisam de limites que os chatbots não precisam. Uma resposta incorreta de um chatbot é um parágrafo errado. Uma resposta incorreta de um agente é um parágrafo errado, além de tudo o que o agente fez com base nele.