Laboratório: Agente de Indicadores de Equipe com Claude Agent SDK e MCP

Roteiro para estudo em ambiente de laboratório ou de teste. Execute apenas em equipamentos, redes e contas que você tenha autorização para usar, com backup e homologação próprios. Comandos podem causar indisponibilidade ou perda de dados. Software e marcas citados pertencem aos seus titulares. Termos de Uso.

Duração estimada

120 min

Passos

13

Validações

4

Versões da documentação consultada

Python 3.10 ou superior · Claude Agent SDK Python a versão estável atual · FastAPI a versão estável atual · Uvicorn a versão estável atual · Model Context Protocol 2026-07-28

Topologia

Uma máquina local (192.168.56.10) executa o agente Claude via Agent SDK em Python. O agente acessa um servidor MCP local (192.168.56.11) que simula um sistema de indicadores de equipe. Toda a comunicação é via localhost ou rede privada, sem expor dados externos.

+---------------------+
|   Usuário           |
| (terminal local)    |
+----------+----------+
           |
           v
+---------------------+
| Claude Agent SDK    |
| (192.168.56.10)     |
+----------+----------+
           |
           v
+---------------------+
| MCP Server (API)    |
| (192.168.56.11)     |
+---------------------+

Equipamentos e software

Roteiro

1. Preparar ambiente Python

   Crie um ambiente virtual isolado para evitar conflitos de dependências.

   python3 -m venv venv
   source venv/bin/activateCopiar

   O que você deve ver: Prompt com (venv) indicando ambiente ativado.

2. Instalar dependências

   Instale as bibliotecas necessárias: Claude Agent SDK, FastAPI e Uvicorn.

   pip install claude-agent-sdk-python fastapi uvicornCopiar

   O que você deve ver: Mensagens de instalação sem erros.

3. Criar servidor MCP simulado

   Implemente um servidor FastAPI local que expõe um endpoint /metrics para retornar indicadores simulados.

   cat > mcp_server.py <<'EOF'
   from fastapi import FastAPI
   from pydantic import BaseModel
   
   app = FastAPI()
   
   class Metrics(BaseModel):
       equipe: str
       produtividade: int
       atrasos: int
       meta_produtividade: int
       meta_atrasos: int
   
   @app.get('/metrics', response_model=Metrics)
   def get_metrics():
       return Metrics(
           equipe='EXEMPLO',
           produtividade=78,
           atrasos=4,
           meta_produtividade=85,
           meta_atrasos=2
       )
   EOFCopiar

   O que você deve ver: Arquivo mcp_server.py criado com o endpoint /metrics.

4. Rodar o servidor MCP

   Inicie o servidor FastAPI para simular o sistema de indicadores.

   uvicorn mcp_server:app --host 0.0.0.0 --port 8001 &Copiar

   O que você deve ver: Log do Uvicorn informando que está ouvindo em 0.0.0.0:8001.

5. Testar o endpoint MCP

   Confirme que o endpoint /metrics retorna os dados simulados.

   curl http://localhost:8001/metricsCopiar

   O que você deve ver: JSON com produtividade, atrasos e metas da equipe EXEMPLO.

6. Escrever prompt de sistema versionado

   Crie um prompt de sistema claro, em português, para o agente Claude. Salve como system_prompt_v1.txt.

   cat > system_prompt_v1.txt <<'EOF'
   Você é um agente de gestão de equipes. Sua função é consultar indicadores de produtividade e atrasos da equipe no endpoint MCP, comparar com as metas e registrar um alerta se houver desvio. Nunca toma decisões finais: apenas prepara e registra alertas para revisão humana. Use apenas os dados fornecidos. Responda sempre em português.
   EOFCopiar

   O que você deve ver: Arquivo system_prompt_v1.txt criado com o prompt completo.

7. Definir ferramenta MCP no agente

   Implemente a ferramenta 'consultar_indicadores' para acessar o MCP. Defina contrato: sem parâmetros, retorna dicionário com produtividade, atrasos, meta_produtividade, meta_atrasos.

   cat > tools.py <<'EOF'
   def consultar_indicadores():
       import requests
       r = requests.get('http://localhost:8001/metrics')
       return r.json()
   EOFCopiar

   O que você deve ver: Arquivo tools.py criado com a função de consulta.

