"""Client for interacting with HTTP-based A2A-compatible agents"""

def __init__(self, endpoint_url: str, headers: Optional[Dict[str, str]] = None,

timeout: int = 30, google_a2a_compatible: bool = False):

"""

self.endpoint_url = endpoint_url.rstrip("/")

self.headers = headers or {}

self.timeout = timeout

self._use_google_a2a = google_a2a_compatible

self._protocol_detected = google_a2a_compatible # True after we've detected the protocol type

# Always include content type for JSON

if "Content-Type" not in self.headers:

self.headers["Content-Type"] = "application/json"

# Try to fetch the agent card for A2A protocol support

try:

self.agent_card = self._fetch_agent_card()

# Check for protocol hints in the agent card

if hasattr(self.agent_card, 'capabilities'):

capabilities = getattr(self.agent_card, 'capabilities', {})

if isinstance(capabilities, dict) and (

capabilities.get("google_a2a_compatible") or

capabilities.get("parts_array_format")

):

self._use_google_a2a = True

self._protocol_detected = True

except Exception as e:

# Create a default agent card

self.agent_card = AgentCard(

name="Unknown Agent",

description="Agent card not available",

url=self.endpoint_url,

version="unknown"

)

def get_agent_card(self) -> AgentCard:

"""

return self.agent_card

def _extract_json_from_html(self, html_content: str) -> Dict[str, Any]:

"""Extract JSON data from HTML content, typically when agent card is rendered as HTML"""

try:

# Look for JSON content in a <pre><code class="language-json"> block

# This pattern matches JSON content between code tags

json_pattern = re.compile(r'<code[^>]*>(.*?)</code>', re.DOTALL)

matches = json_pattern.findall(html_content)

if matches:

# Get the longest match (most likely to be complete JSON)

json_text = max(matches, key=len)

# Unescape HTML entities if present

json_text = json_text.replace('&quot;', '"')

json_text = json_text.replace('&#34;', '"')

json_text = json_text.replace('&amp;', '&')

# Parse the extracted JSON

return json.loads(json_text)

except (json.JSONDecodeError, Exception):

pass

# Fallback: Try to find any JSON-like content in the HTML

try:

json_pattern = re.compile(r'({[\s\S]*"name"[\s\S]*})')

matches = json_pattern.findall(html_content)

if matches:

for match in matches:

try:

return json.loads(match)

except:

continue

except Exception:

pass

# No valid JSON found

return {}

def _fetch_agent_card(self):

"""Fetch the agent card from the well-known URL, following A2A protocol standards"""

# Try endpoints in order of A2A protocol preference

endpoints = [

f"{self.endpoint_url}/.well-known/agent.json", # A2A standard endpoint

f"{self.endpoint_url}/agent.json", # Alternative endpoint

f"{self.endpoint_url}/a2a/agent.json" # Legacy endpoint

]

last_error = None

for card_url in endpoints:

try:

# Add Accept header to prefer JSON

headers = dict(self.headers)

headers["Accept"] = "application/json"

# Make the request

response = requests.get(card_url, headers=headers, timeout=self.timeout)

response.raise_for_status()

# Check content type to handle HTML responses

content_type = response.headers.get("Content-Type", "").lower()

if "json" in content_type:

# JSON response

card_data = response.json()

elif "html" in content_type:

# HTML response - extract JSON

card_data = self._extract_json_from_html(response.text)

if not card_data:

raise ValueError("Could not extract JSON from HTML response")

else:

# Try parsing as JSON anyway

try:

card_data = response.json()

except json.JSONDecodeError:

# Try to extract JSON from the response text

card_data = self._extract_json_from_html(response.text)

if not card_data:

raise ValueError(f"Unexpected content type: {content_type}")

# If we get here, we successfully retrieved the agent card

break

except Exception as e:

last_error = e

# Continue to next endpoint

continue

else:

# All endpoints failed - raise connection error

raise A2AConnectionError(

f"Failed to fetch agent card from any endpoint: {str(last_error)}"

) from last_error

# Check for protocol hints in the agent card

if "capabilities" in card_data:

capabilities = card_data.get("capabilities", {})

if isinstance(capabilities, dict) and (

capabilities.get("google_a2a_compatible") or

capabilities.get("parts_array_format")

):

self._use_google_a2a = True

self._protocol_detected = True

# Create AgentSkill objects from data

skills = []

for skill_data in card_data.get("skills", []):

