feat: add correlated audit events to Safe Agent API

Add structured audit events correlated by request_id for allowed and denied tool executions, with tests and documentation after all CI gates passed.

Author: Videirafo

README.md

@@ -12,7 +12,7 @@
 
 | Status | Projeto executável | Qualidade |
 |---|---|---|
-| `v0.3` | **Safe Agent API** | GitHub Actions · pytest · CodeQL · Docker · secret scan |
+| `v0.4` | **Safe Agent API** | GitHub Actions · pytest · CodeQL · Docker · audit correlation |
 
 `agentic-ai` · `guardrails` · `tool-calling` · `RAG` · `MCP` · `evals` · `observability` · `security`
 
@@ -55,14 +55,16 @@ A API implementa uma camada determinística de policy antes da execução de too
 | `send_notification` | exige aprovação humana |
 | `delete_record` | bloqueada no exemplo |
 
+O fluxo `POST /v1/run-demo` também retorna um **audit event estruturado**. O `correlation_id` é derivado do `request_id`, permitindo ligar decisão, execução e diagnóstico operacional sem armazenar conversa privada.
+
 Endpoints:
 
 - `GET /health`
 - `POST /v1/tool-check`
 - `POST /v1/run-demo`
 - documentação OpenAPI em `/docs`
 
-Os testes verificam same-tenant access, cross-tenant denial, approval gate e bloqueio de ação destrutiva.
+Os testes verificam same-tenant access, cross-tenant denial, approval gate, bloqueio destrutivo e correlação de auditoria para ações permitidas e negadas.
 
 ## Modelo de produção
 
@@ -75,7 +77,8 @@ USE CASE
 → RAG / MEMORY
 → EVALS
 → HUMAN APPROVAL
-→ DEPLOY
+→ EXECUTION
+→ AUDIT + CORRELATION
 → TRACE
 → INCIDENT RESPONSE
 → IMPROVE
@@ -91,8 +94,10 @@ flowchart TB
     O --> T[Tool Registry]
     T --> A[Approval Gate]
     A --> S[Business Systems]
+    S --> AU[Audit Event + Correlation ID]
     O --> H[Human Handoff]
     O --> X[Tracing / Evals / Metrics]
+    AU --> X
 ```
 
 ## Checklist essencial
@@ -115,6 +120,7 @@ flowchart TB
 - [ ] task success, tool selection e argumentos avaliados;
 - [ ] testes de segurança/autorização;
 - [ ] tracing, custo, latência e taxa de erro observáveis;
+- [ ] audit event correlacionado por execução crítica;
 - [ ] handoff humano e kill switch disponíveis.
 
 ## Conteúdo técnico

examples/safe-agent-api/README.md

@@ -1,16 +1,32 @@
 # Safe Agent API
 
-Projeto executável do **AI Agent Production Checklist**. Ele demonstra uma camada determinística de autorização para tools de agentes sem depender de LLM ou API key.
+Projeto executável do **AI Agent Production Checklist**. Demonstra uma camada determinística de autorização, aprovação e auditoria para tools de agentes sem depender de LLM ou API key.
 
 ## O que demonstra
 
 - tenant isolation;
 - least privilege;
 - approval gate humano;
 - bloqueio de tool destrutiva;
+- audit event estruturado;
+- `request_id` propagado como `correlation_id`;
 - contratos Pydantic;
 - API FastAPI com OpenAPI automática;
-- testes de segurança com pytest.
+- testes de segurança com pytest;
+- execução via Docker.
+
+## Rodar com Docker
+
+```bash
+git clone https://github.com/Videirafo/AI-Agent-Production-Checklist.git
+cd AI-Agent-Production-Checklist/examples/safe-agent-api
+docker compose up --build
+```
+
+Abra:
+
+- API docs: `http://127.0.0.1:8000/docs`
+- health: `http://127.0.0.1:8000/health`
 
 ## Clonar e abrir no VS Code
 
@@ -20,15 +36,13 @@ cd AI-Agent-Production-Checklist/examples/safe-agent-api
 code .
 ```
 
-Crie o ambiente e instale:
-
 ### Windows PowerShell
 
 ```powershell
 py -m venv .venv
 .\.venv\Scripts\Activate.ps1
 python -m pip install -e ".[dev]"
-fastapi dev
+fastapi dev app/main.py
 ```
 
 ### Linux/macOS
@@ -37,21 +51,16 @@ fastapi dev
 python3 -m venv .venv
 source .venv/bin/activate
 python -m pip install -e ".[dev]"
-fastapi dev
+fastapi dev app/main.py
 ```
 
-Abra:
-
-- API docs: `http://127.0.0.1:8000/docs`
-- health: `http://127.0.0.1:8000/health`
-
 ## Executar testes
 
 ```bash
 pytest
 ```
 
-## Exemplo de política
+## Políticas
 
 | Tool | Regra |
 |---|---|
@@ -61,20 +70,23 @@ pytest
 
 A autorização é executada **fora do prompt/modelo**. Um LLM pode sugerir uma ação, mas não concede a si mesmo permissão para executá-la.
 
