fix(adk): annotate serialize_metadata_value as str | dict by anxkhn · Pull Request #2173 · kagent-dev/kagent

anxkhn · 2026-07-07T08:00:55Z

What

serialize_metadata_value in python/packages/kagent-adk/src/kagent/adk/converters/event_converter.py accepted arbitrary metadata values, but its annotation and docstring said it always returned str. Pydantic values were already returned as dict objects through model_dump(...), and that structured metadata is intentional because consumers such as the UI read fields like token usage directly.

Fix

Update the helper contract to return str | dict[str, Any] and document the structured metadata behavior. For Pydantic values, keep returning a dict, but serialize with model_dump(mode="json", exclude_none=True, by_alias=True) so the metadata is JSON-compatible, omits None fields, and preserves aliases. Non-Pydantic values still fall back to str(value).

Tests

Expanded TestSerializeMetadataValue to cover:

structured Pydantic metadata staying as a dict,
aliases via by_alias=True,
omitted None fields via exclude_none=True,
enum values serialized in JSON mode, and
plain values still serializing to strings.

Verification:

cd python && uv run ruff format packages/kagent-adk/src/kagent/adk/converters/event_converter.py packages/kagent-adk/tests/unittests/converters/test_event_converter.py
cd python && uv run ruff check packages/kagent-adk/src/kagent/adk/converters/event_converter.py packages/kagent-adk/tests/unittests/converters/test_event_converter.py
cd python && uv run pytest packages/kagent-adk/tests/unittests/ -> 341 passed, 1 skipped
cd python && uv run pytest packages/kagent-adk/tests/unittests/converters/test_event_converter.py -> 4 passed

Copilot

Pull request overview

This PR fixes serialize_metadata_value in the ADK event converter so it consistently returns a str for Pydantic model inputs, aligning behavior with its type annotation/docstring and avoiding injecting dict objects into A2A event metadata.

Changes:

Wrap value.model_dump(...) with str(...) when serializing Pydantic values.
Add unit tests covering Pydantic-model and plain-value serialization behavior.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
python/packages/kagent-adk/src/kagent/adk/converters/event_converter.py	Ensures Pydantic `model_dump()` output is coerced to `str` to match function contract and metadata expectations.
python/packages/kagent-adk/tests/unittests/converters/test_event_converter.py	Adds tests validating string output for both Pydantic and non-Pydantic inputs.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

supreme-gg-gg

There's nothing wrong with returning dict here. A2A metadata allows them and they are needed in the frontend to properly show things like token usage:

kagent/ui/src/lib/messageHandlers.ts

Lines 390 to 398 in 3eff08b

    
           function getMessageTokenStats(metadata: Record<string, unknown> | undefined): TokenStats | undefined { 
        
             const usage = getMetadataValue<ADKMetadata["kagent_usage_metadata"]>(metadata, "usage_metadata"); 
        
             if (!usage) return undefined; 
        
             return { 
        
               total: usage.totalTokenCount ?? 0, 
        
               prompt: usage.promptTokenCount ?? 0, 
        
               completion: usage.candidatesTokenCount ?? 0, 
        
             }; 
        
           }

A better fix would be to update the type annotation to str | dict[str, Any] and the docstring.

If you trace the langgraph example you cited, you will find that even though serialize_metadata_value does return string it is in fact never used in the converter with any metadata, so it's effectively dead code.

supreme-gg-gg · 2026-07-08T20:59:58Z

@anxkhn pls update PR title and description

serialize_metadata_value was annotated -> str, but values with a model_dump attribute intentionally serialize to a dict. A2A message metadata accepts structured values, and consumers rely on them for fields such as usage_metadata token counts, so coercing Pydantic values to a string would break that usage. Fix the contract instead of the value: annotate the return as str | dict[str, Any] and update the docstring to describe both cases. Use model_dump(mode="json", exclude_none=True, by_alias=True) so returned Pydantic dicts remain JSON-compatible while preserving aliases and excluding null fields. Add regression coverage for structured Pydantic metadata, including aliases, omitted nulls, and enum serialization, plus the plain-value string fallback. Signed-off-by: Anas Khan <[email protected]>

anxkhn · 2026-07-09T16:46:32Z

Updated the title and description to reflect the structured metadata fix.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

@yanivmn

