Search for a command to run...
A Tale of Protocol Quirks, JSON Wrestling, and the Joy of Finding the Bug
I work as a Tech Arch Senior Manager at Accenture and am a mother to two wonderful kids who test my patience and inspire me to be curious. I love cooking, reading, and painting.
No comments yet. Be the first to comment.
In 2018, OpenAI pledged its "primary fiduciary duty is to humanity." Seven years later, the company launches erotic AI companions while families testify in courtrooms about children who never came home. We're conducting the largest unregulated behavi...
Did you know that 68% of organizations now identify data silos as their top operational concern? A 7% increase from 2023, according to a 2024 DATAVERSITY® Trends in Data Management Survey. In today's hyper-personalized business landscape, enterprises...
The Changing Search Paradigm This week, OpenAI introduced shopping capabilities within ChatGPT's search feature, coinciding with Mastercard unveiling Agent Pay, a new payment approach that enables AI agents to securely complete purchases. These devel...
The Reality of AI Hallucinations: Recent Examples Last week, the AI coding assistant tool Cursor encountered a crisis when its front-line AI support bot named “Sam” confidently provided a user with a completely fabricated policy. The user raised a su...
How participating in Google's Agent Builder Challenge taught me that "abstraction" doesn't always mean "magic"
Ever had that moment where your code looks perfect, your architecture feels right, but something's just... off? Welcome to my 1:47AM Eureka moment with Google's Agent-to-Agent (A2A) protocol during the Google’s Agent Build Challenge.
The multi-agent IAM orchestrator built on top of the Google Agent Development Kit is almost perfect. The orchestrator agent talking to agents, RAG engines humming with policy context, NLU classifiers dissecting human intent with surgical precision.
And then came the A2A remote call to the server to pull in the response - full of run-time errors. My RemoteA2aAgent was responding. Authentication? ✅ Green. A2A handshake? ✅ Golden. HTTP status codes? ✅ Beautiful 200s across the board.
But where I expected a rich Python dictionary brimming with provisioning results, I got... no response where it expected a rich Python dictionary.
Why do we care about this debugging journey? Because in the world of agent-to-agent communication, particularly with evolving frameworks, the boundaries between "framework magic" and "your responsibility" aren't always clearly marked. And misunderstanding that boundary can cost you hours (or in a hackathon context, your entire submission).
Here's where it gets interesting. I did what any modern developer would do: I consulted an AI assistant. I showed it my code. Multiple AI Assistants (Gemini 3, Claude Sonnet 4.5 and GPT 5.1) said the same thing. RemoteA2aAgent should handle call to the server, deserialize the response automatically.
It sounded right. The advice was to just call the remote agent's tools directly, like this:
# The "obviously correct" approach (that doesn't work)
backend_agent = self.find_agent("secure_executor_client")
processing_tool = backend_agent.tools[0].func
outcome = await processing_tool(
operation_type="transform_data",
target_resource="resource-alpha-7",
execution_context="production-env"
)
# Expecting: {"state": "COMPLETED", "metadata": {...}}
# Getting: None (or worse, an error)
Elegant. Simple. Wrong.
But something nagged at me. Call it developer intuition. Call it the paranoia that comes from too many "it should just work" moments that didn't. I decided to do something radical: actually look at what my A2A server was returning.
Before we begin dissecting the response format, a quick disclaimer: The techniques we'll explore require understanding that abstraction layers have edges, places where the framework's responsibility ends and yours begins.
Here's what I discovered:
The A2A server response structure that was returning:
{
"jsonrpc": "2.0",
"id": "txn-847",
"result": {
"contextId": "ctx-912",
"status": "completed",
"role": "agent",
"parts": [
{
"text": "{\"state\": \"COMPLETED\", \"timestamp\": \"2025-01-15T02:34:56Z\", \"execution_summary\": {\"operation\": \"transform_data\", \"target\": \"resource-alpha-7\", \"metrics\": {\"duration_ms\": 342}}}"
}
]
}
}
See it? The actual result isn't a Python object. It's a JSON string wrapped in a text field, nested inside a parts array, buried in a result envelope.
This is the moment where everything clicked.
Let me unpack what RemoteA2aAgent actually does (and what it doesn't do):
What RemoteA2aAgent Abstracts:
HTTP transport layer
Authentication token management
A2A protocol envelope formatting
Request/response routing
Content/Part object marshalling
What RemoteA2aAgent Doesn't (and probably shouldn't) Assume:
Your custom response data format
How you serialize tool results
Whether you're returning JSON, protobuf, plain text, or binary data
It's not a bug. It's a design boundary. The framework handles the envelope; you handle the content.
If you're building A2A systems, here's the mental model that helped me:
1. The A2A protocol is envelope-oriented
Think of it like postal mail. The protocol handles:
The envelope (JSON-RPC structure)
The addressing (context IDs, message routing)
The delivery confirmation (status codes)
2. Your content format is your responsibility
What's inside that envelope? That's your domain:
Are you returning plain text?
Structured JSON?
Binary data?
A mix of content types?
3. The Runner pattern exists for a reason
When you see code using Runner to interact with RemoteA2aAgent, it's not redundant - it's giving you access to the event stream where you can inspect and deserialize responses according to your format.
Our modern solutions aren't just about technology, they are about creating intelligent, adaptive bridges between systems that speak different dialects of "success." This is what I enjoy the most working in the integration space, an intersection of disparate systems where it is critical that both systems talk to each other and information is not lost in the process.
Here's the pattern that actually works. First, understand that the Runner gives you access to the event stream where responses arrive:
async def _invoke_remote_execution(
self,
backend_agent: RemoteA2aAgent,
**operation_params
) -> Dict[str, Any]:
"""
Invokes remote A2A agent and deserializes the response.
Why Runner? Because the response comes as Content/Part objects
that need unpacking. RemoteA2aAgent handles protocol, not
deserialization of YOUR custom format.
"""
runner = Runner(
agent=backend_agent,
app_name="SecureExecutor",
session_service=self.session_service
)
# Build the A2A-compliant message
message = types.Content(
role="user",
parts=[
types.Part(
mime_type="application/json",
data={
"tool_calls": [{
"type": "function",
"function": {
"name": "process_operation",
"arguments": json.dumps(operation_params)
}
}]
}
)
]
)
# Execute and parse response
outcome = None
async for event in runner.run_async(
user_id=operation_params.get("initiator_id"),
session_id=f"exec_{uuid.uuid4()}",
new_message=message
):
outcome = self._extract_outcome_from_event(event)
if outcome:
break # Got what we need
return outcome or {
"state": "NO_RESPONSE",
"error": "Remote agent didn't return valid data"
}
def _extract_outcome_from_event(self, event) -> Optional[Dict[str, Any]]:
"""
The critical deserialization step.
A2A sends: Content -> Parts -> Text (JSON string)
We need: Python dict
"""
if not hasattr(event, 'content') or not event.content:
return None
if not hasattr(event.content, 'parts') or not event.content.parts:
return None
for part in event.content.parts:
# The response is JSON-as-text, not structured data
if hasattr(part, 'text') and part.text:
try:
parsed = json.loads(part.text)
# Validate it looks like our expected format
if isinstance(parsed, dict) and 'state' in parsed:
logging.info(f"✅ Deserialized response: {parsed.get('state')}")
return parsed
except json.JSONDecodeError as e:
logging.warning(f"Part contained non-JSON text: {e}")
continue
return None
Understanding this boundary has profound implications:
✅ Your agents can evolve independently - Change your response format without touching the protocol layer
✅ You're not constrained by framework assumptions - Want to return protobuf? Binary data? Mixed content? Go ahead.
✅ The pattern is portable - This same approach works across any A2A implementation, not just ADK
✅ You maintain explicit control - No "magic" deserialization that might hide bugs or performance issues
If you're participating in the Google Agent Builder Challenge or any hackathon, this understanding will save you hours of searching for the "right way" that doesn't exist.
1. Understand abstraction boundaries
Every abstraction has edges. Knowing where the framework's responsibility ends and yours begins is crucial.
2. Read what your code is actually doing
Print statements, debug logs, actual response inspection - these never go out of style.
3. The hackathon pressure is real, but accuracy matters more
When you're racing against a deadline, it's tempting to take the easy route because someone said it’s done automatically. Resist that urge. Validate and confirm it.
In our increasingly interconnected digital ecosystem, understanding where framework responsibilities end and application logic begins isn't just a technical skill, it's a critical competency. The ADK team made a deliberate architectural choice: the protocol handles transport, you handle interpretation.
Let's unpack how we can make our systems work smarter, not harder: by recognizing that explicit deserialization isn't technical debt, it's intentional architecture. 💡
Have you encountered similar moments where AI advised you incorrectly and documentation is vague? What design boundaries did you discover while building agent systems? Drop your experiences in the comments - the community learns best when we share our debugging journeys!
Enjoy my blog? For more such awesome blog articles - follow, subscribe, and let's connect.