[Feature Request] Fragile Enforcement of JSON-only A2UI Output

[devchas]

I would suggest building in some prompt augmentation to the agent SDK to enforce proper A2UI messages. I don’t think you should be required to write something like Your final output MUST be a a2ui UI JSON response. Even with that, it doesn’t always work.

For example, my role description of You are a helpful agent that helps find and book weekend activities. Your final output MUST be a a2ui UI JSON response generated an A2UI validation failure.

However, something like this did work: You are a powerful and intelligent agent that translates user requests into a stream of valid A2UI JSON messages. You must respond to the user's request using only the component and data schemas provided below. Do not add any conversational text or markdown outside of the designated component properties. Your entire response must be a valid JSON array of A2UI messages.

[jswortz]

Hi @devchas @selamw1 — I've been running into this exact issue across multiple production agents and have iterated on a solution I'd like to contribute back.

Context

I maintain a multi-agent grocery retail system deployed on Vertex AI Agent Engine with A2UI v0.8. We have 3 agents (main assistant, analytics dashboard, A/B test simulator) that all need to produce reliable A2UI-first output. We hit this problem immediately — even with aggressive ui_description text and manual "Your final output MUST be..." in the role description, the LLM would still fall back to markdown tables and bullet lists ~30-40% of the time.

What we learned

After several iterations, we found that enforcement requires three layers working together:

1. Output ordering — The LLM needs to be told that A2UI JSON comes FIRST, text comes AFTER (max 1-2 sentences). The current DEFAULT_WORKFLOW_RULES saying "you can provide conversational text between blocks" actively undermines this by framing text as equally valid output.

2. Anti-markdown rules — Explicit bans are essential: "NEVER use markdown tables — use Row with Card children instead." Without these, the LLM treats markdown as the path of least resistance since it's what it was primarily trained on.

3. Component-to-alternative mapping — Telling the LLM what to use instead is more effective than just saying "don't use markdown." Mapping markdown tables → Row+Card, markdown lists → List+Card, markdown headers → Text with usageHint gives the LLM a clear substitution path.

Proposed change

I'd like to submit a PR adding a strict_output: bool = False parameter to generate_system_prompt(). When enabled:

• Swaps DEFAULT_WORKFLOW_RULES for STRICT_WORKFLOW_RULES (A2UI-first, anti-markdown, component diversity)
• Fully backward-compatible — defaults to False, existing behavior unchanged
• Two files changed: constants.py (new constant) + manager.py (one new parameter)
• 14 new test cases

This would let the restaurant_finder sample drop the manual "Your final output MUST be a a2ui UI JSON response" from ROLE_DESCRIPTION and just pass strict_output=True.

Would you be open to a PR for this? Happy to adjust the approach based on your feedback.