Laboratório: Agente Multi-LLM para Triagem de Alertas do NOC com Claude Agent SDK e OpenAI Agents SDK

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

12

Validações

4

Versões da documentação consultada

Python a versão estável atual · Claude Agent SDK (Python) a versão estável atual · OpenAI Agents SDK (Python) a versão estável atual

Topologia

Um host local executa dois agentes Python: um com Claude Agent SDK, outro com OpenAI Agents SDK. Ambos consomem alertas de um arquivo JSON local, processam, classificam e executam ações simuladas (runbooks). O agente registra logs em disco e apresenta resultados no terminal. Não há conexão externa obrigatória além das APIs dos provedores (Anthropic e OpenAI) via internet pública.

+-------------------------+
|        Host VM          |
|-------------------------|
|  [alertas.json]         |
|  |                      |
|  v                      |
| [Claude Agent SDK]      |
|  |                      |
|  v                      |
| [OpenAI Agents SDK]     |
|  |                      |
|  v                      |
|   [runbooks.py]         |
|  |                      |
|  v                      |
|   [logs.txt]            |
+-------------------------+

Equipamentos e software

Roteiro

1. Preparar ambiente Python isolado

   Crie um ambiente virtual para isolar dependências. Isso evita conflitos e facilita a limpeza.

   python3 -m venv venv
   source venv/bin/activateCopiar

   O que você deve ver: Prompt do terminal com (venv) à esquerda.

2. Instalar dependências dos SDKs

   Instale Claude Agent SDK e OpenAI Agents SDK via pip. Ambos são necessários para rodar os agentes.

   pip install claude-agent-sdk openai-agentsCopiar

   O que você deve ver: Mensagens de sucesso do pip para ambos os pacotes.

3. Configurar variáveis de ambiente para segredos

   Defina as chaves de API como variáveis de ambiente. Nunca coloque segredos em código ou prompt.

   export ANTHROPIC_API_KEY='SUA_CHAVE_CLAUDE'
   export OPENAI_API_KEY='SUA_CHAVE_OPENAI'Copiar

   O que você deve ver: Variáveis disponíveis na sessão. Não há saída visível.

4. Criar arquivo de alertas simulados

   Monte um arquivo alertas.json com 3 alertas de EXEMPLO, variando severidade e origem. Isso permite testar o fluxo sem sistemas reais.

   cat > alertas.json <<EOF
   [
     {"id": 1, "origem": "switch01", "tipo": "link_down", "severidade": "alta", "mensagem": "Link caiu na porta 3"},
     {"id": 2, "origem": "router02", "tipo": "cpu_high", "severidade": "media", "mensagem": "CPU acima de 85%"},
     {"id": 3, "origem": "firewall01", "tipo": "login_fail", "severidade": "baixa", "mensagem": "Falha de login repetida"}
   ]
   EOFCopiar

   O que você deve ver: Arquivo alertas.json salvo no diretório atual.

5. Escrever prompt de sistema versionado para o agente Claude

   Crie um arquivo prompt_claude_v1.txt com instruções claras para triagem de alertas do NOC. O prompt define o comportamento e será versionado.

   cat > prompt_claude_v1.txt <<EOF
   Você é um agente do NOC. Sua tarefa é ler alertas, correlacionar por origem e tipo, classificar a severidade (alta, média, baixa) e sugerir ações de runbook. Não execute ações irreversíveis. Registre toda decisão. Use respostas objetivas e em português. Versão: v1.
   EOFCopiar

   O que você deve ver: Arquivo prompt_claude_v1.txt criado com o texto acima.

6. Definir ferramentas (runbooks) como funções Python

   Implemente funções para simular execução de runbooks: reiniciar porta, coletar logs, notificar responsável. Cada função recebe parâmetros claros e retorna resultado textual.

   cat > runbooks.py <<EOF
   def reiniciar_porta(origem, porta):
       return f"Porta {porta} do equipamento {origem} reiniciada (SIMULADO)."
   def coletar_logs(origem):
       return f"Logs coletados do equipamento {origem} (SIMULADO)."
   def notificar_responsavel(alerta_id, severidade):
       return f"Responsável notificado sobre alerta {alerta_id} de severidade {severidade} (SIMULADO)."
   EOFCopiar

   O que você deve ver: Arquivo runbooks.py criado com as funções simuladas.

