if (!this.adjacency.has(node.id)) { this.adjacency.set(node.id, []); } }

addEdge(edge: AuditEdge): void { this.adjacency.get(edge.sourceId)?.push(edge); this.adjacency.get(edge.targetId)?.push({ ...edge, sourceId: edge.targetId, targetId: edge.sourceId }); }

// Path-level risk assessment query queryRiskPath(startNodeId: string, maxDepth: number = 5): AuditEdge[] { const visited = new Set<string>(); const riskEdges: AuditEdge[] = []; const queue: Array<{ nodeId: string; depth: number; path: AuditEdge[] }> = [ { nodeId: startNodeId, depth: 0, path: [] } ];

while (queue.length > 0) {
  const { nodeId, depth, path } = queue.shift()!;
  if (depth > maxDepth || visited.has(nodeId)) continue;
  visited.add(nodeId);

  const outgoing = this.adjacency.get(nodeId) || [];
  for (const edge of outgoing) {
    const enrichedPath = [...path, edge];
    
    // Flag edges with security anomalies
    if (edge.securityFlags.length > 0 || 
        this.nodes.get(edge.targetId)?.securityLevel === 'CRITICAL') {
      riskEdges.push(...enrichedPath);
    }

    queue.push({ nodeId: edge.targetId, depth: depth + 1, path: enrichedPath });
  }
}

return riskEdges;

} }

### Architecture Decisions & Rationale

1. **Directed Graph over Undirected**: Causality in agent execution is strictly forward-moving. A directed structure preserves execution order and prevents false-positive correlations during traversal.
2. **Attribute-Rich Edges**: Security context belongs on edges, not nodes. An action node is neutral; the edge connecting it to a tool reveals whether the invocation was authorized, expected, or anomalous.
3. **Layer Separation**: Decoupling static capabilities from dynamic states allows independent scaling. Static layers can be versioned and audited at deployment time, while dynamic layers stream in real-time without bloating the base schema.
4. **In-Memory Adjacency for Low Latency**: The example uses a local adjacency map for sub-millisecond query resolution. In production, this structure syncs to a persistent graph database (Neo4j, TigerGraph, or Amazon Neptune) for long-term retention and cross-session analysis.

## Pitfall Guide

### 1. Linear Log Fallacy
**Explanation**: Treating agent execution as a sequential event stream ignores branching reasoning paths and parallel tool invocations. Linear logs cannot represent concurrent state mutations or backtracking reasoning.
**Fix**: Enforce graph insertion at the reasoning layer, not just the I/O layer. Capture decision points as nodes, not just outcomes.

### 2. Unbounded Graph Growth
**Explanation**: Continuous execution without pruning causes memory exhaustion and query degradation. Reasoning trajectories can generate thousands of intermediate nodes per session.
**Fix**: Implement temporal compaction. Collapse reasoning chains older than a configurable window into summary nodes while preserving edge metadata for audit trails.

### 3. Missing Temporal Context
**Explanation**: Security attributes evaluated without time windows produce false positives. A tool invocation that was safe yesterday may be malicious today if the capability binding changed.
**Fix**: Attach monotonic timestamps and session IDs to every edge. Query engines must support time-bound traversal filters.

### 4. Overlooking Cross-Agent Edges
**Explanation**: Multi-agent systems introduce trust boundaries that linear monitoring misses. Agent A's output becomes Agent B's input, creating cascading risk propagation.
**Fix**: Explicitly model inter-agent communication as `TRUSTS` or `DERIVES_FROM` edges. Apply cross-agent permission validation during graph construction.

### 5. Static-Only Security Tagging
**Explanation**: Applying security levels only to static capability nodes ignores runtime context. A low-risk tool becomes high-risk when invoked with elevated memory access.
**Fix**: Compute dynamic security scores during edge creation. Combine static capability risk with runtime state attributes to produce context-aware security flags.

### 6. Ignoring Reasoning Drift
**Explanation**: Agents frequently deviate from initial goals due to tool failures or ambiguous prompts. Treating all reasoning paths as equally valid masks adversarial manipulation.
**Fix**: Attach confidence metrics and goal-alignment scores to `REASONING` nodes. Flag paths where alignment drops below a threshold for manual review.

