Agente de IA para Monitoramento de Performance de APIs

06 de December de 2025 • Tempo de leitura: 5 min

Como criar um agente de IA que monitora a performance de APIs de bureaus de crédito, alertando sobre degradações de serviço e propondo ajustes.

Biblioteca de Prompts e Agentes

1. Propósito e Escopo

Este documento define todos os prompts, configurações de memória, transição entre estados, ferramentas como chamadas a sistemas externos e demais requisitos funcionais para o Fluxo de Agentes "Monitoramento de Performance de APIs", uma solução projetada para garantir a performance estável das APIs de bureaus de crédito através de monitoramento contínuo e proativo. Essa documentação é um modelo de PRD ou Documento de Requisitos de Produto específicos para construção de Agentes de IA.

O objetivo principal é monitorar a performance das APIs, alertar sobre degradações de serviço e propor ajustes de configuração para garantir a eficiência e estabilidade do serviço.

2. Contexto e Problema

Problemas Específicos

O agente de IA foi projetado para resolver os seguintes problemas:

  • Degradações de serviço em APIs de bureaus de crédito.
  • Falta de monitoramento contínuo e proativo de performance.

Atualmente, a ausência de monitoramento contínuo significa que problemas de performance podem passar despercebidos até que impactem significativamente os serviços. Isso pode resultar em tempo de inatividade, erros em transações e insatisfação do cliente.

3. Impactos Esperados

A implementação deste agente de IA visa alcançar os seguintes resultados:

  • Melhoria na detecção de degradações em tempo real.
  • Redução do tempo de resposta para resolver problemas de performance.
  • Aumento da satisfação do cliente por meio da manutenção de um serviço confiável.
  • Propostas de ajustes proativos para prevenir futuras degradações.

4. Visão Geral da Solução

O agente de IA para monitoramento de performance de APIs analisa continuamente as métricas de performance das APIs de bureaus de crédito, detecta degradações de serviço e sugere ajustes de configuração. A seguir são detalhadas todas as regras de negócio e especificações funcionais necessárias para que esse agente atue como um monitor proativo e eficiente na gestão de performance de APIs.

A solução consiste em um fluxo de automação composto por 5 agentes de IA. O processo inicia com a coleta de métricas de performance e termina com o envio de alertas aos responsáveis pela manutenção das APIs.

A execução dos agentes é sequencial e linear, seguindo a ordem definida na tabela abaixo. O fluxo inclui etapas condicionais que são executadas apenas se critérios específicos forem atendidos, conforme detalhado após a tabela.

Agentes Função Principal
Agente de Execução de Chamada à API (Coleta de Métricas de Bureaus) (RF 1) Executar chamadas às APIs para coletar métricas e logs brutos de performance.
Agente de Normalização e Cálculo de Métricas (RF 2) Padronizar os dados brutos e calcular métricas por API.
Agente de Detecção de Degradação de Serviço (RF 3) Determinar se há degradação de serviço por API.
Agente de Recomendações de Ajuste de Performance (RF 4) Propor ajustes de configuração e mitigação baseados nos padrões de degradação detectados.
Agente de Geração e Envio de Alertas (RF 5) Gerar payloads de alerta para os canais definidos e enviar via API do canal.

5. Protótipos

Para proporcionar uma visão clara e tangível da solução proposta, criamos protótipos interativos que demonstram tanto o fluxo de trabalho dos agentes quanto o resultado final que o cliente receberá. Explore os links abaixo para entender melhor a solução em ação.

Ver Agente na Prototipe AI

6. Requisitos Funcionais

RF 1. Agente de Execução de Chamada à API (Coleta de Métricas de Bureaus)

1.1 Tarefa do Agente

Executar chamadas às APIs/fonte de observabilidade para coletar métricas e logs brutos de performance das APIs de bureaus de crédito.

1.2 Prompt ou Instruções do Agente 
 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um JSON com lista de endpoints/fonte de dados, parâmetros de janela de tempo, credenciais/token, e métricas desejadas.

