Decorating a single function with multiple routes across different routers can cause FastAPI to generate duplicate operationIds in the OpenAPI schema, which violates the OpenAPI specification and can break client generation tools. It is highly recommended to define separate, clearly named handler functions for each route to ensure unique operation IDs and cleaner routing.

@discovery_router.get("/.well-known/agent-card.json", response_model=A2AAgentCard)
async def get_well_known_agent_card() -> A2AAgentCard:
    """Return public A2A discovery metadata at the root well-known path."""
    return build_agent_card()


@router.get("/agent-card.json", response_model=A2AAgentCard)
async def get_a2a_agent_card() -> A2AAgentCard:
    """Return public A2A discovery metadata at the versioned path."""
    return build_agent_card()


@router.get("/.well-known/agent-card.json", response_model=A2AAgentCard)
async def get_a2a_well_known_agent_card() -> A2AAgentCard:
    """Return public A2A discovery metadata at the versioned well-known path."""
    return build_agent_card()

If the incoming A2A message contains no text parts or only empty text, request.text() will return an empty string. Forwarding an empty input to the downstream workflow engine can cause unexpected failures or errors. Adding a validation check to reject empty messages early improves robustness and adheres to defensive programming principles.

async def send_message(
    x_consumer_username: Annotated[str, Header()],
    request: A2ASendMessageRequest,
) -> Union[StreamingResponse, JSONResponse]:
    """
    Map an A2A text message to the existing workflow chat completion API.
    """
    message_text = request.text().strip()
    if not message_text:
        from fastapi import HTTPException
        raise HTTPException(status_code=400, detail="Message content cannot be empty")

    parameters = dict(request.parameters)
    parameters.setdefault("input", message_text)

Including /workflow/v1/a2a/message:send in CHAT_OPEN_API_PATHS forces all validation and middleware errors for this endpoint to be returned as SSE (text/event-stream) responses. However, A2A clients may send non-streaming requests (where stream=False) or expect standard JSON error payloads for HTTP-level failures (like 400 Bad Request). Returning SSE format for early validation errors will break standard HTTP clients. It is safer to remove this path from CHAT_OPEN_API_PATHS so that early errors are returned as standard JSON, while active stream errors are still handled gracefully within the handler.

CHAT_OPEN_API_PATHS = [
    "/workflow/v1/chat/completions",
    "/workflow/v1/resume",
]