Como aprender agentes de IA do zero em seis etapas

O caminho em seis etapas

Para aprender sobre agentes de IA desde o início, siga seis etapas em ordem: os conceitos, seu primeiro loop, ferramentas, memória, design do loop e segurança. Em cada etapa, você cria uma coisa com as próprias mãos. Avançar etapas é o motivo mais comum de as pessoas pararem, porque um framework oculta exatamente a parte que você precisava ver.

Um agente de IA é um loop em torno de um modelo de linguagem que pode chamar ferramentas. Essa frase resume todo o assunto. Todo o restante são detalhes sobre o que entra no loop, o que as ferramentas podem acessar e como interromper o loop quando algo dá errado. Se você consegue explicar o loop para outra pessoa, aprendeu o conceito. Se consegue apenas citar frameworks, ainda não aprendeu.

O plano abaixo pressupõe que você aprende criando. Leia uma etapa, crie o item pequeno, provoque uma falha de propósito e depois avance. Uma etapa que você apenas leu é uma etapa que ainda não concluiu.

O que você 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.

• Você consegue ler e escrever Python ou TypeScript no nível de um script de cinquenta linhas.
• Você se sente à vontade em um shell Linux: instalar um pacote, editar um arquivo e ler um log.
• Você tem uma chave de API para um modelo hospedado ou uma máquina capaz de executar um modelo local.

Essa é a lista completa. Você não precisa de conhecimentos de teoria de machine learning nem precisa ter treinado um modelo. Nada no trabalho com agentes envolve gradientes ou dados de treinamento. Uma placa gráfica só importa se você decidir executar o modelo por conta própria, o que é uma habilidade separada que você pode aprender mais tarde em hospedando o Ollama em um VPS para executar um LLM por conta própria.

O que as pessoas subestimam é a parte do 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 arquivo faz você fechar o terminal, passe primeiro um fim de semana estudando os fundamentos do Linux. Isso poupará um mês depois.

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

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

Em seguida, aprenda a usar ferramentas. Essa é a única ideia realmente nova em todo o campo. Você descreve uma função para o modelo usando um nome, uma descrição e um esquema JSON (JavaScript object notation) para as entradas. O modelo não executa nada. Ele responde com uma solicitação estruturada: chame run_command com estes argumentos. Seu código executa a função, envia a saída de volta como uma mensagem e consulta o modelo novamente. O modelo é um planejador que lê texto e escreve texto. Seu código é o componente que executa ações.

Um chatbot termina após uma resposta. Um agente repete essa troca até o modelo parar de solicitar ferramentas. Essa repetição é toda a diferença e também explica por que os modos de falha são diferentes. Um chatbot fornece uma resposta incorreta uma vez. Um agente executa ações com base em uma resposta incorreta várias vezes antes que alguém perceba.

Estágio 2: escreva o loop você mesmo, uma vez

Não comece com um framework. Escreva cerca de trinta linhas de Python para definir a estrutura por conta própria.

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 com python3 agent.py. Uma execução normal imprime um parágrafo que identifica seus sistemas de arquivos e o espaço livre, porque o modelo solicitou df -h, seu código executou o comando, e a segunda passagem transformou essa tabela em uma frase. Se nada for impresso, o loop terminou antes que um bloco de texto fosse recebido. Adicione print(response.stop_reason) dentro do loop e observe os valores mudarem.

Agora provoque uma falha de propósito. Exclua a linha tool_use_id e leia o erro, porque um resultado de ferramenta sem um id correspondente é rejeitado pela API, e esse é o erro mais comum de iniciantes. Faça uma pergunta que exija dois comandos e observe o loop executar duas vezes. Faça uma pergunta impossível e observe o loop desistir ou entrar em execução infinita.

Um aviso sobre este exemplo. Ele envia diretamente a saída do modelo para um shell usando shell=True, o que é aceitável em uma máquina de testes que você possa reconstruir, mas é inadequado em qualquer outro ambiente. O estágio 6 corrige isso. Os conceitos por trás do loop são explicados com mais detalhes em criando seu próprio agente de IA em um VPS.

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

