Maintainer-owned vNext proposal. Community contributors: please do not pick up or start implementing this issue. This is a breaking public-API change for the Agent Framework core team to design and schedule.
Problem
ChatResponse.value and AgentResponse.value currently parse structured output lazily inside a property (python/packages/core/agent_framework/_types.py). await agent.run(...) can succeed, but merely reading result.value may later raise ValueError or a Pydantic ValidationError. A property read is a surprising place to trigger parsing or discover a malformed model response.
The current timing is intentional: context providers see the full response before a caller requests parsing (see test_context_provider_after_run_preserves_lazy_structured_value_parsing). Do not solve this by eagerly parsing during run() or from_updates() and changing that observation order.
vNext direction
Offer an explicit operation such as result.get_value() for lazy, cached structured-value parsing on both response types. In vNext, .value should no longer be the operation that runs the parser; plan its migration/removal rather than keeping an unexpectedly throwing property indefinitely. Keep the existing successful value shapes, Pydantic-model and JSON-schema-mapping support, None for empty/refusal responses, and parse failure information. The intended caller should choose an explicit call when it needs validated structured output.
Acceptance criteria
- Parsing and its errors occur on the explicit method call, not on an attribute read or as a side effect of
run().
- Non-streaming and streaming responses,
from_updates, and context-provider observation retain their supported behavior apart from the deliberate API change.
- Examples, type surfaces, and tests describe the new vNext contract and migration from
.value.
Ownership: Core maintainers only; not available for community pickup.
Problem
ChatResponse.valueandAgentResponse.valuecurrently parse structured output lazily inside a property (python/packages/core/agent_framework/_types.py).await agent.run(...)can succeed, but merely readingresult.valuemay later raiseValueErroror a PydanticValidationError. A property read is a surprising place to trigger parsing or discover a malformed model response.The current timing is intentional: context providers see the full response before a caller requests parsing (see
test_context_provider_after_run_preserves_lazy_structured_value_parsing). Do not solve this by eagerly parsing duringrun()orfrom_updates()and changing that observation order.vNext direction
Offer an explicit operation such as
result.get_value()for lazy, cached structured-value parsing on both response types. In vNext,.valueshould no longer be the operation that runs the parser; plan its migration/removal rather than keeping an unexpectedly throwing property indefinitely. Keep the existing successful value shapes, Pydantic-model and JSON-schema-mapping support,Nonefor empty/refusal responses, and parse failure information. The intended caller should choose an explicit call when it needs validated structured output.Acceptance criteria
run().from_updates, and context-provider observation retain their supported behavior apart from the deliberate API change..value.Ownership: Core maintainers only; not available for community pickup.