skills.append(AgentSkill(

id=skill_data.get("id", str(uuid.uuid4())),

name=skill_data.get("name", "Unknown Skill"),

description=skill_data.get("description", ""),

tags=skill_data.get("tags", []),

examples=skill_data.get("examples", [])

))

# Create AgentCard object

return AgentCard(

name=card_data.get("name", "Unknown Agent"),

description=card_data.get("description", ""),

url=self.endpoint_url,

version=card_data.get("version", "unknown"),

authentication=card_data.get("authentication"),

capabilities=card_data.get("capabilities", {}),

skills=skills,

provider=card_data.get("provider"),

documentation_url=card_data.get("documentationUrl")

)

def _detect_protocol_version(self, response_error=None):

"""

# Already detected or explicitly set

if self._protocol_detected:

return self._use_google_a2a

# Check if error contains clues about missing 'parts' field (Google A2A)

if response_error:

error_str = str(response_error).lower()

# Be very specific with error detection to avoid false positives

if "parts" in error_str and any(term in error_str for term in

["required", "missing", "validation", "schema"]):

self._use_google_a2a = True

self._protocol_detected = True

return True

# Special handling for specific common Google A2A errors with strict pattern

if ("tagged-union" in error_str and "parts" in error_str and

"missing" in error_str):

self._use_google_a2a = True

self._protocol_detected = True

return True

# No clear indication, use the current setting

return self._use_google_a2a

def send_message(self, message: Message) -> Message:

"""

# Try endpoints in a more logical order with fewer variations

base_url = self.endpoint_url.rstrip("/")

endpoints_to_try = [

base_url, # Agent's main endpoint first

f"{base_url}/a2a" # A2A specific endpoint if main fails

]

# Only add tasks/send if this looks like a task-specific endpoint

if not base_url.endswith(("/a2a", "/tasks", "/send")):

endpoints_to_try.append(f"{base_url}/tasks/send")

# Deduplicate endpoints

endpoints_to_try = list(dict.fromkeys(endpoints_to_try))

# First try A2A protocol style with tasks

task_response = None

for endpoint in endpoints_to_try:

try:

# Create a task from the message

task = self._create_task(message)

# Try to send the task to this endpoint

result = self._send_task(task, endpoint_override=endpoint)

# If we get here, the endpoint worked

# Remember this working endpoint for future requests

self.endpoint_url = endpoint

# Convert the task result back to a message

if result.artifacts and len(result.artifacts) > 0:

for artifact in result.artifacts:

if "parts" in artifact:

parts = artifact["parts"]

for part in parts:

if part.get("type") == "text":

task_response = Message(

content=TextContent(text=part.get("text", "")),

role=MessageRole.AGENT,

parent_message_id=message.message_id,

conversation_id=message.conversation_id

)

break

elif part.get("type") == "function_response":

task_response = Message(

content=FunctionResponseContent(

name=part.get("name", ""),

response=part.get("response", {})

),

role=MessageRole.AGENT,

parent_message_id=message.message_id,

conversation_id=message.conversation_id

)

break

elif part.get("type") == "function_call":

# Convert parameters to FunctionParameter objects

params = []

for param in part.get("parameters", []):

params.append(FunctionParameter(

name=param.get("name", ""),

value=param.get("value", "")

))

task_response = Message(

content=FunctionCallContent(

name=part.get("name", ""),

parameters=params

),

role=MessageRole.AGENT,

parent_message_id=message.message_id,

conversation_id=message.conversation_id

)

break

elif part.get("type") == "error":

task_response = Message(

content=ErrorContent(message=part.get("message", "")),

role=MessageRole.AGENT,

parent_message_id=message.message_id,

conversation_id=message.conversation_id

)

break

# If we got a response, return it

if task_response is not None:

return task_response

except Exception as e:

# This endpoint didn't work, try the next one

continue

# If we get here, all task endpoints failed, try legacy behavior - direct message posting

# First try standard python_a2a format

if not self._use_google_a2a:

for endpoint in endpoints_to_try:

try:

# Standard python_a2a format

response = requests.post(

endpoint,

json=message.to_dict(),

headers=self.headers,

timeout=self.timeout

)

# If we succeed, remember this endpoint

self.endpoint_url = endpoint

# Check for HTTP error

try:

response.raise_for_status()

except requests.HTTPError as e:

# Try to extract error details for protocol detection

try:

error_data = response.json()

error_str = json.dumps(error_data)

except:

error_str = str(e)

# Update protocol detection based on error

