Modulo 4.1 - Agentes, MCP e Skills

1

O que sao Agentes de IA

Automacao vs agentes inteligentes, loops de decisao, ReAct pattern

Um agente de IA nao e apenas um chatbot que responde perguntas. E um sistema autonomo que percebe, raciocina, planeja e age no mundo real. Enquanto automacao tradicional segue regras fixas (se X entao Y), um agente usa um LLM como "cerebro" para tomar decisoes dinamicas, escolher ferramentas e adaptar seu comportamento com base no contexto.

O padrao mais usado e o ReAct (Reason + Act): o agente raciocina sobre a situacao, executa uma acao, observa o resultado, e repete ate atingir o objetivo. Esse loop de decisao e o que diferencia um agente de um script.

📊 Dados do Mercado

42%

das empresas ja tem agentes em producao (2025/26)

92%

dos devs nos EUA usam IA no dia a dia de desenvolvimento

ReAct

padrao dominante para agentes: Reason + Act em loop

2026

ano em que agentes saem de PoC para producao em escala

Automacao vs Agentes Inteligentes

Aspecto	Automacao Tradicional	Agente de IA
Decisao	Regras fixas (if/else)	LLM raciocina em tempo real
Adaptacao	Nenhuma, precisa recodificar	Adapta com base no contexto
Ferramentas	Hardcoded no fluxo	Escolhe qual usar dinamicamente
Falha	Para ou ignora	Tenta abordagem alternativa

O Loop ReAct

O padrao ReAct e um ciclo que se repete ate o agente resolver a tarefa:

1. Think

Raciocina sobre o problema e planeja proxima acao

2. Act

Executa uma acao (chamar tool, buscar dado)

3. Observe

Analisa o resultado da acao executada

4. Repeat

Volta ao passo 1 ate concluir

💡 Dica

Comece simples: um agente com 2-3 tools ja resolve muitos problemas reais. A complexidade vem do loop de decisao, nao da quantidade de ferramentas. Um agente com acesso a filesystem + web search + code execution cobre 80% dos casos de uso.

Fazer

●Definir objetivo claro para o agente antes de construir
●Limitar o numero de tools para reduzir confusao do LLM
●Implementar timeout e max iterations no loop
●Logar cada passo do ReAct para debug

Evitar

●Deixar agente em loop infinito sem limite de iteracoes
●Dar acesso a tools destrutivas sem confirmacao humana
●Assumir que o agente sempre escolhera a tool correta
●Ignorar custo: cada iteracao do loop consome tokens

2

Multiagentes e Orquestracao

Executor, Analyst, Reviewer, pods especializados, routing

Um unico agente tem limitacoes: context window finita, risco de confusao com muitas tools, e incapacidade de processar em paralelo. Sistemas multiagentes resolvem isso dividindo responsabilidades entre agentes especializados, cada um com seu papel, suas tools e seu escopo de atuacao.

O orquestrador e o componente central: recebe a tarefa, classifica a intencao, roteia para o agente correto e coordena o fluxo entre eles. Pode ser um LLM leve (para classificacao) ou um router baseado em regras.

📊 Dados e Referencia

Devin

primeiro agente de engenharia end-to-end (planner + coder + tester)

Manus AI

agente generalista com multiagentes internos para browser, code, research

CrewAI

framework Python para multiagentes com roles, goals e backstory

OpenAI Swarm

padrao de handoff entre agentes com funcoes de transferencia

Padroes de Orquestracao

Sequential Chain

Agente A processa, passa resultado para Agente B, que passa para Agente C. Ideal para pipelines lineares como: gerar conteudo > revisar > publicar.

Parallel Execution

Multiplos agentes processam partes diferentes ao mesmo tempo. Ex: um pesquisa dados enquanto outro gera template e outro prepara assets.

Router Pattern

Um classificador (LLM leve ou regra) analisa a mensagem e roteia para o agente especialista. Ex: mensagem sobre codigo vai para o Code Agent, sobre dados vai para o Data Agent.

Supervisor Pattern

Um agente supervisor delega tarefas, monitora progresso e valida resultados dos agentes workers. Controle centralizado com execucao distribuida.

Roles Comuns em Multiagentes

Executor

Faz o trabalho: gera codigo, redige texto, processa dados. E o "braco" do sistema.

Analyst

Avalia resultados, identifica problemas, sugere melhorias. E o "olho critico".

Reviewer

Valida qualidade, checa consistencia, aprova ou rejeita output. E o "QA".

💡 Dica

Use modelos diferentes por role: um modelo barato e rapido (como Qwen 14B ou Llama 3.2) para o router/classificador, e um modelo potente (Claude Sonnet, GPT-4o) para o executor que precisa de raciocinio complexo. Isso otimiza custo sem perder qualidade.

