Como aprender agentes de IA do zero em seis etapas

O percurso em seis etapas

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

Um agente de IA é um loop em torno 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, o que as ferramentas podem aceder e como parar o loop quando algo corre mal. Se consegue explicar o loop a outra pessoa, aprendeu o essencial. Se apenas consegue enumerar frameworks, ainda não aprendeu.

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

O que realmente precisa antes da etapa 1

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

• Sabe ler e escrever Python ou TypeScript ao nível de um script de cinquenta linhas.
• Sente-se à vontade numa shell Linux: instalar um pacote, editar um ficheiro e ler um log.
• Tem uma chave de API 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. Nada no trabalho com agentes envolve gradientes ou dados de treino. Uma placa gráfica só é relevante se decidir executar o modelo localmente. Essa é uma competência separada que pode aprender mais tarde em alojar o Ollama numa VPS para alojar um LLM localmente.

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 faz fechar o terminal, dedique primeiro um fim de semana aos 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 loop. Envie um prompt, imprima a resposta e consulte 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 com um nome, uma descrição e um esquema JSON (JavaScript object notation) para as entradas. O modelo não executa nada. Responde com um pedido estruturado: chame 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 ações.

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. É também por isso que os modos de falha são diferentes. Um chatbot dá uma resposta errada uma vez. Um agente atua várias vezes com base numa resposta errada antes de alguém perceber o problema.

Fase 2: escreva o loop uma vez, por sua conta

Não comece por um framework. Escreva cerca de trinta linhas de Python para definir a estrutura do programa.

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, porque o modelo pediu df -h, o seu código executou o comando e a segunda passagem converteu 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 como os valores mudam.

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. Este é o erro mais comum entre principiantes. Faça uma pergunta que exija dois comandos e observe o loop ser executado duas vezes. Faça uma pergunta impossível e observe se o programa desiste ou fica num loop infinito.

Há um aviso sobre este exemplo. Ele envia diretamente a saída do modelo para uma shell com shell=True. Isso é aceitável numa máquina de testes que possa reconstruir, mas está errado em qualquer outro ambiente. A Fase 6 corrige esse problema. Os conceitos subjacentes ao loop são explicados com mais detalhe em 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 servidor: um sistema de tickets, uma base de dados, 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 que a indústria adotou. 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á-las sem integração personalizada. O servidor de sistema de ficheiros de referência é executado com um único comando:

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

Isto requer que o Node esteja instalado, e o argumento de diretório é o único caminho que o servidor poderá utilizar. Este é o modelo de segurança em termos simples: o servidor define o limite, não o modelo. Aponte um cliente para ele e o seu agente passa a ter capacidade de ler e escrever ficheiros sem que tenha de implementar essa funcionalidade. 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.

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 recursos acabará por eliminar recursos.

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. Reenvia toda a conversa a cada chamada. Por isso, uma sessão longa custa mais por turno do que uma sessão curta. A memória divide-se, portanto, em dois problemas. O primeiro é saber o que cabe na janela de contexto neste momento. Pode gerir isso criando resumos, removendo resultados antigos de ferramentas e colocando em cache o prefixo estável do seu prompt, para pagar apenas uma fração desse valor. O segundo é saber o que sobrevive a 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 em quase todos os primeiros projetos. Dê-lhe um ficheiro, indique o formato e diga-lhe para ler esse ficheiro antes de começar e atualizá-lo quando aprender algo. Obtém a maior parte do benefício e pode abrir o ficheiro para ver aquilo em que o agente acredita. Recorra a embeddings e recuperação quando as notas deixarem de caber na janela de contexto, e não antes.

Etapa 5: o loop é o produto

