Executar lógica personalizada no Python para o Agente SRE do Azure

Em execução em uma área restrita segura, o SRE Agent permite que você execute o código Python com acesso a bibliotecas comuns do Python para adicionar lógica personalizada ao agente.

Este artigo mostra como criar, configurar e testar ferramentas do Python no Agente SRE do Azure.

Pré-requisitos

• Acesso a uma instância do Agente SRE do Azure
• Familiaridade com a programação do Python

Criar uma ferramenta do Python

1. No portal do Azure, acesse o Azure SRE Agent.

2. Selecione Construtor>Construtor de subagentes na navegação à esquerda.

   

3. Selecione Criar>Ferramenta.

   

4. Selecione a ferramenta Python.

   

5. Na caixa de diálogo de criação da ferramenta Python, configure os seguintes campos:

   Campo	Description
   Nome da ferramenta	Um identificador exclusivo usando caracteres alfanuméricos e hifens (no máximo 64 caracteres).
   Descrição	Uma descrição do que a ferramenta faz.
   Tempo limite (segundos)	Tempo limite de execução entre 5 e 900 segundos. O padrão é UTF-120.
   Código do Python	Seu código de função. Deve conter uma def main função.

   

6. Selecione a aba Playground de teste para validar seu código.

   

7. Insira valores de teste para seus parâmetros e selecione Teste.

8. Depois que o teste for bem-sucedido, selecione Criar ferramenta.

Escrever a função principal

Seu código deve conter uma main função. O agente chama essa função como o ponto de entrada.

def main(param1, param2="default"):
    """
    Your tool's main function.
    
    Args:
        param1: Required parameter
        param2: Optional parameter with default
        
    Returns:
        Result to return to the agent
    """
    # Your logic here
    return {"result": "success"}

Observação

Você também pode nomear a função execute, mas main é recomendável.

Retornar valores

O sistema serializa automaticamente valores retornados para JSON. Os seguintes tipos têm suporte:

• Dicionários → objetos JSON
• Lista → matrizes JSON
• Cadeias de caracteres, números, boolianos → primitivas
• None → nulo

def main():
    return {
        "status": "complete",
        "count": 42,
        "items": ["a", "b", "c"],
        "nested": {"key": "value"}
    }

Gerenciar erros

Crie exceções para indicar erros. O agente recebe a mensagem de erro.

def main(resource_id):
    if not resource_id:
        raise ValueError("resource_id is required")
    
    if not resource_id.startswith("/subscriptions/"):
        raise ValueError(f"Invalid resource ID format: {resource_id}")
    
    return {"valid": True}

Usar a geração de código assistida por IA

Você pode usar o assistente de IA para gerar código Python automaticamente.

1. Na caixa Descrever o que a função deve fazer , insira uma descrição de linguagem natural.

2. Selecione Gerar para criar o código inicial.

3. Examine e modifique o código gerado conforme necessário.

Prompts de Exemplo:

• "Analisar logs JSON e extrair mensagens de erro"
• "Calcular o tempo médio de resposta dos dados de métricas"
• "Formatar IDs de recursos do Azure em nomes legíveis"

Configurar dependências

Especifique os pacotes python que sua ferramenta requer na configuração dependências.

O runtime inclui pacotes comuns como json, re, datetimee collectionsitertools.

Dependências comuns que você pode adicionar:

Package	Caso de uso
requests	Solicitações HTTP
pandas	Análise de dados
numpy	Computação numérica

Dica

Inclua apenas pacotes que você realmente usa. Evite pacotes com dependências nativas quando possível.

Definir o tempo limite

Defina tempos limite apropriados com base na complexidade da função.

Scenario	Tempo limite recomendado
Cálculos simples	5 a 30 segundos
Chamadas à API	30 a 120 segundos
Processamento de dados	120 a 300 segundos
Operações em lotes grandes	300-900 segundos

Aviso

Se uma função for executada por mais tempo do que o tempo limite, o sistema encerrará a função e retornará um erro.

Configurar o modo de ferramenta

Controlar como o agente invoca sua ferramenta.

Mode	Description
Automático	O Agente decide automaticamente quando usar a ferramenta com base no contexto.
Manual	O usuário deve solicitar explicitamente a ferramenta.
Escondido	A ferramenta está disponível, mas não é mostrada em listagens de ferramentas.

