Laboratório: Agente Tributário Comparador de Regimes 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

13

Validações

5

Versões da documentação consultada

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

Topologia

Um notebook ou VM local (192.168.56.10) executa o agente Python, que usa Claude Agent SDK e OpenAI Agents SDK para orquestrar os modelos Claude e GPT. Não há conexão externa obrigatória além das APIs dos provedores (chaves de API via variáveis de ambiente). O agente recebe perguntas do usuário, consulta as ferramentas internas (simulador de regimes e memória de consultas) e retorna respostas com premissas explícitas, registrando logs locais.

+-------------------+
|   Usuário local   |
+--------+----------+
         |
         v
+-------------------+
|  Python Agent App |
+----+--------+-----+
     |        |
     v        v
Claude SDK  OpenAI SDK
     |        |
   Modelos   Modelos
     |        |
+----+--------+-----+
|  Ferramentas locais |
+--------------------+

Equipamentos e software

Roteiro

1. Preparar o ambiente Python

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

   python3 -m venv ia-tributario-env
   source ia-tributario-env/bin/activateCopiar

   O que você deve ver: Prompt do terminal indica ambiente ativado, geralmente com (ia-tributario-env) à esquerda.

2. Instalar dependências

   Instale Claude Agent SDK e OpenAI Agents SDK, além do FastAPI para testes HTTP e Pydantic para validação.

   pip install claude-agent-sdk-python openai-agents fastapi pydanticCopiar

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

3. Configurar variáveis de ambiente para as APIs

   Defina as chaves de API das plataformas Claude e OpenAI em variáveis de ambiente para segurança.

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

   O que você deve ver: Nenhuma saída. As variáveis ficam disponíveis na sessão.

4. Criar o prompt de sistema versionado

   Crie um arquivo prompt_v1.txt com as instruções para o agente: sempre explicitar premissas, citar fontes e registrar cada consulta.

   echo 'Você é um agente tributário. Sempre explicite as premissas usadas, cite fontes fictícias como EXEMPLO, e registre cada consulta na memória. Decisões com efeito legal exigem revisão humana.' > prompt_v1.txtCopiar

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

5. Implementar ferramenta de comparação de regimes

   Implemente uma função Python que recebe dados fictícios (receita anual, número de funcionários) e retorna simulação de dois regimes (EXEMPLO Simples e EXEMPLO Lucro Presumido).

   cat <<EOF > compara_regimes.py
   def compara_regimes(receita_anual, funcionarios):
       premissas = 'Receita anual e número de funcionários são EXEMPLO.'
       resultado = {
           'Simples': {'alíquota': 'EXEMPLO 6%', 'imposto': receita_anual * 0.06},
           'Lucro Presumido': {'alíquota': 'EXEMPLO 12%', 'imposto': receita_anual * 0.12},
           'premissas': premissas
       }
       return resultado
   EOFCopiar

   O que você deve ver: Arquivo compara_regimes.py criado com função de simulação.

6. Implementar ferramenta de memória de consultas

   Crie uma função que registra cada consulta em um arquivo local, garantindo rastreabilidade.

   cat <<EOF > memoria_consultas.py
   def registrar_consulta(pergunta, resposta):
       with open('memoria.txt', 'a') as f:
           f.write(f'Pergunta: {pergunta}\nResposta: {resposta}\n---\n')
   EOFCopiar

   O que você deve ver: Arquivo memoria_consultas.py criado.

7. Montar o agente Claude com ferramenta customizada

   Implemente um agente Claude que usa o prompt_v1.txt e expõe a ferramenta compara_regimes.

   cat <<EOF > agente_claude.py
   from claude_agent_sdk import Agent, Tool
   from compara_regimes import compara_regimes
   
   with open('prompt_v1.txt') as f:
       prompt = f.read()
   
   class ComparaRegimesTool(Tool):
       name = 'compara_regimes'
       description = 'Compara regimes tributários fictícios.'
       parameters = {'receita_anual': float, 'funcionarios': int}
       def run(self, receita_anual, funcionarios):
           return compara_regimes(receita_anual, funcionarios)
   
   agent = Agent(
       instructions=prompt,
       tools=[ComparaRegimesTool()]
   )
   EOFCopiar

   O que você deve ver: Arquivo agente_claude.py criado com definição do agente e ferramenta.