Sua ferramenta run_command funciona, mas um agente real precisa de ferramentas que acessem recursos externos: um sistema de chamados, um banco 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 adotada pelo setor. Um servidor MCP expõe um conjunto de ferramentas por meio de um transporte padrão, e qualquer agente compatível com MCP pode usá-lo sem integração personalizada. O servidor de filesystem de referência é executado com um comando:

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

É necessário ter o Node instalado, e o argumento de diretório é o único caminho que o servidor poderá acessar. Este é o modelo de segurança em sua forma mais simples: o servidor define o limite, não o modelo. Aponte um cliente para ele, e seu agente terá recursos de leitura e gravação de arquivos que você não precisou implementar. A execução correta desses servidores, com uma conta de serviço e com as opções de transporte explicadas, é abordada em executando servidores MCP em um VPS para agentes de codificação com IA.

A lição desta etapa é que o projeto das ferramentas é o trabalho principal. Uma descrição vaga faz o modelo tentar adivinhar. Uma ferramenta que retorna quarenta mil caracteres contamina a janela de contexto. Uma ferramenta que pode excluir itens acabará excluindo itens.

Etapa 4: memória, que consiste principalmente em arquivos

Iniciantes recorrem a um banco de dados vetorial nesta etapa. Não faça isso, pelo menos ainda não.

Um agente não tem memória entre chamadas. Você reenvia toda a conversa a cada chamada. Por isso, uma sessão longa custa mais por turno do que uma sessão curta. Portanto, a memória se divide em dois problemas. O primeiro é o que cabe na janela de contexto neste momento. Você gerencia isso resumindo, removendo saídas antigas de ferramentas e armazenando em cache o prefixo estável do prompt, para pagar apenas uma fração do preço por ele. O segundo é o que sobrevive a uma reinicialização. Isso é armazenamento.

Para o segundo problema, um arquivo markdown simples que o agente possa ler e gravar é melhor do que um banco de dados vetorial em quase todos os primeiros projetos. Dê a ele um arquivo, informe o formato e instrua-o a ler esse arquivo antes de começar e atualizá-lo quando aprender algo. Você obtém a maior parte do benefício e pode abrir o arquivo para ver no que o agente acredita. Recorra a embeddings e recuperação quando as anotações deixarem de caber na janela de contexto, e não antes.

Estágio 5: o loop é o produto

A esta altura, você consegue criar um agente que funciona enquanto você o acompanha. O Estágio 5 consiste em fazê-lo funcionar quando você não estiver acompanhando.

Quatro perguntas determinam se é seguro deixar um agente não supervisionado. O que o aciona, para que ele não seja executado sem uma tarefa. Dentro de qual limite ele opera, para que um erro permaneça pequeno. Como o resultado é verificado, porque um agente que corrige a própria tarefa sempre a aprova. Qual orçamento o interrompe, em tokens ou em tempo de execução. Projetar esses quatro aspectos deliberadamente é a disciplina descrita em engenharia de loops e o que essa definição abrange.

O exercício: use o agente do estágio 2, atribua a ele uma tarefa que exija quatro ou cinco etapas e adicione um limite rígido de iterações. Depois remova o limite e observe o efeito de um loop sem limite na sua conta de tokens. Faça isso uma vez com um orçamento pequeno, para nunca fazer isso por acidente com um orçamento grande.

Etapa 6: segurança, segredos e custo

Esta etapa não é opcional. Ela fica por último apenas porque você não consegue perceber o risco antes de construir algo que funcione.

Execute o agent com seu próprio usuário sem privilégios. Nunca o execute como root nem como sua própria conta. Assim, o raio de impacto fica limitado a um diretório, e não à máquina inteira. Mantenha as credenciais fora do alcance do modelo. Qualquer informação presente na janela de contexto pode ser reproduzida por meio de uma chamada de ferramenta. A correção consiste em usar tokens de curta duração, com escopo limitado, por meio de um helper, conforme descrito em mantendo segredos fora dos seus agentes de IA. Defina um limite rígido para os gastos. Um loop sem supervisão gera cobranças a cada iteração, e os limites e o processamento em lotes que mantêm esse custo sob controle estão descritos em controle de custos de agentes de IA em um VPS sempre ativo.

