autourgos-history

Agent execution history middleware for the Autourgos framework.

Attach it to any Autourgos agent and every run is automatically recorded: every Thought, every Tool Call, every Observation, and the Final Answer — written to a Markdown file and a structured JSON file.

Sensitive values (API keys, tokens, passwords) are automatically redacted before writing.

Zero required dependencies. Pure Python 3.10+.

Why use this?

When you build agents, you need to know what they did. This middleware gives you a complete, readable audit trail of every agent run without adding any code to your agent logic.

• Debug — see exactly where the agent went wrong
• Audit — keep records of every tool call and its inputs
• Monitor — review agent reasoning in plain English
• Privacy — choose exactly what gets logged with per-field flags

Table of Contents

• Install
• Quick Start
• Output Files
• Privacy Controls
• Custom File Location
• Using with ReactAgent
• Using with Any Agent
• Flushing Logs
• Constructor Reference
• Markdown Output Format
• JSON Output Format
• Redaction Rules
• Thread Safety

Install

pip install autourgos-history

Requires Python 3.10+. No other dependencies.

Quick Start

This example constructs an OpenAIChatModel, so set the OPENAI_API_KEY environment variable first (or pass api_key= directly).

from autourgos_history     import AgentHistoryMiddleware
from autourgos_react_agent import ReactAgent
from autourgos_openaichat  import OpenAIChatModel

def my_tool(city: str) -> str:
    """Look up the weather for a city."""
    return f"The weather in {city} is 22C and sunny."

history = AgentHistoryMiddleware(
    include_query=True,
    include_tools=True,
    include_observations=True,
    include_final=True,
)

agent = ReactAgent(
    llm=OpenAIChatModel(model="gpt-4o"),
    middleware=[history],
)
agent.add_tools(my_tool)

result = agent.invoke("What is the weather in Tokyo?")
print(result)
# The weather in Tokyo is 22°C and sunny.

After the run, two files appear in ./Agent History/:

Agent History/
├── Task_20260616_120000_abc12345.md    ← human-readable Markdown
└── Task_20260616_120000_abc12345.json  ← structured JSON

If agent is a ReactAgent(verbose=True) (requires autourgos-react-agent>=1.5.0), one line announcing the file path is printed once per run, at the start, into the same verbose trace — nothing is printed per-iteration:

[History] Logging this run to ./Agent History/Task_20260616_120000_abc12345.md

Output Files

Markdown file (.md)

Human-readable. Open in any editor or Markdown viewer.

# Task Session: ReactAgent
**Started At:** 2026-06-16 12:00:00

## Initial Query
What is the weather in Tokyo?

---

## Iteration 1

### Thought
I need to call the get_weather tool to find the weather in Tokyo.

### Action (Tools)
**Tool:** `get_weather`
**Parameters:**
```json
{
  "city": "Tokyo",
  "unit": "celsius"
}

Observations

get_weather: "The weather in Tokyo is 22°C and sunny."

Final Answer

The weather in Tokyo is 22°C and sunny.

### JSON file (`.json`)

Structured. Use for programmatic processing, dashboards, or storage.

```json
{
  "query": "What is the weather in Tokyo?",
  "agent_name": "ReactAgent",
  "start_time": "2026-06-16T12:00:00.123456",
  "end_time":   "2026-06-16T12:00:02.456789",
  "iterations": [
    {
      "iteration": 1,
      "thought": "I need to call the get_weather tool...",
      "tools": [
        {"tool": "get_weather", "params": {"city": "Tokyo", "unit": "celsius"}}
      ],
      "observations": [
        {"tool": "get_weather", "result": "The weather in Tokyo is 22°C and sunny."}
      ]
    }
  ],
  "final_response": "The weather in Tokyo is 22°C and sunny.",
  "error": null
}

Privacy Controls

By default, content is redacted — you see the structure but not the values. Enable fields individually:

history = AgentHistoryMiddleware(
    include_query=False,        # user query    → [REDACTED: length=32]
    include_tools=True,         # tool params   → written as JSON
    include_observations=True,  # tool results  → written as JSON
    include_final=True,         # final answer  → written as text
)