# 2. Objetivo
Executar chamadas às APIs para coletar métricas e logs brutos de performance das APIs de bureaus de crédito.

# 3. Regras que você deve seguir para gerar sua resposta
- Este agente apenas executa a coleta. Não aplicar interpretação, cálculo ou alerta. Retornar exatamente o que a fonte responder.
- Preservar timestamps originais em UTC.
- Se uma fonte falhar, retornar "raw_data_collected": false e um campo "erro" sem interromper as demais fontes.
- Limitar o período de consulta à janela recebida.
- Nunca expor o token no output.

# 4. Exemplo de Output que você deve produzir
{"raw_data": [{"api_id":"bureauX-score","amostras":[{"ts":"2025-12-06T08:00:05Z","latency_ms":420,"status_code":200},{"ts":"2025-12-06T08:00:06Z","timeout":true}] }], "raw_data_collected": true }
1.3 Configurações do Agente

1.3.1 Especificação do Input

  • Mecanismo de Acionamento: Este agente é o ponto de partida do fluxo e deve ser acionado pelo envio de um JSON contendo lista de endpoints e parâmetros via API. Na fase de testes, o fluxo será iniciado pelo envio manual dos dados, que serão enviados para o agente diretamente por upload do JSON na interface da Prototipe AI, para acelerar o processo de validação.
  • Tipo do input: O input inicial para o fluxo é um JSON com lista de endpoints, parâmetros de janela de tempo, credenciais e métricas desejadas.
  • Formatos Suportados: Esse agente deve ser capaz de receber inputs no formato: .json.
  • Número de caracteres esperado: Este agente deve ter capacidade para processar um input de texto com até 10.000 caracteres.

1.3.2 Especificação do Output

  • Formato de output: O output deve ser um JSON que contém dados brutos coletados por fonte e por API.
  • Exemplo de Estrutura de Output: 
     {"raw_data": [{"api_id":"bureauX-score","amostras":[{"ts":"2025-12-06T08:00:05Z","latency_ms":420,"status_code":200},{"ts":"2025-12-06T08:00:06Z","timeout":true}] }], "raw_data_collected": true }
  • Número de caracteres esperado: O JSON de output terá um tamanho aproximado de 5.000 caracteres.

1.3.3 Parâmetros de Geração

  • Modelo: GPT-5
  • Temperatura: 0.6

1.3.4 Ferramentas do Agente

  • Documentos: Não consulta documentos externos.
  • Calculadora: Não utiliza.
  • Busca Online: Não utiliza.
  • Sistemas Externos: Respeitar limites de rate limit informados no input. Em caso de HTTP 429, aguardar o retry_after se fornecido pela fonte e reexecutar uma vez.

1.3.5 Memória

1.3.6 Regras de Orquestração e Transição

Ao concluir sua execução, esse agente aciona o Agente de Normalização e Cálculo de Métricas (RF 2).

RF 2. Agente de Normalização e Cálculo de Métricas

2.1 Tarefa do Agente

Padronizar os dados brutos e calcular métricas por API: latências (p50/p90/p95/p99), taxa de erro, timeouts, disponibilidade e throughput.

2.2 Prompt ou Instruções do Agente 
 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um JSON com raw_data do agente anterior e, opcionalmente, configurações de agregação.

# 2. Objetivo
Padronizar os dados brutos e calcular métricas por API.

# 3. Regras que você deve seguir para gerar sua resposta
- Considerar como erro qualquer status_code >= 500 ou 429.
- Considerar timeout explícito como erro para error_rate e timeout_rate.
- Calcular availability_pct = 100 - (erros_totais/requisicoes_totais*100).
- Se não houver requisições na janela, retornar métricas com null e campo "sem_dados": true.
- Arredondar percentuais em uma casa decimal e latências em milissegundos inteiros.