kagent 0.10.0 Created-by: HarmonybrewBot Commit-by: HarmonybrewBot Merged-by: HarmonybrewBot Description: Created by `brew bump` --- Created with `brew bump-formula-pr`.<details> <summary>release notes</summary> <pre> ## What's Changed ### Features * feat(streaming): configurable nginx, controller, and UI inactivity ti… by @yanivmn in kagent-dev/kagent#1973 * feat(helm): add controller service annotations by @anthonyhaussman in kagent-dev/kagent#2088 * feat: enable sharing of chat sessions by @onematchfox in kagent-dev/kagent#1935 * feat: substrate support for BYO and python runtimes for SandboxAgent CR by @jmhbh in kagent-dev/kagent#2043 * feat(substrate): bump agent substrate to 0.0.7 by @supreme-gg-gg in kagent-dev/kagent#2109 * feat(substrate): bump agent substrate to 0.0.8 by @jjamroga in kagent-dev/kagent#2140 * feat(helm/kagent): support deployment annotations by @anthonyhaussman in kagent-dev/kagent#2143 * feat: add nodeSelector support to agent helm charts by @the-mentor in kagent-dev/kagent#2145 * feat: expose icon, provider, documentation URL and version on agent A2A card by @QuentinBisson in kagent-dev/kagent#2188 * feat: add claude ACP sandbox target by @the-mentor in kagent-dev/kagent#2189 * feat(sandbox-agents): Store session state in `durableDir` volume for declarative sandbox agents by @jmhbh in kagent-dev/kagent#2171 * feat(helm): add UI HTTPRoute by @younsl in kagent-dev/kagent#2165 * feat(helm): bump bundled oauth2-proxy subchart to ~10.7.0 by @elihai-risk in kagent-dev/kagent#2254 * feat: default nodeSelector for agent deployments (--default-agent-node-selector) by @elihai-risk in kagent-dev/kagent#2259 * feat(helm): add podLabels for controller and UI pod templates by @elihai-risk in kagent-dev/kagent#2237 * feat(helm): add extraObjects for arbitrary manifests by @younsl in kagent-dev/kagent#2174 * feat(ui-test): Playwright ui tests foundation stage 0 by @cjlg-soloio in kagent-dev/kagent#2262 * feat: allow read-only shares to read A2A tasks by @QuentinBisson in kagent-dev/kagent#2191 * feat(controller): make Go (ADK) runtime agent image independently configurable by @QuentinBisson in kagent-dev/kagent#2021 * feat(helm): allow custom annotations on the default ModelConfig by @marians in kagent-dev/kagent#2201 * feat(ui-test): Playwright UI E2E suite — helpers + feature flows (stage 2) by @cjlg-soloio in kagent-dev/kagent#2264 * feat: serve A2A ListTasks from the task store by @QuentinBisson in kagent-dev/kagent#2187 * feat(models): add maxCompletionTokens for OpenAI by @anthonytwh in kagent-dev/kagent#2175 * feat(models): wire maxOutputTokens for native Gemini and Vertex by @anthonytwh in kagent-dev/kagent#2147 * feat: add envFrom support to agent deployment spec by @uncycler in kagent-dev/kagent#2321 * feat: add native AWS Bedrock Guardrails support to ModelConfig by @sanskar-singh-2403 in kagent-dev/kagent#2323 * feat(bedrock): configurable Bedrock read/connect timeout by @go-faustino in kagent-dev/kagent#2223 * feat: add deploymentAnnotations to agent deployment spec by @anthonyhaussman in kagent-dev/kagent#2359 * feat(helm/kagent): allow disabling default modelconfig by @anthonyhaussman in kagent-dev/kagent#2142 * feat(sts): send RFC 8707 resource and audience on token exchange by @QuentinBisson in kagent-dev/kagent#2106 * feat(sts): send RFC 8707 resource and audience on token exchange (Python) by @QuentinBisson in kagent-dev/kagent#2107 * Backport of 2407 (pg connection) to 0.10.x release by @supreme-gg-gg in kagent-dev/kagent#2399 * Backport 2409 (db session cleanup) to 0.10.x release by @supreme-gg-gg in kagent-dev/kagent#2403 * Backport of 2408 (s3 skills) to 0.10.x release by @supreme-gg-gg in kagent-dev/kagent#2405 * feat: configurable refresh interval for tool server controllers by @supreme-gg-gg in kagent-dev/kagent#2480 * feat: support file upload in agent chat by @supreme-gg-gg in kagent-dev/kagent#2429 ### Bug Fixes * fix(ui): chat interface overflows viewport causing input to be hidden below fold by @onematchfox in kagent-dev/kagent#2081 * fix(ui): avoid false stale chat send guard by @erauner12 in kagent-dev/kagent#2034 * fix(go-adk): extract system prompt from genai.GenerateContentConfig in Ollama and Bedrock model providers by @supreme-gg-gg in kagent-dev/kagent#2118 * fix(helm): support omitting image.registry in grafana-mcp chart by @michaelspinks in kagent-dev/kagent#2125 * fix(helm): support omitting image.registry in querydoc chart by @michaelspinks in kagent-dev/kagent#2124 * fix(security): patch CRITICAL/HIGH CVEs in golang-adk-full and app images by @jsonmp-k8 in kagent-dev/kagent#2133 * fix(go-adk): openai embeddings generation by @supreme-gg-gg in kagent-dev/kagent#2132 * fix(helm): omit empty repository segment in bundled image path by @michaelspinks in kagent-dev/kagent#2120 * fix: intermittent Postgres deadlock for concurrent memory searches by @supreme-gg-gg in kagent-dev/kagent#2146 * fix(deps): bump google-adk to 1.32.0 for Anthropic thinking blocks by @anxkhn in kagent-dev/kagent#2172 * fix: fix typos in part_converter comments by @mesutoezdil in kagent-dev/kagent#2195 * fix(adk): annotate serialize_metadata_value as str | dict by @anxkhn in kagent-dev/kagent#2173 * fix(ui): fix model name editing on the model config form by @Valyrian-Code in kagent-dev/kagent#1979 * fix: correct package comment in v1alpha2 groupversion_info by @mesutoezdil in kagent-dev/kagent#2183 * fix(crewai): unwrap Part before DataPart check so structured inputs are used by @anxkhn in kagent-dev/kagent#2231 * fix(helm): expose nodeSelector and tolerations for kagent-tools subchart by @the-mentor in kagent-dev/kagent#2213 * fix(helm): make the cluster DNS domain configurable by @shekhargit1912 in kagent-dev/kagent#2209 * fix: parse migration filenames the same way golang-migrate does by @mesutoezdil in kagent-dev/kagent#2194 * fix: build sandbox runtime outside QEMU emulation by @peterj in kagent-dev/kagent#2299 * fix: set kgateway.dev/a2a as appProtoco for BYO agents by @supreme-gg-gg in kagent-dev/kagent#2305 * fix(db): normalize agent name in memory vector search by @mesutoezdil in kagent-dev/kagent#2307 * fix(adk/bedrock): coerce nil tool-call args to empty object by @go-faustino in kagent-dev/kagent#2222 * fix: correct webhook typo in CLI help text by @tziyon31 in kagent-dev/kagent#2203 * fix(build): use AZURE_OPENAI_API_KEY env var name consistently by @mesutoezdil in kagent-dev/kagent#2310 * fix(security): scope task get, create, and delete to the owner by @mesutoezdil in kagent-dev/kagent#2265 * fix(adk): keep token refresh loop alive after a failed read by @mesutoezdil in kagent-dev/kagent#2330 * fix(acp-shim): drain child stdout during terminate to avoid teardown deadlock by @tomsen02 in kagent-dev/kagent#2338 * fix(adk): keep full session state when num_recent_events is set by @mesutoezdil in kagent-dev/kagent#2329 * fix(controller): wire up SessionSharesHandler in NewHandlers (#2363) by @onematchfox in kagent-dev/kagent#2420 * fix: ensure API key passthrough works for OpenAI embedding models by @onematchfox in kagent-dev/kagent#2494 * fix(adk): validate ask_user questions by @erauner12 in kagent-dev/kagent#2486 * Backport fix(golang-adk): resolve user identity from A2A call context to 0.10.x by @buravc in kagent-dev/kagent#2507 * fix(a2a): serve exact task reads from the persistent store by @erauner12 in kagent-dev/kagent#2484 * fix(ui): preserve post-login redirect target through `oauth2-proxy` sign-in by @onematchfox in kagent-dev/kagent#2532 ### Documentation * docs: fix duplicate descriptions and broken link in README by @mesutoezdil in kagent-dev/kagent#2068 * docs: fix typos and errors in component READMEs by @mesutoezdil in kagent-dev/kagent#2070 * docs: fix typos and list formatting in contributor docs by @mesutoezdil in kagent-dev/kagent#2069 * docs: replace outdated AutoGen reference in SECURITY.md by @mesutoezdil in kagent-dev/kagent#2110 * docs(python): fix kagent-langgraph README import to kagent.langgraph by @anxkhn in kagent-dev/kagent#2167 * docs(python): fix KAgentSession import path in kagent-openai README by @anxkhn in kagent-dev/kagent#2163 * docs: fix stale references and See merge request: Harmonybrew/homebrew-core!18335

