Skip to content

Python: [BREAKING] Honor MIME text modes in hosting-a2a - #10362

Draft
Atharva Vichare (atty57) wants to merge 1 commit into
microsoft:mainfrom
atty57:fix/10351-a2a-text-mime-modes
Draft

Atharva Vichare (atty57) wants to merge 1 commit into
microsoft:mainfrom
atty57:fix/10351-a2a-text-mime-modes

Conversation

@atty57

@atty57 Atharva Vichare (atty57) commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Motivation & Context

A2A cards advertising text/plain or text/* currently reject ordinary text input/output. Advertising both text/plain and application/json incorrectly 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

  • What are the major changes? Treat text, text/plain, and text/* as generic text modes in the shared matcher. Use a text part's explicit media type, or text/plain when absent. Prefer text over the JSON fallback when a generic text mode is advertised. Add regression coverage and update package guidance and adapter docstrings.
  • What is the impact of these changes? The same behavior applies to completed agent responses, agent streaming updates, workflow inputs, and completed workflow outputs. Card defaults stay ("text",). JSON-only output retains its existing parsing. Concrete formats such as text/markdown still require application-owned output conversion.
  • What do you want reviewers to focus on? The generic-text alias boundary and the compatibility change: a text part explicitly labeled application/json or image/png is 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:

from a2a.types import Message as A2AMessage, Part, Role
from agent_framework import Message
from agent_framework_hosting_a2a import a2a_from_run, a2a_to_run

message = A2AMessage(message_id="m1", role=Role.ROLE_USER, parts=[Part(text="hello")])
run = a2a_to_run(message, input_modes=["text/plain"])
parts = a2a_from_run(Message("assistant", ["hi"]), output_modes=["application/json", "text/plain"])

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

  • No material AI assistance was used.
  • This is an AI-assisted contribution.

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

  • The code builds clean without any errors or warnings
  • All unit tests pass, and I have added new tests where possible
  • The PR follows the Contribution Guidelines
  • This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
  • This is not a breaking change. If it is a breaking change, add the breaking change label (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.

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
Copilot AI balanced review requested due to automatic review settings November 14, 2026 16:52
@agent-framework-automation agent-framework-automation Bot added documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs python Usage: [Issues, PRs], Target: Python breaking change Usage: [PRs], Target: all PRs that introduce changes that are not backward compatible labels Nov 14, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 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, and text/* 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

@surlymochan Nick (surlymochan) left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. With input_modes=["text"], a part labelled text/html (or text/csv) is now accepted and flattened into a plain Message text — the subtype is dropped on the way in, since Message carries no media-type field. The README is explicit on the output side ("receiving a part already labeled text/markdown does 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 only text, should text/html input be accepted as plain text, or rejected so the client knows the subtype is not honoured?
  2. In _mode_allowed, the generic-text early return keys on the advertised modes containing a generic text mode, while _part_mode now returns the part's own media_type (or text/plain when absent). For a data part the mode is still _JSON_MODE, so JSON parsing stays gated on no generic text mode being advertised — confirmed by test_a2a_from_run_emits_text_for_text_modes with ["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.

This branch was successfully deployed

1 active deployment
github-app-auth — dbdf94be Deployed Nov 14, 2026 by atty57 via add_label #27866
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

breaking change Usage: [PRs], Target: all PRs that introduce changes that are not backward compatible documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs python Usage: [Issues, PRs], Target: Python

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Python: [Bug]: hosting-a2a rejects plain text when the advertised modes use MIME types such as text/plain or text/*

3 participants