Agente de IA para Controle de Uso de Vale-Transporte

Realizar conexão com o sistema de bilhetagem/ERP de VT para obter dados de uso (validações) de vale-transporte em um período definido.

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 parâmetros de consulta 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 de um arquivo na interface da Prototipe AI, para acelerar o processo de validação.
• Tipo do input: Parâmetros de consulta estruturados em JSON.
• 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 até 5.000 caracteres.

1.3.2 Especificação do Output

• Formato de output: O output deve ser um JSON contendo os dados brutos das transações de vale-transporte.
• Exemplo de Estrutura de Output:

   {
    "transacoes": [
      {
        "transacao_id": "string",
        "usuario_id": "string",
        "data_hora_validacao": "ISO-8601",
        "linha": "string",
        "modalidade": "string",
        "municipio": "string",
        "estacao_ou_ponto": "string",
        "sentido": "ida|volta|nao_informado",
        "valor_tarifa": "number",
        "dispositivo_id": "string",
        "latitude": "number|opcional",
        "longitude": "number|opcional"
      }
    ],
    "metadata_origem": {
      "fonte": "nome_sistema",
      "periodo_consultado": {
        "inicio": "YYYY-MM-DD",
        "fim": "YYYY-MM-DD"
      },
      "total_registros": "number"
    }
  } 

• Número de caracteres esperado: O JSON gerado deve ser claro e direto, com um tamanho estimado em 10.000 caracteres.

1.3.3 Parâmetros de Geração

• Modelo: Não se aplica
• Temperatura: Não se aplica

1.3.4 Ferramentas do Agente

• Documentos: Não consulta documentos externos.
• Calculadora: Não utiliza.
• Busca Online: Não utiliza.
• Sistemas Externos: Conecta-se ao sistema de bilhetagem/ERP de VT para obter dados.

1.3.5 Memória

• Visibilidade das Instruções (Prompt): As instruções não são visíveis para agentes subsequentes.
• Visibilidade da Resposta: A resposta gerada por este agente deve ser visível para o Agente de Normalização e Qualidade de Dados (RF 2).

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

Ao concluir sua execução, esse agente aciona o Agente de Normalização e Qualidade de Dados (RF 2).

Padronizar o schema das transações, corrigir inconsistências simples e produzir um resumo de qualidade de dados pronto para análise.

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 contendo dados brutos das transações de vale-transporte.
• 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 até 10.000 caracteres.

2.3.2 Especificação do Output

• Formato de output: O output deve ser um JSON contendo as transações normalizadas e um resumo de qualidade de dados.
• Exemplo de Estrutura de Output:

   {
    "transacoes_normalizadas": [
      {
        "transacao_id": "string",
        "usuario_id": "string",
        "data_hora_validacao_local": "ISO-8601",
        "dia_da_semana": "1-7 (1=segunda)",
        "hora": "HH:MM",
        "linha": "string",
        "modalidade": "enum[onibus,metro,trem,ferry,BRT,outros,desconhecida]",
        "municipio": "string",
        "estacao_ou_ponto": "string",
        "sentido": "ida|volta|nao_informado",
        "valor_tarifa": "number",
        "dispositivo_id": "string",
        "geo": {
          "lat": "number|null",
          "lng": "number|null"
        }
      }
    ],
    "qualidade_dados_resumo": {
      "total_entrada": "number",
      "total_saidas": "number",
      "registros_descartados": {
        "motivo_campos_essenciais_ausentes": "number",
        "motivo_data_invalida": "number",
        "motivo_duplicidade": "number"
      },
      "percentual_campos_faltantes_por_campo": {
        "linha": "number",
        "modalidade": "number",
        "municipio": "number",
        "estacao_ou_ponto": "number",
        "sentido": "number",
        "valor_tarifa": "number",
        "dispositivo_id": "number"
      }
    }
  } 

• Número de caracteres esperado: O JSON gerado deve ser claro e direto, com um tamanho estimado em 15.000 caracteres.

2.3.3 Parâmetros de Geração

• Modelo: Não se aplica
• Temperatura: Não se aplica

2.3.4 Ferramentas do Agente

• Documentos: Não consulta documentos externos.
• Calculadora: Não utiliza.
• Busca Online: Não utiliza.
• Sistemas Externos: Não se conecta a sistemas externos.

2.3.5 Memória

• Visibilidade das Instruções (Prompt): As instruções não são visíveis para agentes subsequentes.
• Visibilidade da Resposta: A resposta gerada por este agente deve ser visível para o Agente de Engenharia de Atributos e Perfil de Uso (RF 3).

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