Copilot AI review requested due to automatic review settings July 7, 2026 08:00

anxkhn requested review from EItanya, iplay88keys, jmhbh, peterj, supreme-gg-gg and yuval-k as code owners July 7, 2026 08:00

github-actions Bot added the bug Something isn't working label Jul 7, 2026

Copilot started reviewing on behalf of anxkhn July 7, 2026 08:01

View session

Copilot AI reviewed Jul 7, 2026

View reviewed changes

Comment thread python/packages/kagent-adk/tests/unittests/converters/test_event_converter.py Resolved

Comment thread python/packages/kagent-adk/tests/unittests/converters/test_event_converter.py Resolved

supreme-gg-gg requested changes Jul 7, 2026

View reviewed changes

anxkhn force-pushed the fix/adk-serialize-metadata-value-str branch from 97a9ea6 to 62125e2 Compare July 8, 2026 20:41

anxkhn requested a review from a team as a code owner July 8, 2026 20:41

anxkhn force-pushed the fix/adk-serialize-metadata-value-str branch from 62125e2 to 40084c5 Compare July 9, 2026 16:42

anxkhn changed the title ~~fix(adk): return str from serialize_metadata_value for pydantic values~~ fix(adk): annotate serialize_metadata_value as str | dict Jul 9, 2026