7. Implementar agente Claude Agent SDK para triagem

   Monte um script Python que carrega alertas, lê o prompt, instancia o agente Claude, define as ferramentas e processa cada alerta. O agente sugere e executa ações via funções.

   cat > agente_claude.py <<EOF
   import os, json
   from claude_agent_sdk import Agent, Tool
   from runbooks import reiniciar_porta, coletar_logs, notificar_responsavel
   with open('alertas.json') as f:
       alertas = json.load(f)
   with open('prompt_claude_v1.txt') as f:
       prompt = f.read()
   tools = [
       Tool('reiniciar_porta', reiniciar_porta, {'origem': str, 'porta': str}),
       Tool('coletar_logs', coletar_logs, {'origem': str}),
       Tool('notificar_responsavel', notificar_responsavel, {'alerta_id': int, 'severidade': str})
   ]
   agente = Agent(
       name='AgenteNOCClaude',
       instructions=prompt,
       tools=tools,
       api_key=os.environ['ANTHROPIC_API_KEY']
   )
   for alerta in alertas:
       entrada = f"Alerta: {alerta}"
       resposta = agente.run(entrada)
       print(resposta)
       with open('logs.txt', 'a') as log:
           log.write(resposta + '\n')
   EOFCopiar

   O que você deve ver: Arquivo agente_claude.py criado. Não há saída ainda.

8. Implementar agente OpenAI Agents SDK para triagem

   Monte um script Python similar usando OpenAI Agents SDK, com o mesmo prompt e ferramentas. Isso permite comparar abordagens.

   cat > agente_openai.py <<EOF
   import os, json
   from openai_agents import Agent, Tool
   from runbooks import reiniciar_porta, coletar_logs, notificar_responsavel
   with open('alertas.json') as f:
       alertas = json.load(f)
   with open('prompt_claude_v1.txt') as f:
       prompt = f.read()
   tools = [
       Tool('reiniciar_porta', reiniciar_porta, {'origem': str, 'porta': str}),
       Tool('coletar_logs', coletar_logs, {'origem': str}),
       Tool('notificar_responsavel', notificar_responsavel, {'alerta_id': int, 'severidade': str})
   ]
   agente = Agent(
       name='AgenteNOCOpenAI',
       instructions=prompt,
       tools=tools,
       api_key=os.environ['OPENAI_API_KEY']
   )
   for alerta in alertas:
       entrada = f"Alerta: {alerta}"
       resposta = agente.run(entrada)
       print(resposta)
       with open('logs.txt', 'a') as log:
           log.write(resposta + '\n')
   EOFCopiar

   O que você deve ver: Arquivo agente_openai.py criado. Não há saída ainda.

9. Executar agente Claude e revisar logs

   Rode o script do agente Claude. Observe a saída no terminal e o conteúdo do logs.txt.

   python agente_claude.py
   cat logs.txtCopiar

   O que você deve ver: Saída com decisões e ações simuladas para cada alerta, registradas no logs.txt.

10. Executar agente OpenAI e revisar logs

    Rode o script do agente OpenAI. Compare as respostas e ações com o agente Claude.

    python agente_openai.py
    cat logs.txtCopiar

    O que você deve ver: Saída com decisões e ações simuladas, também registradas no logs.txt.

11. Adicionar avaliação automática dos resultados

    Implemente um script simples que verifica se cada alerta teve ação apropriada sugerida/executada, conforme regras de EXEMPLO.

    cat > avaliacao.py <<EOF
    import json
    with open('logs.txt') as f:
        logs = f.readlines()
    criterios = [
        ('link_down', 'reiniciada'),
        ('cpu_high', 'logs coletados'),
        ('login_fail', 'notificado')
    ]
    for tipo, esperado in criterios:
        if not any(esperado in l for l in logs):
            print(f'FALHA: ação {esperado} não encontrada para {tipo}')
        else:
            print(f'OK: ação {esperado} encontrada para {tipo}')
    EOFCopiar

    O que você deve ver: Arquivo avaliacao.py criado. Não há saída ainda.

12. Rodar avaliação automática

    Execute o script de avaliação para conferir se as ações dos agentes batem com os critérios esperados.

    python avaliacao.pyCopiar

    O que você deve ver: Mensagens OK para cada tipo de alerta se a ação correta foi registrada.

Como saber que funcionou

Troubleshooting

Segurança e hardening

• Nunca exponha chaves de API em código ou logs
• Restrinja permissões do arquivo logs.txt
• Não use dados reais de clientes ou sistemas em testes
• Garanta que scripts de runbook não executem comandos reais sem aprovação
• Apague variáveis de ambiente ao finalizar

Checklist final

• Ambiente Python isolado criado
• SDKs instalados sem erro
• Variáveis de ambiente setadas
• alertas.json preenchido
• Prompt versionado salvo
• Funções de runbook implementadas
• Scripts dos agentes criados
• Logs gerados e revisados
• Avaliação automática OK