DS DevShelfHub Projects · AI tools
Tutorials / CrewAI / Reference / Methods / validate_a2ui_message()
Method A2A / A2UI

validate_a2ui_message(): Reference Guide

By DevShelfHub

Validates an Agent-to-UI extension message against the A2UI schema.

See the CrewAI methods catalog, CrewAI introduction, kickoff() reference, and core concepts for surrounding context.

What is validate_a2ui_message()?

Agent-to-Agent (A2A) traffic can carry an optional Agent-to-UI (A2UI) extension: structured messages that tell a host application which UI fragments to render, update, or tear down. Those envelopes are still untrusted input — they may be malformed, generated by an older client, or crafted by a malicious peer. validate_a2ui_message() is the narrow guard that checks a Python dict (typically JSON-decoded) against the A2UI contract so you fail closed before your renderer, router, or state machine touches the payload.

Call it at trust boundaries: immediately after you receive a message from the network, before you enqueue work for an agent, and again before you forward a message you synthesized to a downstream UI host. The function is intentionally small and side-effect free so you can wrap transports, WebSocket handlers, or queue consumers without pulling in the rest of the UI stack. Pair validation with normal authn/authz on the A2A session — schema checks complement, but never replace, identity and policy.

CrewAI ships this helper under crewai.a2a.extensions.a2ui; pin the crewai[a2a] extra to the version you tested because schema keywords and required fields can evolve across releases. When validation fails, log a correlation id and return a generic client error instead of echoing internal schema details.

Use Cases

  • • Hardening A2UI server handlers before render
  • • Sanity-checking client-built messages before send
  • • Regression tests for saved A2UI fixtures

Key Features

  • ✓ Contract check against the A2UI schema
  • ✓ Lightweight dict in / bool-style guard for hot paths
  • ✓ Usable from transports without importing UI widgets

When NOT to Use

Pure A2A flows with no UI extension, trusted in-process fixtures where you already constructed typed models, or when you need richer diagnostics than a pass/fail guard — use a full validator or contract tests there.

Notes

Schema drift across crewai versions

A2UI is an evolving extension. Upgrading crewai without re-running your integration tests can flip a previously accepted fixture to invalid if required keys change. Pin crewai[a2a] in deployment and keep a small golden-file suite that calls validate_a2ui_message on recorded payloads.

Validation is not a security boundary by itself

Passing validate_a2ui_message only means the JSON shape matches the contract. You still need TLS, token verification, audience checks, and authorization before acting on UI instructions that could exfiltrate data or drive sensitive host actions.

Hot-path cost and observability

Schema validation adds CPU on every message. For very high QPS channels, batch or sample logging of failures, and avoid re-validating identical structures you already validated in the same request lifecycle unless the dict was mutated.

When you need more than pass/fail

This helper optimizes for a simple guard. If you need line numbers, JSON paths, or custom coercions, compose it with your own structured error type upstream and keep validate_a2ui_message as the first cheap filter.

Parameters

Parameter Type Required Purpose
message dict No Decoded A2UI message body to validate.

Code Examples

Reject invalid inbound payloads before routing

python 
from crewai.a2a.extensions.a2ui import validate_a2ui_message

def handle_a2ui_event(envelope: dict) -> None:
    if not validate_a2ui_message(envelope):
        raise ValueError('Invalid A2UI envelope')
    route_to_renderer(envelope)

Log and drop bad messages in an async consumer

python 
import logging
from crewai.a2a.extensions.a2ui import validate_a2ui_message

log = logging.getLogger(__name__)

async def consume_a2ui_stream(item: dict) -> None:
    if not validate_a2ui_message(item):
        log.warning('dropping invalid A2UI message', extra={'keys': sorted(item)})
        return
    await apply_ui_patch(item)

Gate outbound UI updates built in application code

python 
from crewai.a2a.extensions.a2ui import validate_a2ui_message

def publish_if_safe(ui_message: dict) -> bool:
    if not validate_a2ui_message(ui_message):
        return False
    broker.publish('a2ui', ui_message)
    return True

When to Use

A2UI-enabled transports, custom A2A servers or clients that surface UI directives, or any code path that accepts dict-shaped A2UI messages from outside your process.

Common Mistakes

❌ Validating only once at startup for a long-lived session

✅ Validate every inbound envelope — peers can send malformed messages at any time.

❌ Assuming JSON parse success means A2UI compliance

✅ json.loads gives structure; validate_a2ui_message enforces the A2UI contract on that dict.

Related: @tool decorator reference, Agent class reference, and the first Crew tutorial.

validate_a2ui_message() FAQ

What is validate_a2ui_message() in CrewAI?

Validates an Agent-to-UI extension message against the A2UI schema. Agent-to-Agent (A2A) traffic can carry an optional Agent-to-UI (A2UI) extension: structured messages that tell a host application which UI fragments to render, update, or tear down. Those envelopes are still untrusted input — they may be malformed, generated by an older client, or crafted by a malicious peer. validate_a2ui_message() is the narrow guard that checks a Python dict (typically JSON-decoded) against the A2UI contract so you fail closed before your renderer, router,…

Which CrewAI types expose the method validate_a2ui_message()?

DevShelfHub documents validate_a2ui_message() on A2A / A2UI. The reference maps it to Python module crewai.a2a.extensions.a2ui — pin your installed crewai version and match imports to the snippet on this page.

When should I use validate_a2ui_message()?

A2UI-enabled transports, custom A2A servers or clients that surface UI directives, or any code path that accepts dict-shaped A2UI messages from outside your process.

When should I avoid validate_a2ui_message()?

Pure A2A flows with no UI extension, trusted in-process fixtures where you already constructed typed models, or when you need richer diagnostics than a pass/fail guard — use a full validator or contract tests there.

How do I call validate_a2ui_message() from Python?

ok = validate_a2ui_message(message)

Where can I explore more CrewAI API reference pages?

Open the CrewAI API reference index on DevShelfHub to search classes, methods, and decorators, each with runnable examples, parameters, common mistakes, and cross-links.