feat: built-in JSONL trace exporter via Hook (issue #942)

[park338]

What

Implements a built-in, out-of-the-box local JSONL trace exporter for AgentScope-Java based on the existing Hook event system (issue #942).

This makes it easy to dump a complete “LLM conversation + execution trace” to a local file for offline debugging / incident review / attaching to issues, without requiring Studio or custom hook code for every user.

Why

When troubleshooting Agent runs, users often need a simple, local, offline, file-based trace that includes:

• user input and final agent output
• every reasoning input/output (PreReasoning/PostReasoning)
• optional streaming chunks (ReasoningChunk / ActingChunk)
• optional tool events (PreActing/PostActing)
• basic metadata (timestamp, agent info, run/turn/step id)
• optional trace/span id if OpenTelemetry is enabled

Existing options (JsonSession/Memory/Studio) are useful but not a direct substitute for a lightweight, portable audit log.

Changes

• Added built-in exporter:

  • agentscope-core/src/main/java/io/agentscope/core/hook/recorder/JsonlTraceExporter.java
  • Writes one JSON object per hook event line (JSONL)
  • Default events: PRE_CALL, POST_CALL, PRE_REASONING, POST_REASONING, PRE_ACTING, POST_ACTING, ERROR
  • Optional: .includeReasoningChunks(true), .includeActingChunks(true), .includeSummary(true), .includeSummaryChunks(true)
  • Best-effort by default (does not break agent execution on IO/serialization errors), configurable failFast(true)
  • Uses Reactor boundedElastic to avoid blocking agent execution threads
  • Attempts to attach trace_id/span_id via reflection when OpenTelemetry is present (no hard dependency)

• Added tests:

  • agentscope-core/src/test/java/io/agentscope/core/hook/recorder/JsonlTraceExporterTest.java

• Updated example to demonstrate usage:

  • agentscope-examples/quickstart/src/main/java/io/agentscope/examples/quickstart/HookExample.java
  • Adds exporter hook and uses try-with-resources to ensure flush/close

• Updated docs:

  • docs/en/task/hook.md
  • docs/zh/task/hook.md

Output Format (JSONL)

Each line contains common fields like:

• ts, event_type, agent_id, agent_name
• run_id, turn_id, step_id
• optional trace_id, span_id

And event-specific payloads, e.g.:

• input_messages (PreCall/PreReasoning/PreSummary)
• reasoning_message (PostReasoning)
• final_message (PostCall)
• tool_use / tool_result (Acting events)
• incremental_chunk / accumulated (chunk events)
• error_class / error_message / stacktrace (ErrorEvent)

How To Use

import io.agentscope.core.hook.recorder.JsonlTraceExporter;
import java.nio.file.Path;

try (JsonlTraceExporter exporter =
        JsonlTraceExporter.builder(Path.of("logs", "agentscope-trace.jsonl"))
                .includeReasoningChunks(true)
                .includeActingChunks(true)
                .build()) {
    ReActAgent agent = ReActAgent.builder()
            .name("Assistant")
            .model(model)
            .toolkit(toolkit)
            .hooks(List.of(exporter))
            .build();
}

[cla-assistant]

All committers have signed the CLA.

[codecov]

Codecov Report

❌ Patch coverage is 87.84530% with 22 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ntscope/core/hook/recorder/JsonlTraceExporter.java	87.84%	12 Missing and 10 partials ⚠️

📢 Thoughts on this report? Let us know!