-## Teste manual
+## Audit + correlation
+
+`POST /v1/run-demo` recebe um `request_id`. A resposta inclui um `audit_event` cujo `correlation_id` usa o mesmo identificador. Assim uma decisão permitida ou negada pode ser ligada à execução e ao diagnóstico operacional.
 
-POST `/v1/tool-check`:
+Exemplo:
 
 ```json
 {
+  "request_id": "req-demo-002",
   "actor_tenant_id": "alpha",
   "resource_tenant_id": "alpha",
   "tool": "send_notification",
-  "human_approved": false
+  "human_approved": true
 }
 ```
 
-O resultado deve indicar `human_approval_required`.
+A resposta registra `allowed`, `executed`, `reason`, tenants, tool e `human_approved`, sem armazenar prompt ou conteúdo de conversa.
 
 ## Fazer sua branch
 

examples/safe-agent-api/app/main.py

@@ -1,12 +1,18 @@
 from fastapi import FastAPI
 
-from app.models import RunDemoRequest, RunDemoResponse, ToolCheckRequest, ToolDecision
+from app.models import (
+    AuditEvent,
+    RunDemoRequest,
+    RunDemoResponse,
+    ToolCheckRequest,
+    ToolDecision,
+)
 from app.policy import evaluate_tool
 
 app = FastAPI(
     title="Safe Agent API",
-    version="0.1.0",
-    description="Deterministic policy layer for agent tool execution demos.",
+    version="0.2.0",
+    description="Deterministic policy and audit layer for agent tool execution demos.",
 )
 
 
@@ -20,6 +26,23 @@ def tool_check(request: ToolCheckRequest) -> ToolDecision:
     return evaluate_tool(request)
 
 
+def build_audit_event(
+    request: RunDemoRequest,
+    decision: ToolDecision,
+    executed: bool,
+) -> AuditEvent:
+    return AuditEvent(
+        correlation_id=request.request_id,
+        actor_tenant_id=request.actor_tenant_id,
+        resource_tenant_id=request.resource_tenant_id,
+        tool=request.tool,
+        allowed=decision.allowed,
+        executed=executed,
+        reason=decision.reason,
+        human_approved=request.human_approved,
+    )
+
+
 @app.post("/v1/run-demo", response_model=RunDemoResponse)
 def run_demo(request: RunDemoRequest) -> RunDemoResponse:
     decision = evaluate_tool(request)
@@ -29,6 +52,7 @@ def run_demo(request: RunDemoRequest) -> RunDemoResponse:
             request_id=request.request_id,
             decision=decision,
             executed=False,
+            audit_event=build_audit_event(request, decision, executed=False),
         )
 
     simulated_result = {
@@ -41,4 +65,5 @@ def run_demo(request: RunDemoRequest) -> RunDemoResponse:
         decision=decision,
         executed=True,
         result=simulated_result,
+        audit_event=build_audit_event(request, decision, executed=True),
     )

examples/safe-agent-api/app/models.py

@@ -22,8 +22,21 @@ class RunDemoRequest(ToolCheckRequest):
     request_id: str = Field(min_length=1)
 
 
+class AuditEvent(BaseModel):
+    event_type: Literal["tool_execution_decision"] = "tool_execution_decision"
+    correlation_id: str
+    actor_tenant_id: str
+    resource_tenant_id: str
+    tool: ToolName
+    allowed: bool
+    executed: bool
+    reason: str
+    human_approved: bool
+
+
 class RunDemoResponse(BaseModel):
     request_id: str
     decision: ToolDecision
     executed: bool
     result: str | None = None
+    audit_event: AuditEvent

examples/safe-agent-api/tests/test_api.py

@@ -58,7 +58,7 @@ def test_notification_requires_human_approval() -> None:
     assert body["requires_human_approval"] is True
 
 
-def test_destructive_tool_is_disabled() -> None:
+def test_destructive_tool_denial_is_correlated_in_audit_event() -> None:
     response = client.post(
         "/v1/run-demo",
         json={
@@ -72,3 +72,33 @@ def test_destructive_tool_is_disabled() -> None:
     body = response.json()
     assert body["executed"] is False
     assert body["decision"]["reason"] == "destructive_tool_disabled_in_demo"
+    assert body["audit_event"]["correlation_id"] == "req-demo-001"
+    assert body["audit_event"]["allowed"] is False
+    assert body["audit_event"]["executed"] is False
+
+
+def test_approved_notification_execution_is_audited() -> None:
+    response = client.post(
+        "/v1/run-demo",
+        json={
+            "request_id": "req-demo-002",
+            "actor_tenant_id": "alpha",
+            "resource_tenant_id": "alpha",
+            "tool": "send_notification",
+            "human_approved": True,
+        },
+    )
+    body = response.json()
+    assert body["executed"] is True
+    assert body["result"] == "demo_notification_sent"
+    assert body["audit_event"] == {
+        "event_type": "tool_execution_decision",
+        "correlation_id": "req-demo-002",
+        "actor_tenant_id": "alpha",
+        "resource_tenant_id": "alpha",
+        "tool": "send_notification",
+        "allowed": True,
+        "executed": True,
+        "reason": "policy_allowed",
+        "human_approved": True,
+    }