8. Montar o agente OpenAI com ferramenta de memória

   Implemente um agente OpenAI Agents SDK que usa o mesmo prompt e registra consultas.

   cat <<EOF > agente_openai.py
   from openai_agents import Agent, Tool
   from memoria_consultas import registrar_consulta
   
   with open('prompt_v1.txt') as f:
       prompt = f.read()
   
   class MemoriaTool(Tool):
       name = 'registrar_consulta'
       description = 'Registra consulta e resposta.'
       parameters = {'pergunta': str, 'resposta': str}
       def run(self, pergunta, resposta):
           registrar_consulta(pergunta, resposta)
           return {'status': 'registrado'}
   
   agent = Agent(
       name='Agente Tributário OpenAI',
       instructions=prompt,
       tools=[MemoriaTool()]
   )
   EOFCopiar

   O que você deve ver: Arquivo agente_openai.py criado com definição do agente e ferramenta.

9. Orquestrar multiagente com FastAPI

   Monte uma API FastAPI que recebe perguntas, chama o agente Claude para simular regimes e registra a consulta com o agente OpenAI.

   cat <<EOF > app.py
   from fastapi import FastAPI
   from agente_claude import agent as claude_agent
   from agente_openai import agent as openai_agent
   
   app = FastAPI()
   
   @app.post('/comparar')
   def comparar(payload: dict):
       receita = payload.get('receita_anual', 100000)
       funcionarios = payload.get('funcionarios', 5)
       pergunta = payload.get('pergunta', 'Comparar regimes EXEMPLO')
       resposta = claude_agent.run({'receita_anual': receita, 'funcionarios': funcionarios})
       openai_agent.run({'pergunta': pergunta, 'resposta': str(resposta)})
       return {'resposta': resposta}
   EOFCopiar

   O que você deve ver: Arquivo app.py criado com endpoint /comparar.

10. Adicionar guardrails de entrada e saída

    Implemente validação com Pydantic para garantir que só dados numéricos positivos sejam aceitos.

    cat <<EOF > schemas.py
    from pydantic import BaseModel, Field
    class CompararInput(BaseModel):
        receita_anual: float = Field(..., gt=0)
        funcionarios: int = Field(..., gt=0)
        pergunta: str
    EOFCopiar

    O que você deve ver: Arquivo schemas.py criado.

11. Integrar validação à API

    Altere app.py para usar o schema CompararInput como parâmetro do endpoint.

    sed -i '/def comparar(payload: dict):/c\def comparar(payload: schemas.CompararInput):' app.pyCopiar

    O que você deve ver: Linha do endpoint alterada para usar validação Pydantic.

12. Rodar a aplicação

    Inicie o servidor FastAPI para expor o endpoint.

    uvicorn app:app --host 0.0.0.0 --port 8000Copiar

    O que você deve ver: Servidor rodando em http://0.0.0.0:8000 com logs de inicialização.

13. Executar casos de teste automatizados

    Teste o endpoint com dados de EXEMPLO e verifique o registro na memória.

    curl -X POST http://localhost:8000/comparar -H 'Content-Type: application/json' -d '{"receita_anual": 200000, "funcionarios": 10, "pergunta": "Qual regime é melhor para minha empresa?"}'Copiar

    O que você deve ver: Resposta JSON com simulação dos regimes e arquivo memoria.txt atualizado.

Como saber que funcionou

Troubleshooting

Segurança e hardening

• Nunca inclua chaves de API em arquivos de código ou logs.
• Permita escrita em memoria.txt apenas para o processo do agente.
• Limite o acesso ao endpoint FastAPI à rede local durante testes.
• Garanta que dados pessoais reais não sejam usados sem base legal.
• Desative logs detalhados em produção ou remova dados sensíveis.

Checklist final

• Ambiente virtual Python criado e ativado
• Claude Agent SDK e OpenAI Agents SDK instalados
• Chaves de API configuradas em variáveis de ambiente
• Prompt de sistema versionado criado
• Ferramentas compara_regimes e memoria_consultas implementadas
• Agentes Claude e OpenAI definidos e integrados
• API FastAPI rodando e acessível
• Casos de teste executados com sucesso
• Memória de consultas persistente e auditável