Como aprender agentes de IA em 2026: tutorial prático com tools, MCP e RAG

Function calling, MCP, memória, RAG e frameworks aparecem juntos quando se estuda agentes de IA, mas cada peça resolve um problema diferente.

Vamos montar um assistente de suporte que consulta pedidos. A cada etapa, você verá o que funciona e quando vale adicionar outra tecnologia.

Comece com uma tarefa que tenha uma resposta fácil de conferir: informar o status de um pedido. O modelo pode entender a pergunta e escrever uma resposta, mas não conhece os pedidos da empresa. Para isso, ele precisa receber dados da aplicação.

Antes de conectar qualquer ferramenta, escreva os limites do assistente. Neste exercício, ele só consulta pedidos fictícios, não altera dados e deve avisar quando o pedido não existe. Esses limites deixam claro o que será considerado uma resposta correta.

• Entrada: “Onde está o pedido 8241?”
• Dado necessário: status do pedido 8241.
• Saída esperada: resposta baseada no registro, sem inventar uma previsão.
• Quando não houver registro: informar que não encontrou o pedido.

Essa separação ajuda a definir o que testar: quais dados o assistente pode consultar e qual resposta conta como correta.

O modelo entende o pedido. A aplicação decide o que pode ser consultado.

Vamos ligar a função ao modelo pela API de Responses. O exemplo usa pedidos fictícios para mostrar o ciclo completo: o modelo solicita uma consulta, a aplicação executa a função e devolve o resultado para o modelo responder. Primeiro, instale o SDK oficial e configure uma chave de API no ambiente.

npm install openai

Depois de salvar o exemplo como agente.mjs, configure a chave no PowerShell e execute o arquivo. O SDK lê OPENAI_API_KEY do ambiente. Não coloque uma chave real no código nem a envie para um repositório. O modelo gpt-6-astra precisa estar disponível para sua conta; se não estiver, troque-o por um modelo compatível com function calling.

$env:OPENAI_API_KEY = 'sua-chave'
node agente.mjs

import OpenAI from 'openai';

const openai = new OpenAI();
const model = 'gpt-6-astra';

// Dados fictícios. Em produção, consulte a API ou o banco da aplicação.
const pedidos = [
  { id: '8241', status: 'em transporte' },
  { id: '8242', status: 'separado' },
];

function buscarPedido(id) {
  return pedidos.find((pedido) => pedido.id === id) ?? null;
}

const tools = [{
  type: 'function',
  name: 'buscar_pedido',
  description: 'Consulta o status de um pedido pelo identificador.',
  parameters: {
    type: 'object',
    properties: { id: { type: 'string' } },
    required: ['id'],
    additionalProperties: false,
  },
  strict: true,
}];

const instructions =
  'Responda sobre pedidos usando apenas o resultado da ferramenta. ' +
  'Se o pedido não existir, diga que não foi encontrado. Não invente previsões.';

let response = await openai.responses.create({
  model,
  instructions,
  tools,
  input: 'Onde está o pedido 8241?',
});

// Limita as rodadas para evitar um ciclo de ferramentas sem fim.
for (let rodada = 0; rodada < 3; rodada += 1) {
  const chamadas = response.output.filter(
    (item) => item.type === 'function_call',
  );

  if (chamadas.length === 0) break;

  const resultados = chamadas.map((chamada) => {
    if (chamada.name !== 'buscar_pedido') {
      return {
        type: 'function_call_output',
        call_id: chamada.call_id,
        output: JSON.stringify({ erro: 'Ferramenta desconhecida.' }),
      };
    }

    const { id } = JSON.parse(chamada.arguments);
    const pedido = buscarPedido(id);

    return {
      type: 'function_call_output',
      call_id: chamada.call_id,
      output: JSON.stringify(pedido ?? { erro: 'Pedido não encontrado.' }),
    };
  });

  response = await openai.responses.create({
    model,
    instructions,
    tools,
    previous_response_id: response.id,
    input: resultados,
  });
}

if (response.output.some((item) => item.type === 'function_call')) {
  throw new Error('O agente atingiu o limite de chamadas de ferramenta.');
}

console.log(response.output_text);

Execute o arquivo depois de configurar a chave. A definição da ferramenta explica ao modelo seu nome, sua finalidade e o formato dos argumentos. A propriedade strict e o esquema JSON ajudam a restringir os argumentos ao formato esperado.

Repare no caminho: o modelo não executa a função por conta própria nem recebe acesso direto ao banco. A aplicação interpreta a solicitação, verifica permissões, executa buscarPedido e envia um function_call_output. Com esse resultado, o modelo produz a resposta final. O limite de rodadas também evita uma sequência de chamadas sem controle.

O modelo pede uma ação. A aplicação valida e executa.

O array de pedidos é uma simulação para rodar o exemplo sem banco de dados. Ao trocar pela integração real, valide a identidade e a autorização da pessoa dentro da aplicação antes de devolver qualquer dado. Comece com leitura; ações que alteram pedidos exigem controles adicionais.