Ao concluir sua execução, esse agente aciona o Agente de Engenharia de Atributos e Perfil de Uso (RF 3).

Construir o perfil de uso por usuário e métricas agregadas necessárias para detecção de anomalias.

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 contendo transações normalizadas e um resumo de qualidade de dados.
• 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 até 15.000 caracteres.

3.3.2 Especificação do Output

• Formato de output: O output deve ser um JSON contendo o perfil de uso dos usuários e métricas agregadas.
• Exemplo de Estrutura de Output:

   {
    "perfil_usuarios": [
      {
        "usuario_id": "string",
        "estatisticas_uso": {
          "media_validacoes_por_dia_util": "number",
          "desvpad_validacoes_por_dia_util": "number",
          "media_validacoes_fim_semana": "number",
          "hora_primeira_validacao_media": "HH:MM",
          "hora_ultima_validacao_media": "HH:MM"
        },
        "rotas_frequentes": [
          {
            "linha": "string",
            "modalidade": "string",
            "municipio": "string",
            "frequencia": "number"
          }
        ],
        "janelas_horarias_habituais": [
          {
            "inicio": "HH:MM",
            "fim": "HH:MM",
            "dias_da_semana": [1, 2, 3, 4, 5]
          }
        ],
        "uso_medio_por_dia": [
          {
            "data": "YYYY-MM-DD",
            "validacoes": "number",
            "e_fim_de_semana": "boolean"
          }
        ]
      }
    ],
    "metricas_globais": {
      "usuarios_total": "number",
      "validacoes_total": "number",
      "media_validacoes_por_usuario_no_periodo": "number"
    }
  } 

• Número de caracteres esperado: O JSON gerado deve ser claro e direto, com um tamanho estimado em 20.000 caracteres.

3.3.3 Parâmetros de Geração

• Modelo: Não se aplica
• Temperatura: Não se aplica

3.3.4 Ferramentas do Agente

• Documentos: Não consulta documentos externos.
• Calculadora: Não utiliza.
• Busca Online: Não utiliza.
• Sistemas Externos: Não se conecta a sistemas externos.

3.3.5 Memória

• Visibilidade das Instruções (Prompt): As instruções não são visíveis para agentes subsequentes.
• Visibilidade da Resposta: A resposta gerada por este agente deve ser visível para o Agente de Detecção de Anomalias e Suspeita de Fraude (RF 4).

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

Ao concluir sua execução, esse agente aciona o Agente de Detecção de Anomalias e Suspeita de Fraude (RF 4).

Aplicar regras de negócio e limiares para classificar transações e usuários com suspeita de fraude.

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 contendo o perfil de uso dos usuários e métricas agregadas.
• 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 até 20.000 caracteres.

4.3.2 Especificação do Output

• Formato de output: O output deve ser um JSON contendo as suspeitas de fraude e um resumo.
• Exemplo de Estrutura de Output:

   {
    "suspeitas": [
      {
        "usuario_id": "string",
        "tipo": "enum[uso_simultaneo_improvavel, compartilhamento_cartao, uso_fora_expediente, uso_excessivo_fds, desvio_rota, pico_anormal_uso, uso_geograficamente_impossivel]",
        "score_risco": 0,
        "severidade": "baixa|media|alta|critica",
        "evidencias": [
          "string explicativa curta com valores observados e limiares aplicados"
        ],
        "registros_relacionados": ["transacao_id", "transacao_id"],
        "data_referencia": "YYYY-MM-DD",
        "recomendacao_acao": "string curta e objetiva"
      }
    ],
    "resumo": {
      "total_suspeitas": "number",
      "usuarios_unicos_sinalizados": "number",
      "tipos_mais_comuns": [
        {
          "tipo": "string",
          "quantidade": "number"
        }
      ]
    }
  } 

• Número de caracteres esperado: O JSON gerado deve ser claro e direto, com um tamanho estimado em 25.000 caracteres.

4.3.3 Parâmetros de Geração

• Modelo: Não se aplica
• Temperatura: Não se aplica

4.3.4 Ferramentas do Agente

• Documentos: Não consulta documentos externos.
• Calculadora: Não utiliza.
• Busca Online: Não utiliza.
• Sistemas Externos: Não se conecta a sistemas externos.

4.3.5 Memória

