feat(a2a): emit a single A2A client span and suppress a2a-sdk noise (#932)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: 2 people

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uipath-langchain"
-version = "0.13.6"
+version = "0.13.7"
 description = "Python SDK that enables developers to build and deploy LangGraph agents to the UiPath Cloud Platform"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"

src/uipath_langchain/agent/tools/a2a/__init__.py

@@ -1,6 +1,17 @@
 """A2A (Agent-to-Agent) tools."""
 
-from .a2a_tool import (
+import os
+
+# The a2a-sdk auto-instruments its JSON-RPC transport with OpenTelemetry spans
+# (``a2a.client.transports.jsonrpc.JsonRpcTransport.*``). Those internal spans
+# surface as noisy, unparented nodes in the Execution Trace and are not a
+# meaningful representation of the call. Disable that instrumentation before the
+# SDK is imported (it reads this variable at import time), so the single A2A
+# span emitted by ``a2a_tool`` is the only node for the call. ``setdefault``
+# preserves an explicit opt-in when the variable is already set.
+os.environ.setdefault("OTEL_INSTRUMENTATION_A2A_SDK_ENABLED", "false")
+
+from .a2a_tool import (  # noqa: E402
     A2aClient,
     create_a2a_tools_and_clients,
     open_a2a_tools,

src/uipath_langchain/agent/tools/a2a/a2a_tool.py

@@ -30,9 +30,11 @@
 from langchain_core.messages import ToolCall, ToolMessage
 from langchain_core.tools import BaseTool
 from langgraph.types import Command
+from opentelemetry import trace as otel_trace
 from pydantic import BaseModel, Field
 from uipath._utils._ssl_context import get_httpx_client_kwargs
 from uipath.agent.models.agent import AgentA2aResourceConfig
+from uipath.core.tracing.span_utils import UiPathSpanUtils
 
 from uipath_langchain._utils import get_execution_folder_path
 from uipath_langchain.agent.react.types import AgentGraphState
@@ -251,10 +253,50 @@ def _create_a2a_tool(
         "slug": config.slug,
     }
 
+    async def _invoke(
+        *, message: str, task_id: str | None, context_id: str | None
+    ) -> tuple[str, str, str | None, str | None]:
+        """Send one message to the remote agent inside an A2A trace span.
+
+        The span is parented under the active tool-call span (via
+        ``UiPathSpanUtils.get_parent_context``) so the remote call nests under
+        the tool in the Execution Trace, and is marked
+        ``uipath.custom_instrumentation`` so the LLMOps exporter keeps it. The
+        a2a-sdk's own transport spans are disabled in this package's __init__,
+        so this is the single node representing the call.
+        """
+        parent_ctx = UiPathSpanUtils.get_parent_context()
+        tracer = otel_trace.get_tracer(__name__)
+        with tracer.start_as_current_span(raw_name, context=parent_ctx) as span:
+            # "openinference.span.kind" drives the SpanType shown in the UI;
+            # "toolCall" is the recognized type for a tool invocation.
+            span.set_attribute("openinference.span.kind", "toolCall")
+            span.set_attribute("type", "toolCall")
+            span.set_attribute("span_type", "toolCall")
+            span.set_attribute("uipath.custom_instrumentation", True)
+            span.set_attribute("tool_type", "a2a")
+            span.set_attribute("input", message)
+            span.set_attribute("input.value", message)
+
+            client = await a2a_client.get()
+            text, response_state, new_task_id, new_context_id = await _send_a2a_message(
+                client,
+                agent_label,
+                message=message,
+                task_id=task_id,
+                context_id=context_id,
+            )
+
+            span.set_attribute("output", text)
+            span.set_attribute("output.value", text)
+            span.set_attribute("task_state", response_state)
+            if response_state == "error":
+                span.set_status(otel_trace.StatusCode.ERROR, text)
+            return text, response_state, new_task_id, new_context_id
+
     async def _send(*, message: str) -> str:
-        client = await a2a_client.get()
-        text, state, _, _ = await _send_a2a_message(
-            client, agent_label, message=message, task_id=None, context_id=None
+        text, state, _, _ = await _invoke(
+            message=message, task_id=None, context_id=None
         )
         return _format_response(text, state)
 
@@ -267,10 +309,7 @@ async def _a2a_wrapper(
         task_id = prior.get("task_id")
         context_id = prior.get("context_id")
 
-        client = await a2a_client.get()
-        text, task_state, new_task_id, new_context_id = await _send_a2a_message(
-            client,
-            agent_label,
+        text, task_state, new_task_id, new_context_id = await _invoke(
             message=call["args"]["message"],
             task_id=task_id,
             context_id=context_id,

tests/agent/tools/test_a2a_tool.py

@@ -5,12 +5,20 @@
 MCP servers are resolved — not from a field baked into the resource config.
 """
 
+import os
 from types import SimpleNamespace
 from typing import Any, cast
 
 import pytest
 from a2a.client import Client
 from a2a.types import AgentCard, Message, Part, Role, TextPart
+from opentelemetry import trace as otel_trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import (
+    InMemorySpanExporter,
+)
+from opentelemetry.trace import StatusCode
 from uipath.agent.models.agent import AgentA2aResourceConfig
 
 import uipath_langchain.agent.tools.a2a.a2a_tool as a2a_tool
@@ -308,3 +316,68 @@ async def _get():
     stored = command.update["inner_state"]["tools_storage"][tool.name]
     assert stored["context_id"] == "ctx-9"
     assert "pong" in command.update["messages"][0].content
+
+
+def test_a2a_sdk_telemetry_suppressed_by_default() -> None:
+    """Importing the a2a package disables the a2a-sdk's own OTel transport spans.
+
+    The package __init__ runs (via the module imports above) before the a2a-sdk
+    is imported and sets the suppression default.
+    """
+    assert os.environ.get("OTEL_INSTRUMENTATION_A2A_SDK_ENABLED") == "false"
+
+
+async def test_tool_invocation_emits_custom_a2a_span(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Invoking the tool emits one custom-instrumentation A2A span carrying the
+    toolCall kind and the message/response."""
+    provider = TracerProvider()
+    exporter = InMemorySpanExporter()
+    provider.add_span_processor(SimpleSpanProcessor(exporter))
+    monkeypatch.setattr(otel_trace, "get_tracer", provider.get_tracer)
+
+    resource = _make_resource(cached_agent_card=_cached_card())
+    tools, clients = create_a2a_tools_and_clients([resource])
+    fake = _FakeA2aClient([_agent_message("pong", context_id="ctx-1")])
+
+    async def _get():
+        return fake
+
+    monkeypatch.setattr(clients[0], "get", _get)
+
+    result = await tools[0].ainvoke({"message": "ping"})
+    assert "pong" in result
+
+    a2a_spans = [s for s in exporter.get_finished_spans() if s.name == "Remote Agent"]
+    assert len(a2a_spans) == 1
+    attrs = a2a_spans[0].attributes or {}
+    assert attrs["uipath.custom_instrumentation"] is True
+    assert attrs["openinference.span.kind"] == "toolCall"
+    assert attrs["tool_type"] == "a2a"
+    assert attrs["input.value"] == "ping"
+    assert attrs["output.value"] == "pong"
+
+
+async def test_tool_invocation_marks_span_error(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A failed remote call sets the A2A span status to ERROR."""
+    provider = TracerProvider()
+    exporter = InMemorySpanExporter()
+    provider.add_span_processor(SimpleSpanProcessor(exporter))
+    monkeypatch.setattr(otel_trace, "get_tracer", provider.get_tracer)
+
+    resource = _make_resource(cached_agent_card=_cached_card())
+    tools, clients = create_a2a_tools_and_clients([resource])
+
+    async def _get():
+        return _RaisingA2aClient()
+
+    monkeypatch.setattr(clients[0], "get", _get)
+
+    await tools[0].ainvoke({"message": "ping"})
+
+    a2a_spans = [s for s in exporter.get_finished_spans() if s.name == "Remote Agent"]
+    assert len(a2a_spans) == 1
+    assert a2a_spans[0].status.status_code == StatusCode.ERROR