Even with all flags set to True, automatic redaction still applies to sensitive keys and values. See Redaction Rules.

Custom File Location

Save to a specific folder

history = AgentHistoryMiddleware(folder="/var/log/agents")
# writes: /var/log/agents/Task_20260616_120000_abc12345.md
#         /var/log/agents/Task_20260616_120000_abc12345.json

Save with a specific filename

history = AgentHistoryMiddleware(file_path="run_001.md")
# writes: ./run_001.md
#         ./run_001.json

Combine folder + filename

history = AgentHistoryMiddleware(
    folder="/var/log/agents",
    file_path="my_task.md",
)
# writes: /var/log/agents/my_task.md
#         /var/log/agents/my_task.json

Default (no arguments)

Files are auto-named and saved to ./Agent History/ in your working directory.

Using with ReactAgent

from autourgos_history     import AgentHistoryMiddleware
from autourgos_react_agent import ReactAgent
from autourgos_openaichat  import OpenAIChatModel

def search(query: str) -> str:
    return f"Search results for: {query}"

search_tool = {
    "name": "search",
    "description": "Search the web.",
    "parameters": {
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "Search terms"}
        },
        "required": ["query"],
    },
    "func": search,
}

history = AgentHistoryMiddleware(
    include_query=True,
    include_tools=True,
    include_observations=True,
    include_final=True,
)

agent = ReactAgent(
    llm=OpenAIChatModel(model="gpt-4o"),
    middleware=[history],
)
agent.add_tools(search_tool)

result = agent.invoke("Find the latest Python release notes.")
print(result)

# history.flush() — optional, ensures files are fully written before process exits

Using with Any Agent

AgentHistoryMiddleware is a CallbackHandler. Any agent that accepts middleware / callback handlers will work.

Add it at construction time:

agent = MyAgent(llm=llm, middleware=[AgentHistoryMiddleware()])

Or after construction:

agent.add_middleware(AgentHistoryMiddleware())

The middleware listens for these lifecycle events fired by the agent:

Flushing Logs

File I/O is async (dispatched to a background thread). If your process might exit immediately after invoke(), call flush() to wait for all writes to complete:

result = agent.invoke("My task")
history.flush()  # wait for files to finish writing

This is rarely needed in long-running applications but important in scripts and tests.

Constructor Reference

Markdown Output Format

# Task Session: <AgentName>
**Started At:** YYYY-MM-DD HH:MM:SS

## Initial Query
<query or [REDACTED: length=N]>

---

## Iteration 1

### Thought
<LLM reasoning>

### Action (Tools)
**Tool:** `tool_name`
**Parameters:**
```json
{ ... }

Observations

tool_name: <result or [REDACTED]>

Final Answer

<answer or [REDACTED]>

---

## JSON Output Format

```json
{
  "query":          "string | null",
  "agent_name":     "string",
  "start_time":     "ISO 8601 datetime",
  "end_time":       "ISO 8601 datetime",
  "iterations": [
    {
      "iteration":    1,
      "thought":      "string | null",
      "tools": [
        {"tool": "tool_name", "params": { ... }}
      ],
      "observations": [
        {"tool": "tool_name", "result": "string"}
      ]
    }
  ],
  "final_response": "string | null",
  "error":          "string | null"
}

Redaction Rules

Applied automatically before any write, regardless of include_* flags.

By key name

Keys matching this pattern (case-insensitive) have their value replaced with [REDACTED]:

api_key, api-key, token, secret, password,
authorization, cookie, session, credential

Example:

{"api_key": "sk-abc123"}  →  {"api_key": "[REDACTED]"}

By value shape

Values that look like secrets are replaced regardless of key name:

By length

String values longer than 512 characters are truncated:

"very long text..." → "first 512 chars... [TRUNCATED]"

Thread Safety

Each concurrent agent call gets its own thread-local state — query, iteration data, file paths, and the logger are all isolated per thread. Multiple agents can run concurrently with the same AgentHistoryMiddleware instance and their logs will never mix.

All disk writes are dispatched to a single-worker background executor per middleware instance, keeping agent execution fast and preventing file corruption from concurrent writes.

License

MIT — Copyright (c) 2026 Jitin Kumar Sengar