Tutorial prático de agentes de IA para iniciantes

O que é um agente de IA (e em que difere de um bot)?

O que é, afinal, um agente de IA? E porque não é apenas um chatbot?

Um agente de IA perceciona o ambiente, toma decisões e age por conta própria para atingir objetivos concretos. Um bot simples limita-se a seguir um guião rígido. Já o agente tem autonomia e capacidade de adaptação, o que o torna fundamentalmente diferente dos seus antecessores mais simples.

No essencial, um agente tem apenas quatro partes principais: * Modelo: O "cérebro" do agente, normalmente um LLM que lhe dá capacidade de compreender, raciocinar e planear tarefas complexas. * Perceção: São os sensores ou entradas que o agente usa para recolher informação do ambiente, seja texto de uma página web ou dados em bruto de uma API. * Memória: Este componente permite ao agente reter o contexto de ações e observações anteriores.

* Ferramentas: São as "mãos" do agente. São as funções ou APIs externas que ele usa para interagir de facto com o seu mundo e fazer as coisas acontecer.

Um agente hipotético de deteção de fraude poderia analisar padrões de transações, sinalizar anomalias e encaminhar os casos incertos para um revisor. O exemplo ilustra um ciclo de agente, sem apresentar uma implementação fictícia num banco como experiência da AIGROW.

Compreender os diferentes tipos de agentes de IA

Nem todos os agentes são iguais.

São classificados numa hierarquia clara, consoante a sua inteligência, tornando-se mais sofisticados à medida que aprendem a modelar o mundo e a perseguir objetivos. Compreender estes tipos é essencial, porque evita que complique demasiado uma tarefa simples ou que subdimensione uma tarefa complexa.

Estas são as cinco principais categorias de agentes de IA: 1. Agentes reativos simples: O tipo mais básico. Funcionam com regras simples do tipo "se...

então...", acionadas pelo que veem naquele momento, sem memória do passado. O termóstato é um exemplo perfeito: se a temperatura descer abaixo de X, liga o aquecimento. 2.

Agentes reativos baseados em modelo: Constroem e mantêm um modelo interno do mundo. Este mapa interno permite-lhes lidar com ambientes parcialmente observáveis, lembrando como as coisas mudam ao longo do tempo. Um aspirador robô que memoriza a disposição da sua sala é um agente baseado em modelo.

3. Agentes baseados em objetivos: Um grande salto. Estes agentes não se limitam a reagir: têm objetivos explícitos e planeiam sequências de ações para chegar a um estado futuro desejado.

Pense num GPS que calcula o melhor percurso até ao seu destino. É um agente baseado em objetivos em ação. 4.

Agentes baseados em utilidade: Quando vários caminhos levam ao objetivo, estes agentes escolhem o de maior "utilidade" ou retorno. Ponderam vantagens e desvantagens para fazer a melhor escolha, o que é ideal em decisões complexas. Um agente de negociação de ações que executa operações para maximizar o lucro é um exemplo clássico de agente baseado em utilidade.

5. Agentes de aprendizagem: Os mais avançados. Estes agentes melhoram de facto o seu desempenho ao longo do tempo, analisando o feedback de ações passadas e modificando os seus componentes internos para decidirem melhor no futuro.

Quase todos os agentes de IA generativa modernos incorporam alguma capacidade de aprendizagem.

Neste tutorial, o foco está em criar agentes que combinam elementos baseados em modelo, em objetivos e de aprendizagem para realizar trabalho útil.

Passo 1: defina a missão do seu agente com o framework PEAS

Pare. Antes de escrever uma única linha de código, precisa de um plano.

Os projetos de agentes precisam de um plano rigoroso antes da implementação. O framework PEAS, que abrange medidas de desempenho, ambiente, atuadores e sensores, é uma forma de definir a tarefa e as restrições de funcionamento antes de escolher as ferramentas.

O PEAS divide a missão em quatro componentes claros: * P - Medida de desempenho (Performance): Como define uma vitória? Tem de ser um número. "Melhorar a satisfação do cliente" é uma métrica inútil.

"Reduzir em 30% o tempo médio de resposta aos tickets" é boa, porque é específica, mensurável e ligada a um objetivo de negócio. * E - Ambiente (Environment): Onde vive o agente? Inclui o software e o hardware em que corre, os dados a que pode aceder e as regras que tem de cumprir.

Num agente de suporte, pode ser uma plataforma de helpdesk, uma base de conhecimento e APIs internas da empresa. * A - Atuadores (Actuators): Como age o agente? São as ferramentas que usa para afetar o ambiente.

As ações podem ser enviar um email, atualizar um registo numa base de dados ou chamar uma API externa. * S - Sensores (Sensors): Como vê o agente? Os sensores são as entradas do agente.

Pode ser um email recebido, uma mensagem de chat de um utilizador ou dados recentes de uma ferramenta de monitorização.

Vamos tornar isto concreto com um agente que reserva salas de reuniões. * Desempenho: Reservar uma sala que cumpra todos os critérios (horário, capacidade, equipamento audiovisual) em menos de 60 segundos e minimizar conflitos de reservas. * Ambiente: O Google Calendar da empresa, uma API de reserva de salas e uma interface do Slack para os utilizadores.

