11-04-02 — Desafio: pipeline vendas SAP → Fabric → agente

Contexto do desafio

Sua empresa usa SAP S/4HANA para gestao comercial. O time de vendas quer um assistente que responda: "Quais clientes estao abaixo da meta neste trimestre?", "Qual o ticket medio por regiao?", "Quais pedidos estao em risco de atraso?" — sem abrir SAP nem aguardar relatorios do BI.

O desafio e construir a plataforma de dados e o agente que entregam isso.

Arquitetura alvo

Passo 1 — Ingerir dados do SAP

O SAP S/4HANA expoe dados de vendas (modulo SD) via OData APIs ou via conector JDBC. No Fabric Data Factory, use o conector nativo SAP OData ou SAP HANA.

Tabelas SAP relevantes para vendas:

• VBAK — Cabecalho de pedidos de vendas
• VBAP — Itens de pedidos de vendas
• KNA1 — Dados de clientes
• VBRK / VBRP — Faturas emitidas

No Fabric Data Factory, crie um pipeline com Copy Activity apontando para cada tabela e destino no OneLake Bronze:

# Estrutura de pastas no OneLake (Bronze)
# abfss://workspace@onelake.dfs.fabric.microsoft.com/bronze/sap/
# ├── vbak/
# │   └── year=2025/month=04/vbak_20250429.parquet
# ├── vbap/
# └── kna1/

# No Notebook Spark (Bronze → Silver): unificacao e limpeza
from pyspark.sql import functions as F

vbak = spark.read.format("delta").load("abfss://bronze@onelake.../sap/vbak/")
vbap = spark.read.format("delta").load("abfss://bronze@onelake.../sap/vbap/")
kna1 = spark.read.format("delta").load("abfss://bronze@onelake.../sap/kna1/")

# Join pedidos + itens + clientes
pedidos_silver = (
    vbak
    .join(vbap, "VBELN")
    .join(kna1, vbak.KUNNR == kna1.KUNNR, "left")
    .select(
        F.col("VBELN").alias("pedido_id"),
        F.col("ERDAT").alias("data_pedido"),
        F.col("NETWR").alias("valor_liquido"),
        F.col("NAME1").alias("cliente_nome"),
        F.col("REGIO").alias("regiao"),
        F.col("MATNR").alias("material_id"),
        F.col("KWMENG").alias("quantidade")
    )
)

pedidos_silver.write.format("delta").mode("overwrite").save("abfss://silver@onelake.../vendas/pedidos/")

Passo 2 — Gold Layer: metricas agregadas

A camada Gold deve conter tabelas prontas para consumo — pre-calculadas, com metricas de negocio claras.

# Silver → Gold: tabela de performance por cliente e periodo
from pyspark.sql import functions as F
from pyspark.sql.window import Window

pedidos = spark.read.format("delta").load("abfss://silver@onelake.../vendas/pedidos/")

# Meta de vendas por cliente (tabela de referencia)
metas = spark.read.format("delta").load("abfss://silver@onelake.../vendas/metas/")

gold = (
    pedidos
    .withColumn("ano_mes", F.date_format("data_pedido", "yyyy-MM"))
    .groupBy("cliente_nome", "regiao", "ano_mes")
    .agg(
        F.sum("valor_liquido").alias("receita_realizada"),
        F.countDistinct("pedido_id").alias("qtd_pedidos"),
        F.avg("valor_liquido").alias("ticket_medio")
    )
    .join(metas, ["cliente_nome", "ano_mes"], "left")
    .withColumn("pct_meta", F.col("receita_realizada") / F.col("meta_receita"))
    .withColumn("status", F.when(F.col("pct_meta") >= 1.0, "OK")
                           .when(F.col("pct_meta") >= 0.7, "ATENCAO")
                           .otherwise("CRITICO"))
)

gold.write.format("delta").mode("overwrite").option("overwriteSchema", "true")\
    .save("abfss://gold@onelake.../vendas/performance_clientes/")

Passo 3 — Agente Foundry com acesso ao Gold

Com a camada Gold pronta, crie o agente no Azure AI Foundry usando a integracao Fabric (ver 11-03-04):

import os
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import FabricTool

client = AIProjectClient.from_connection_string(
    os.environ["AIPROJECT_CONNECTION_STRING"]
)

fabric_tool = FabricTool(
    connection_id=os.environ["FABRIC_CONNECTION_ID"],
    lakehouse_name="gold_vendas"
)

agent = client.agents.create_agent(
    model="gpt-4o",
    name="sales-agent",
    instructions="""Voce e um assistente de vendas especializado.
    Tem acesso aos dados de performance de clientes no Fabric (tabela: performance_clientes).
    Colunas disponiveis: cliente_nome, regiao, ano_mes, receita_realizada, qtd_pedidos, 
    ticket_medio, pct_meta, status (OK/ATENCAO/CRITICO).
    
    Ao responder:
    - Cite sempre o periodo dos dados
    - Use emojis para status: ✅ OK, ⚠️ ATENCAO, 🔴 CRITICO
    - Sugira acoes quando identificar clientes criticos
    - Responda em portugues
    """,
    tools=fabric_tool.definitions,
    tool_resources=fabric_tool.resources,
)

print(f"Agente criado: {agent.id}")

Passo 4 — Teste e validacao

Perguntas para testar o agente:

1. "Quais clientes estao abaixo de 70% da meta em abril 2025?"
2. "Qual a regiao com maior ticket medio no ultimo trimestre?"
3. "Liste os 5 clientes com mais pedidos em 2025."
4. "Compara a receita de SP vs RJ nos ultimos 3 meses."

Pontos de atencao para producao

• Refresh do pipeline: Agende o Data Factory para rodar diariamente (ou via trigger do SAP se disponivel)
• Schema evolution: SAP frequentemente muda estrutura de tabelas em upgrades. Use mergeSchema no Delta Write
• PII e LGPD: Dados de clientes precisam de mascaramento na camada Bronze antes do processamento
• Monitoring: Configure alertas no Fabric Monitor para pipelines com falha