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: - Agent Principal: Which governed agent principal is responsible for the action - 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

agent_id identifies the governed principal, not merely the display name of the assistant. Human-readable names such as agent_label belong in metadata and are non-authoritative.

Basic Structure

{
  "agent_id": "urn:acgp:agent:support:prod:7f4c9d2a",
  "reasoning": "User requested password reset for verified email",
  "action": {
    "name": "send_password_reset_email",
    "parameters": {
      "email": "user@example.com",
      "verification_method": "sms"
    }
  },
  "context": {
    "user_id": "12345",
    "previous_attempts": 0,
    "account_status": "active"
  },
  "meta": {
    "agent_label": "Support-Assistant"
  }
}

Creating Traces

from acgp import CognitiveTrace

trace = CognitiveTrace(
  agent_id="urn:acgp:agent:financeops:prod:7f4c9d2a",
    reasoning="Customer complaint is valid, offering compensation",
    action="issue_credit",
  parameters={"amount": 50, "reason": "service_recovery"},
  meta={"agent_label": "FinanceOps-Agent"}
)

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

// CognitiveTrace is a type (interface), not a class
const trace: CognitiveTrace = {
  agentId: "urn:acgp:agent:financeops:prod:7f4c9d2a",
  reasoning: "Customer complaint is valid, offering compensation",
  action: "issue_credit",
  parameters: { amount: 50, reason: "service_recovery" },
  meta: { agent_label: "FinanceOps-Agent" }
};

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"]
}

Reflection Blueprints See Specification — Trace Model (ACGP-3 §4)