Python: add progressive A2A hosting adapters

[eavanvalkenburg]

Motivation & Context

Hosting Agent Framework agents through A2A currently requires applications to duplicate card metadata and provides no equivalent typed conversion path for workflows. This change adds progressively managed adapters while preserving native A2A SDK ownership of executors, tasks, queues, stores, routes, authentication, transport, and deployment.

Description & Review Guide

• What are the major changes? Adds AgentA2AAdapter and WorkflowA2AAdapter for native card generation, state-backed target resolution, Agent Framework skill discovery, and re-exposed conversion helpers. Adds typed workflow input/output conversion, mode-aware validation and parsing, package documentation, focused tests, and updates the standalone A2A hosting sample.
• What is the impact of these changes? Applications can start with standalone conversion functions, adopt card generation without surrendering server control, or use one adapter for card setup and request conversion. Existing standalone agent conversions remain available and permissive unless explicit mode validation is requested.
• What do you want reviewers to focus on? The boundary between adapter-owned value/card conversion and application-owned A2A execution, plus the mode parsing and validation behavior for text, JSON, binary, and extensible media types.

Related Issue

None. This PR was requested without a corresponding issue.

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 is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• 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 the title prefix in sync automatically.

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/hosting-a2a/agent_framework_hosting_a2a
_adapters.py	112	8	92%	111, 115, 145, 279, 281, 310, 312, 327
_conversion.py	203	9	95%	113–115, 121, 146–147, 157–158, 361
TOTAL	45375	5110	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
9232	33 💤	0 ❌	0 🔥	2m 38s ⏱️

[Copilot]

Pull request overview

This PR enhances the Python agent-framework-hosting-a2a package to support progressively managed A2A hosting composition by adding adapter types that generate native A2A AgentCards while keeping A2A server/execution ownership in application code, and by extending conversion helpers to cover typed workflow I/O with optional advertised-mode validation.

Changes:

• Added AgentA2AAdapter and WorkflowA2AAdapter to generate native A2A cards from Agent/Workflow metadata (with optional Agent Framework skill discovery) and to re-expose conversion helpers with mode validation defaults.
• Extended conversion helpers with optional input_modes/output_modes validation plus new workflow conversions (a2a_to_workflow_run, a2a_from_workflow_run) using declared workflow types.
• Updated docs, sample usage, and added focused unit tests for adapters and conversion behavior.

Reviewed changes

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

Show a summary per file

File	Description
python/samples/04-hosting/a2a/README.md	Updates sample table entry to reflect card inference + app-owned server boundary.
python/samples/04-hosting/a2a/agent_framework_to_a2a.py	Refactors sample to use AgentA2AAdapter and Agent Framework skills metadata.
python/packages/hosting-a2a/tests/hosting_a2a/test_conversion.py	Expands conversion tests to cover mode validation and workflow I/O conversions.
python/packages/hosting-a2a/tests/hosting_a2a/test_adapters.py	Adds new adapter tests for card inference, skill inference, and workflow mode behavior.
python/packages/hosting-a2a/README.md	Reworks package README to document progressive adoption levels and mode parsing rules.
python/packages/hosting-a2a/AGENTS.md	Updates package guidance, boundaries, and supported mode inference/validation behavior.
python/packages/hosting-a2a/agent_framework_hosting_a2a/_conversion.py	Adds mode parsing/validation utilities and workflow conversion helpers.
python/packages/hosting-a2a/agent_framework_hosting_a2a/_adapters.py	Introduces agent/workflow adapter implementations for native card generation and conversions.
python/packages/hosting-a2a/agent_framework_hosting_a2a/init.py	Exports new adapters and workflow conversion helpers.

[github-actions]

Automated Code Review

Reviewers: 5 | Confidence: 88%

✓ Correctness

The PR adds progressive A2A hosting adapters with well-designed layered abstractions. The conversion logic correctly handles text, JSON, binary, and wildcard mode validation. The adapter pattern properly separates card generation from value conversion. Framework type usage (AgentState, WorkflowState, SkillsProvider, Workflow properties) aligns with verified interface contracts. No bugs, race conditions, or incorrect API usage found.

✓ Security Reliability

The PR introduces well-structured A2A hosting adapters with proper input validation at trust boundaries (mode validation, Pydantic type validation for workflow inputs), safe deserialization patterns, no hardcoded secrets, no resource leaks, and appropriate error propagation. The wildcard mode matching, JSON parsing, and protobuf conversion paths are all bounded and safe. No blocking security or reliability issues found.

✓ Test Coverage

Test coverage for the new conversion helpers and adapters is solid overall. The tests cover the happy paths, mode validation, adapter card generation, skill inference, and error conditions for most branches. However, there are a few untested error paths in a2a_to_workflow_run (zero compatible parts and schema validation failure) and _part_from_text (non-text/non-json output modes) that represent meaningful edge cases.

✓ Failure Modes

The PR introduces well-structured conversion and adapter code with proper explicit error raising at all boundaries. Mode validation rejects invalid input/output with clear ValueErrors. The WorkflowA2AAdapter correctly gates output-mode validation behind get_card() resolution via RuntimeError. The sample executor catches and reports failures via task status updates. No silent failure paths, swallowed exceptions, or partial-write scenarios that could lead to data loss were identified in the library code.

✓ Design Approach

I found one design inconsistency repeated in both input conversion helpers: advertised-mode validation runs on the raw message.parts collection before the helper applies its documented/previous omission and compatibility filtering. That makes opt-in validation reject messages that the conversion layer would otherwise successfully handle by ignoring unsupported parts.

Suggestions

• Add a test for a2a_to_workflow_run when the data part passes type matching but fails Pydantic schema validation (e.g., {"text": "go", "repeat": "not_a_number"} for a workflow expecting int). This would exercise the adapter.validate_python(value) error path at _conversion.py:387.
• Add a test for the _part_from_text fallthrough raise at _conversion.py:104-106 (when output_modes excludes both 'text' and 'application/json'). For example, a2a_from_run(Message('assistant', ['hello']), output_modes=['application/octet-stream']) would exercise this path.

---

Automated review by eavanvalkenburg's agents

[eavanvalkenburg]

Addressed the automated coverage suggestions in 18025d4: added coverage for typed workflow data that fails Pydantic validation and for Agent Framework text output when neither text nor JSON is advertised.