Fazer

●Definir roles claros com system prompts especificos por agente
●Usar modelo leve para routing e classificacao
●Implementar fallback quando o agente alvo falha
●Logar cada handoff com contexto passado e recebido

Evitar

●Criar agentes demais: comece com 2-3, escale conforme necessidade
●Deixar agentes conversarem entre si sem limite (loop infinito)
●Usar modelo caro para classificacao simples
●Ignorar latencia acumulada de multiplos hops entre agentes

3

Skills e Tools

Capacidades especializadas, JSON schemas, function calling, structured outputs

Tools sao funcoes que o agente pode chamar para interagir com o mundo externo. Cada tool tem um nome, uma descricao e um JSON Schema que define seus parametros. O LLM decide quando e qual tool chamar baseado na conversa, e retorna uma chamada estruturada em vez de texto.

Skills sao pacotes de tools + logica + prompts que implementam uma capacidade completa: "enviar email", "consultar clima", "analisar PDF". Uma skill pode usar multiplas tools internamente e ter seu proprio fluxo de execucao.

Anatomia de uma Tool

{
  "name": "search_database",
  "description": "Busca registros no banco de dados por query",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Termo de busca"
      },
      "limit": {
        "type": "number",
        "description": "Maximo de resultados",
        "default": 10
      }
    },
    "required": ["query"]
  }
}

O LLM recebe esse schema e decide chamar a tool quando faz sentido. A resposta vem como tool_calls com os parametros preenchidos, nao como texto livre.

Fluxo de Function Calling

1. Prompt

Usuario pede algo que requer acao externa

2. LLM decide

Modelo escolhe tool + preenche params

3. Executa

App executa a funcao com os params

4. Retorno

Resultado volta ao LLM como contexto

5. Resposta

LLM gera resposta final com o dado

Structured Outputs

Structured outputs garantem que o LLM retorne dados em formato tipado e validavel, nao texto livre. Isso e essencial para integracoes programaticas.

Sem structured output:

"O preco e R$49,90 e o produto esta disponivel"

Com structured output:

{"price": 49.90, "available": true}

💡 Dica

A descricao da tool e mais importante que o nome. O LLM usa a descricao para decidir quando chamar. Seja especifico: em vez de "busca dados", escreva "busca registros de clientes por nome, email ou ID no banco PostgreSQL".

Fazer

●Escrever descricoes claras e especificas para cada tool
●Validar parametros antes de executar a funcao
●Retornar erros estruturados quando a tool falha
●Agrupar tools relacionadas em skills coerentes

Evitar

●Registrar dezenas de tools: LLMs confundem com muitas opcoes
●Descricoes vagas como "faz coisas no sistema"
●Confiar que o LLM sempre vai preencher params corretos
●Expor tools que modificam dados sem confirmacao

4

MCP (Model Context Protocol)

Anthropic open standard, Host/Client/Server, milhares de conectores

O Model Context Protocol (MCP) e um padrao aberto criado pela Anthropic que padroniza como aplicacoes de IA se conectam a fontes de dados e ferramentas externas. Pense nele como o USB-C das integracoes de IA: em vez de cada aplicacao implementar cada conector do zero, um MCP Server padronizado serve qualquer host compativel.

A arquitetura e simples: o Host (sua aplicacao) cria Clients que conectam a MCP Servers. Cada server expoe resources (dados), tools (acoes) e prompts (templates). Ja existem milhares de servers prontos para GitHub, Slack, bancos de dados, APIs e muito mais.

📊 Ecossistema MCP

1000+

MCP Servers disponiveis no ecossistema open-source

3 SDKs

Python, TypeScript e Java oficiais da Anthropic

Open

Padrao aberto: qualquer app pode implementar, nao so da Anthropic

2 Transports

stdio (local, subprocess) e HTTP+SSE (remoto, cloud)

Arquitetura Host / Client / Server

Host

A aplicacao principal que inicia conexoes MCP. Exemplos: Claude Desktop, VS Code, sua app SaaS. O Host cria e gerencia multiplos Clients.

Client

Mantém conexao 1:1 com um MCP Server especifico. Gerencia protocolo, capacidades e estado da conexao. Um Host pode ter varios Clients simultanios.

Server

Expoe capabilities para os Clients: resources (fontes de dados), tools (acoes executaveis) e prompts (templates reutilizaveis). Pode rodar localmente ou remotamente.

O que um MCP Server expoe

Resources

Dados que o host pode ler: arquivos, registros de banco, conteudo de APIs. Acesso read-only com URI padronizado.

Tools