* Atuadores: A API do Calendar (para criar eventos) e a API do Slack (para enviar confirmações). * Sensores: Mensagens dos utilizadores no Slack e a API do Calendar (para verificar os horários livres).

Usar o framework PEAS dá-lhe um âmbito claro e um objetivo mensurável. Isto não é opcional: é o primeiro passo crítico em qualquer projeto sério.

Passo 2: construa o núcleo do seu agente com Python e um framework

Com o plano definido, é hora de construir.

Isto não é um exercício teórico: vamos escrever código para criar o seu primeiro agente. Usaremos Python, o rei indiscutível do desenvolvimento de IA, e um framework de agentes que preferimos para a maioria dos projetos de automação de fluxos de trabalho: o CrewAI.

Porquê o CrewAI?

É uma ótima escolha para iniciantes porque a sua estrutura é extremamente intuitiva. Todo o framework assenta no conceito de uma "crew" (equipa) de agentes em que cada um tem uma função específica e todos colaboram para atingir um objetivo, o que mantém o projeto organizado desde o início. A nossa missão é criar um agente de pesquisa simples.

O utilizador indica um tema, e a nossa equipa pesquisa-o e escreve um relatório curto. E não subestime esta abordagem: dados recentes mostram que os agentes de programação já são usados por 85% dos programadores e escrevem 46% do código dos seus utilizadores. O potencial está aí para ser aproveitado.

Configurar o projeto 1. Instale as bibliotecas: Vai precisar de crewai, crewai-tools e de uma biblioteca para o LLM escolhido. Vamos usar a OpenAI.

pip install crewai crewai-tools 'crewai[openai]'

1. Defina a chave de API: Crie um ficheiro chamado .env na pasta do projeto e adicione a sua chave de API da OpenAI.

OPENAI_API_KEY="your-api-key-here"

Escrever o código Agora, crie um ficheiro Python (por exemplo, main.py). O agente completo pode ser construído com menos de 40 linhas de código.

import os
from crewai import Agent, Task, Crew
from crewai_tools import SerperDevTool


# Load environment variables
from dotenv import load_dotenv
load_dotenv()


# Set the model you want to use
os.environ["OPENAI_MODEL_NAME"] = "gpt-6.1-terra"


# 1. Define Tools
# We'll use a search tool for our researcher
search_tool = SerperDevTool()


# 2. Create Agents
# First, a researcher agent
researcher = Agent(
 role='Senior Research Analyst',
 goal='Uncover groundbreaking technologies and trends',
 backstory='You are a master of sniffing out emerging tech and analyzing its impact.',
 verbose=True,
 tools=[search_tool]
)


# Second, a writer agent
writer = Agent(
 role='Tech Content Strategist',
 goal='Craft compelling content on tech advancements',
 backstory='You turn complex technical concepts into engaging, easy-to-understand narratives.',
 verbose=True
)


# 3. Define Tasks
# A research task for the researcher agent
research_task = Task(
 description='Identify the top 3 most exciting AI trends in 2026.',
 expected_output='A bullet-point list of the top 3 trends with a brief explanation for each.',
 agent=researcher
)


# A writing task for the writer agent
write_task = Task(
 description='Compose an insightful blog post about the top 3 AI trends identified.',
 expected_output='A well-structured blog post of about 4 paragraphs.',
 agent=writer
)


# 4. Assemble the Crew
# Create the crew with the agents and tasks
tech_crew = Crew(
 agents=[researcher, writer],
 tasks=[research_task, write_task],
 verbose=2 # Verbose output shows the agent's thought process
)


# 5. Kick off the work!
result = tech_crew.kickoff()


print("\n\n########################")
print("## Here is the result:")
print("########################\n")
print(result)

Este script simples cria uma equipa de dois agentes que trabalham em conjunto. O researcher encontra informação e o writer usa essa informação para criar um relatório final. Executá-lo dá um exemplo claro dos fundamentos da criação de agentes e prepara-o para projetos mais complexos.

Passo 3: avalie, proteja e implemente o seu agente de IA (AgentOps)

Um agente no seu portátil é um protótipo. Nada mais.

Para o levar para produção, onde gera valor real, precisa de um processo disciplinado. Chamamos-lhe AgentOps. Este ciclo de vida abrange três etapas inegociáveis: avaliação, segurança e implementação.

Os iniciantes quase sempre saltam estes passos, e é por isso que os seus projetos nunca têm impacto real.

1. Avaliação Como prova que o seu agente funciona? É preciso medir o desempenho de forma sistemática.

• Defina métricas de sucesso: Comece por estabelecer indicadores-chave de desempenho (KPIs) claros, ligados ao seu framework PEAS. O objetivo é reduzir o tempo de resolução de tickets, aumentar as conversões de vendas ou concluir um fluxo de trabalho específico? Se não consegue medir, não consegue melhorar.
• Crie um conjunto de teste: Construa um "golden set" com entradas variadas e difíceis. Deve incluir casos comuns, casos-limite estranhos e até exemplos adversariais concebidos para pôr o agente à prova.
• Automatize a avaliação: Execute o seu agente sobre este conjunto de teste automaticamente após cada alteração. Ao comparar os resultados com uma referência sabidamente correta, deteta regressões de imediato e evita que o agente piore lentamente com o tempo.