### 7. Inadequate Edge Typing
**Explanation**: Using generic connection types (`CONNECTED_TO`) destroys semantic meaning. Security queries cannot distinguish between a tool invocation and a memory modification.
**Fix**: Enforce strict edge typing at the schema level. Validate edge types against a controlled vocabulary during graph construction.

## Production Bundle

### Action Checklist
- [ ] Define static capability nodes: Catalog all models, tools, memory stores, and permission boundaries before deployment.
- [ ] Implement dynamic state capture: Instrument the agent's reasoning loop to emit `GOAL`, `REASONING`, and `ACTION` nodes in real-time.
- [ ] Attach security attributes to edges: Ensure every invocation, modification, and trust relationship carries authorization context and timestamps.
- [ ] Deploy temporal compaction: Configure automatic summarization of reasoning chains older than your retention window.
- [ ] Map OWASP Agentic Top 10 patterns: Encode detection rules as graph traversal queries targeting privilege abuse, memory poisoning, and supply-chain hijacking.
- [ ] Establish cross-agent trust edges: Explicitly model inter-agent communication channels and validate permission boundaries at runtime.
- [ ] Integrate with SIEM/SOAR: Stream graph audit paths to your security operations pipeline for automated incident response.

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| Single-agent workflow with fixed toolset | In-memory graph + periodic snapshot | Low overhead, sufficient for bounded execution | Low |
| Multi-agent ecosystem with dynamic tool loading | Persistent graph database + real-time streaming | Handles cross-session correlation and cascading risks | Medium |
| High-compliance environment (SOC2, HIPAA) | Immutable graph ledger + cryptographic edge signing | Provides tamper-evident audit trails for adjudication | High |
| Rapid prototyping / research | Lightweight adjacency map + CSV export | Fast iteration, minimal infrastructure | Low |

### Configuration Template

```typescript
// agent-audit-schema.config.ts
export const AuditSchemaConfig = {
  nodeTypes: {
    STATIC: ['MODEL', 'TOOL', 'MEMORY', 'PERMISSION_BOUNDARY'],
    DYNAMIC: ['GOAL', 'REASONING_STEP', 'INTERMEDIATE_STATE', 'EXECUTED_ACTION']
  },
  edgeTypes: {
    INVOKES: { direction: 'DYNAMIC_TO_STATIC', securityContext: true },
    MODIFIES: { direction: 'DYNAMIC_TO_STATIC', securityContext: true },
    REASON_ABOUT: { direction: 'DYNAMIC_TO_DYNAMIC', securityContext: false },
    TRUSTS: { direction: 'DYNAMIC_TO_DYNAMIC', securityContext: true },
    DERIVES_FROM: { direction: 'DYNAMIC_TO_DYNAMIC', securityContext: false }
  },
  securityAttributes: {
    required: ['authorization_level', 'session_id', 'timestamp'],
    optional: ['confidence_score', 'goal_alignment', 'origin_agent_id']
  },
  retention: {
    dynamicCompactionWindow: '24h',
    staticSnapshotInterval: '7d',
    auditTrailRetention: '1y'
  }
};

Quick Start Guide

1. Initialize the Graph Builder: Import the AgentAuditGraph class and instantiate it within your agent's execution loop. Configure node and edge types according to your schema.
2. Instrument the Reasoning Loop: Wrap your agent's decision-making function to emit REASONING_STEP nodes before each tool call. Attach goal context and confidence metrics.
3. Capture Capability Bindings: When the agent selects a tool or accesses memory, create an INVOKES or MODIFIES edge linking the dynamic action to the static capability. Populate security attributes.
4. Run Risk Queries: Execute queryRiskPath() against action nodes flagged by your monitoring system. Review returned edges for security flags, unexpected capability bindings, or cross-session contamination.
5. Persist & Alert: Stream high-risk paths to your SIEM. Configure automated alerts when traversal depth exceeds thresholds or when TRUSTS edges cross unauthorized agent boundaries.

Graph-driven observability transforms LLM agent security from reactive guesswork into deterministic auditability. By modeling execution as a hierarchical attributed graph, you gain path-level visibility into reasoning, capability bindings, and cross-agent trust relationships. Implement the schema, enforce strict edge typing, and query continuously. The semantic gap closes when you stop logging events and start mapping intent.