A esta altura, 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 não supervisionado a funcionar sozinho. O que o aciona, para que não seja executado sem motivo. Dentro de que limite opera, para que um erro permaneça pequeno. Como o resultado é verificado, porque um agente que corrige o próprio trabalho dá sempre o trabalho como correto. Que limite o impede de exceder o orçamento, em tokens ou em tempo real. Conceber estes quatro elementos de forma deliberada é a disciplina descrita em engenharia de loops e o que essa definição abrange.

O exercício: use o seu 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 limite na sua fatura de tokens. Faça isto uma vez com um orçamento pequeno, para nunca o fazer por acidente com um orçamento elevado.

Etapa 6: segurança, segredos e custos

Esta etapa não é opcional. Só aparece no fim porque não é possível sentir o risco antes de criar algo que funcione.

Execute o agente com o seu próprio utilizador sem privilégios. Nunca o execute como root nem com a sua própria conta. Assim, o impacto de uma intrusão fica limitado a um diretório, em vez de abranger toda a máquina. Mantenha as credenciais fora do alcance do modelo, porque 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, através de um helper, conforme descrito em manter os segredos fora dos seus agentes de IA. Defina um limite máximo rígido para os gastos, porque um loop sem supervisão cobra cada iteração sem ninguém a monitorizar. Os limites e o processamento em lotes que mantêm os custos sob controlo estão descritos em controlo dos custos de agentes de IA numa VPS sempre ligada.

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 conversacional que reenvie uma conversa cada vez maior pode processar algumas centenas de milhares de tokens numa única tarefa. O armazenamento em cache de prompts 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, quem escreveu esse texto também está a escrever instruções para o agente. A defesa não é um system prompt mais elaborado. É o limite de permissões, porque não é possível convencer um agente a eliminar um repositório que não consegue eliminar.

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 acima. As listas de repositórios de agentes em destaque são úteis para perceber o que existe, mas são muito menos úteis como currículo, porque uma lista ordenada por estrelas é ordenada por popularidade, não pela sequência de aprendizagem.

Quando quiser um projeto real para praticar, 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 sistema 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 isto demora?

Para quem já programa, as etapas 1 e 2 ocupam uma noite. A etapa 3 ocupa um fim de semana, passado sobretudo a descrever ferramentas, e não a trabalhar no protocolo. As etapas 4 e 5 exigem algumas semanas de utilização real, porque só aprende o que o seu agente esquece quando observa os esquecimentos. A etapa 6 nunca termina completamente, porque cada nova capacidade que concede ao agente volta a abrir esta questão.

Dois meses de trabalho consistente à noite permitem à maioria das pessoas criar um agente funcional, limitado e útil. Quem demora um ano costuma ser quem continuou a ler em vez de construir.

FAQ

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

Não. Criar um agente significa chamar um modelo através de uma API e ligar os pedidos das suas ferramentas a funções reais, o que corresponde a programação de aplicações normal. Nunca 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, que é uma tarefa diferente e tem pré-requisitos diferentes.

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

Escreva primeiro um ciclo sem abstrações e só depois adote um framework. Um framework substitui as 30 linhas da etapa 2 por um objeto de configuração. Isto é conveniente quando já sabe o que foi substituído, mas pode ser confuso antes disso. Quando o agente apresenta um comportamento inesperado, precisa de analisar diretamente a lista de mensagens e os resultados das ferramentas. Isso é muito mais difícil se nunca os tiver visto. Depois de escrever um ciclo 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 limitar os custos. Uma chave de API alojada e um pequeno VPS cobrem tudo nestas 6 etapas. O risco real não é o custo por hora. É um ciclo sem limite que cobra cada iteração enquanto dorme. Defina um limite máximo de gastos na sua conta da API logo no primeiro dia, adicione um limite de iterações a todos os ciclos 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 que permite ao agente concluir uma tarefa com várias etapas. É também por isso que os agentes precisam de limites que os chatbots não precisam. Uma resposta errada de um chatbot é um parágrafo incorreto. Uma resposta errada de um agente é um parágrafo incorreto e tudo o que o agente fez a partir dele.