8. Implementar agente Claude com SDK

   Monte o agente Claude com o prompt versionado e a ferramenta MCP. Configure tracing e guardrails simples (validação de tipos).

   cat > agente.py <<'EOF'
   from claude_agent_sdk import Agent, Tool, Runner
   from tools import consultar_indicadores
   
   with open('system_prompt_v1.txt') as f:
       system_prompt = f.read()
   
   def validar_saida(saida):
       assert isinstance(saida, str)
       assert 'Alerta' in saida or 'Sem desvios' in saida
   
   tools = [
       Tool(
           name='consultar_indicadores',
           func=consultar_indicadores,
           description='Consulta indicadores da equipe no MCP.'
       )
   ]
   
   agent = Agent(
       name='AgenteIndicadores',
       instructions=system_prompt,
       tools=tools,
       guardrails={'output': validar_saida}
   )
   
   if __name__ == '__main__':
       entrada = 'Verifique os indicadores da equipe e registre alertas.'
       resultado = Runner.run_sync(agent, entrada)
       print(resultado)
   EOFCopiar

   O que você deve ver: Arquivo agente.py criado com agente Claude configurado.

9. Executar o agente e registrar alerta

   Rode o agente para processar os indicadores e gerar alerta de desvio.

   python agente.pyCopiar

   O que você deve ver: Saída em português indicando alerta de desvio (produtividade abaixo da meta ou atrasos acima da meta).

10. Criar casos de teste automatizados

    Implemente testes para validar a resposta do agente em cenários de desvio e sem desvio.

    cat > test_agente.py <<'EOF'
    import subprocess
    
    def test_alerta():
        proc = subprocess.run(['python', 'agente.py'], capture_output=True, text=True)
        assert 'Alerta' in proc.stdout
    
    def test_sem_desvio():
        # Simule MCP sem desvio
        import requests
        requests.post('http://localhost:8001/metrics', json={
            'equipe': 'EXEMPLO', 'produtividade': 90, 'atrasos': 1, 'meta_produtividade': 85, 'meta_atrasos': 2
        })
        proc = subprocess.run(['python', 'agente.py'], capture_output=True, text=True)
        assert 'Sem desvios' in proc.stdout
    EOFCopiar

    O que você deve ver: Arquivo test_agente.py criado com dois testes automatizados.

11. Rodar testes automatizados

    Execute os testes para garantir que o agente responde corretamente.

    python test_agente.pyCopiar

    O que você deve ver: Testes passam sem erro, confirmando detecção de desvio e ausência de desvio.

12. Registrar logs de execução (tracing)

    Implemente logging básico para registrar entradas, saídas e alertas gerados pelo agente.

    cat >> agente.py <<'EOF'
    import logging
    logging.basicConfig(filename='agente.log', level=logging.INFO)
    logging.info(f'Entrada: {entrada}')
    logging.info(f'Saída: {resultado}')
    EOFCopiar

    O que você deve ver: Arquivo agente.log criado com registros das execuções.

13. Revisão manual de alertas

    Abra o arquivo agente.log e confira se os alertas registrados correspondem aos desvios simulados. A decisão final é sempre humana.

    cat agente.logCopiar

    O que você deve ver: Log detalhado das execuções, com entradas, saídas e alertas claros.

Como saber que funcionou

Troubleshooting

Segurança e hardening

• Nunca inclua segredos ou chaves de API no prompt ou código versionado.
• Restrinja o acesso ao servidor MCP à rede local.
• Garanta que logs não exponham dados pessoais.
• Desative o agente após o laboratório para evitar execuções não supervisionadas.

Checklist final

• Ambiente Python isolado criado
• Servidor MCP rodando e acessível
• Prompt de sistema versionado salvo
• Ferramenta MCP implementada no agente
• Agente Claude funcionando localmente
• Testes automatizados passam
• Logs de execução registrados
• Revisão manual dos alertas realizada