Neste artigo, você aprenderá como implementar uma porta de permissão human-in-the-loop para agentes autônomos de IA usando um padrão de decorador Python.
Os tópicos que cobriremos incluem:
- Por que chamadas de ferramentas de alto risco em agentes de IA exigem supervisão humana e como uma abordagem baseada em decorador aborda isso de forma limpa.
- Como construir um
@requires_approvaldecorador que intercepta a execução da ferramenta e solicita confirmação humana explícita antes de prosseguir. - Como esse padrão é dimensionado para ambientes de produção, como a substituição do immediate da CLI por webhooks assíncronos ou painéis de administração.
Implementando chamadas de ferramentas com permissão de permissão em agentes Python
Introdução
Agentes de IA evoluíram além dos chatbots passivos. Hoje em dia são construídos como entidades de software program ativas que podem realizar ações de forma autônoma, como executar código externo. Não é de surpreender que haja um aumento geral do risco associado a esses recursos autônomos de chamada de ferramentas.
Ações de baixo risco, como consultar uma API meteorológica, geralmente são executadas em segundo plano e são consideradas seguras. Entretanto, ações de alto risco, como iniciar transações financeiras, manipular uma base de dados ou entregar e-mails, exigem mecanismos de supervisão muito mais rigorosos. Uma dessas estratégias para resolver isso é injetar uma camada intermediária humana no circuito.
Este artigo ilustra como implementar um ferramenta com permissão em um agente Python, contando totalmente com a funcionalidade integrada da linguagem. O resultado: um mecanismo de interceptação robusto e gratuito baseado em um padrão decorador simples.
Nossa solução de exemplo não codificará as verificações de segurança diretamente no loop de raciocínio principal do agente ou na lógica de negócios. Em vez disso, usaremos um decorador Python chamado @requires_approval. Este decorador atua como um gateway: se o agente tentar usar uma ferramenta empacotada, o gateway interrompe o fluxo de execução, exibe os argumentos para um tomador de decisão humano e aguarda aprovação explícita.
A implementação proposta depende totalmente do Python functools biblioteca, sem serviços pagos ou APIs externas necessárias quando executadas localmente.
A função decoradora do Python
A primeira parte do código outline nossa função principal de decorador Python. Ele envolve uma função e adiciona uma camada de “aprovação humana” antes de executar a função passada como argumento, func. Quando qualquer outra função (que definiremos mais tarde) é decorada com @requires_approvalo decorador imprimirá uma mensagem de alerta de segurança, mostrará os argumentos propostos e solicitará a aprovação ou negação do usuário por meio de uma simples entrada de texto — ‘y’ para aprovação, ‘n’ para negação.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | importar ferramentas funcionais # 1. Interceptor (camada intermediária) definitivamente requer_aprovação(função): “”“Decorador para pausar a execução e solicitar validação humana.”“” @ferramentas funcionais.embrulhos(função) definitivamente invólucro(*argumentos, **kwargs): imprimir(f“n(ALERTA DE SEGURANÇA) Agente tentando ação de alto risco: ‘{func.__name__}'”) imprimir(f“-> Argumentos propostos: args={args}, kwargs={kwargs}”)
# Simulando Human-in-the-Loop through entrada CLI aprovação = entrada(“-> Aprova esta execução? (s/n): “).tira().mais baixo()
se aprovação == ‘você’: imprimir(“(SYSTEM) Ação aprovada. Executando…n”) retornar função(*argumentos, **kwargs) outro: imprimir(“(SYSTEM) Ação bloqueada pelo superintendente humano.n”) # Retornando uma string para informar ao agente que a ferramenta falhou retornar “ERRO: Execução da ferramenta bloqueada pelo administrador.”
retornar invólucro |
As ferramentas do agente
A seguir, definimos duas funções que constituem as ferramentas disponíveis do agente. Para simplificar, eles simulam o uso de ferramentas por um agente, em vez de depender de ferramentas externas reais.
- A primeira, destinada a recuperar an information e hora atuais, é considerada uma ferramenta de baixo risco e pode ser executada de forma autônoma.
- A segunda — que simula a exclusão permanente de uma tabela em um banco de dados — é rotulada como uma operação de alto risco. Decoramos para que antes de sua execução o decorador previamente definido intercepte a chamada e solicite aprovação humana.
# 2. Definindo as ferramentas do agente definitivamente get_current_time(fuso horário): “”“Ferramenta de baixo risco: pode ser executada de forma autônoma.”“” retornar f“O horário simulado em {timezone} é 10h.” @requer_aprovação definitivamente drop_database_table(nome_tabela): “”“Ferramenta de alto risco: protegida pelo decorador HITL.”“” retornar f“SUCESSO: a tabela ‘{table_name}’ foi excluída permanentemente.” |
Executando a simulação
Próximo, simulate_agent() contém uma sequência simulada de ações que um agente normalmente executaria ao chamar as duas ferramentas definidas acima. As mensagens de log serão impressas durante todo o processo.
# 3. Simulando o Pipeline de Execução do Agente definitivamente simular_agente(): imprimir(“Log do agente: o usuário perguntou a hora.”) resultado_hora = get_current_time(“UTC”) imprimir(f“Resultado da ferramenta: {time_result}n”)
imprimir(“Log do agente: usuário solicitou limpar o banco de dados temporário.”) # Tentativa do agente de ligar para a ferramenta de alto risco resultado_bd = drop_database_table(nome_tabela=“staging_users”) imprimir(f“Resultado da ferramenta: {db_result}”) |
Agora estamos prontos para executar a simulação. Definimos um bloco principal que invoca o fluxo de trabalho do agente simulado:
# Execute a simulação se __nome__ == “__principal__”: simular_agente() |
A seguir saída é obtido – observe que o usuário digitou ‘y’ na interface para aprovar a execução após o alerta de segurança ter sido acionado:
Agente Registro: Usuário perguntado para o tempo. Ferramenta Resultado: O simulado tempo em UTC é 10:00 SOU. Agente Registro: Usuário perguntado para claro o encenação banco de dados. (SEGURANÇA ALERTA) Agente tentando alto–risco Ação: ‘drop_database_table’ -> Proposto Argumentos: argumentos=(), kwargs={‘nome_tabela’: ‘staging_users’} -> Aprovar esse execução? (sim/n): sim (SISTEMA) Ação aprovado. Executando... Ferramenta Resultado: SUCESSO: Mesa ‘staging_users’ tem estive permanentemente excluído. |
Simples, mas eficaz. Uma pergunta que você pode estar fazendo é: como essa solução de camada intermediária é dimensionada? A estratégia baseada em decorador se adapta perfeitamente a ambientes de produção. Você pode querer substituir o simples enter() chame dentro do wrapper com um webhook assíncrono. O wrapper pode enviar uma carga útil para um painel de administração interno ou até mesmo para um canal do Slack, passando o nome da função e seus argumentos. O agente continuará aguardando a resposta do webhook – uma aprovação ou negação humana no conforto de um telefone celular.
Concluindo
Neste artigo, mostrei as principais ideias programáticas por trás da implementação de um mecanismo de chamada de ferramentas com permissão para agentes autônomos de IA usando um decorador Python — uma abordagem prática para controlar a execução de tarefas de alto risco que podem exigir aprovação humana.