Como Desenvolver um Agente de IA Multiuso em Python Integrando Scripts Legados

É comum que iniciativas de Inteligência Artificial comecem de forma descentralizada. Em muitas equipes técnicas, o primeiro contato com Large Language Models (LLMs) resulta em pequenos scripts independentes: uma rotina para sintetizar relatórios, outra para extrair dados de documentos e um script rápido para responder a dúvidas operacionais.

Com o tempo, essa abordagem fragmentada gera problemas de manutenção, duplicação de chamadas de API, redundância de contexto e falta de consistência nas respostas. Quando a demanda interna cresce, torna-se necessário transformar esses utilitários pontuais em uma arquitetura de agente de IA multiuso, capaz de coordenar ferramentas, manter estado e decidir dinamicamente qual tarefa executar.

Neste artigo, você entenderá como unificar utilitários isolados em um ecossistema coeso de agente inteligente utilizando Python e boas práticas de arquitetura de software.

O Gargalo dos Scripts Isolados

Quando temos vários utilitários independentes baseados em LLMs, enfrentamos três limites operacionais evidentes:

1. Ausência de Contexto Compartilhado: Um script não sabe o que o outro executou. Se uma tarefa exige análise documental seguida pelo envio de um resumo para um webhook, o processo requer intervenção manual ou código adesivo frágil.
2. Alto Custo de Manutenção: Atualizações em prompts de sistema, modelos subjacentes (como migrar de versões do GPT ou Claude) e tratamentos de exceção precisam ser replicados em múltiplos arquivos.
3. Falta de Tomada de Decisão Autônoma: Scripts convencionais seguem um fluxo linear rígido. Um verdadeiro agente de IA multiuso precisa avaliar a intenção do usuário, planejar as etapas necessárias e invocar as ferramentas adequadas dinamicamente.

Como especialista em IA e engenharia de software, observo que a transição de scripts soltos para um agente integrado não exige reconstruir tudo do zero, mas sim encapsular os utilitários existentes como ferramentas (tools) sob a supervisão de um orquestrador central.

Arquitetura de um Agente Multiuso

Para que um único agente resolva problemas variados sem se tornar caótico, a arquitetura deve ser dividida em camadas bem definidas:

• Camada de Orquestração (Roteamento): Recebe o input do usuário, analisa a intenção e planeja o plano de execução.
• Camada de Ferramentas (Tooling): Onde os scripts antigos residem. Cada script é refatorado como uma função pura com tipagem estrita (usando bibliotecas como Pydantic).
• Memória de Estado: Armazena o histórico recente de conversação e o contexto operacional entre execuções de ferramentas.
• Mecanismo de Guardrails e Fallbacks: Trata falhas de execução das ferramentas e valida saídas geradas antes de entregá-las ao usuário.

Implementação Prática: Da Função Isolada ao Agente Integrado

Considere que você já possui duas funções legadas: uma que consulta métricas internas de vendas e outra que gera relatórios sumarizados. Vamos transformá-las em ferramentas e orquestrá-las através de um agente estruturado em Python.

python
import json
from typing import Dict, Any
from openai import OpenAI

client = OpenAI()

1. Refatoração dos scripts legados em funções padronizadas

def consultarmetricas(periodo: str) -> str:
“””Consulta métricas internas de desempenho no período especificado.”””
# Simulação do script antigo de métricas
dados = {“periodo”: periodo, “conversao”: “18.4%”, “usuariosativos”: 1420}
return json.dumps(dados)

def gerarresumoexecutivo(dadosbrutos: str) -> str:
“””Gera um resumo textual estruturado a partir de dados JSON.”””
# Simulação de formatação ou processamento legado
return f”Resumo Operacional: Dados processados com sucesso -> {dadosbrutos}”

Mapeamento dinâmico de ferramentas para o modelo

FERRAMENTASDISPONIVEIS = {
“consultarmetricas”: consultarmetricas,
“gerarresumoexecutivo”: gerarresumo_executivo
}

