Humans are fallible. Even the ones that are meant to be well trained.
I spent years in America on a visa that nobody recognised because there are so few in circulation (E3). I almost got arrested at a DMV because a police officer went on a power trip about me being in the country illegally because of the date on my Verizon bill being before my visa start date. On the same day I had a DMV employee refuse me a drivers license three times (I waited for him to finish his shift and the next person who came on processed me no worries). I had to argue with the IRS sending me a $10,000 bill for 3 months of income and my entitlement to file a 1040-NR. I had to explain to the lady at the social security office on two separate occasions about my right to an SSN on my visa. Every time I only got a positive outcome only when I escalated to the persons superior.
So as to what went wrong, the agent made a mistake. It happens. It happens all the time. As for how to avoid it? You need to know the system better than everyone. And I mean that. You need to know your rights and the laws that enforce your rights so that when you get into a disagreement with an official you can request to speak to their supervisor and present the supervisor with the correct information.
And then cross your fingers that the supervisor is not having a bad day and decides to take it out on you.
As an aside: I also had issues boarding a flight the USA, alone, on a one-way ticket. The gate agent quizzed me heavily, and then a seperate security guard asked me a bunch of questions on behalf of the US Government (apparently), and then I got flagged
SSSS on my ticket which means you're going to get delayed at every single security checkpoint and get touched in personal places and maybe even miss your connecting flight because you're waiting for the single security person working at LAX at 5:30am to come back so they can excruciatingly go through every single item in your luggage and then not repack it neatly. Or so I've heard.
Update: If you wanted to print out your requirements to show to an uncooperative gate agent and you believe you are in the right, you would want to show them the IATA Timatic information for your flight. Public access to the system comes and goes over time as airlines add/remove functionality from their websites. However as of May 2019 you can access https://skyteam.traveldoc.aero/
This is only very basic information however you can see the part highlighted in yellow that states
Passengers not holding onward/return tickets or other acceptable evidence of onward/return travel may be refused entry.
My guess is that this is what the agent fixated on, ignoring your visa for whatever reason. So in this case having the document may not have actually helped, but knowing your rights may have.
There is a more complicated but slightly more comprehensive check at https://www.timaticweb2.com/integration/external.php?ref=d975cfc59f5c0abd06d16e872198110b
This basically says the same information, giving more evidence that your agent was being ignorant.