Não avalie o agente só por uma conversa que parece ter dado certo. Guarde perguntas conhecidas e confira o comportamento esperado sempre que mudar as instruções, o modelo ou a ferramenta.

• Pedido existente: consultar o status correto.
• Pedido inexistente: dizer que não encontrou, sem inventar um resultado.
• Pedido de outra pessoa: respeitar a regra de acesso da aplicação.
• Pergunta que não depende de pedido: responder sem chamar a ferramenta.

Esses casos mostram se a ferramenta é chamada quando precisa, se os dados retornados são usados corretamente e se o sistema recusa uma consulta sem autorização. A avaliação começa pequena, mas deve começar antes de aumentar a arquitetura.

Se esse assistente é o único aplicativo que consulta pedidos e você tem uma ou duas funções, chamar as funções da própria aplicação é uma solução direta. MCP não é uma etapa obrigatória para chamar uma ferramenta.

O valor de MCP aparece quando você quer disponibilizar ferramentas ou dados por uma interface padronizada para mais de um aplicativo compatível. Sem um padrão compartilhado, cada cliente pode precisar de uma integração própria com o mesmo serviço. Com MCP, você pode criar um servidor que expõe essas capacidades e conectar clientes que entendem o protocolo.

Na arquitetura, o host é o aplicativo de IA. Dentro dele, um cliente MCP mantém a conexão com um servidor MCP, que fornece recursos. O servidor pode expor ferramentas para ações, resources para dados e prompts reutilizáveis. Assim, por exemplo, uma ferramenta de consulta de pedidos pode ser descoberta e chamada por diferentes clientes compatíveis, respeitando as configurações e permissões de cada um.

SEM UMA INTERFACE COMPARTILHADA
Aplicativo A -> integração feita para A -> serviço de pedidos
IDE B        -> integração feita para B -> serviço de pedidos
Chat C       -> integração feita para C -> serviço de pedidos

COM MCP
Aplicativo A [host + cliente MCP] -> servidor MCP de pedidos -> API
IDE B        [host + cliente MCP] -> servidor MCP de pedidos -> API
Chat C       [host + cliente MCP] -> servidor MCP de pedidos -> API

O reaproveitamento depende de suporte ao protocolo, configuração, autenticação e permissões em cada cliente.

MCP poupa integrações repetidas quando clientes compatíveis usam as mesmas ferramentas.

Function calling deixa o modelo solicitar uma função à aplicação. MCP padroniza como clientes e servidores compartilham ferramentas e contexto. Uma aplicação pode usar os dois.

Regra prática: se você está aprendendo com um protótipo de uma aplicação, comece com uma função direta. Se precisa oferecer a mesma integração a vários clientes que suportam MCP, investigue um servidor MCP. Em ações que alteram dados, restrinja permissões e peça confirmação quando necessário.

Depois que a consulta funciona, adicione uma capacidade apenas se o exemplo mostrar uma necessidade concreta. MCP, memória, RAG e frameworks não são nomes diferentes para o mesmo recurso.

• Estado da conversa: mantém o contexto necessário entre mensagens da mesma conversa.
• Memória: guarda informações selecionadas para uso em outra sessão, quando a aplicação realmente precisa se lembrar delas.
• RAG: busca trechos relevantes em uma base de documentos para responder com apoio nesses materiais. É útil quando a resposta depende de conhecimento que não deve ser colocado inteiro em cada solicitação.
• Framework: organiza partes recorrentes do agente, como chamadas de ferramenta, estado, repetição, transferência de tarefa e observabilidade.
• Multiagente: divide trabalho entre agentes diferentes. Só vale quando a separação melhora o resultado o bastante para compensar mais coordenação e pontos de falha.

MCP pode fornecer ferramentas e dados, mas não cria sozinho memória durável nem uma busca RAG. RAG pode ser útil para consultar manuais de suporte; memória pode ajudar a continuar uma conversa; um framework pode ajudar quando o fluxo manual ficou difícil de controlar.

• Faça o modelo responder a uma tarefa delimitada.
• Crie uma função de consulta com dados fictícios e conecte-a usando function calling.
• Teste pedidos válidos, inexistentes, sem permissão e perguntas que não precisam da função.
• Conecte essa capacidade por MCP quando precisar compartilhá-la com outros clientes compatíveis.
• Adicione estado, memória ou RAG somente quando o fluxo de suporte demonstrar essa necessidade.
• Escolha um framework quando controlar o ciclo, as falhas e o estado manualmente ficar trabalhoso.

O valor de aprender nessa ordem é prático: cada tecnologia entra para resolver uma dificuldade que você já encontrou. MCP facilita reaproveitar integrações entre aplicações compatíveis. Ele não é obrigatório para todo agente, mas pode economizar trabalho quando ferramentas e contexto precisam estar disponíveis em mais de um cliente.