DEFINICOESTOOLS = [
{
“type”: “function”,
“function”: {
“name”: “consultarmetricas”,
“description”: “Recupera métricas operacionais consolidadas.”,
“parameters”: {
“type”: “object”,
“properties”: {
“periodo”: {“type”: “string”, “description”: “Ex: ‘outubro2023′ ou ‘ultimotrimestre'”}
},
“required”: [“periodo”] }
}
},
{
“type”: “function”,
“function”: {
“name”: “gerarresumoexecutivo”,
“description”: “Estrutura uma análise formal a partir de dados brutos.”,
“parameters”: {
“type”: “object”,
“properties”: {
“dadosbrutos”: {“type”: “string”, “description”: “String JSON contendo os dados a resumir.”}
},
“required”: [“dadosbrutos”] }
}
}
]

2. Loop de orquestração do Agente Multiuso

def executaragente(promptusuario: str) -> str:
mensagens = [
{“role”: “system”, “content”: “Você é um assistente operacional autônomo. Use as ferramentas disponíveis para resolver as solicitações dos usuários de ponta a ponta.”},
{“role”: “user”, “content”: prompt_usuario}
]

while True:
    resposta = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=mensagens,
        tools=DEFINICOES_TOOLS,
        tool_choice="auto"
    )

    mensagem_resposta = resposta.choices[0].message
    mensagens.append(mensagem_resposta)

    # Se o modelo decidir responder sem acionar mais ferramentas, encerra o ciclo
    if not mensagem_resposta.tool_calls:
        return mensagem_resposta.content

    # Processa as ferramentas acionadas pelo agente
    for chamada in mensagem_resposta.tool_calls:
        nome_funcao = chamada.function.name
        argumentos = json.loads(chamada.function.arguments)

        funcao_alvo = FERRAMENTAS_DISPONIVEIS.get(nome_funcao)
        if funcao_alvo:
            resultado_execucao = funcao_alvo(**argumentos)
        else:
            resultado_execucao = f"Erro: Ferramenta {nome_funcao} não encontrada."

        mensagens.append({
            "role": "tool",
            "tool_call_id": chamada.id,
            "content": resultado_execucao
        })

O que muda nessa abordagem?

1. Composição em vez de encadeamento rígido: O modelo decide a ordem em que as funções são chamadas. Se o usuário pedir apenas a consulta, ele não executará o resumo. Se pedir ambos, ele próprio cria a cadeia lógica.
2. Tratamento de Contexto Unificado: Os resultados intermediários trafegam pelo fluxo de mensagens, mantendo a coerência sem a necessidade de gravar arquivos intermediários ou criar scripts adaptadores manuais.

Controle de Custo, Latência e Observabilidade

Ao consolidar utilitários em um agente com permissão para invocar múltiplas ações, você deve monitorar três fatores essenciais:

• Limite de Ciclos (Recursion Limit): Implemente um teto máximo de interações no loop while (ex: 5 passos) para impedir que o modelo entre em repetições infinitas se uma ferramenta falhar sistematicamente.
• Cache Semântico: Ferramentas determinísticas (como consultas estáticas ao banco de dados) devem ter respostas armazenadas em cache para poupar latência e chamadas de API.
• Rastreamento de Execução: Ferramentas de observabilidade (como Langfuse, Arize Phoenix ou logs estruturados em Python) são indispensáveis para auditar por que o agente escolheu determinada ferramenta e quanto cada operação custou.

Estruture Seus Sistemas de IA de Forma Profissional

Transformar rotinas experimentais em uma arquitetura de agente estável e pronta para produção exige planejamento rigoroso de dependências, controle de estados e mitigação de falhas.

Se a sua empresa já utiliza automações com LLMs mas precisa unificar fluxos, reduzir custos operacionais ou implementar agentes corporativos robustos, conte com suporte técnico especializado. Entre em contato para avaliar sua infraestrutura atual e desenhar uma solução sob medida em Python para seus fluxos de trabalho.