# 4. Exemplo de Output que você deve produzir
{"metrics": [{"api_id":"bureauX-score","janela":{"inicio":"2025-12-06T08:00:00Z","fim":"2025-12-06T08:05:00Z"}, "latency_ms":{"p50":180,"p90":320,"p95":380,"p99":520}, "error_rate_pct":1.8, "timeout_rate_pct":0.4, "availability_pct":99.7, "throughput_rps":12.4}], "metrics_computed": true}
2.3 Configurações do Agente

2.3.1 Especificação do Input

  • Mecanismo de Acionamento: Este agente deve ser acionado automaticamente após a conclusão do agente anterior (RF 1).
  • Tipo do input: Este agente deve ser apto a receber como input um JSON com raw_data do agente anterior.
  • Formatos Suportados: Esse agente deve ser capaz de receber inputs no formato: .json.
  • Número de caracteres esperado: Este agente deve ter capacidade para processar um input de texto com até 10.000 caracteres.

2.3.2 Especificação do Output

  • Formato de output: O output deve ser um JSON que contém métricas agregadas por API e por janela.
  • Exemplo de Estrutura de Output: 
     {"metrics": [{"api_id":"bureauX-score","janela":{"inicio":"2025-12-06T08:00:00Z","fim":"2025-12-06T08:05:00Z"}, "latency_ms":{"p50":180,"p90":320,"p95":380,"p99":520}, "error_rate_pct":1.8, "timeout_rate_pct":0.4, "availability_pct":99.7, "throughput_rps":12.4}], "metrics_computed": true}
  • Número de caracteres esperado: O JSON de output terá um tamanho aproximado de 5.000 caracteres.

2.3.3 Parâmetros de Geração

  • Modelo: GPT-5
  • Temperatura: 0.6

2.3.4 Ferramentas do Agente

  • Documentos: Não consulta.
  • Calculadora: Não utiliza.
  • Busca Online: Não utiliza.
  • Sistemas Externos: Não utiliza.

2.3.5 Memória

2.3.6 Regras de Orquestração e Transição

Ao concluir sua execução, esse agente aciona o Agente de Detecção de Degradação de Serviço (RF 3).

RF 3. Agente de Detecção de Degradação de Serviço

3.1 Tarefa do Agente

Determinar se há degradação de serviço por API comparando métricas com limites/SLA ou baseline e classificar severidade.

3.2 Prompt ou Instruções do Agente 
 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um JSON com metrics do agente anterior e parâmetros de comparação.

# 2. Objetivo
Determinar se há degradação de serviço por API comparando métricas com limites/SLA ou baseline e classificar severidade.

# 3. Regras que você deve seguir para gerar sua resposta
- Aplicar, na ordem: 1) Limiares explícitos do input; 2) Se ausentes, usar baseline+fator: p95>baseline*1.25, error_rate>baseline+1.0pp, availability<99.5, timeout_rate>1.0; 3) Se não houver baseline nem limiares, usar defaults: p95>450ms, error_rate>2.0%, availability<99.5%, timeout_rate>1.0%.
- Definir severidade: alta se violar 2+ critérios ou se availability<99.0; média se 1 critério crítico (p95, error_rate, availability) for violado; baixa se apenas timeout_rate for violado.
- Incluir sempre "criterios_violados" com nomes descritivos.

# 4. Exemplo de Output que você deve produzir
{"incidents": [{"api_id":"bureauX-score","status":"degradado","severidade":"alta","evidencias": {"p95_ms":520, "error_rate_pct":3.1}, "criterios_violados":["p95_ms>limite","error_rate>limite"], "defaults_utilizados": false}], "incident_detected": true}
3.3 Configurações do Agente

3.3.1 Especificação do Input

  • Mecanismo de Acionamento: Este agente deve ser acionado automaticamente após a conclusão do agente anterior (RF 2).
  • Tipo do input: Este agente deve ser apto a receber como input um JSON com metrics do agente anterior e parâmetros de comparação.
  • Formatos Suportados: Esse agente deve ser capaz de receber inputs no formato: .json.
  • Número de caracteres esperado: Este agente deve ter capacidade para processar um input de texto com até 10.000 caracteres.

