As ferramentas que usamos para construir agentes de IA

Há centenas de ferramentas para construir agentes de IA, e todas as semanas aparecem mais. Para uma empresa que quer um agente a funcionar, e não um projecto de investigação, a escolha das ferramentas decide três coisas: quanto tempo demora a chegar a produção, quanto custa manter e quão fácil é mudar de fornecedor amanhã.

Neste artigo abrimos a caixa e mostramos o conjunto de ferramentas com que trabalhamos, camada a camada, e porquê.

1. O modelo: Claude

O "cérebro" do agente é um modelo de linguagem. Trabalhamos sobretudo com os modelos Claude, da Anthropic, por três razões práticas: são fortes a usar ferramentas e a seguir instruções em tarefas de vários passos, têm uma janela de contexto grande (cabem documentos inteiros de uma vez) e a família tem modelos para cada necessidade.

• Claude Haiku 4.5 para tarefas simples e de grande volume: classificar, extrair campos, triagem
• Claude Sonnet 5.5 para a maioria dos agentes do dia-a-dia
• Claude Opus 5.5 quando a tarefa exige mais raciocínio e mais passos

Num mesmo projecto é comum usar dois: um mais capaz a coordenar e um mais barato nos passos repetitivos, a lógica dos subagentes. Os custos de cada um estão no artigo sobre quanto custa um agente de IA.

2. O código: AI SDK da Vercel e TypeScript

Para ligar o modelo à aplicação usamos o AI SDK, uma biblioteca aberta da Vercel para TypeScript. Trata do diálogo com o modelo, das ferramentas que o agente pode chamar, das respostas em tempo real e dos dados estruturados, e funciona com vários fornecedores de modelos. Para chamadas mais específicas do Claude, usamos também o SDK oficial da Anthropic.

A vantagem de escrever o agente em código, e não apenas numa plataforma visual, é o controlo: cada ferramenta tem as permissões exactas que definimos, cada passo fica registado e o agente vive dentro da aplicação da empresa, não numa conta de terceiros.

3. O acesso aos modelos: um gateway

Entre a aplicação e os fornecedores de modelos colocamos um gateway, como o AI Gateway da Vercel. Com uma única chave dá acesso a modelos de vários fornecedores, permite definir um modelo de reserva se o principal falhar, mostra o consumo de cada pedido e ajuda a pôr limites de gasto. Mudar de modelo passa a ser uma linha de configuração, não um projecto.

4. As ligações aos sistemas: MCP

Um agente só é útil se chegar aos dados da empresa. O MCP (Model Context Protocol) é a norma aberta para ligar agentes a ferramentas e fontes de dados: email, calendário, gestor de clientes, documentos. Foi criado pela Anthropic e entregue em Dezembro de 2025 a uma fundação da Linux Foundation, criada com a OpenAI e a Block e apoiada pela Google, pela Microsoft e pela AWS, o que lhe dá futuro independente de um único fornecedor.

Quando uma ligação MCP já existe e é de confiança, usamo-la. Quando não existe, ou quando precisamos de controlar ao detalhe o que o agente pode fazer, escrevemos a ferramenta nós, com as permissões mínimas. Explicamos porquê no artigo sobre segurança em agentes de IA.

5. Os dados: Supabase

O agente precisa de um sítio para guardar pedidos, resultados, registos e o conhecimento da empresa. Usamos o Supabase, uma plataforma sobre Postgres, uma das bases de dados abertas mais usadas no mundo, com:

• Base de dados para pedidos, estados e o registo de cada acção do agente
• Pesquisa por significado (com a extensão pgvector), para o agente encontrar a resposta certa na documentação da empresa mesmo quando a pergunta usa outras palavras
• Armazenamento de ficheiros para facturas, PDFs e anexos
• Regras de acesso por linha, para cada parte do sistema ver apenas os dados que lhe dizem respeito

É a mesma base sobre a qual corre o site e o backoffice da MarcaWeb.

6. A aplicação e o alojamento: Next.js e Vercel

A interface onde a equipa vê e aprova o trabalho do agente (a caixa de pedidos, o painel, os botões de aprovar e rejeitar) é feita em Next.js e alojada na Vercel, ou num servidor próprio quando o cliente o prefere. Para tarefas longas, que têm de sobreviver a falhas e retomar onde ficaram, usamos fluxos duráveis em vez de um pedido que fica à espera.

7. As automações simples: n8n e companhia

Nem tudo precisa de um agente. Para os passos com regras fixas, como mover um ficheiro, criar um contacto ou enviar uma notificação, uma plataforma de automação como o n8n ou o Make é mais rápida de montar e mais barata de manter. Muitos dos nossos projectos são híbridos: automação no esqueleto e agente só no passo que exige julgamento.

E as bibliotecas de orquestração como o LangChain? Conhecemo-las e usamo-las quando o projecto as pede, mas para a maioria dos agentes de uma PME o AI SDK chega e dá menos camadas para manter.

8. O que não se vê: registo, avaliação e limites

• Registo de cada passo: que pedido chegou, que ferramentas o agente usou e que resultado deu
• Avaliação: um conjunto de casos reais com a resposta certa, que corremos sempre que mudamos instruções ou modelo, para saber se melhorou ou piorou
• Limites de gasto e alertas no fornecedor do modelo e no gateway
• Aprovação humana em tudo o que tem impacto, desenhada na interface desde o primeiro dia

Como escolhemos, em três regras

1. Normas abertas primeiro. MCP, Postgres e TypeScript não prendem o cliente a ninguém.
2. O mais simples que resolve. Automação onde chega, agente onde é preciso, o modelo mais barato que mantém a qualidade.
3. O cliente fica com tudo. Código, dados e contas em nome da empresa, para poder mudar de fornecedor, incluindo de nós.

Em resumo

Um agente de IA bem construído é sobretudo boa engenharia à volta de um modelo: código com permissões claras, ligações por normas abertas, dados numa base sólida, uma interface para a equipa aprovar e registo de tudo. As ferramentas mudam depressa; estas regras não.

Quer saber que ferramentas fariam sentido no seu caso? Peça uma análise gratuita e conte-nos que sistemas usa hoje. Respondemos em 48 horas.