Python: Fix missing methods on the Content class in durable tasks

[eavanvalkenburg]

Motivation and Context

The Content class exposes to_dict/from_dict for dictionary serialization but lacks corresponding to_json/from_json methods for JSON string serialization, forcing users to manually call json.dumps/json.loads as a workaround.

Fixes #4719

Description

The fix adds a to_json instance method that serializes Content to a JSON string via to_dict, and a from_json classmethod that deserializes a JSON string back into a Content instance via from_dict. Both methods delegate to the existing dict-based serialization logic to stay consistent. A minor type-narrowing fix in DurableAgentStateUnknownContent.to_ai_content was also included to resolve a related type-checking issue with Content.from_dict.

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

---

Note: PR autogenerated by eavanvalkenburg's agent

[eavanvalkenburg]

Automated Code Review

Reviewers: 4 | Confidence: 86%

✓ Correctness

Clean, straightforward addition of JSON serialization/deserialization methods to the Content class, plus a type-narrowing fix in the durable agent state module. The logic is correct and well-tested. One minor robustness concern: from_json passes the result of json.loads directly to from_dict without checking it's a dict, which could produce a confusing AttributeError instead of a clear ValueError if the JSON string represents a non-object type (e.g., a list or string). No blocking issues.

✓ Security Reliability

The diff adds to_json/from_json serialization helpers to Content and refactors a type-narrowing cast in the durable agent state module. The changes are low-risk overall. The main reliability concern is that from_json passes the result of json.loads directly to from_dict without verifying it is a dict, which means non-object JSON inputs (e.g., arrays, scalars) will produce confusing errors instead of a clear validation message.

✓ Test Coverage

The new to_json and from_json methods on Content are reasonably well tested: basic serialization/deserialization, the exclude_none flag, roundtrip, and invalid input (missing 'type'). However, the exclude parameter of to_json() has zero test coverage despite being part of the public API, and the **kwargs pass-through to json.dumps is also untested. The refactor in _durable_agent_state.py is purely a type-narrowing change with no behavioral difference, so no new tests are needed there.

✓ Design Approach

The diff adds to_json/from_json convenience methods to Content and fixes a type-narrowing issue in DurableAgentStateUnknownContent.to_ai_content. The JSON serialization methods are thin, correct wrappers around the existing to_dict/from_dict pair and introduce no design problems. The durable-state fix properly casts to dict[str, Any] after an isinstance guard. No fundamentally misguided approaches or leaky abstractions are present. The test coverage is thorough and aligns with the existing roundtrip pattern. The only minor concern is that from_json silently delegates all error handling to json.loads and from_dict; callers will receive a raw json.JSONDecodeError on malformed JSON rather than a domain-level ValueError, which is inconsistent with the ValueError raised by from_dict for semantic errors — but this is a modest inconsistency rather than a design flaw requiring changes.

Suggestions

• In from_json, validate that json.loads(value) returns a dict before passing to from_dict, and consider wrapping json.JSONDecodeError into a ValueError for a consistent exception contract with from_dict. Currently, non-object JSON input (e.g., "[1,2,3]") raises a confusing AttributeError on .get("type"), and malformed JSON raises json.JSONDecodeError rather than the ValueError that from_dict uses for semantic errors.
• Add a test for Content.to_json(exclude=...) — it's an explicit public API parameter with no coverage. For example, serialize a Content with a known field excluded and assert it's absent from the JSON output.
• Consider adding a test that to_json(**kwargs) forwards options to json.dumps (e.g., to_json(indent=2) produces indented output), since the **kwargs pass-through is part of the public signature.

---

Automated review by eavanvalkenburg's agents

[eavanvalkenburg]

Please move the json.dumps into the durable task

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
TOTAL	24006	2640	89%

report-only-changed-files is enabled. No files were changed during this commit :)

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
5247	20 💤	0 ❌	0 🔥	1m 25s ⏱️

[Copilot]

Pull request overview

Adds first-class JSON string serialization/deserialization for the Python Content type, and updates Durable Task state handling/tests to ensure MCP-related content can be JSON-serialized (addressing the Azure Durable Functions to_json expectation reported in #4719).

Changes:

• Add Content.to_json() / Content.from_json() implemented via existing to_dict() / from_dict() logic.
• Ensure DurableAgentStateUnknownContent stores Content instances as dicts (JSON-serializable) and can restore Content from those dicts.
• Add unit tests for Content JSON roundtrips and Durable Task JSON serialization scenarios involving MCP content.

Reviewed changes

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

File	Description
python/packages/core/agent_framework/_types.py	Adds to_json/from_json on Content.
python/packages/core/tests/core/test_types.py	Adds tests for Content JSON serialization/deserialization.
python/packages/durabletask/agent_framework_durabletask/_durable_agent_state.py	Makes unknown durable content JSON-safe by dict-serializing Content and restoring via Content.from_dict.
python/packages/durabletask/tests/test_durable_agent_state.py	Adds Durable Task tests reproducing JSON serialization scenarios with MCP content.

---

You can also share your feedback on Copilot code review. Take the survey.

[giles17]

PR title and description still reference to_json and from_json which were removed