github-actions Bot added bug Something isn't working and removed bug Something isn't working labels Jul 9, 2026

anxkhn commented Jul 9, 2026

View reviewed changes

Comment thread python/packages/kagent-adk/src/kagent/adk/converters/event_converter.py Resolved

anxkhn commented Jul 9, 2026

View reviewed changes

Comment thread python/packages/kagent-adk/src/kagent/adk/converters/event_converter.py Resolved

anxkhn commented Jul 9, 2026

View reviewed changes

Comment thread python/packages/kagent-adk/src/kagent/adk/converters/event_converter.py Resolved

anxkhn commented Jul 9, 2026

View reviewed changes

Comment thread python/packages/kagent-adk/tests/unittests/converters/test_event_converter.py Resolved

anxkhn requested review from Copilot and supreme-gg-gg July 9, 2026 16:47

Copilot started reviewing on behalf of anxkhn July 9, 2026 16:48

View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Merge branch 'main' into fix/adk-serialize-metadata-value-str

e90c127

supreme-gg-gg approved these changes Jul 9, 2026

View reviewed changes

EItanya approved these changes Jul 10, 2026

View reviewed changes

EItanya merged commit 5676223 into kagent-dev:main Jul 10, 2026
30 checks passed

BrewTestBot mentioned this pull request Nov 9, 2026

kagent 1.0.0 Homebrew/homebrew-core#324443

Merged

Navigation Menu

Repository navigation

fix(adk): annotate serialize_metadata_value as str | dict - #2173

fix(adk): annotate serialize_metadata_value as str | dict#2173
EItanya merged 2 commits into
kagent-dev:mainfrom
anxkhn:fix/adk-serialize-metadata-value-str

anxkhn commented Jul 7, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

supreme-gg-gg left a comment

Uh oh!

supreme-gg-gg commented Jul 8, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

anxkhn commented Jul 9, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	function getMessageTokenStats(metadata: Record<string, unknown> \| undefined): TokenStats \| undefined {
	const usage = getMetadataValue<ADKMetadata["kagent_usage_metadata"]>(metadata, "usage_metadata");
	if (!usage) return undefined;
	return {
	total: usage.totalTokenCount ?? 0,
	prompt: usage.promptTokenCount ?? 0,
	completion: usage.candidatesTokenCount ?? 0,
	};
	}

Conversation

anxkhn commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Fix

Tests

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

supreme-gg-gg left a comment

Choose a reason for hiding this comment

Uh oh!

supreme-gg-gg commented Jul 8, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

anxkhn commented Jul 9, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

anxkhn commented Jul 7, 2026 •

edited

Loading