should_retry_with_google = self._detect_protocol_version(error_str)

# If we detected Google A2A format, break to try Google format

if should_retry_with_google:

break

# Otherwise try next endpoint

continue

# Process successful response

try:

# Check if response has clear Google A2A format indicators

response_data = response.json()

# Check for clear Google A2A format markers

if ("parts" in response_data and isinstance(response_data.get("parts"), list) and

"role" in response_data and not "content" in response_data):

# Response is in Google A2A format

self._use_google_a2a = True

self._protocol_detected = True

return Message.from_google_a2a(response_data)

else:

# Standard format

return Message.from_dict(response_data)

except ValueError as e:

# Try to get plain text if JSON parsing fails

try:

text_content = response.text.strip()

if text_content:

return Message(

content=TextContent(text=text_content),

role=MessageRole.AGENT,

parent_message_id=message.message_id,

conversation_id=message.conversation_id

)

except:

pass

# Try next endpoint

continue

except requests.RequestException:

# Try next endpoint

continue

# Try with Google A2A format if needed

if self._use_google_a2a or self._protocol_detected:

for endpoint in endpoints_to_try:

try:

# Get the message in Google A2A format

message_data = message.to_google_a2a()

# Ensure messageId is at the top level

if "metadata" in message_data and "message_id" in message_data["metadata"]:

message_data["messageId"] = message_data["metadata"]["message_id"]

request_data = {

"jsonrpc": "2.0",

"id": 1,

"method": "message/send",

"params": {

"message": message_data

}

}

response = requests.post(

endpoint,

json=request_data,

headers=self.headers,

timeout=self.timeout

)

# If we succeed, remember this endpoint

self.endpoint_url = endpoint

# Handle HTTP errors

try:

response.raise_for_status()

except requests.HTTPError:

# Try next endpoint

continue

# Process successful response

try:

response_data = response.json()

# Check for Google A2A format response

if ("parts" in response_data and

isinstance(response_data.get("parts"), list) and

"role" in response_data):

# Google A2A format response

self._use_google_a2a = True

self._protocol_detected = True

return Message.from_google_a2a(response_data)

else:

# Standard format response

return Message.from_dict(response_data)

except Exception:

# Try to handle plain text response

try:

text = response.text.strip()

if text:

return Message(

content=TextContent(text=text),

role=MessageRole.AGENT,

parent_message_id=message.message_id,

conversation_id=message.conversation_id

)

except:

pass

# Try next endpoint

continue

except requests.RequestException:

# Try next endpoint

continue

# If we get here, all endpoints failed

return Message(

content=ErrorContent(message=f"Failed to communicate with agent at {self.endpoint_url}. Tried multiple endpoint variations."),

role=MessageRole.AGENT,

parent_message_id=message.message_id,

conversation_id=message.conversation_id

)

def send_conversation(self, conversation: Conversation) -> Conversation:

"""

# Try possible endpoints in order of preference

endpoints_to_try = [

self.endpoint_url, # Try the exact URL first

self.endpoint_url.rstrip("/"), # URL without trailing slash

f"{self.endpoint_url.rstrip('/')}/a2a", # Try /a2a endpoint

]

# Deduplicate endpoints

endpoints_to_try = list(dict.fromkeys(endpoints_to_try))

# First try standard python_a2a format

if not self._use_google_a2a:

for endpoint in endpoints_to_try:

try:

response = requests.post(

endpoint,

json=conversation.to_dict(),

headers=self.headers,

timeout=self.timeout

)

# If we succeed, remember this endpoint

self.endpoint_url = endpoint

# Handle HTTP errors

try:

response.raise_for_status()

except requests.HTTPError as e:

# Try to extract error details for protocol detection

try:

error_data = response.json()

error_str = json.dumps(error_data)

except:

error_str = str(e)

# Update protocol detection based on error

should_retry_with_google = self._detect_protocol_version(error_str)

# If we detected Google A2A format, break to try Google format

if should_retry_with_google:

break

# Otherwise try next endpoint

continue

# Process successful response

try:

response_data = response.json()

# Check if the response is in Google A2A format

if "messages" in response_data and isinstance(response_data["messages"], list):

if (response_data["messages"] and

"parts" in response_data["messages"][0] and

isinstance(response_data["messages"][0].get("parts"), list)):

# Response is in Google A2A format

self._use_google_a2a = True

self._protocol_detected = True

return Conversation.from_google_a2a(response_data)

# Standard format

return Conversation.from_dict(response_data)

except Exception:

# Try to extract text content if JSON parsing fails

try:

text_content = response.text.strip()

if text_content:

# Create a new message with the response text

last_message = conversation.messages[-1] if conversation.messages else None

parent_id = last_message.message_id if last_message else None

# Add a response message to the conversation

conversation.create_text_message(

text=text_content,

role=MessageRole.AGENT,

parent_message_id=parent_id

)

return conversation

except:

pass

# Try next endpoint

continue

except requests.RequestException:

# Try next endpoint

continue

# Try with Google A2A format if needed

if self._use_google_a2a or self._protocol_detected:

for endpoint in endpoints_to_try:

try:

# Google A2A format

response = requests.post(

endpoint,

json=conversation.to_google_a2a(),

headers=self.headers,

timeout=self.timeout

)

# If we succeed, remember this endpoint

self.endpoint_url = endpoint

# Handle HTTP errors

try:

response.raise_for_status()

except requests.HTTPError:

# Try next endpoint

continue

# Process successful response

try:

response_data = response.json()

# Check if the response is in Google A2A format

if "messages" in response_data and isinstance(response_data["messages"], list):

if (response_data["messages"] and

"parts" in response_data["messages"][0] and

isinstance(response_data["messages"][0].get("parts"), list)):

# Response is in Google A2A format

self._use_google_a2a = True

self._protocol_detected = True

return Conversation.from_google_a2a(response_data)

# Standard format

return Conversation.from_dict(response_data)

except Exception:

# Try to extract text content if JSON parsing fails

try:

text_content = response.text.strip()

if text_content:

# Create a new message with the response text

last_message = conversation.messages[-1] if conversation.messages else None

parent_id = last_message.message_id if last_message else None

# Add a response message to the conversation

conversation.create_text_message(

text=text_content,

role=MessageRole.AGENT,

parent_message_id=parent_id

)

return conversation

except:

pass

# Try next endpoint

continue

except requests.RequestException:

# Try next endpoint

continue

# If we get here, all endpoints failed

# Create an error message and add it to the conversation

error_msg = f"Failed to communicate with agent at {self.endpoint_url}. Tried multiple endpoint variations."

conversation.create_error_message(error_msg)

return conversation

def ask(self, message_text):

"""

# Check if message is already a Message object

if isinstance(message_text, str):

message = Message(

content=TextContent(text=message_text),

role=MessageRole.USER

)

else:

message = message_text

# Send message

response = self.send_message(message)

# Extract text from response

if response and hasattr(response, "content"):

content_type = getattr(response.content, "type", None)

if content_type == "text":

return response.content.text

elif content_type == "error":

return f"Error: {response.content.message}"

elif content_type == "function_response":

return f"Function '{response.content.name}' returned: {json.dumps(response.content.response, indent=2)}"

elif content_type == "function_call":

params = {p.name: p.value for p in response.content.parameters}

return f"Function call '{response.content.name}' with parameters: {json.dumps(params, indent=2)}"

elif response.content is not None:

return str(response.content)

# If text extraction from standard format failed, check for Google A2A format

if response:

try:

# Try to access parts directly

google_format = response.to_google_a2a()

if "parts" in google_format:

for part in google_format["parts"]:

if part.get("type") == "text" and "text" in part:

return part["text"]

except:

pass

return "No text response"

def _create_task(self, message):

"""

# Convert string to Message if needed

if isinstance(message, str):

message = Message(

content=TextContent(text=message),

role=MessageRole.USER

)

# Create a task

return Task(

id=str(uuid.uuid4()),

message=message.to_dict() if isinstance(message, Message) else message

)

def _send_task(self, task, endpoint_override=None):

"""

# Use the override if provided, otherwise use the standard endpoint

base_url = endpoint_override if endpoint_override else self.endpoint_url

base_url = base_url.rstrip("/")

# Prepare JSON-RPC request

request_data = {

"jsonrpc": "2.0",

"id": 1,

"method": "tasks/send",

"params": task.to_dict()

}

# Try endpoints in order of preference

task_endpoints = []

# If the base URL already ends with a task-related path, use it directly

if base_url.endswith(("/tasks/send", "/a2a/tasks/send")):

task_endpoints.append(base_url)

else:

# For normal agent endpoints, try task-specific paths

task_endpoints.extend([

f"{base_url}/tasks/send",

f"{base_url}/a2a/tasks/send"

])

last_error = None

for endpoint in task_endpoints:

try:

response = requests.post(

endpoint,

json=request_data,

headers=self.headers,

timeout=self.timeout

)

response.raise_for_status()

# Check for content type and parse response

content_type = response.headers.get("Content-Type", "").lower()

if "application/json" in content_type:

response_data = response.json()

else:

# Try to parse as JSON anyway

try:

response_data = response.json()

except json.JSONDecodeError:

raise ValueError("Response is not valid JSON")

# If we reach here, the request succeeded

break

except Exception as e:

last_error = e

continue

else:

# All task endpoints failed

if last_error:

raise last_error

else:

raise A2AConnectionError("No task endpoints available")

# Parse the response

result = response_data.get("result", {})

# If result is empty but we have a text response, create a task with it

if not result and isinstance(response_data, dict) and "text" in response_data:

# Create a simple task with text response

task.artifacts = [{

"parts": [{

"type": "text",

"text": response_data["text"]

}]

}]

task.status = TaskStatus(state=TaskState.COMPLETED)

return task

# Convert to Task object or use raw result if parsing fails

try:

result_task = Task.from_dict(result)

# Check if this might be Google A2A format

if result and isinstance(result, dict):

try:

for artifact in result.get("artifacts", []):

if "parts" in artifact and isinstance(artifact["parts"], list):

for part in artifact["parts"]:

if part.get("type") == "text" and "text" in part:

# This looks like Google A2A format

self._use_google_a2a = True

self._protocol_detected = True

break

except:

pass

return result_task

except Exception:

# Create a simple task with the raw result

task.artifacts = [{

"parts": [{

"type": "text",

"text": str(result)

}]

}]

task.status = TaskStatus(state=TaskState.COMPLETED)

return task

def get_task(self, task_id, history_length=0):

"""

# Prepare JSON-RPC request

request_data = {

"jsonrpc": "2.0",

"id": 1,

"method": "tasks/get",

"params": {

"id": task_id,

"historyLength": history_length

}

}

# Try possible endpoints

endpoints = [

f"{self.endpoint_url}/tasks/get",

f"{self.endpoint_url}/a2a/tasks/get"

]

for endpoint in endpoints:

try:

response = requests.post(

endpoint,

json=request_data,

headers=self.headers,

timeout=self.timeout

)

response.raise_for_status()

# Parse the response

response_data = response.json()

result = response_data.get("result", {})

# Try to convert to Task object

try:

# Check for Google A2A format

if result and isinstance(result, dict):

for artifact in result.get("artifacts", []):

if "parts" in artifact and isinstance(artifact["parts"], list):

for part in artifact["parts"]:

if part.get("type") == "text" and "text" in part:

# This looks like Google A2A format

self._use_google_a2a = True

self._protocol_detected = True

return Task.from_google_a2a(result)

# Standard format

return Task.from_dict(result)

except Exception:

# If conversion fails, create a simple task with the raw result

return Task(

id=task_id,

status=TaskStatus(state=TaskState.COMPLETED),

artifacts=[{

"parts": [{

"type": "text",

"text": str(result or response_data)

}]

}]

)

except Exception:

# Try next endpoint

continue

# If we get here, all endpoints failed

return Task(

id=task_id,

status=TaskStatus(

state=TaskState.FAILED,

message={"error": f"Failed to get task from {self.endpoint_url}"}

)

)

def cancel_task(self, task_id):

"""

# Prepare JSON-RPC request

request_data = {

"jsonrpc": "2.0",

"id": 1,

"method": "tasks/cancel",

"params": {

"id": task_id

}

}

# Try possible endpoints

endpoints = [

f"{self.endpoint_url}/tasks/cancel",

f"{self.endpoint_url}/a2a/tasks/cancel"

]

for endpoint in endpoints:

try:

response = requests.post(

endpoint,

json=request_data,

headers=self.headers,

timeout=self.timeout

)

response.raise_for_status()

# Parse the response

response_data = response.json()

result = response_data.get("result", {})

# Try to convert to Task object

try:

# Check for Google A2A format

if result and isinstance(result, dict):

for artifact in result.get("artifacts", []):

if "parts" in artifact and isinstance(artifact["parts"], list):

for part in artifact["parts"]:

if part.get("type") == "text" and "text" in part:

# This looks like Google A2A format

self._use_google_a2a = True

self._protocol_detected = True

return Task.from_google_a2a(result)

# Standard format

return Task.from_dict(result)

except Exception:

# If conversion fails, create a simple task with the raw result