Decisions & Audit

Every agent decision is logged with full context for audit, compliance, and performance analysis. The decision log is the foundation of the shadow mode comparison system and the primary compliance artifact.

Decision structure

Each logged decision contains:

Field	Type	Description
id	string	Unique decision identifier (UUID)
agent_id	string	Which agent made the decision
tenant_id	string	Which tenant the decision belongs to
mode	string	Agent mode at decision time (shadow or active)
trigger_type	string	How the agent was triggered (manual, scheduled, event, api)
decision	string	The decision: approve, reject, escalate, resolve, alert, skip
confidence	float	Confidence score (0-100)
risk_level	string	Risk classification: LOW, MEDIUM, HIGH, CRITICAL
reasoning	string	Natural language explanation
action_taken	boolean	Whether the agent executed an action
action_result	object	Result of the action if taken
human_decision	string	What the human decided (populated after human review)
human_agreed	boolean	Whether the human agreed with the agent
created_at	datetime	When the decision was made (ISO 8601)

Querying decisions

Use the GET /ai/agents/{agent_id}/decisions endpoint with pagination:

curl "https://api.korastratum.com/ai/api/v1/ai/agents/fraud_prevention_agent/decisions?limit=50&offset=0" \
  -H "Authorization: Bearer $KORA_API_KEY" \
  -H "X-Tenant-ID: $KORA_TENANT_ID"

Response:

{
  "decisions": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "agent_id": "fraud_prevention_agent",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "mode": "shadow",
      "trigger_type": "event",
      "decision": "alert",
      "confidence": 87.3,
      "risk_level": "HIGH",
      "reasoning": "Velocity breach detected: 12 transactions in 5 minutes exceeds threshold of 8",
      "action_taken": false,
      "action_result": null,
      "human_decision": "alert",
      "human_agreed": true,
      "created_at": "2026-04-06T14:23:01Z"
    }
  ],
  "total": 342,
  "limit": 50,
  "offset": 0
}

Human comparison

In shadow mode, the platform pairs each agent decision with the eventual human decision:

• human_decision — Populated when a human reviews the same case the agent decided on
• human_agreed — true if the human decision matches the agent's, false if they diverge

This pairing is the basis for the activation readiness calculation. A high agreement rate indicates the agent is ready for promotion to active mode.

Disagreement analysis

When human_agreed is false, the decision log preserves both sides for analysis:

• What did the agent decide, and with what confidence?
• What did the human decide instead?
• Was the human's decision better, or was the agent's equally valid?

This data feeds into the metrics endpoint's shadow_comparison object.

Performance metrics

The GET /ai/agents/{agent_id}/metrics endpoint provides aggregated performance data:

curl "https://api.korastratum.com/ai/api/v1/ai/agents/fraud_prevention_agent/metrics?date_from=2026-03-01&date_to=2026-04-06" \
  -H "Authorization: Bearer $KORA_API_KEY" \
  -H "X-Tenant-ID: $KORA_TENANT_ID"

Response includes:

• daily_metrics — Daily rollup of total runs, auto-resolved, escalated, human agreed/disagreed, average confidence, average latency
• shadow_comparison — Detailed agreement statistics between agent and human decisions
• ready_for_activation — Boolean indicating whether the agent meets activation criteria

Compliance use cases

The decision audit trail supports several compliance requirements:

Requirement	How the audit trail helps
Explainability	Every decision includes a reasoning field explaining why the agent decided as it did
Accountability	trigger_type and triggered_by identify who or what initiated the agent run
Traceability	Decision IDs link to upstream events and downstream actions
Non-repudiation	Immutable decision log with timestamps; decisions cannot be modified after creation
Human oversight	Shadow mode comparison proves human-in-the-loop validation before activation

Internal decision logging

The POST /ai/agent-decisions endpoint is used internally by the agent framework to persist decisions. It is called automatically during the agent's Observe-Decide-Act cycle and is not intended for external use.