agent_platform_oci/Tuning-Performance/Transaction_Evidence

Transaction Evidence / Evidência Operacional de Transação

Esta variante demonstra a funcionalidade Transaction Evidence do agent_framework_oci. Ela preserva o resultado estruturado de transações executadas no estado/checkpoint do LangGraph e o reutiliza, quando relevante, em turnos posteriores como evidência operacional para composição de resposta e groundedness.

Transaction Evidence não é Long Term Memory. É estado operacional associado à sessão/workflow e aos recursos envolvidos na transação.

Problema que resolve

Sem esta funcionalidade, uma transação pode ocorrer corretamente em um turno:

quero cancelar pedido
PED-1001
sim
→ protocolo CANCEL-2026-001

mas, no turno seguinte:

quero meu pedido

o runtime pode consultar apenas consultar_pedido. Se a resposta mencionar o cancelamento/protocolo visto no turno anterior, o judge de groundedness pode tratar isso como informação não evidenciada.

Com Transaction Evidence, o resultado transacional confirmado fica estruturado em transaction_evidence e pode aparecer como relevant_transaction_evidence quando correlacionado ao recurso atual.

Fluxo demonstrado

cancelar_pedido(PED-1001)
        ↓
transação executada
        ↓
transaction_evidence
  - tool_name
  - arguments
  - transaction_id
  - status
  - result/protocolo
        ↓
checkpoint da sessão
        ↓
novo turno: "quero meu pedido"
        ↓
consultar_pedido(PED-1001)
        +
relevant_transaction_evidence(PED-1001)
        ↓
resposta + groundedness com evidência operacional

Regras de segurança e correlação

A implementação do framework:

• registra apenas resultados transacionais efetivamente executados;
• mantém histórico bounded das evidências mais recentes;
• correlaciona por identificadores de recurso, como order_id, invoice_id, asset_id, resource_key e outros campos *_id;
• evita reutilizar evidência de um recurso diferente;
• disponibiliza somente a evidência relevante do turno em relevant_transaction_evidence;
• expõe a evidência relevante no metadata da resposta para diagnóstico;
• inclui a evidência relevante no contexto usado pelos judges/groundedness.

Configuração

Não existe uma variável obrigatória ENABLE_TRANSACTION_EVIDENCE nesta versão. A funcionalidade faz parte do runtime transacional do framework e depende da persistência de estado/checkpoint já usada pelo agente.

Os principais pontos do exemplo são:

• app/state.py: campos transaction_evidence, last_transaction_evidence e relevant_transaction_evidence;
• app/workflows/agent_graph.py: injeta evidência relevante no contexto dos judges;
• app/main.py: publica transaction_evidence no metadata da resposta;
• framework: runtime/agent_runtime.py: grava, correlaciona e materializa a evidência.

Executar

cd Tuning-Performance/Transaction_Evidence/agent_template_backend
pip install -e ../../../libs/agent_framework
pip install -r requirements.txt
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Use o frontend normalmente apontando para http://localhost:8000.

Cenário de teste recomendado

Execute na mesma sessão:

quero meu pedido
quero cancelar pedido
PED-1001
sim
quero meu pedido

Na última rodada, valide no JSON de resposta:

{
  "route": "orders_agent",
  "intent": "retail_order_tracking",
  "transaction_evidence": [
    {
      "tool_name": "cancelar_pedido",
      "status": "COMPLETED"
    }
  ]
}

A estrutura exata do result depende da tool transacional, mas o protocolo retornado pela transação deve estar presente na evidência relevante quando o recurso correlacionar.

Resultado esperado

No último quero meu pedido:

1. a intent deve ser retail_order_tracking;
2. consultar_pedido deve ser executada normalmente;
3. a evidência da transação anterior de PED-1001 deve ser recuperada;
4. a resposta pode mencionar o cancelamento/protocolo porque essa informação agora está suportada por evidência operacional;
5. o judge de groundedness deve receber essa mesma evidência.

Diferença para Long Term Memory

Transaction Evidence	Long Term Memory
Estado operacional	Memória semântica/pessoal
Resultado de tools/transações	Preferências e fatos duráveis
Correlacionado a recursos	Correlacionado ao sujeito
Usado para grounding operacional	Usado para personalização/contexto
Curto/médio prazo de workflow	Longo prazo entre conversas

---

English summary

This variant demonstrates Transaction Evidence: executed transactional tool outcomes are persisted as structured operational evidence in LangGraph state/checkpoint. On later turns, the runtime correlates prior evidence with the current resource and exposes it as relevant_transaction_evidence to both response composition and judges/groundedness. It is operational workflow state, not Long Term Memory.

Recommended test sequence:

show my order
cancel my order
PED-1001
yes
show my order

On the last turn, verify that the response metadata contains relevant transaction evidence for the cancellation of PED-1001.