• Visibilidade das Instruções (Prompt): As instruções não são visíveis para agentes subsequentes.
• Visibilidade da Resposta: A resposta gerada por este agente deve ser visível para o Agente de Preparação de Alertas e Roteamento (RF 5).

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

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

Consolidar suspeitas em alertas por responsável e preparar payloads para notificação ou integração.

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 contendo as suspeitas de fraude e um resumo.
• 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 até 25.000 caracteres.

5.3.2 Especificação do Output

• Formato de output: O output deve ser um JSON contendo os alertas preparados para notificação ou integração.
• Exemplo de Estrutura de Output:

   {
    "alertas": [
      {
        "alerta_id": "string",
        "destinatario_tipo": "RH|Compliance|Gestor_Unidade|Usuario",
        "severidade": "baixa|media|alta|critica",
        "score_maximo": "number",
        "usuarios_afetados": ["usuario_id"],
        "suspeitas_ids": ["derivado ou hash de evidencias"],
        "mensagem_resumo": "string curta",
        "payload": {
          "detalhes": "objeto com suspeitas agregadas e recomendações",
          "anexos": ["opcional"]
        },
        "sla_horas": "number"
      }
    ],
    "contadores": {
      "total_alertas_gerados": "number",
      "por_destinatario": {
        "RH": "number",
        "Compliance": "number",
        "Gestor_Unidade": "number",
        "Usuario": "number"
      }
    }
  } 

• Número de caracteres esperado: O JSON gerado deve ser claro e direto, com um tamanho estimado em 30.000 caracteres.

5.3.3 Parâmetros de Geração

• Modelo: Não se aplica
• Temperatura: Não se aplica

5.3.4 Ferramentas do Agente

• Documentos: Não consulta documentos externos.
• Calculadora: Não utiliza.
• Busca Online: Não utiliza.
• Sistemas Externos: Não se conecta a sistemas externos.

5.3.5 Memória

• Visibilidade das Instruções (Prompt): As instruções não são visíveis para agentes subsequentes.
• Visibilidade da Resposta: A resposta gerada por este agente deve ser visível para o Agente de Relatórios Periódicos de Uso e Fraude (RF 6).

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

Ao concluir sua execução, esse agente aciona o Agente de Relatórios Periódicos de Uso e Fraude (RF 6).

Gerar relatórios regulares sobre o uso do vale-transporte e sobre detecções de possíveis fraudes para apoiar a tomada de decisão.

6.3.1 Especificação do Input

• Mecanismo de Acionamento: Este agente deve ser acionado automaticamente após a conclusão do agente anterior (RF 5).
• Tipo do input: Este agente deve ser apto a receber como input um JSON contendo transações normalizadas e suspeitas de fraude.
• 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 até 30.000 caracteres.

6.3.2 Especificação do Output

• Formato de output: O output deve ser um JSON contendo o relatório resumo e, opcionalmente, o relatório detalhado em base64.
• Exemplo de Estrutura de Output:

   {
    "relatorio_resumo": {
      "periodo": {
        "inicio": "YYYY-MM-DD",
        "fim": "YYYY-MM-DD"
      },
      "kpis": {
        "validacoes_totais": "number",
        "usuarios_ativos": "number",
        "media_validacoes_por_usuario": "number",
        "taxa_fim_de_semana": "number",
        "suspeitas_geradas": "number",
        "usuarios_sinalizados": "number",
        "top_tipos_suspeita": [
          {
            "tipo": "string",
            "percentual": "number"
          }
        ]
      },
      "tendencias": [
        {
          "data": "YYYY-MM-DD",
          "validacoes": "number",
          "suspeitas": "number"
        }
      ],
      "ranking_risco_usuarios": [
        {
          "usuario_id": "string",
          "maior_score": "number",
          "qtd_suspeitas": "number"
        }
      ]
    },
    "relatorio_detalhado_csv_base64": "string|opcional"
  } 

• Número de caracteres esperado: O JSON gerado deve ser claro e direto, com um tamanho estimado em 35.000 caracteres.

6.3.3 Parâmetros de Geração

• Modelo: Não se aplica
• Temperatura: Não se aplica

6.3.4 Ferramentas do Agente

• Documentos: Não consulta documentos externos.
• Calculadora: Não utiliza.
• Busca Online: Não utiliza.
• Sistemas Externos: Não se conecta a sistemas externos.

6.3.5 Memória

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

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

A execução deste agente finaliza o fluxo. O relatório gerado é o resultado que deve ser disponibilizado ao usuário.