📝 agentlog

Structured logging and replay for AI agent executions.

An agent "run" is a sequence of steps — LLM calls, tool invocations, decisions, errors. agentlog records each as a structured event in an append-only JSON-Lines log, so you can replay, inspect, and analyze what an agent did: for debugging, evaluation, audit trails, and cost accounting.

Wrap your agent once at the boundaries; get a full, portable trace you can share, diff, or pipe into analysis. Zero hard dependencies.

Features

• 🧩 Structured events — LLM calls, tool calls, steps, errors, start/end, each with timestamp + monotonic seq
• 📜 Append-only JSONL — one run = one portable file; load, share, diff, version it
• ▶️ Replay — render a readable timeline of everything the agent did
• 📊 Summarize — token totals, latency, tool usage, error capture, run status
• 🪝 Ergonomic API — context manager auto-emits START/END; r.llm_call(...), r.tool_call(...)
• 🚫 Zero dependencies — pure stdlib; resilient (a tool error doesn't crash the trace)

Quick Start

pip install agentlog

Usage

Instrument an agent

from agentlog import record

with record(agent_name="research-bot", task="answer question", model="gpt-4o", path="run.jsonl") as r:
    r.llm_call(prompt="What is RAG?", response="Let me search.",
               input_tokens=8, output_tokens=4, latency_ms=110)
    r.tool_call(tool="web_search", args={"q": "rag"}, result=["doc1"], latency_ms=350)
    r.llm_call(prompt="synthesize", response="RAG combines retrieval+generation.",
               input_tokens=30, output_tokens=12, latency_ms=180)
    r.step(name="finalize", detail="done")

Replay & summarize from the CLI

agentlog show run.jsonl          # readable replay
agentlog summary run.jsonl       # aggregate stats
agentlog summary run.jsonl --json
agentlog tail run.jsonl -n 5     # last 5 events as JSON
agentlog tokens run1.jsonl run2.jsonl   # aggregate token usage

show output:

● Run a1b2c3 — research-bot  «answer question»  [gpt-4o]
  status: completed  events: 6  llm: 2  tools: 1  errors: 0

  [  1] 12:01:01 start research-bot
  [  2] 12:01:01 llm   'What is RAG?' 8+4tok (110ms)
  [  3] 12:01:01 tool  web_search (350ms)
  [  4] 12:01:02 llm   'synthesize' 30+12tok (180ms)
  [  5] 12:01:02 step  finalize: done
  [  6] 12:01:02 end   status=completed

  total tokens: 54 (in 38/out 16)  llm 290ms  tools 350ms
  tools: web_search×1

Programmatic API

from agentlog.replay import load, summarize

log = load("run.jsonl")
s = summarize(log)
print(s.total_tokens, s.n_tool_calls, s.status, s.tools_used)

Event kinds

Kind	Fields
start	agent_name, task, model, run_id, metadata
llm_call	prompt, response, model, input/output_tokens, latency_ms
tool_call	tool, args, result, error, latency_ms
step	name, detail, data
error	message, exception_type, traceback
end	status (completed/failed/cancelled), result

Development

git clone https://github.com/alvabillwu/agentlog.git
cd agentlog
pip install -e ".[dev]"
pytest -v
python examples/demo.py

License

MIT © alvabillwu