Skip to content

API reference

AgentLogger

AgentLogger(
    agent_name=None,
    workflow_name=None,
    sink=None,
    redact_payloads=True,
    redaction_config=None,
    default_risk=None,
    metadata=None,
)

run(input=None, metadata=None) returns a context manager and emits lifecycle events. emit(event_type, payload=None, **kwargs) writes a general event. See Events and runs for the specialized helpers.

trace_tool

@log.trace_tool("tool.name")
def function(argument):
    ...

Decorates a synchronous callable and emits tool_call, followed by tool_result or error. Return values and raised exceptions retain their original behavior.

trace_model_call

with log.trace_model_call("provider", "model") as trace:
    result = call_provider()
    trace.set_response(result)

Returns ModelCallTrace. Entering emits model_call; set_response(result) causes a model_response on normal exit. Exceptions emit error and are re-raised.

AgentEvent

The event dataclass accepts the fields described in the event schema. IDs and timestamps are generated when omitted. to_dict(), to_json(), and from_dict() support persistence and reconstruction.

redact

redact(value, config=None)

Returns a recursively redacted copy. Scalars remain scalars, tuples remain tuples, and sets become deterministically ordered lists suitable for JSON serialization.

RedactionConfig

Controls the replacement string, individual detector switches, and sensitive field names. All built-in detectors are enabled by default.

Sinks

  • JSONLSink(path) appends event JSON to a file.
  • MemorySink() exposes an events list.
  • NullSink() discards events.
  • BufferedSink(...) provides bounded background delivery.
  • AsyncJSONLSink(...) and AsyncBufferedSink(...) provide async write APIs.
  • EventSink is the runtime-checkable sink protocol.

StructuredLoggingSink and OpenTelemetrySink adapt events to standard telemetry infrastructure. See Logging and telemetry.

Context functions

Advanced integrations can use get_current_run_id(), set_current_run_id(), and reset_current_run_id() from agentlogsafe.context. Prefer AgentLogger.run() for normal application code so lifecycle events and restoration are handled together.

Exceptions

  • AgentLogSafeError: package exception base.
  • InvalidEventTypeError: rejected event type.
  • SinkError: built-in sink could not persist an event.
  • RedactionError: a value could not be safely traversed or transformed.