Sagents.Middleware.DebugLog (Sagents v0.8.0-rc.3)

Copy Markdown

Middleware that writes detailed, structured logs to per-conversation log files.

Captures the full lifecycle of agent execution -- every message, tool call, state change, and error -- in a dedicated, readable log file. Each conversation gets its own log file, separate from application logs.

Usage

Place DebugLog first in the middleware stack so before_model sees raw state and after_model sees the final processed state:

middleware: [
  {Sagents.Middleware.DebugLog, [log_dir: "tmp/agent_logs"]},
  TodoList,
  FileSystem,
  # ...
]

Configuration

  • :enabled - Enable or disable logging (default: true). When false, all callbacks become noops -- no files are created and no I/O occurs. Useful for keeping the middleware in the stack but disabling it in non-dev environments.
  • :log_dir - Directory for log files (default: "tmp/agent_logs")
  • :prefix - Filename prefix (default: "debug")
  • :log_deltas - Log streaming deltas? (default: false)
  • :pretty - Pretty-print inspect output? (default: true)
  • :inspect_limit - Inspect limit for large structs (default: :infinity)

Disabling in Production

Since Mix.env() is not available in compiled releases, use application config:

# config/dev.exs (or simply omit -- defaults to true)
config :my_app, :debug_logging, true

# config/prod.exs
config :my_app, :debug_logging, false

# In your middleware stack
{Sagents.Middleware.DebugLog, [enabled: Application.compile_env(:my_app, :debug_logging, false)]}

Log File Naming

{log_dir}/{prefix}_{start_timestamp}_{agent_id}.log

The timestamp comes first so that log files sort chronologically when listed alphabetically. The timestamp is captured when the middleware initializes, so a server restart produces a new log file.