fix(fara): populate gen_ai.tool.definitions on AGENT span (Review #1)

AgentRunWrapper now attaches gen_ai.tool.definitions as a JSON array
covering the 11 canonical Fara tools, reusing _attrs.tool_definitions(capture).
capture=False -> {type, name} entries; capture=True -> entries with description.

Adds two unit tests asserting the AGENT span carries an 11-element JSON
array with the expected canonical tool names, in both capture modes.

Author: 123liuziming

instrumentation-loongsuite/loongsuite-instrumentation-fara/src/opentelemetry/instrumentation/fara/internal/_wrappers.py

@@ -194,15 +194,19 @@ async def __call__(
         request_model = client_config.get("model") if isinstance(client_config, dict) else None
         conversation_id = state.get_entry_session_id()
 
+        capture = capture_message_content()
         inv = InvokeAgentInvocation(
             provider="openai",
             agent_name=agent_name,
             agent_description="Fara-7B Computer Use Agent",
             conversation_id=conversation_id,
             request_model=request_model,
-            attributes={"gen_ai.framework": FRAMEWORK_NAME},
+            attributes={
+                "gen_ai.framework": FRAMEWORK_NAME,
+                "gen_ai.tool.definitions": safe_json_dumps(tool_definitions(capture)),
+            },
         )
-        if capture_message_content() and user_message:
+        if capture and user_message:
             inv.input_messages = _make_input_messages(str(user_message))
 
         # Reset STEP rotation state for this agent run.

instrumentation-loongsuite/loongsuite-instrumentation-fara/tests/test_wrappers.py

@@ -21,6 +21,7 @@
 from __future__ import annotations
 
 import asyncio
+import json
 import uuid
 
 import fara.fara_agent as fara_agent_mod
@@ -129,6 +130,56 @@ def test_agent_span_error_on_exception(instrument, span_exporter):
     assert agent_spans[0].status.is_ok is False
 
 
+def _canonical_tool_names():
+    return [
+        "key",
+        "type",
+        "mouse_move",
+        "left_click",
+        "scroll",
+        "visit_url",
+        "web_search",
+        "history_back",
+        "pause_and_memorize_fact",
+        "wait",
+        "terminate",
+    ]
+
+
+def test_agent_span_tool_definitions_default(instrument, span_exporter):
+    # capture disabled: AGENT span must still carry gen_ai.tool.definitions
+    # as a JSON array of 11 {type, name} entries (no description).
+    agent = _build_agent()
+    _await(agent.run("click the search box"))
+    spans = span_exporter.get_finished_spans()
+    agent_span = spans_by_name(spans, "invoke_agent FaraAgent")[0]
+    raw = span_attr(agent_span, "gen_ai.tool.definitions")
+    assert raw is not None
+    defs = json.loads(raw)
+    assert isinstance(defs, list)
+    assert len(defs) == 11
+    assert [d["name"] for d in defs] == _canonical_tool_names()
+    for d in defs:
+        assert d["type"] == "function"
+        assert "description" not in d
+
+
+def test_agent_span_tool_definitions_with_content(instrument_with_content, span_exporter):
+    # capture enabled: each entry should also carry a description.
+    agent = _build_agent()
+    _await(agent.run("click the search box"))
+    spans = span_exporter.get_finished_spans()
+    agent_span = spans_by_name(spans, "invoke_agent FaraAgent")[0]
+    raw = span_attr(agent_span, "gen_ai.tool.definitions")
+    assert raw is not None
+    defs = json.loads(raw)
+    assert len(defs) == 11
+    assert [d["name"] for d in defs] == _canonical_tool_names()
+    for d in defs:
+        assert d["type"] == "function"
+        assert d.get("description")
+
+
 # ---------------------------------------------------------------------------
 # STEP span
 # ---------------------------------------------------------------------------