Repository navigation
Python: [BREAKING] Honor MIME text modes in hosting-a2a - #10362
Atharva Vichare (atty57) wants to merge 1 commit into
Conversation
Recognize generic text MIME modes before JSON fallback and honor explicit part media types. Keep concrete output format conversion application-owned. BREAKING CHANGE: Text-only cards reject text parts explicitly labeled with non-text media types instead of ignoring those labels. Fixes microsoft#10351
There was a problem hiding this comment.
🔵 Needs a closer look
Maintainer agreement is still required on treating text/plain as a generic-text alias and enforcing stricter MIME validation that breaks previously accepted behavior.
No open issues 🎉
What changed in this PR
Updates Python’s A2A hosting conversion helpers to recognize MIME text modes, addressing #10351 while preserving default card modes and JSON-only output handling.
Changes:
- Treats
text,text/plain, andtext/*as generic text modes, preferring text output over JSON parsing when both are advertised. - Uses explicit text-part media types for validation, introducing stricter rejection of non-text labels on text-only cards.
- Adds regression coverage and documents the supported conversion boundaries.
| File | Description |
|---|---|
python/packages/hosting-a2a/tests/hosting_a2a/test_conversion.py |
Covers text aliases, explicit media types, output precedence, and workflow conversion. |
python/packages/hosting-a2a/tests/hosting_a2a/test_adapters.py |
Verifies card-advertised MIME text modes work through the agent adapter. |
python/packages/hosting-a2a/README.md |
Explains text-mode handling and application-owned conversion requirements. |
python/packages/hosting-a2a/AGENTS.md |
Updates package guidance for generic text modes. |
python/packages/hosting-a2a/agent_framework_hosting_a2a/_conversion.py |
Adds shared text-alias matching and media-type-aware text-part validation. |
python/packages/hosting-a2a/agent_framework_hosting_a2a/_adapters.py |
Documents MIME text modes in adapter constructor docstrings. |
Review effort: Balanced
Nick (surlymochan)
left a comment
There was a problem hiding this comment.
Verified the new behaviour against the implementation and the tests: text, text/plain and text/* now select the built-in text handling on both directions, text/markdown parts are accepted by the generic text modes, and non-text media types are still rejected when only text modes are advertised. The parametrized coverage (including " TEXT/PLAIN " with surrounding whitespace/case) is thorough.
Two questions:
- With
input_modes=["text"], a part labelledtext/html(ortext/csv) is now accepted and flattened into a plainMessagetext — the subtype is dropped on the way in, sinceMessagecarries no media-type field. The README is explicit on the output side ("receiving a part already labeledtext/markdowndoes not imply that the helpers format arbitrary agent output as Markdown"), but is silently dropping the input subtype the intended contract too? If a client advertises onlytext, shouldtext/htmlinput be accepted as plain text, or rejected so the client knows the subtype is not honoured? - In
_mode_allowed, the generic-text early return keys on the advertised modes containing a generic text mode, while_part_modenow returns the part's ownmedia_type(ortext/plainwhen absent). For adatapart the mode is still_JSON_MODE, so JSON parsing stays gated on no generic text mode being advertised — confirmed bytest_a2a_from_run_emits_text_for_text_modeswith["application/json", "text/plain"]emitting text. That matches the README's "JSON parsing is used only when no generic text mode is advertised". No issue, just confirming the intended precedence is text-wins when both are advertised.
Non-blocking: the breaking-change surface here is exactly the advertised-mode behaviour, and the docs/AGENTS.md updates describe it consistently.
Motivation & Context
A2A cards advertising
text/plainortext/*currently reject ordinary text input/output. Advertising bothtext/plainandapplication/jsonincorrectly sends ordinary text through the JSON parser.This draft supplies a concrete candidate for #10351 while maintainer agreement on the support boundary is pending.
Description & Review Guide
text,text/plain, andtext/*as generic text modes in the shared matcher. Use a text part's explicit media type, ortext/plainwhen absent. Prefer text over the JSON fallback when a generic text mode is advertised. Add regression coverage and update package guidance and adapter docstrings.("text",). JSON-only output retains its existing parsing. Concrete formats such astext/markdownstill require application-owned output conversion.application/jsonorimage/pngis now rejected by a text-only card instead of ignoring that label. Exact matching of explicitly advertised non-text media types remains supported. This stricter validation is why the draft is marked[BREAKING].Before this change, both calls below fail; afterward the input is accepted and the output is one text part:
Related Issue
Fixes #10351.
Concrete text output formats are discussed separately in #10363; this draft does not implement that feature.
No competing open PR was found. The issue has automated reproduction but no recorded maintainer agreement; this remains a draft for discussion of the proposed direction and compatibility change.
AI Assistance
AI assistance details: Codex assisted with analysis, implementation, regression tests, documentation, and this description, and ran local verification. Human contributor verification and maintainer review remain pending; this draft does not claim those steps are complete.
Contribution Checklist
breaking changelabel (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.The affected package's 77 unit tests pass. Ruff formatting/lint, strict source Pyright, and the configured test type checkers (Pyright, mypy, pyrefly, ty, zuban) pass. The tests emit two existing experimental-feature warnings. Full workspace tests and a distribution build were not run.