Cognitive Traces

Cognitive traces capture an agent's reasoning and planned actions for governance evaluation.

What is a Cognitive Trace?

A cognitive trace is a structured record of: - Reasoning: Why the agent decided to act - Action: What the agent plans to do - Parameters: How the action will be executed - Context: Relevant situational information

Basic Structure

{
  "reasoning": "User requested password reset for verified email",
  "action": "send_password_reset_email",
  "parameters": {
    "email": "user@example.com",
    "verification_method": "sms"
  },
  "context": {
    "user_id": "12345",
    "previous_attempts": 0,
    "account_status": "active"
  }
}

Creating Traces

from acgp import CognitiveTrace

trace = CognitiveTrace(
    reasoning="Customer complaint is valid, offering compensation",
    action="issue_credit",
    parameters={"amount": 50, "reason": "service_recovery"}
)

import { CognitiveTrace } from '@acgp-protocol/sdk';

// CognitiveTrace is a type (interface), not a class
const trace: CognitiveTrace = {
  reasoning: "Customer complaint is valid, offering compensation",
  action: "issue_credit",
  parameters: { amount: 50, reason: "service_recovery" }
};

Trace Quality Factors

Traces are evaluated on: - Clarity: Is the reasoning clear and understandable? - Completeness: Does it include all necessary information? - Logic: Is the reasoning sound? - Appropriateness: Is the action suitable for the situation?

Best Practices

Good Reasoning

Be specific and explain the logic: 

# Good
reasoning = "Customer has 3 failed login attempts within 5 minutes from different IPs. Likely account compromise. Locking account and notifying user."

# Bad
reasoning = "Suspicious activity detected"

Include Context

Provide relevant situational data: 

context = {
    "user_id": "12345",
    "login_attempts": 3,
    "time_window": "5 minutes",
    "ip_addresses": ["1.2.3.4", "5.6.7.8", "9.10.11.12"]
}

CTQ Evaluation See Specification