# Agent Decision Tracing

## The Problem

Cannot trace agent decision-making process (strategy selection, tool use, reasoning steps), making it impossible to debug unexpected agent behavior.

### Symptoms

* ❌ Agent chose wrong RAG strategy (Redwood vs Cedar)
* ❌ Cannot see reasoning process
* ❌ Tool selection unexplained
* ❌ Strategy switch mid-conversation mysterious
* ❌ No audit trail of agent decisions

### Real-World Example

```
User: "How do I configure authentication?"

Agent behavior:
→ Uses Cedar strategy (context-aware)
→ Calls tool: get_user_context()
→ Retrieves 15 chunks
→ Switches to Redwood mid-response

Question: Why switch strategies?
→ No logging of decision process
→ Cannot debug
→ Cannot reproduce
```

***

## Deep Technical Analysis

### Agent Decision Points

**Strategy Selection:**

```
Agent must decide:
→ Redwood (standard RAG)
→ Cedar (context-aware)
→ Cypress (advanced agentic)

Decision factors:
→ Query complexity
→ Conversation history
→ User role/permissions
→ Available context

Log decision:
{
  "query": "...",
  "strategy_selected": "Cedar",
  "reasoning": "Complex query requiring user context",
  "confidence": 0.85
}
```

**Tool Selection:**

```
Agent has tools:
→ search_knowledge_base()
→ get_user_permissions()
→ query_database()
→ call_external_api()

Agent decides: Use search_knowledge_base() + get_user_permissions()

Log:
{
  "tools_available": [...],
  "tools_selected": ["search_knowledge_base", "get_user_permissions"],
  "reasoning": "Need both knowledge base and user context"
}
```

### Reasoning Chain Logging

**Step-by-Step Trace:**

```json
{
  "query": "Can Alice access Production DB?",
  "reasoning_chain": [
    {
      "step": 1,
      "thought": "Need to find Alice's team",
      "action": "search_knowledge_base('Alice team')",
      "result": "Alice is in Engineering team"
    },
    {
      "step": 2,
      "thought": "Need team's database access",
      "action": "search_knowledge_base('Engineering database access')",
      "result": "Engineering has access to Prod-DB"
    },
    {
      "step": 3,
      "thought": "Combine findings",
      "conclusion": "Yes, Alice can access Prod-DB (via Engineering team)"
    }
  ]
}
```

**Chain-of-Thought Visibility:**

```
Agent uses chain-of-thought prompting:
→ LLM outputs thinking process
→ Capture and log this

Example output:
"Let me think step-by-step:
1. Alice is in Engineering team (from doc_123)
2. Engineering team has Prod-DB access (from doc_456)
3. Therefore, Alice has access"

Log this intermediate reasoning
```

### Strategy Switch Detection

**Mid-Conversation Changes:**

```
Turn 1: Strategy = Redwood
Turn 2: Strategy = Cedar

Why switch?
→ Log trigger:
{
  "previous_strategy": "Redwood",
  "new_strategy": "Cedar",
  "trigger": "User asked follow-up requiring context",
  "timestamp": "..."
}

Enables debugging strategy oscillation
```

**Fallback Triggers:**

```
Agent tries Cedar:
→ Fails to find context
→ Falls back to Redwood

Log fallback:
{
  "attempted_strategy": "Cedar",
  "fallback_strategy": "Redwood",
  "reason": "User context unavailable",
  "attempt_duration_ms": 1500
}
```

### Decision Confidence Tracking

**Confidence Scores:**

```
Agent decisions have uncertainty:
{
  "strategy": "Cedar",
  "confidence": 0.75,
  "alternatives": [
    {"strategy": "Redwood", "score": 0.60},
    {"strategy": "Cypress", "score": 0.45}
  ]
}

Low confidence (< 0.70):
→ Flag for review
→ May indicate ambiguous query
→ Consider asking user for clarification
```

***

## How to Solve

**Log agent strategy selection with reasoning + trace tool calls (which tools, why, results) + capture chain-of-thought reasoning steps + monitor strategy switches and log triggers + track decision confidence scores + implement replay capability for agent decisions + alert on low-confidence decisions (< 0.70) + build agent decision timeline visualization + test decision quality with eval set.** See [Agent Tracing](/rag-scenarios-and-solutions/monitoring/agent-tracing.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.twig.so/rag-scenarios-and-solutions/monitoring/agent-tracing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.