3.3.2 Especificação do Output

  • Formato de output: O output deve ser um JSON que contém lista de incidentes por API quando detectados.
  • Exemplo de Estrutura de Output: 
     {"incidents": [{"api_id":"bureauX-score","status":"degradado","severidade":"alta","evidencias": {"p95_ms":520, "error_rate_pct":3.1}, "criterios_violados":["p95_ms>limite","error_rate>limite"], "defaults_utilizados": false}], "incident_detected": true}
  • Número de caracteres esperado: O JSON de output terá um tamanho aproximado de 5.000 caracteres.

3.3.3 Parâmetros de Geração

  • Modelo: GPT-5
  • Temperatura: 0.6

3.3.4 Ferramentas do Agente

  • Documentos: Não consulta.
  • Calculadora: Não utiliza.
  • Busca Online: Não utiliza.
  • Sistemas Externos: Não utiliza.

3.3.5 Memória

3.3.6 Regras de Orquestração e Transição

Ao concluir sua execução, esse agente aciona o Agente de Recomendações de Ajuste de Performance (RF 4).

RF 4. Agente de Recomendações de Ajuste de Performance

4.1 Tarefa do Agente

Propor ajustes de configuração e mitigação baseados nos padrões de degradação detectados.

4.2 Prompt ou Instruções do Agente 
 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um JSON com incidents e métricas correlatas.

# 2. Objetivo
Propor ajustes de configuração e mitigação baseados nos padrões de degradação detectados.

# 3. Regras que você deve seguir para gerar sua resposta
- Mapeamento de causa-ação: 1) p95>limite: aumentar timeout em 25-50% (máx. 3000ms) e habilitar backoff exponencial; 2) error_rate entre 2-5%: retries=2 com jitter; >5%: retries=0 e acionar circuit breaker; 3) availability<99.5: ativar fallback e roteamento alternativo; 4) timeout_rate>1%: elevar pool_conexoes; 5) throughput alto com latência crescente: recomendar rate limiting e lotes assíncronos.
- Cada ação deve incluir: parametro_atual, parametro_sugerido, racional, risco, impacto_esperado e indicador_de_reversao.

# 4. Exemplo de Output que você deve produzir
{"recommendations": [{"api_id":"bureauX-score","acoes": [{"tipo":"timeout","sugerido_ms":2000,"racional":"p95 acima do limite"},{"tipo":"retries","sugerido":2,"racional":"picos de 5xx 3.1%"},{"tipo":"circuit_breaker","sugerido": {"falhas_pct":3,"janela_s":60}, "racional":"proteger chamadas"}]}]}
4.3 Configurações do Agente

4.3.1 Especificação do Input

  • Mecanismo de Acionamento: Este agente deve ser acionado automaticamente após a conclusão do agente anterior (RF 3).
  • Tipo do input: Este agente deve ser apto a receber como input um JSON com incidents e métricas correlatas.
  • Formatos Suportados: Esse agente deve ser capaz de receber inputs no formato: .json.
  • Número de caracteres esperado: Este agente deve ter capacidade para processar um input de texto com até 10.000 caracteres.

4.3.2 Especificação do Output

  • Formato de output: O output deve ser um JSON que contém recomendações estruturadas com parâmetros sugeridos, justificativa e impacto esperado.
  • Exemplo de Estrutura de Output: 
     {"recommendations": [{"api_id":"bureauX-score","acoes": [{"tipo":"timeout","sugerido_ms":2000,"racional":"p95 acima do limite"},{"tipo":"retries","sugerido":2,"racional":"picos de 5xx 3.1%"},{"tipo":"circuit_breaker","sugerido": {"falhas_pct":3,"janela_s":60}, "racional":"proteger chamadas"}]}]}
  • Número de caracteres esperado: O JSON de output terá um tamanho aproximado de 5.000 caracteres.

4.3.3 Parâmetros de Geração

  • Modelo: GPT-5
  • Temperatura: 0.6

