# Decision Log (/learning/stores/decision-log)



The Decision Log Store records decisions made by agents with reasoning, context, and outcomes. Useful for auditing agent behavior, debugging unexpected outcomes, and building feedback loops.

| Aspect              | Value                                                   |
| ------------------- | ------------------------------------------------------- |
| **Scope**           | Per agent                                               |
| **Persistence**     | Long-term                                               |
| **Default mode**    | Agentic (`DecisionLogConfig()` and `decision_log=True`) |
| **Supported modes** | Agentic only                                            |

## Setup [#setup]

```bash
pip install agno openai sqlalchemy "psycopg[binary]" pgvector
export OPENAI_API_KEY="your-api-key"
```

The examples use a local PostgreSQL database on port 5532. With Docker running, start it using:

<Steps>
    <Step title="Run PgVector">
      <CodeBlockTabs defaultValue="macOS / Linux">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="macOS / Linux">
            macOS / Linux
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="Windows">
            Windows
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="macOS / Linux">
          ```bash
          docker run -d \
            -e POSTGRES_DB=ai \
            -e POSTGRES_USER=ai \
            -e POSTGRES_PASSWORD=ai \
            -e PGDATA=/var/lib/postgresql \
            -v pgvolume:/var/lib/postgresql \
            -p 5532:5432 \
            --name pgvector \
            agnohq/pgvector:18
          ```
        </CodeBlockTab>

        <CodeBlockTab value="Windows">
          ```powershell
          docker run -d `
            -e POSTGRES_DB=ai `
            -e POSTGRES_USER=ai `
            -e POSTGRES_PASSWORD=ai `
            -e PGDATA=/var/lib/postgresql `
            -v pgvolume:/var/lib/postgresql `
            -p 5532:5432 `
            --name pgvector `
            agnohq/pgvector:18
          ```
        </CodeBlockTab>
      </CodeBlockTabs>
    </Step>
</Steps>

Later configuration fragments reuse the imports and `db` from the first complete example.

## Basic Usage [#basic-usage]

```python
from agno.agent import Agent
from agno.db.postgres import PostgresDb
from agno.learn import LearningMachine, DecisionLogConfig
from agno.models.openai import OpenAIResponses

db = PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")

agent = Agent(
    id="my-agent",
    model=OpenAIResponses(id="gpt-5.2"),
    db=db,
    learning=LearningMachine(
        decision_log=DecisionLogConfig(),  # defaults to LearningMode.AGENTIC
    ),
    instructions=[
        "When you make a significant choice, use log_decision to record it.",
        "Include your reasoning and alternatives you considered.",
    ],
)

agent.print_response(
    "I need help choosing between Python and JavaScript for web scraping.",
    session_id="session_1",
)

# View logged decisions
lm = agent.learning_machine
lm.decision_log_store.print(agent_id="my-agent", limit=5)
```

## Agentic Mode [#agentic-mode]

The agent receives tools to explicitly log decisions.

```python
from agno.learn import LearningMachine, LearningMode, DecisionLogConfig

agent = Agent(
    id="my-agent",
    model=OpenAIResponses(id="gpt-5.2"),
    db=db,
    learning=LearningMachine(
        decision_log=DecisionLogConfig(mode=LearningMode.AGENTIC),
    ),
)
```

Available tools: `log_decision`, `record_outcome`, `search_decisions`

The agent decides when a decision is significant enough to log.

## Logging Coverage [#logging-coverage]

The store records decisions the agent explicitly logs through its tools. It does not automatically record every tool call or response. Automatic processing is a no-op; use separate runtime tracing when you need a record of execution events.

## Data Model [#data-model]

| Field             | Description                                               |
| ----------------- | --------------------------------------------------------- |
| `id`              | Unique identifier (e.g., "dec\_abc123")                   |
| `decision`        | What was decided                                          |
| `reasoning`       | Why this decision was made                                |
| `decision_type`   | Category: tool\_selection, response\_style, clarification |
| `context`         | The situation that required a decision                    |
| `alternatives`    | Other options considered                                  |
| `confidence`      | How confident (0.0 to 1.0)                                |
| `outcome`         | What happened as a result                                 |
| `outcome_quality` | Was it good, bad, or neutral                              |
| `created_at`      | When the decision was made                                |

## Recording Outcomes [#recording-outcomes]

Update decisions with what actually happened to build feedback loops:

```python
lm = agent.learning_machine

# Via store directly; replace this ID with one returned by search or logging
lm.decision_log_store.update_outcome(
    decision_id="dec_abc123",
    outcome="User was satisfied with Python recommendation",
    outcome_quality="good",
)
```

Or the agent can use the `record_outcome` tool during conversation.

## Accessing Decisions [#accessing-decisions]

```python
lm = agent.learning_machine

# Search decisions
decisions = lm.decision_log_store.search(
    agent_id="my-agent",
    decision_type="tool_selection",
    days=7,
    limit=10,
)

for d in decisions:
    print(f"{d.decision}: {d.reasoning}")

# Debug output
lm.decision_log_store.print(agent_id="my-agent", limit=5)
```

## Context Injection [#context-injection]

Recent decisions are injected into the system prompt:

```
<decision_log>
Recent decisions:

- **Recommended Python over JavaScript**
  Reasoning: Web scraping libraries are more mature in Python
  Outcome: User was satisfied

- **Used web search for current info**
  Reasoning: Question about recent developments requires fresh data
</decision_log>
```

## Decision Types [#decision-types]

Common categories for organizing decisions:

| Type             | When to use                               |
| ---------------- | ----------------------------------------- |
| `tool_selection` | Choosing which tool to call               |
| `response_style` | Deciding how to format or phrase response |
| `clarification`  | Choosing to ask for more info             |
| `escalation`     | Deciding to defer to human                |
| `approach`       | Choosing between solution strategies      |

## Use Cases [#use-cases]

* **Auditing**: Review what decisions agents made and why
* **Debugging**: Understand unexpected behavior by examining reasoning
* **Learning**: Analyze outcome patterns to improve agent instructions
* **Feedback loops**: Record outcomes to identify successful patterns