Please make sure you read the contribution guide and file the issues in the right place.
Contribution guide.
🔴 Required Information
Is your feature request related to a specific problem?
When an agent misbehaves, adk-java has no way to produce a record of what happened that you can read
afterwards, diff against another run, or attach to a bug report. What was sent to the model and what
came back, each tool call and its result, the events the runner yielded - all of it goes out as log
lines, mixed in with everything else the process is printing. Nothing gathers one invocation into one
place.
adk-python closed that gap by shipping DebugLoggingPlugin, which writes one YAML document per
invocation to a file. adk-java has no equivalent.
Describe the Solution You'd Like
DebugLoggingPlugin in com.google.adk.plugins.debuglogging, registered on a Runner like any
other plugin, behaving as adk-python's does:
- record the user message, every LLM request and response, every tool call, result and error, every
event the runner yields, and — optionally — a snapshot of session state as the invocation ends;
- write one YAML document per invocation, appended to a file, so a session's invocations
accumulate in one readable artifact that can be attached to a bug report;
- curate rather than dump, as upstream does: tool declarations recorded as names only, inline
data as its mime type with the bytes omitted, grounding metadata as a boolean, requested auth
configs as a count;
- switch the session-state snapshot and full system instructions on or off per instance.
No existing class changes and no existing API changes. All twelve callbacks it needs are already
declared on Plugin, and every one of them is observe-only here: eleven return Maybe.empty(), and
afterRunCallback returns a Completable that only writes the file. None of them returns a value
that alters the run.
Impact on your work
When an agent does something unexpected, there is nothing to save and nothing to hand to someone
else. Not blocking, and there is no timeline — this is a parity gap, not an outage.
Willingness to contribute
Yes. A PR follows immediately after this issue: one new public plugin class plus supporting types in
a plugins.debuglogging subpackage, with tests. No existing file is modified, and no new dependency
is added — jackson-dataformat-yaml is already a compile-scope dependency of core.
🟡 Recommended Information
Describe Alternatives You've Considered
LoggingPlugin, which adk-java already has. It logs prose lines to slf4j while the run happens,
truncating what it prints. That is useful for watching a run go by, but what it produces cannot be
re-read as data, diffed between two runs, or attached to an issue. Complementary, not a replacement —
the same hooks, a different output.
ADK's tracing/telemetry. Spans answer "where did the time go" and are read in a tracing backend.
A debug trace answers "what was said, in order", is read in a text editor, and needs no backend.
ReplayPlugin and the recordings package in google-adk-dev. Closer in spirit, but it reads
recordings rather than writing them, and it targets deterministic playback rather than a document a
person reads. It also ships in a different artifact from core.
Write the plugin in application code. It works — the behavior above was built using public API
only. But it is a few hundred lines of serialization curation per application, it drifts from
upstream separately in each copy, and the parts that matter most (what to omit) are exactly the
parts each copy will get wrong differently.
Proposed API / Implementation
Registration needs no new API:
Runner runner =
new InMemoryRunner(
agent, "my-app", ImmutableList.of(new DebugLoggingPlugin(Path.of("adk_debug.yaml"))));All twelve hooks upstream overrides are already declared on Plugin, with compatible shapes -
for example, the two that carry the model exchange, and the one that does the writing:
default Maybe<LlmResponse> beforeModelCallback(
CallbackContext callbackContext, LlmRequest.Builder llmRequest)
default Maybe<LlmResponse> afterModelCallback(
CallbackContext callbackContext, LlmResponse llmResponse)
// returns Completable, so the file write need not block the caller
default Completable afterRunCallback(InvocationContext invocationContext)The class is written and tested; the PR carries it.
Please make sure you read the contribution guide and file the issues in the right place.
Contribution guide.
🔴 Required Information
Is your feature request related to a specific problem?
When an agent misbehaves, adk-java has no way to produce a record of what happened that you can read
afterwards, diff against another run, or attach to a bug report. What was sent to the model and what
came back, each tool call and its result, the events the runner yielded - all of it goes out as log
lines, mixed in with everything else the process is printing. Nothing gathers one invocation into one
place.
adk-pythonclosed that gap by shippingDebugLoggingPlugin, which writes one YAML document perinvocation to a file.
adk-javahas no equivalent.Describe the Solution You'd Like
DebugLoggingPluginincom.google.adk.plugins.debuglogging, registered on aRunnerlike anyother plugin, behaving as adk-python's does:
event the runner yields, and — optionally — a snapshot of session state as the invocation ends;
accumulate in one readable artifact that can be attached to a bug report;
data as its mime type with the bytes omitted, grounding metadata as a boolean, requested auth
configs as a count;
No existing class changes and no existing API changes. All twelve callbacks it needs are already
declared on
Plugin, and every one of them is observe-only here: eleven returnMaybe.empty(), andafterRunCallbackreturns aCompletablethat only writes the file. None of them returns a valuethat alters the run.
Impact on your work
When an agent does something unexpected, there is nothing to save and nothing to hand to someone
else. Not blocking, and there is no timeline — this is a parity gap, not an outage.
Willingness to contribute
Yes. A PR follows immediately after this issue: one new public plugin class plus supporting types in
a
plugins.debugloggingsubpackage, with tests. No existing file is modified, and no new dependencyis added —
jackson-dataformat-yamlis already a compile-scope dependency ofcore.🟡 Recommended Information
Describe Alternatives You've Considered
LoggingPlugin, which adk-java already has. It logs prose lines to slf4j while the run happens,truncating what it prints. That is useful for watching a run go by, but what it produces cannot be
re-read as data, diffed between two runs, or attached to an issue. Complementary, not a replacement —
the same hooks, a different output.
ADK's tracing/telemetry. Spans answer "where did the time go" and are read in a tracing backend.
A debug trace answers "what was said, in order", is read in a text editor, and needs no backend.
ReplayPluginand therecordingspackage ingoogle-adk-dev. Closer in spirit, but it readsrecordings rather than writing them, and it targets deterministic playback rather than a document a
person reads. It also ships in a different artifact from
core.Write the plugin in application code. It works — the behavior above was built using public API
only. But it is a few hundred lines of serialization curation per application, it drifts from
upstream separately in each copy, and the parts that matter most (what to omit) are exactly the
parts each copy will get wrong differently.
Proposed API / Implementation
Registration needs no new API:
All twelve hooks upstream overrides are already declared on
Plugin, with compatible shapes -for example, the two that carry the model exchange, and the one that does the writing:
The class is written and tested; the PR carries it.