Configurar identidade

Para ferramentas que precisam acessar recursos do Azure, configure o acesso de identidade gerenciada na guia Identidade .

1. Selecione a guia Identidade .

2. Configure as permissões de identidade gerenciada.

3. Use o SDK do Azure em seu código para autenticar.

def main(resource_group):
    """List resources using managed identity."""
    from azure.identity import DefaultAzureCredential
    from azure.mgmt.resource import ResourceManagementClient
    
    credential = DefaultAzureCredential()
    # Use credential to access Azure resources
    return {"authenticated": True}

Exemplos

Transformação de dados

def main(metrics_data):
    """Transform metrics into summary statistics."""
    import json
    
    data = json.loads(metrics_data) if isinstance(metrics_data, str) else metrics_data
    values = [m.get("value", 0) for m in data]
    
    return {
        "count": len(values),
        "sum": sum(values),
        "avg": sum(values) / len(values) if values else 0,
        "min": min(values) if values else 0,
        "max": max(values) if values else 0,
    }

solicitação HTTP

def main(url, method="GET", headers=None):
    """Fetch data from an external URL."""
    import requests
    import json
    
    request_headers = json.loads(headers) if headers else {}
    response = requests.request(method, url, headers=request_headers, timeout=30)
    response.raise_for_status()
    
    return {
        "status_code": response.status_code,
        "content_type": response.headers.get("Content-Type"),
        "data": response.json() if "application/json" in response.headers.get("Content-Type", "") else response.text
    }

Processamento de texto

def main(log_line):
    """Parse a log line into structured components."""
    import re
    
    pattern = r'\[(\d{4}-\d{2}-\d{2}T[\d:]+Z?)\]\s*(\w+):\s*(.*)'
    match = re.match(pattern, log_line)
    
    if not match:
        return {"error": "Unable to parse log format", "raw": log_line}
    
    timestamp, level, message = match.groups()
    
    return {
        "timestamp": timestamp,
        "level": level.upper(),
        "message": message.strip(),
        "parsed": True
    }

Analisador de recursos do Azure

def main(resource_id, include_tags=True):
    """Parse Azure resource ID into components."""
    parts = resource_id.split('/')
    
    result = {
        "subscription": parts[2] if len(parts) > 2 else None,
        "resource_group": parts[4] if len(parts) > 4 else None,
        "resource_type": parts[6] if len(parts) > 6 else None,
        "resource_name": parts[8] if len(parts) > 8 else None,
    }
    
    if include_tags:
        result["tags"] = {}
        
    return result

Teste sua ferramenta

Use o playground de teste para validar seu código antes da implantação.

1. Selecione a guia Test playground na caixa de diálogo de criação da ferramenta.

2. Insira valores de teste para cada parâmetro.

3. Selecione Testar para executar sua função.

4. Examine os resultados e corrija os erros.

5. Repita até que o teste seja aprovado.

Dicas de depuração

• Comece com o código mínimo e adicione complexidade gradualmente.
• Use print() declarações para depuração. A saída aparece nos resultados do teste.
• Encapsular código arriscado em blocos try/except.
• Valide as entradas antes do processamento.
• Teste com entradas vazias, dados inválidos e valores de limite.

Solucionar erros comuns

Erro	Motivo	Solução
Function must contain a 'def main' function	Função principal ausente	Adicione def main(...): ao seu código.
Timeout must be between 5 and 900	Valor de tempo limite inválido	Defina o tempo limite dentro de 5 a 900 segundos.
ModuleNotFoundError: No module named 'xxx'	Dependência ausente	Adicione o pacote às dependências.
SyntaxError	Sintaxe do Python inválida	Verifique se há erros de digitação, falta de dois pontos ou erros de recuo.

Considerações de segurança

Tenha em mente as seguintes considerações de segurança:

• O código Python é executado em um ambiente em área restrita.
• O acesso à rede está disponível para chamadas de API externas.
• O acesso ao sistema de arquivos é restrito.
• Não decodificar dados confidenciais. Em vez disso, use parâmetros seguros.
• Examine os pacotes de terceiros antes de adicioná-los como dependências.

Conteúdo relacionado

• Criar um subagente