Acoes executaveis: criar arquivo, enviar mensagem, executar query. Mesmo formato JSON Schema de function calling.

Prompts

Templates reutilizaveis com parametros: "resuma este documento", "analise este PR". Prompts versionados e parametrizaveis.

Exemplo: Configuracao MCP

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem",
               "/home/user/projetos"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres",
               "postgresql://localhost:5432/mydb"]
    }
  }
}

Essa configuracao conecta sua app a 3 MCP Servers simultaneamente: filesystem local, GitHub e um banco PostgreSQL. Cada um expoe suas tools e resources de forma padronizada.

💡 Dica

Comece com o MCP Server de filesystem: e o mais simples de configurar e ja permite ao agente ler/escrever arquivos. Depois adicione GitHub para repos e um banco de dados. A maioria dos MCP Servers funciona com um simples npx -y @modelcontextprotocol/server-nome.

Fazer

●Usar MCP Servers oficiais do ecossistema quando disponiveis
●Isolar tokens e credenciais em variaveis de ambiente
●Limitar escopo de acesso (ex: somente diretorio especifico)
●Testar cada server isoladamente antes de integrar

Evitar

●Dar acesso ao filesystem raiz inteiro
●Hardcodar tokens no arquivo de configuracao
●Conectar muitos servers sem necessidade (overhead)
●Usar MCP Servers nao-oficiais sem revisar o codigo

5

Memoria e Handoff entre Agentes

Short vs long-term memory, context passing, tenant isolation

Agentes sem memoria sao como conversas com um desconhecido toda vez: comecam do zero, nao lembram preferencias, repetem perguntas. Memoria e o que transforma um agente em um assistente util a longo prazo.

Em sistemas multiagentes, o handoff e igualmente critico: quando o Agente A passa a tarefa para o Agente B, precisa transferir contexto suficiente para que B continue sem pedir ao usuario para repetir tudo. Em SaaS multi-tenant, cada usuario precisa ter sua memoria isolada por seguranca.

📊 Tipos de Memoria

Short-term

Context window do LLM. Dura uma sessao. Limitada (128k-200k tokens). Inclui mensagens recentes.

Long-term

Banco de dados ou vector store. Persiste entre sessoes. Sem limite pratico. Precisa de retrieval.

Episodica

Eventos especificos: "usuario preferiu formato JSON na ultima vez". Fatos pontuais recuperaveis.

Semantica

Conhecimento geral: "usuario trabalha com marketing digital". Perfil acumulado ao longo do tempo.

Implementacoes de Memoria

SQLite / PostgreSQL

Armazena memorias como registros com campos: content, type, salience, created_at. Busca por query SQL. Simples e eficiente para memorias estruturadas.

Vector Store (Pinecone, Chroma, pgvector)

Converte memorias em embeddings e busca por similaridade semantica. Ideal para encontrar informacoes relevantes sem query exata. Ex: "usuario gosta de cafe" encontrado por "preferencias alimentares".

Arquivos Markdown (CLAUDE.md, MEMORY.md)

Abordagem simples usada pelo Claude Code: um arquivo de texto que o agente le e atualiza. Sem infraestrutura extra. Funciona bem para agentes pessoais com volume baixo de memorias.

Handoff entre Agentes

Quando um agente passa uma tarefa para outro, o contexto precisa ser transferido de forma estruturada:

{
  "handoff": {
    "from": "research-agent",
    "to": "writer-agent",
    "task": "Escrever artigo sobre MCP",
    "context": {
      "research_results": [...],
      "user_preferences": "tom tecnico, exemplos praticos",
      "constraints": "maximo 2000 palavras"
    },
    "conversation_summary": "Usuario pediu artigo sobre MCP.
      Pesquisa concluida: 5 fontes, 3 exemplos de codigo."
  }
}

O handoff inclui: quem enviou, quem recebe, a tarefa, contexto relevante e um resumo da conversa ate o momento. Isso evita que o agente receptor peca ao usuario para repetir informacoes.

Tenant Isolation

Em SaaS multi-tenant, cada usuario precisa de memoria isolada. Padroes comuns:

Por Coluna

Tabela unica com coluna tenant_id. Simples mas requer WHERE em toda query. Risco se esquecer o filtro.

Por Schema

Schema separado por tenant no PostgreSQL. Melhor isolamento, facil de migrar. Custo medio.

Por Database

Banco separado por tenant. Isolamento maximo, mas caro e complexo de gerenciar em escala.

💡 Dica

Para projetos iniciais, SQLite + coluna tenant_id resolve. Nao precisa de vector store no dia 1. Adicione embeddings quando o volume de memorias crescer e busca por keyword nao for mais suficiente. Premature optimization e a raiz de todo mal em infra de memoria.