2. Salvaguardas de segurança essenciais Um agente autónomo com acesso a ferramentas é uma arma carregada.

Um agente comprometido pode apagar bases de dados, esvaziar contas bancárias ou divulgar dados sensíveis. É preciso protegê-lo.

• Princípio do menor privilégio: Conceda ao agente o mínimo absoluto de permissões necessárias para fazer o seu trabalho. Nada mais. Se só precisa de ler uma base de dados, nunca lhe dê acesso de escrita.
• Humano no circuito (human-in-the-loop): Para qualquer ação de grande impacto (como processar um reembolso superior a $100 ou eliminar um utilizador), exija aprovação humana. O agente pode fazer todo o trabalho preparatório e depois colocar a ação final em fila para uma pessoa clicar em "confirmar".
• Sanitização de entradas e saídas: Trate cada entrada como hostil. Tem de sanitizar os dados recebidos para se defender de prompt injection, em que um atacante engana o agente para seguir as suas instruções maliciosas em vez das suas.

3. Implementação em produção Implementar um agente não é só executar python main.py num servidor.

• Use um ambiente cloud: Plataformas como AWS, Google Cloud ou Azure oferecem a infraestrutura escalável de que precisa para crescer.
• Coloque a aplicação num contentor: Empacote o agente e todas as suas dependências num contentor Docker. Fica portátil e funciona da mesma forma em qualquer lado.
• Configure registos e monitorização: Registe cada decisão, cada chamada a ferramentas e cada resultado. Sem ferramentas de observabilidade para acompanhar o desempenho, o custo e as taxas de erro em tempo real, está a voar às cegas.

Um ciclo de vida AgentOps estruturado não é apenas uma boa prática. É o que separa um projeto de passatempo de um sistema de nível de produção em que pode confiar.

Porque falha a maioria dos projetos de agentes de iniciantes (e como garantir que o seu tem sucesso)

Eis a verdade dura. A maioria dos projetos de agentes de iniciantes falha.

Muitos projetos de agentes ficam parados porque o fluxo de trabalho, as permissões, os casos de avaliação e o responsável operacional nunca foram definidos. A escolha do modelo não resolve a falta de âmbito ou de um teste de aceitação.

Um âmbito de projeto útil indica o fluxo de trabalho, a medida de sucesso, as ações permitidas, o caminho de escalonamento e o orçamento de falhas. Um objetivo como resolver pedidos de estado de encomendas dentro de um nível de serviço definido é testável; um objetivo como construir um agente de apoio ao cliente é demasiado amplo.

É uma restrição de conceção crítica, não algo a pensar no fim.

1. Sem framework de avaliação: Como sabe se as suas alterações ajudam ou prejudicam? Sem uma suite de testes padronizada (um "golden set"), está apenas a adivinhar. Sempre que ajusta um prompt ou uma ferramenta, arrisca introduzir falhas silenciosas que só notará semanas depois. Um processo de avaliação rigoroso e automatizado é absolutamente inegociável em qualquer implementação séria.
2. Projetar para autonomia total cedo demais: Muitos iniciantes têm uma fantasia perigosa de um agente totalmente autónomo que dispensa supervisão humana. É uma receita para o desastre. Um lançamento mais seguro começa com o agente a preparar o trabalho para aprovação humana. Alargue a autonomia só quando testes representativos e a monitorização em produção sustentarem a mudança. Este desenho com human-in-the-loop gera confiança e, mais importante, oferece uma rede de segurança crítica.

O sucesso na construção de agentes não passa por encontrar o prompt perfeito. Passa por engenharia disciplinada, objetivos claros e uma abordagem realista à automação.

Como escolher o framework de agentes de IA certo?

O framework que escolher importa. E muito.

Determina a sua velocidade de desenvolvimento, o poder do agente e quão penosa será a manutenção do projeto. Com tantas opções, a escolha pode parecer paralisante. Por isso, vamos cortar o ruído e comparar os três grandes: LangChain, AutoGen e CrewAI.

A escolha do framework depende do fluxo de trabalho e deve ser testada com um protótipo representativo. Compare gestão de estado, integração de ferramentas, observabilidade, modelo de implementação, manutenção e licenciamento com os mesmos testes de aceitação antes de se comprometer.

Qual deve um iniciante escolher? Para quem segue este tutorial, a nossa recomendação é clara: comece com o CrewAI.

A sua abstração baseada em papéis é simples de entender e permite construir um sistema multiagente poderoso com muito pouco código. Mais importante, impõe uma estrutura limpa ao projeto, ajudando a evitar erros de conceção comuns.

Quando tiver mais experiência, pode passar para o LangChain (em particular o LangGraph) para um controlo mais granular sobre fluxos de execução complexos, ou explorar o AutoGen para investigação avançada. Mas para ter um agente real a funcionar de forma rápida e eficaz, o CrewAI é o vencedor óbvio.