Desenvolvimento de Software Apoiado por IA — 2026.4

Aula 2
Agentes

👨‍🏫 Prof. Gustavo Pinto 🏛️ UFPA 📅 3 de setembro de 2026 🕐 20h

O que é um agente

Um agente recebe um objetivo, decide sozinho quais ações tomar, executa essas ações com ferramentas, e repete até concluir.

O mordomo Alfred se apresenta no portao da mansao

Alfred raciocina e planeja diante da caixa de ferramentas

Ninguém disse a ele qual botão apertar. O pedido é o objetivo, e não a instrução. huggingface.co/learn/agents-course

LLMs e agentes

Os componentes de um agente

Diagrama do agente ligado a memoria, ferramentas, planejamento e acao

Memória, tools e planning. Três peças, e é a combinação delas que separa um agente de uma chamada de API.

Memória

In context, curto prazo

Informação no prompt atual. Rápida e temporária, desaparece ao fim da requisição.

Episódica

Histórico de conversas e interações anteriores. Permite lembrar de usuários e preferências.

Externa, longo prazo

Banco vetorial ou SQL. Persistente entre sessões, recuperada por busca semântica.

Quando o agente esquece o que combinaram há dez minutos, o problema quase sempre está aqui.

growthjockey.com/blogs/agentic-ai-memory

Tools

Extensão de capacidades. As tools executam tarefas como busca na web, consulta ao banco de dados e execução de código
Execução dinâmica. O agente decide quando e como usar cada ferramenta

Sem tools, o LLM apenas fala sobre o mundo. Com tools, o LLM age no mundo.

Planning

Decomposição em submetas. Quebrar o objetivo em passos que cabem em uma ação
Raciocínio em cadeia. Escrever o raciocínio antes de agir, e usar esse texto como parte do contexto
Reflexão e autocrítica. Olhar o resultado da própria ação e decidir se refaz

O planejamento não é um módulo separado. Ele acontece dentro do mesmo texto que o modelo gera.

O laço agêntico

START, laco agentico com Reason, Act e Observe, e END

developers.openai.com/api/docs/guides/function-calling

Duas regras que valem para qualquer agente

O modelo pede a chamada, e quem executa é você. O modelo nunca roda código.

A tool é escolhida pela descrição. Descrição ruim significa tool ignorada.

A segunda regra é a que mais custa caro na prática, e é a que vocês vão testar no exercício de hoje.

O laço em código: a configuração

Configuracao do agente: MODEL, PERGUNTA, MAX_PASSOS, SYSTEM e as funcoes

Por que um limite de passos?

A linha MAX_PASSOS = 6 destacada no codigo de configuracao

A declaração das tools

Lista TOOLS no formato de function calling, com name, description e parameters

O description não é comentário. É a única coisa que o modelo lê para decidir se chama essa função.

O laço: reason

Laco com ollama.chat recebendo messages e tools, marcado como REASON

Uma chamada ao modelo, com o histórico inteiro e a lista de tools. A resposta entra no histórico.

O laço: a saída

Condicao de parada: se nao ha tool_calls, imprime e retorna

O critério de parada: o modelo respondeu sem pedir nenhuma ferramenta. Foi ele que decidiu que terminou.

O laço: act

Execucao das tool_calls com FUNCS[nome](**args), marcado como ACT

O modelo devolveu o nome e os argumentos, em texto. Quem chama a função de verdade é o nosso código, na linha do FUNCS[nome].

A qualidade da tool é parte do agente

Manifesto de tools: read, edit e shell, com um exemplo de especificacao

Ler antes de editar, substituir trecho em vez do arquivo inteiro, e camadas de proteção no shell. Nenhuma dessas decisões é sobre o modelo.

arxiv.org/abs/2604.09805 · gustavopinto.org/assets/slides/semla-2026/

Escrever o JSON na mão cansa

Decorador @tool usando inspect para gerar o esquema a partir da assinatura e da docstring

A assinatura vira o esquema, e a docstring vira a descrição. É esse truque que os frameworks empacotam.

Frameworks agênticos

Logos de LangChain, LangGraph, LlamaIndex, Agno, CrewAI, AutoGen e smolagents

Todos empacotam o mesmo laço. O smolagents, da Hugging Face, é o menor deles, e por isso é o que deixa o laço mais visível.

smolagents: declarar a tool

Decorador @tool do smolagents com docstring e secao Args

A docstring com a seção Args é o que vira o esquema. huggingface.co/docs/smolagents/en/guided_tour

smolagents: rodar o agente

CodeAgent recebendo tools e model, e agent.run com a pergunta

Três linhas escondem o laço inteiro que escrevemos à mão. huggingface.co/docs/smolagents/en/guided_tour

Qual o problema
das tools?

Cada modelo, cada ferramenta, uma integração

M vezes N integracoes personalizadas, e o MCP como protocolo unico

Com MCP, cada lado implementa uma vez. Passa de M × N para M + N.

MCP, as três capacidades

Tools. Funções que realizam ações ou obtêm dados
Resources. Fontes de dados para fornecer contexto, como documentação
Prompts. Fluxos de trabalho pré-definidos, oferecidos pelo servidor

MCP ligando o LLM a tool, resource e prompt

Cliente e servidor trocando request, response e notification

Cliente e servidor conversam por JSON-RPC 2.0. É protocolo, e não biblioteca.

A arquitetura

Aplicacao de IA falando com um registro de servidores MCP

A aplicação hospeda o LLM, o MCP Client traduz os pedidos, e os MCP Servers expõem as ferramentas por stdio, HTTP ou SSE. Trocar de host não obriga a reescrever os servidores.

arxiv.org/abs/2506.13538

O ciclo de vida da requisição

Inicialização. initialize, resposta, initialized. Cliente e servidor negociam o que cada um suporta
Discovery. tools/list. O cliente descobre em tempo de execução o que existe
Execution. tools/call, notificações opcionais de progresso, resposta
Termination. shutdown e exit

O tools/list é o que permite acrescentar uma ferramenta sem tocar no código do agente.

Um servidor MCP: o setup

Import do FastMCP, criacao do servidor e o dicionario de dados

Um servidor MCP: as tools

Duas funcoes decoradas com mcp.tool e a chamada mcp.run por http

Um cliente MCP

Cliente fastmcp listando tools e chamando call_tool

O list_tools() descobre em tempo de execução o que o servidor oferece.

Onde encontrar MCPs prontos

Panorama de clientes MCP, servidores MCP e marketplaces

Instalar um servidor MCP é dar acesso ao seu ambiente. Voltamos a esse risco em 24/09.

Exercício: construam o laço

Um agente de verdade, em menos de cem linhas, e um experimento sobre a descrição da tool.

1. Escrevam duas tools em Python, uma sem parâmetro e outra com um parâmetro, cada uma com uma docstring que diga o que ela faz
2. Declarem as duas no formato de function calling e rodem o laço com MAX_PASSOS, usando Ollama local ou a API que a dupla já tem
3. Piorem de propósito a descrição de uma das tools, deixando algo vago como "faz uma consulta", e rodem a mesma pergunta de novo
4. Registrem em diario/2026-09-03.md quantos passos o laço levou nos dois casos, e se o modelo ainda escolheu a ferramenta certa

Commit no dia. Em 08 e 10/09 não há aula, por conta do CBSoft 2026.

Aula 2Agentes