Fazer

●Isolar memoria por tenant desde o inicio do projeto
●Incluir conversation_summary em todo handoff
●Definir TTL para memorias de curto prazo (limpar sessoes antigas)
●Versionar o formato de memoria para migracoes futuras

Evitar

●Guardar tudo: memorias sem curadoria viram ruido
●Handoff sem contexto: agente receptor fica perdido
●Memoria compartilhada entre tenants (vazamento de dados)
●Injetar toda a memoria no prompt (estoura context window)

6

Exercicio: Integrar Agentes

Criar 2+ agentes com skills e MCP trabalhando juntos

Hora de colocar tudo em pratica. Neste exercicio voce vai criar um sistema multiagente funcional com pelo menos 2 agentes especializados, cada um com suas tools registradas, conectados a fontes de dados via MCP, com orquestracao e handoff entre eles.

O objetivo nao e perfeicao: e ter um sistema que funciona end-to-end. Agente recebe tarefa, decide quem executa, passa contexto, entrega resultado. Se funcionar com 2 agentes e 3 tools, voce ja domina o padrao para escalar para 10.

Entregas do Exercicio

1

2+ Agentes com roles definidos

Crie pelo menos um Executor (gera conteudo, processa dados) e um Revisor (valida, sugere melhorias). Cada um com system prompt especifico.

2

Skills com JSON Schema

Registre pelo menos 2 tools por agente com JSON Schema completo (nome, descricao, parametros). Teste function calling isolado antes de integrar.

3

MCP Server conectado

Configure pelo menos 1 MCP Server (filesystem, GitHub ou outro). O agente deve conseguir ler/escrever via MCP.

4

Router + Handoff funcional

Implemente routing (qual agente responde) e handoff (passagem de contexto entre agentes). Pode ser regra simples ou LLM classifier.

Exemplo de Arquitetura

projeto/
  agents/
    executor.ts      // Agente que gera conteudo
    reviewer.ts      // Agente que valida e corrige
  skills/
    web-search.ts    // Tool: busca na web
    file-writer.ts   // Tool: escreve arquivos
    code-review.ts   // Tool: analisa codigo
  router.ts          // Classifica e roteia mensagens
  orchestrator.ts    // Coordena fluxo entre agentes
  mcp-config.json    // Configuracao dos MCP Servers
  .env               // API keys e tokens

Checklist de Validacao

Agente Executor responde quando recebe tarefa de criacao Agente Revisor recebe output do Executor e retorna feedback Tools sao chamadas via function calling (nao hardcoded) MCP Server conectado e funcional (ler/escrever via protocolo) Router classifica mensagem e envia para agente correto Handoff inclui contexto suficiente (sem perda de informacao)

💡 Dica

Use Vibe Coding para construir o proprio sistema de agentes. Descreva a arquitetura no prompt, deixe o LLM gerar o scaffold, e itere. O exercicio valida tudo que voce aprendeu nesta trilha, e o resultado se integra diretamente no SaaS que voce esta construindo na imersao.

Fazer

●Comecar com 2 agentes e expandir depois que funcionar
●Testar cada tool isoladamente antes de conectar ao agente
●Logar tudo: input, tool calls, handoffs, output final
●Usar o checklist acima para validar antes de considerar "pronto"

Evitar

●Tentar fazer tudo de uma vez: construa incremental
●Pular o routing e hardcodar qual agente responde
●Ignorar error handling: agentes falham, trate gracefully
●Copiar codigo sem entender: o objetivo e aprender o padrao

O que sao Agentes de IA

📊 Dados do Mercado

Automacao vs Agentes Inteligentes

O Loop ReAct

💡 Dica

Fazer

Evitar

Multiagentes e Orquestracao

📊 Dados e Referencia

Padroes de Orquestracao

Roles Comuns em Multiagentes

💡 Dica

Fazer

Evitar

Skills e Tools

Anatomia de uma Tool

Fluxo de Function Calling

Structured Outputs

💡 Dica

Fazer

Evitar

MCP (Model Context Protocol)

📊 Ecossistema MCP

Arquitetura Host / Client / Server

O que um MCP Server expoe

Exemplo: Configuracao MCP

💡 Dica

Fazer

Evitar

Memoria e Handoff entre Agentes

📊 Tipos de Memoria

Implementacoes de Memoria

Handoff entre Agentes

Tenant Isolation

💡 Dica

Fazer

Evitar

Exercicio: Integrar Agentes

Entregas do Exercicio

Exemplo de Arquitetura

Checklist de Validacao

💡 Dica

Fazer

Evitar

📋 Resumo do Modulo 4.1