Laboratório: Agente Claude executando comandos e gerando relatório automatizado via Claude Agent SDK Python

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

5

Versões da documentação consultada

Python 3.10 ou superior · Claude Agent SDK Python a versão estável atual · pip a versão estável atual

Topologia

Um notebook ou VM local (10.0.2.15) executa o agente Claude via Agent SDK Python. O agente recebe instruções via prompt, executa comandos shell restritos localmente e grava um relatório em arquivo. Não há conexão externa além da API Claude (api.anthropic.com) via internet.

+-------------------+
|  VM/Notebook      |
|  (10.0.2.15)      |
|                   |
| [Claude Agent SDK]|
|        |          |
|     [Shell]       |
|        |          |
|   [Relatório.md]  |
+--------|----------+
         |
   Internet (API Claude)

Equipamentos e software

Roteiro

1. Preparar ambiente Python isolado

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

   python3 -m venv venv
   source venv/bin/activateCopiar

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

2. Instalar Claude Agent SDK Python

   Instale o SDK oficial para rodar agentes Claude localmente.

   pip install claude-agent-sdk-pythonCopiar

   O que você deve ver: Mensagem de sucesso da instalação do pacote.

3. Configurar variável de ambiente da API Key

   Defina a chave de API da Anthropic como variável de ambiente para segurança.

   export ANTHROPIC_API_KEY='sua-chave-aqui'Copiar

   O que você deve ver: Nenhuma saída (variável definida).

4. Criar arquivo de sistema do agente

   Crie o prompt de sistema versionado, restringindo comandos permitidos.

   cat > system_prompt.md <<EOF
   Você é um agente Claude rodando localmente. Só execute comandos shell da lista: ['ls', 'df', 'uptime', 'whoami']. Nunca execute outros comandos. Gere um relatório em Markdown com os resultados.
   EOFCopiar

   O que você deve ver: Arquivo system_prompt.md criado com o texto do prompt.

5. Implementar script Python do agente

   Implemente o agente com hooks para restringir comandos e gerar relatório.

   cat > agente_claude.py <<EOF
   import os
   from claude_agent_sdk import ClaudeAgent, Tool, AgentContext
   
   ALLOWED_COMMANDS = ['ls', 'df', 'uptime', 'whoami']
   
   class SafeShellTool(Tool):
       name = 'safe_shell'
       description = 'Executa comandos shell restritos.'
       def run(self, ctx: AgentContext, command: str):
           cmd = command.strip().split()[0]
           if cmd not in ALLOWED_COMMANDS:
               return {'error': f'Comando {cmd} não permitido.'}
           try:
               output = os.popen(command).read()
               return {'output': output}
           except Exception as e:
               return {'error': str(e)}
   
   with open('system_prompt.md') as f:
       system_prompt = f.read()
   
   agent = ClaudeAgent(
       system_prompt=system_prompt,
       tools=[SafeShellTool()],
       tracing=True
   )
   
   def main():
       print('Iniciando agente. Envie comandos, fim com "sair".')
       relatorio = []
       while True:
           entrada = input('Comando shell permitido: ')
           if entrada.strip() == 'sair':
               break
           resposta = agent.act({'command': entrada})
           print('Resposta:', resposta)
           relatorio.append(f'### Comando: {entrada}\n{resposta}\n')
       with open('relatorio.md', 'w') as f:
           f.write('\n'.join(relatorio))
       print('Relatório salvo em relatorio.md')
   
   if __name__ == '__main__':
       main()
   EOFCopiar

   O que você deve ver: Arquivo agente_claude.py criado com o código do agente.

6. Executar o agente Claude localmente

   Rode o script para iniciar o agente e interagir via terminal.

   python agente_claude.pyCopiar

   O que você deve ver: Mensagem 'Iniciando agente...' e prompt para comandos shell.

7. Executar comandos permitidos

   Teste comandos como 'ls', 'df', 'uptime', 'whoami' e veja as respostas.

   O que você deve ver: Saída dos comandos executados exibida e registrada.

8. Testar comando não permitido

   Digite um comando fora da lista, por exemplo 'cat /etc/passwd', para validar o guardrail.

   O que você deve ver: Mensagem de erro: 'Comando cat não permitido.'

9. Finalizar e gerar relatório

   Digite 'sair' para encerrar e gerar o arquivo relatorio.md.

   O que você deve ver: Arquivo relatorio.md criado com os comandos e respostas.

10. Revisar o relatório gerado

    Abra relatorio.md e confira se os comandos e saídas estão documentados.

    cat relatorio.mdCopiar

    O que você deve ver: Conteúdo em Markdown com cada comando e sua resposta.

11. Verificar rastreamento do agente

    Confirme que o tracing do agente está ativo e logs são exibidos no terminal.

    O que você deve ver: Mensagens de tracing detalhando cada passo do agente.

12. Limpar ambiente

    Desative o ambiente virtual e remova arquivos temporários.

    deactivate
    rm -rf venv agente_claude.py system_prompt.md relatorio.mdCopiar

    O que você deve ver: Ambiente limpo e arquivos removidos.

Como saber que funcionou

Troubleshooting

Segurança e hardening

• Nunca inclua segredos (API Key) em arquivos de código ou relatório.
• Restrinja comandos shell permitidos no prompt e no código.
• Execute o laboratório em ambiente isolado, nunca em produção.
• Revise permissões de arquivos gerados e apague-os ao final.
• Não exponha a porta do agente para a rede externa.

Checklist final

• Ambiente virtual Python criado e ativado
• Claude Agent SDK instalado sem erros
• Chave ANTHROPIC_API_KEY definida corretamente
• Arquivo system_prompt.md criado e revisado
• Script agente_claude.py executa sem falhas
• Comandos permitidos e bloqueados testados
• relatorio.md gerado e validado
• Tracing do agente visível durante execução