4.3.4 Ferramentas do Agente

  • Documentos: Não consulta.
  • Calculadora: Não utiliza.
  • Busca Online: Não utiliza.
  • Sistemas Externos: Não utiliza.

4.3.5 Memória

  • Visibilidade das Instruções (Prompt): As instruções deste agente não devem ser visíveis para nenhum agente subsequente.
  • Visibilidade da Resposta: A resposta gerada por este agente deve ser visível para o Agente de Geração e Envio de Alertas (RF 5).

4.3.6 Regras de Orquestração e Transição

Ao concluir sua execução, esse agente aciona o Agente de Geração e Envio de Alertas (RF 5).

RF 5. Agente de Geração e Envio de Alertas

5.1 Tarefa do Agente

Gerar payloads de alerta para os canais definidos e, se configurado, enviar via API do canal.

5.2 Prompt ou Instruções do Agente 
 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um JSON com incidents, recommendations e canais.

# 2. Objetivo
Gerar payloads de alerta para os canais definidos e, se configurado, enviar via API do canal.

# 3. Regras que você deve seguir para gerar sua resposta
- Construir mensagem com: api_id, severidade, métricas chave violadas, janela temporal, recomendações resumidas (até 3), e link para observabilidade se fornecido.
- Assinar com proprietário: "Owner: Cheila Portela".
- Se "envio_habilitado" for false, apenas gerar payload e retornar enviado=false.
- Para Slack, evitar mensagens > 2800 caracteres; para email, incluir seção "Próximos passos" com as 3 ações prioritárias.
- Não incluir credenciais nos payloads.

# 4. Exemplo de Output que você deve produzir
{"alerts": [{"canal":"slack","enviado": true, "mensagem_previa":"API bureauX-score degradada (p95=520ms, erro=3.1%)"},{"canal":"email","enviado": false, "erro":"SMTP 421"}], "alertas_gerados": true}
5.3 Configurações do Agente

5.3.1 Especificação do Input

  • Mecanismo de Acionamento: Este agente deve ser acionado automaticamente após a conclusão do agente anterior (RF 4).
  • Tipo do input: Este agente deve ser apto a receber como input um JSON com incidents, recommendations e canais.
  • Formatos Suportados: Esse agente deve ser capaz de receber inputs no formato: .json.
  • Número de caracteres esperado: Este agente deve ter capacidade para processar um input de texto com até 10.000 caracteres.

5.3.2 Especificação do Output

  • Formato de output: O output deve ser um JSON que contém confirmação por canal e mensagem gerada.
  • Exemplo de Estrutura de Output: 
     {"alerts": [{"canal":"slack","enviado": true, "mensagem_previa":"API bureauX-score degradada (p95=520ms, erro=3.1%)"},{"canal":"email","enviado": false, "erro":"SMTP 421"}], "alertas_gerados": true}
  • Número de caracteres esperado: O JSON de output terá um tamanho aproximado de 5.000 caracteres.

5.3.3 Parâmetros de Geração

  • Modelo: GPT-5
  • Temperatura: 0.6

5.3.4 Ferramentas do Agente

  • Documentos: Não consulta.
  • Calculadora: Não utiliza.
  • Busca Online: Não utiliza.
  • Sistemas Externos: Se enviar via API, seguir o método e cabeçalhos fornecidos no input. Em falha transitória, 1 retry após 2s. Em falha permanente, registrar erro no output sem nova tentativa.

5.3.5 Memória

  • Visibilidade das Instruções (Prompt): As instruções deste agente não devem ser visíveis para nenhum agente subsequente.
  • Visibilidade da Resposta: A resposta gerada por este agente é o entregável final e não é passada para outros agentes internos.

5.3.6 Regras de Orquestração e Transição

A execução deste agente finaliza o fluxo. Os alertas gerados são o resultado que deve ser disponibilizado ao usuário.

Posts Relacionados

© 2025 prototipe.ai. Todos os direitos reservados.