Skip to content

Commit 71ed59e

Browse files
committed
feat(plugins): port DebugLoggingPlugin from adk-python
1 parent 5d8ef10 commit 71ed59e

21 files changed

Lines changed: 3530 additions & 0 deletions
Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
/*
2+
* Copyright 2026 Google LLC
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package com.google.adk.plugins.debuglogging;
18+
19+
import static com.google.common.collect.ImmutableList.toImmutableList;
20+
import static java.util.function.Predicate.not;
21+
22+
import com.fasterxml.jackson.annotation.JsonIgnore;
23+
import com.fasterxml.jackson.annotation.JsonInclude;
24+
import com.fasterxml.jackson.annotation.JsonProperty;
25+
import com.google.common.collect.ImmutableList;
26+
import com.google.common.collect.ImmutableMap;
27+
import com.google.genai.types.Blob;
28+
import com.google.genai.types.CodeExecutionResult;
29+
import com.google.genai.types.Content;
30+
import com.google.genai.types.ExecutableCode;
31+
import com.google.genai.types.FileData;
32+
import com.google.genai.types.FunctionCall;
33+
import com.google.genai.types.FunctionResponse;
34+
import com.google.genai.types.Part;
35+
import java.util.Optional;
36+
import java.util.stream.Stream;
37+
38+
/**
39+
* One {@link Content} as it appears in the trace — port of adk-python's {@code _serialize_content}.
40+
*
41+
* <p>The factory requires a content; callers holding an {@code Optional<Content>} use {@link
42+
* Optional#map} rather than passing null.
43+
*/
44+
@JsonInclude(JsonInclude.Include.NON_ABSENT)
45+
record ContentTrace(Optional<String> role, ImmutableList<PartTrace> parts) {
46+
47+
/** Always produced — an empty part list is still worth recording, as in the original. */
48+
static ContentTrace from(Content content) {
49+
return new ContentTrace(content.role(), traceParts(content));
50+
}
51+
52+
private static ImmutableList<PartTrace> traceParts(Content content) {
53+
return content.parts().orElseGet(ImmutableList::of).stream()
54+
.map(PartTrace::from)
55+
.flatMap(Optional::stream)
56+
.collect(toImmutableList());
57+
}
58+
59+
/**
60+
* One {@link Part} as it appears in the trace — the declared shape of the per-part dict that
61+
* adk-python builds in {@code _serialize_content}.
62+
*
63+
* <p>The record <em>is</em> the schema: the field names are the trace's keys, and a part kind
64+
* that is not declared here cannot appear in the output.
65+
*/
66+
@JsonInclude(JsonInclude.Include.NON_ABSENT)
67+
record PartTrace(
68+
Optional<String> text,
69+
@JsonProperty("function_call") Optional<FunctionCallTrace> functionCall,
70+
@JsonProperty("function_response") Optional<FunctionResponseTrace> functionResponse,
71+
@JsonProperty("inline_data") Optional<InlineDataTrace> inlineData,
72+
@JsonProperty("file_data") Optional<FileDataTrace> fileData,
73+
@JsonProperty("code_execution_result") Optional<CodeExecutionResultTrace> codeExecutionResult,
74+
@JsonProperty("executable_code") Optional<ExecutableCodeTrace> executableCode) {
75+
76+
/**
77+
* The part's trace form, or empty when it carries nothing worth recording — adk-python's {@code
78+
* if part_data:} guard.
79+
*/
80+
static Optional<PartTrace> from(Part part) {
81+
PartTrace trace =
82+
new PartTrace(
83+
part.text().filter(not(String::isEmpty)),
84+
part.functionCall().map(FunctionCallTrace::from),
85+
part.functionResponse().map(FunctionResponseTrace::from),
86+
part.inlineData().map(InlineDataTrace::from),
87+
part.fileData().map(FileDataTrace::from),
88+
part.codeExecutionResult().map(CodeExecutionResultTrace::from),
89+
part.executableCode().map(ExecutableCodeTrace::from));
90+
return trace.isEmpty() ? Optional.empty() : Optional.of(trace);
91+
}
92+
93+
/** Whether every declared field is absent, so the part would serialize to {@code {}}. */
94+
@JsonIgnore
95+
boolean isEmpty() {
96+
return Stream.of(
97+
text,
98+
functionCall,
99+
functionResponse,
100+
inlineData,
101+
fileData,
102+
codeExecutionResult,
103+
executableCode)
104+
.allMatch(Optional::isEmpty);
105+
}
106+
107+
/**
108+
* A tool call the model requested.
109+
*
110+
* <p>{@code args} stays untyped because it genuinely is: a tool author chooses the argument
111+
* shape, so there is no schema to declare. It goes through {@link SafeSerializer} for the same
112+
* reason adk-python routes it through {@code _safe_serialize}.
113+
*/
114+
@JsonInclude(JsonInclude.Include.NON_ABSENT)
115+
record FunctionCallTrace(
116+
Optional<String> id,
117+
Optional<String> name,
118+
@JsonInclude(JsonInclude.Include.NON_EMPTY) ImmutableMap<String, Object> args) {
119+
120+
static FunctionCallTrace from(FunctionCall call) {
121+
return new FunctionCallTrace(
122+
call.id(),
123+
call.name(),
124+
call.args().map(SafeSerializer::serializeMap).orElseGet(ImmutableMap::of));
125+
}
126+
}
127+
128+
/**
129+
* What a tool returned.
130+
*
131+
* <p>{@code response} is untyped for the same reason as {@link FunctionCallTrace#args()}, and
132+
* is contained by {@link SafeSerializer}, which is not optional here: the stock mapper throws
133+
* on a perfectly legal tool result.
134+
*/
135+
@JsonInclude(JsonInclude.Include.NON_ABSENT)
136+
record FunctionResponseTrace(
137+
Optional<String> id,
138+
Optional<String> name,
139+
@JsonInclude(JsonInclude.Include.NON_EMPTY) ImmutableMap<String, Object> response) {
140+
141+
static FunctionResponseTrace from(FunctionResponse functionResponse) {
142+
return new FunctionResponseTrace(
143+
functionResponse.id(),
144+
functionResponse.name(),
145+
functionResponse
146+
.response()
147+
.map(SafeSerializer::serializeMap)
148+
.orElseGet(ImmutableMap::of));
149+
}
150+
}
151+
152+
/**
153+
* What an inline blob <em>is</em> — never what it contains.
154+
*
155+
* <p>This record has no field for the bytes, which is the point. adk-python drops them by
156+
* choosing not to copy them into a dict, commenting "Omit actual data to keep file size
157+
* manageable"; here the omission is structural, so a later edit cannot reintroduce a base64
158+
* wall by accident.
159+
*/
160+
@JsonInclude(JsonInclude.Include.NON_ABSENT)
161+
record InlineDataTrace(
162+
@JsonProperty("mime_type") Optional<String> mimeType,
163+
@JsonProperty("display_name") Optional<String> displayName,
164+
@JsonProperty("_data_omitted") boolean dataOmitted) {
165+
166+
static InlineDataTrace from(Blob blob) {
167+
return new InlineDataTrace(blob.mimeType(), blob.displayName(), true);
168+
}
169+
}
170+
171+
/** A file reference carried by a part. */
172+
@JsonInclude(JsonInclude.Include.NON_ABSENT)
173+
record FileDataTrace(
174+
@JsonProperty("file_uri") Optional<String> fileUri,
175+
@JsonProperty("mime_type") Optional<String> mimeType) {
176+
177+
static FileDataTrace from(FileData fileData) {
178+
return new FileDataTrace(fileData.fileUri(), fileData.mimeType());
179+
}
180+
}
181+
182+
/** The outcome of an executed code block. */
183+
@JsonInclude(JsonInclude.Include.NON_ABSENT)
184+
record CodeExecutionResultTrace(Optional<String> outcome, Optional<String> output) {
185+
186+
static CodeExecutionResultTrace from(CodeExecutionResult result) {
187+
return new CodeExecutionResultTrace(result.outcome().map(String::valueOf), result.output());
188+
}
189+
}
190+
191+
/** A code block the model asked to run. */
192+
@JsonInclude(JsonInclude.Include.NON_ABSENT)
193+
record ExecutableCodeTrace(Optional<String> language, Optional<String> code) {
194+
195+
static ExecutableCodeTrace from(ExecutableCode executableCode) {
196+
return new ExecutableCodeTrace(
197+
executableCode.language().map(String::valueOf), executableCode.code());
198+
}
199+
}
200+
}
201+
}
Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
/*
2+
* Copyright 2026 Google LLC
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package com.google.adk.plugins.debuglogging;
18+
19+
import com.fasterxml.jackson.annotation.JsonInclude;
20+
import com.fasterxml.jackson.annotation.JsonProperty;
21+
import com.fasterxml.jackson.annotation.JsonValue;
22+
import com.google.common.base.Preconditions;
23+
import java.util.Optional;
24+
25+
/**
26+
* One line of the trace — port of adk-python's {@code _DebugEntry}.
27+
*
28+
* <p>Everything but {@code data} is the same for every entry; {@code data} is what {@link
29+
* TracePayload} models. Note that {@code agentName} is an entry field rather than payload, which is
30+
* why {@code agent_end} can carry {@link TracePayload.MarkerTrace} and still name an agent.
31+
*
32+
* <p>Component order is the serialized order, and matches upstream's field declaration.
33+
*/
34+
@JsonInclude(JsonInclude.Include.NON_ABSENT)
35+
record DebugEntry(
36+
String timestamp,
37+
@JsonProperty("entry_type") Type entryType,
38+
@JsonProperty("invocation_id") String invocationId,
39+
@JsonProperty("agent_name") Optional<String> agentName,
40+
TracePayload data) {
41+
42+
/**
43+
* These components come from a caller's arguments rather than from an ADK object, so they are
44+
* worth guarding: a null here would not fail until the YAML write, on a different thread, long
45+
* after the hook that caused it returned.
46+
*/
47+
DebugEntry {
48+
Preconditions.checkNotNull(timestamp);
49+
Preconditions.checkNotNull(entryType);
50+
Preconditions.checkNotNull(invocationId);
51+
Preconditions.checkNotNull(agentName);
52+
Preconditions.checkNotNull(data);
53+
}
54+
55+
/**
56+
* The kinds of entry, with the wire names upstream writes as bare strings.
57+
*
58+
* <p>An enum rather than a {@code String}: a typo in one of these would produce a
59+
* plausible-looking file that silently does not match adk-python's.
60+
*/
61+
enum Type {
62+
INVOCATION_START("invocation_start"),
63+
USER_MESSAGE("user_message"),
64+
AGENT_START("agent_start"),
65+
AGENT_END("agent_end"),
66+
LLM_REQUEST("llm_request"),
67+
LLM_RESPONSE("llm_response"),
68+
LLM_ERROR("llm_error"),
69+
TOOL_CALL("tool_call"),
70+
TOOL_RESPONSE("tool_response"),
71+
TOOL_ERROR("tool_error"),
72+
EVENT("event"),
73+
SESSION_STATE_SNAPSHOT("session_state_snapshot"),
74+
INVOCATION_END("invocation_end");
75+
76+
private final String wireName;
77+
78+
Type(String wireName) {
79+
this.wireName = wireName;
80+
}
81+
82+
@JsonValue
83+
String wireName() {
84+
return wireName;
85+
}
86+
}
87+
}

0 commit comments

Comments
 (0)