Unify System Instruction Generation for Text and Tool Output Modes

[nan-yu]

Context

Currently, a2ui.schema.manager.generate_system_prompt and send_a2ui_to_client_toolset provide two separate paths for instructing the LLM on how to handle A2UI. This makes it difficult for developers to know exactly what is being sent in the final system instruction.

Problem

• Developers need to set paremeters include_schema and include_examples to False to avoid conflicts with tool-based instructions, which creates ambiguity when a toolset is already providing that context.
• Appending multiple strings from different modules makes prompt tuning and debugging difficult.

Proposed Sollution

Refactor the prompt generation logic into a unified "Skill" or configuration object.

• Introduce an explicit A2UIOutputMode enum: TEXT (for direct schema injection) and TOOL (for tool-calling environments).
• Simplify the API so that system instructions are generated based on the selected mode, preventing accidental double-injection of schemas or instructions.

After reviewing both #1466 and #1465 together, I want to propose a design refinement that addresses the parameter naming issue and consolidates both concerns cleanly.

• Repurpose output_mode enum for the output strictness level.
• Introduce a new schema_injection_mode enum for where and when the schema should be injected.

class A2UISchemaInjectionMode(Enum):
    """Where/when the schema is injected."""
    EMBEDDED = "embedded"   # Schema in system prompt (upfront, one-time)
    TOOL = "tool"           # Schema injected per-request by toolset
    NONE = "none"           # No schema injection (default)

class A2UIOutputMode(Enum):
    """How the LLM should prioritize A2UI vs. text."""
    A2UI_FIRST = "a2ui_first"  # A2UI blocks first, minimal text after
    TEXT_FIRST = "text_first"  # Text and A2UI can be interleaved (default)
    # Future: STRICT_A2UI, A2UI_ONLY for even stricter modes

[jswortz]

Hi @nan-yu — I'd like to take a crack at this. I ran into the exact double-injection problem you describe while building production agents on Vertex AI Agent Engine.

The problem in practice

We have 3 agents using A2UI v0.8. Our MCP analytics agent originally called:

prompt = schema_manager.generate_system_prompt(
    role_description=ROLE,
    include_schema=True,    # Schema injected into system prompt
    include_examples=True,
)

When we later added SendA2uiToClientToolset for tool-based output, we didn't realize process_llm_request() also injects the schema. The LLM was seeing the schema twice — once in the system prompt, once from the toolset — which caused longer prompts, higher latency, and occasionally confused output where the LLM mixed <a2ui-json> text output with send_a2ui_json_to_client tool calls in the same response.

Proposed implementation

An A2UIOutputMode enum with two values:

• TEXT (default) — current behavior, schema in system prompt, LLM wraps output in <a2ui-json> tags
• TOOL — schema injection handled by SendA2uiToClientToolset.process_llm_request(), so generate_system_prompt() automatically skips include_schema and include_examples to prevent double-injection. Uses TOOL_WORKFLOW_RULES that reference send_a2ui_json_to_client instead of <a2ui-json> tags.

from a2ui.schema.output_mode import A2UIOutputMode

# TEXT mode (default, backward compatible)
prompt = manager.generate_system_prompt(
    role_description="You are a restaurant finder.",
    include_schema=True,
    output_mode=A2UIOutputMode.TEXT,
)

# TOOL mode — schema/examples automatically skipped
prompt = manager.generate_system_prompt(
    role_description="You are a restaurant finder.",
    include_schema=True,  # Overridden to False, logs warning
    output_mode=A2UIOutputMode.TOOL,
)

Changes: 3 files + 1 new file, 14 test cases, fully backward-compatible.

Happy to adjust based on your feedback. I also recently submitted #1465 (strict_output mode) which is complementary — output_mode controls where the schema goes, strict_output controls how aggressively to enforce A2UI-first output.