O custo merece 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 agent comunicativo que reenvia uma conversa cada vez maior pode processar algumas centenas de milhares de tokens em uma única tarefa. O armazenamento em cache de prompts e o uso de um modelo menor para etapas rotineiras alteram esse cálculo muito mais do que qualquer ajuste no prompt.

A injeção de prompt também pertence a esta etapa. Se o agent lê uma página da web, um sistema de acompanhamento de issues ou uma caixa de entrada, quem escreveu esse texto também está escrevendo instruções para o agent. A defesa não é um system prompt mais inteligente. É o isolamento, porque um agent que não pode excluir um repositório não pode ser convencido a excluí-lo.

Qual mapa você deve seguir?

Escolha um currículo e conclua-o, em vez de experimentar seis. O repositório ai-agents-for-beginners da Microsoft é o material gratuito mais completo: um curso de dezoito lições que ultrapassou 70,000 estrelas em julho de 2026 e corresponde diretamente às etapas acima. Compilações de repositórios de agentes em alta são úteis para descobrir o que existe, mas são muito menos úteis como plano de estudos, porque uma lista ordenada por estrelas é ordenada por popularidade, não por sequência didática.

Quando quiser um projeto real para praticar, um agente de codificação é o melhor primeiro alvo: o feedback é imediato, as ferramentas são claras e é fácil desfazer os erros. Executando um agente de IA para codificação em um VPS apresenta todo o processo de ponta a ponta. Se preferir estudar sistemas funcionais em vez de criar um do zero, a comparação em os melhores agentes de IA auto-hospedados mostra como vários projetos implementam o mesmo ciclo de maneiras diferentes.

Quanto tempo isso leva?

Para quem já programa, as etapas 1 e 2 levam uma noite. A etapa 3 leva um fim de semana, com a maior parte do tempo dedicada às descrições das ferramentas, não ao protocolo. As etapas 4 e 5 levam algumas semanas de uso real, porque você só aprende o que seu agente esquece observando-o esquecer. A etapa 6 nunca termina completamente, pois cada nova capacidade concedida reabre essa etapa.

Dois meses de noites regulares levam a maioria das pessoas a um agente funcional, com limites definidos e útil. Quem leva um ano geralmente continua lendo em vez de construir.

FAQ

Preciso saber aprendizado de máquina para criar um agente de IA?

Não. Criar um agente significa chamar um modelo por meio de uma API e conectar as solicitações de ferramentas dele a funções reais. Isso é programação comum de aplicações. Você não trabalha diretamente com treinamento, gradientes ou conjuntos de dados. As habilidades que determinam se o agente funcionará são o projeto de schemas para ferramentas, o tratamento de erros e as permissões do Linux. A teoria de aprendizado de máquina só se torna relevante se você decidir fazer fine-tuning de um modelo. Isso é outro trabalho, com pré-requisitos diferentes.

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

Escreva primeiro um loop sem framework. Depois, adote um framework. Um framework substitui as trinta linhas do estágio 2 por um objeto de configuração. Isso é conveniente quando você sabe o que foi substituído, mas pode causar confusão antes disso. Quando o agente apresentar um comportamento incorreto, você precisará analisar diretamente a lista de mensagens e os resultados das ferramentas. Isso é muito mais difícil se você nunca os viu. Depois de criar um loop próprio, um framework economiza tempo em vez de ocultar o mecanismo.

Quanto custa aprender sobre agentes de IA?

Menos do que a maioria das pessoas espera, se você estabelecer limites. Uma chave de API hospedada e uma pequena VPS são suficientes para todas estas seis etapas. O risco real não é a tarifa por hora. É um loop sem limite que cobra por cada iteração enquanto você dorme. Defina um limite rígido de gastos na sua conta de API no primeiro dia. Adicione um limite de iterações a todos os loops que escrever. Use um modelo mais barato nas etapas rotineiras. 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 solicita uma ferramenta, seu código a executa, o resultado retorna e o modelo decide o que fazer em seguida. Essa repetição permite que um agente conclua uma tarefa com várias etapas. Ela também explica por que os agentes precisam de limites que os chatbots não precisam. Uma resposta incorreta de um chatbot é um parágrafo inadequado. Uma resposta incorreta de um agente é um parágrafo inadequado mais tudo o que ele fez a partir dele.