Laboratório: Agente de IA para Desdobramento de Metas e Orçamento 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 3.10 ou superior · Claude Agent SDK a versão estável atual · OpenAI Agents SDK a versão estável atual

Topologia

O agente Python roda em uma máquina local (192.168.56.10), acessando APIs dos SDKs Claude e OpenAI pela internet. O usuário interage via terminal. Dados de teste e arquivos de prompt ficam em disco local. Não há exposição de portas externas. O agente registra logs em arquivo e exige aprovação humana para ações críticas.

+-------------------+
| Usuário (Terminal) |
+---------+---------+
          |
          v
+---------------------+
| Agente Python Local |
+----+----------+-----+
     |          |
     v          v
Claude SDK   OpenAI SDK
     |          |
     +----------+
          |
    Internet (APIs)

Equipamentos e software

Roteiro

1. Preparar ambiente Python isolado

   Evite conflitos criando um ambiente virtual. Isso garante que dependências não afetem o sistema.

   python3 -m venv ia-planning-lab
   source ia-planning-lab/bin/activateCopiar

   O que você deve ver: Prompt do terminal mostra (ia-planning-lab) à esquerda.

2. Instalar Claude Agent SDK e OpenAI Agents SDK

   Instale os SDKs oficiais para acessar as APIs e construir o agente.

   pip install claude-agent-sdk openai-agentsCopiar

   O que você deve ver: Mensagens de sucesso da instalação dos pacotes.

3. Configurar variáveis de ambiente para segredos

   Nunca exponha chaves no código. Use variáveis de ambiente para as APIs.

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

   O que você deve ver: Variáveis exportadas (sem retorno, mas visíveis com echo $ANTHROPIC_API_KEY).

4. Criar prompt de sistema versionado

   Defina o comportamento do agente em um arquivo de prompt. Isso permite rastreabilidade e evolução controlada.

   cat > prompt_v1.txt <<EOF
   Você é um agente de planejamento. Sua tarefa é desdobrar metas estratégicas em metas operacionais, propor orçamento detalhado com premissas explícitas e registrar cada decisão. Nunca aprove ações legais, fiscais ou financeiras sem revisão humana. Sempre peça confirmação antes de registrar decisões finais. Use apenas dados fornecidos e explique cada premissa. Versão do prompt: v1.
   EOFCopiar

   O que você deve ver: Arquivo prompt_v1.txt criado com o conteúdo do sistema.

5. Definir ferramenta de cálculo de orçamento

   Implemente uma função Python que calcula orçamento a partir de parâmetros fornecidos. O contrato da ferramenta deve ser explícito.

   cat > tools.py <<EOF
   def calcular_orcamento(meta, premissas):
       # EXEMPLO: cálculo fictício
       if not isinstance(meta, str) or not isinstance(premissas, dict):
           raise ValueError('Parâmetros inválidos')
       base = premissas.get('base', 10000)
       fator = premissas.get('fator', 1.1)
       return {'orcamento_estimado': base * fator, 'premissas': premissas}
   EOFCopiar

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

6. Implementar agente com Claude Agent SDK

   Monte um agente que lê o prompt, recebe metas e chama a ferramenta de orçamento. O agente deve aplicar guardrails e registrar logs.

   cat > agente_claude.py <<EOF
   import os
   from claude_agent_sdk import Agent, Tool
   from tools import calcular_orcamento
   
   def main():
       with open('prompt_v1.txt') as f:
           prompt = f.read()
       def orcamento_tool(meta, premissas):
           return calcular_orcamento(meta, premissas)
       agent = Agent(
           instructions=prompt,
           tools=[Tool('calcular_orcamento', orcamento_tool, params=['meta', 'premissas'])],
           guardrails={'input': lambda x: isinstance(x, dict) and 'meta' in x and 'premissas' in x}
       )
       entrada = {'meta': 'Aumentar vendas em 15%', 'premissas': {'base': 20000, 'fator': 1.2}}
       resultado = agent.run(entrada)
       with open('log.txt', 'a') as log:
           log.write(str(resultado)+'\n')
       print('Resultado:', resultado)
   if __name__ == '__main__':
       main()
   EOFCopiar

   O que você deve ver: Arquivo agente_claude.py criado. Código pronto para rodar o agente.

7. Implementar agente com OpenAI Agents SDK

   Monte um agente equivalente usando o SDK da OpenAI, para comparar abordagens.

   cat > agente_openai.py <<EOF
   import os
   from openai_agents import Agent, Tool, Runner
   from tools import calcular_orcamento
   
   def main():
       with open('prompt_v1.txt') as f:
           prompt = f.read()
       def orcamento_tool(meta, premissas):
           return calcular_orcamento(meta, premissas)
       agent = Agent(
           name='Planejador OpenAI',
           instructions=prompt,
           tools=[Tool('calcular_orcamento', orcamento_tool, params=['meta', 'premissas'])]
       )
       entrada = {'meta': 'Aumentar vendas em 15%', 'premissas': {'base': 20000, 'fator': 1.2}}
       resultado = Runner.run_sync(agent, entrada)
       with open('log.txt', 'a') as log:
           log.write(str(resultado)+'\n')
       print('Resultado:', resultado)
   if __name__ == '__main__':
       main()
   EOFCopiar

   O que você deve ver: Arquivo agente_openai.py criado. Código pronto para rodar o agente.

8. Criar casos de teste automatizados

   Implemente testes para validar entradas e saídas do agente, garantindo que só resultados corretos sejam aceitos.

   cat > test_agente.py <<EOF
   from tools import calcular_orcamento
   
   def test_calculo():
       r = calcular_orcamento('Meta X', {'base': 10000, 'fator': 1.5})
       assert r['orcamento_estimado'] == 15000
       assert r['premissas']['base'] == 10000
       print('Teste OK')
   if __name__ == '__main__':
       test_calculo()
   EOFCopiar

   O que você deve ver: Arquivo test_agente.py criado com teste automatizado.

9. Executar agente Claude e validar resultado

   Rode o agente Claude e verifique se o desdobramento e orçamento são gerados corretamente.

   python agente_claude.pyCopiar

   O que você deve ver: Saída 'Resultado:' com orçamento estimado e premissas. Log atualizado.

10. Executar agente OpenAI e validar resultado

    Rode o agente OpenAI e compare o resultado com o do Claude.

    python agente_openai.pyCopiar

    O que você deve ver: Saída 'Resultado:' com orçamento estimado e premissas. Log atualizado.

11. Rodar testes automatizados

    Execute o teste para garantir que a ferramenta de orçamento está correta.

    python test_agente.pyCopiar

    O que você deve ver: Saída 'Teste OK' indicando sucesso.

12. Simular revisão humana para ação crítica

    Adapte o prompt ou código para exigir confirmação antes de registrar decisões sensíveis. Simule a aprovação manual.

    echo 'Aprovado por responsável técnico' >> log.txtCopiar

    O que você deve ver: Linha de aprovação registrada no log.txt.

Como saber que funcionou

Troubleshooting

Segurança e hardening

• Nunca inclua chaves de API em código ou logs
• Restrinja permissão de leitura ao arquivo de log
• Garanta que decisões sensíveis passem por revisão humana
• Desabilite ou limpe variáveis de ambiente após uso
• Não use dados pessoais reais sem base legal

Checklist final

• Ambiente virtual criado e ativado
• SDKs instalados sem erro
• Variáveis de ambiente configuradas
• Prompt versionado criado
• Ferramenta de orçamento implementada
• Agente Claude funcional
• Agente OpenAI funcional
• Testes automatizados passam
• Log registra execuções
• Revisão humana registrada