Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
refactor(tracing): refactor the tracing module into an agent middleware (#1579)
qbcaa3e5ad41001
diff --git a/src/agentscope/middleware/__init__.py b/src/agentscope/middleware/__init__.pyindex d898ddea4..b029793ef 100644--- a/src/agentscope/middleware/__init__.py+++ b/src/agentscope/middleware/__init__.py@@ -2,7 +2,10 @@"""Middleware system for AgentScope agents."""from ._base import MiddlewareBase+from ._tracing import TracingMiddleware, setup_tracing__all__ = ["MiddlewareBase",+ "TracingMiddleware",+ "setup_tracing",]diff --git a/src/agentscope/middleware/_base.py b/src/agentscope/middleware/_base.pyindex 884938e3e..3e8968cf1 100644--- a/src/agentscope/middleware/_base.py+++ b/src/agentscope/middleware/_base.py@@ -7,7 +7,7 @@ if TYPE_CHECKING:from ..model import ChatResponse-class MiddlewareBase:+class MiddlewareBase: # pylint: disable=unused-argument"""Base class for all middleware implementations.Middleware provides interception mechanisms at 5 key execution points@@ -80,9 +80,10 @@ class MiddlewareBase:Yields:AgentEvent | Msg: Events from the reply process"""- raise NotImplementedError(+ raise RuntimeError(f"{type(self).__name__} does not implement on_reply",)+ yield # pylint: disable=unreachableasync def on_reasoning(self,@@ -102,9 +103,10 @@ class MiddlewareBase:Yields:Various events from the reasoning process"""- raise NotImplementedError(+ raise RuntimeError(f"{type(self).__name__} does not implement on_reasoning",)+ yield # pylint: disable=unreachableasync def on_acting(self,@@ -124,9 +126,10 @@ class MiddlewareBase:Yields:Events from the tool execution process"""- raise NotImplementedError(+ raise RuntimeError(f"{type(self).__name__} does not implement on_acting",)+ yield # pylint: disable=unreachableasync def on_model_call(self,@@ -152,7 +155,7 @@ class MiddlewareBase:Returns:ChatResponse or AsyncGenerator[ChatResponse, None]"""- raise NotImplementedError(+ raise RuntimeError(f"{type(self).__name__} does not implement on_model_call",)@@ -174,6 +177,6 @@ class MiddlewareBase:Returns:str: The transformed system prompt"""- raise NotImplementedError(- f"{type(self).__name__} does not implement " f"on_system_prompt",+ raise RuntimeError(+ f"{type(self).__name__} does not implement on_system_prompt",)diff --git a/src/agentscope/middleware/_tracing/__init__.py b/src/agentscope/middleware/_tracing/__init__.pynew file mode 100644index 000000000..70811c8d2--- /dev/null+++ b/src/agentscope/middleware/_tracing/__init__.py@@ -0,0 +1,10 @@+# -*- coding: utf-8 -*-+"""The tracing interface class in agentscope."""++from ._setup import setup_tracing+from ._trace import TracingMiddleware++__all__ = [+ "setup_tracing",+ "TracingMiddleware",+]diff --git a/src/agentscope/tracing/_attributes.py b/src/agentscope/middleware/_tracing/_attributes.pysimilarity index 73%rename from src/agentscope/tracing/_attributes.pyrename to src/agentscope/middleware/_tracing/_attributes.pyindex 991481b5a..eb5fe3673 100644--- a/src/agentscope/tracing/_attributes.py+++ b/src/agentscope/middleware/_tracing/_attributes.py@@ -85,9 +85,6 @@ class SpanAttributes:GEN_AI_AGENT_DESCRIPTION = GenAIAttributes.GEN_AI_AGENT_DESCRIPTION"""The gen ai agent description."""- GEN_AI_SYSTEM_INSTRUCTIONS = GenAIAttributes.GEN_AI_SYSTEM_INSTRUCTIONS- """The gen ai system instructions."""-# GenAI Tool AttributesGEN_AI_TOOL_CALL_ID = GenAIAttributes.GEN_AI_TOOL_CALL_ID"""The gen ai tool call ID."""@@ -98,44 +95,57 @@ class SpanAttributes:GEN_AI_TOOL_DESCRIPTION = GenAIAttributes.GEN_AI_TOOL_DESCRIPTION"""The gen ai tool description."""- GEN_AI_TOOL_CALL_ARGUMENTS = "gen_ai.tool.call.arguments"+ GEN_AI_TOOL_CALL_ARGUMENTS = GenAIAttributes.GEN_AI_TOOL_CALL_ARGUMENTS"""The gen ai tool call arguments."""- GEN_AI_TOOL_CALL_RESULT = "gen_ai.tool.call.result"+ GEN_AI_TOOL_CALL_RESULT = GenAIAttributes.GEN_AI_TOOL_CALL_RESULT"""The gen ai tool call result."""- GEN_AI_TOOL_DEFINITIONS = "gen_ai.tool.definitions"+ GEN_AI_TOOL_DEFINITIONS = GenAIAttributes.GEN_AI_TOOL_DEFINITIONS"""The gen ai tool definitions."""- # GenAI Embedding Attributes- GEN_AI_EMBEDDINGS_DIMENSION_COUNT = "gen_ai.embeddings.dimension.count"- """The gen ai embeddings dimension count."""+ AGENTSCOPE_REPLY_ID = "agentscope.agent.reply_id"+ """The reply ID of the current agent reply.- # AgentScope Extended Attributes- AGENTSCOPE_FORMAT_TARGET = "agentscope.format.target"- """The agentscope format target."""+ Shared by both calls in a HITL or external-execution chain, allowing+ observers to group the two ``invoke_agent`` spans that belong to the+ same logical reply.+ """- AGENTSCOPE_FORMAT_COUNT = "agentscope.format.count"- """The count of formatted messages in the result."""+ AGENTSCOPE_HITL_PENDING_TOOLS = "agentscope.agent.hitl_pending_tools"+ """JSON list of tool names that are waiting for human confirmation.- AGENTSCOPE_FUNCTION_NAME = "agentscope.function.name"- """The agentscope function name."""+ Set on the first ``invoke_agent`` span when the agent pauses due to a+ ``RequireUserConfirmEvent``.+ """- AGENTSCOPE_FUNCTION_INPUT = "agentscope.function.input"- """The agentscope function input."""+ AGENTSCOPE_EXTERNAL_EXECUTION_PENDING_TOOLS = (+ "agentscope.agent.external_execution_pending_tools"+ )+ """JSON list of tool names submitted for external execution.- AGENTSCOPE_FUNCTION_OUTPUT = "agentscope.function.output"- """The agentscope function output."""+ Set on the first ``invoke_agent`` span when the agent pauses due to a+ ``RequireExternalExecutionEvent``.+ """+ AGENTSCOPE_INCOMING_EVENT_TYPE = "agentscope.agent.incoming_event_type"+ """Type of the continuation event passed to the second reply call.-class OperationNameValues:- """The operation name values."""+ Possible values: ``"user_confirm_result"``,+ ``"external_execution_result"``.+ """++ AGENTSCOPE_IS_EXTERNAL_EXECUTION = "agentscope.agent.is_external_execution"+ """Marks a synthetic ``execute_tool`` span that represents a tool executed+ externally (i.e. via ``ExternalExecutionResultEvent``).- FORMATTER = "format"- """The formatter operation name."""+ The timestamp reflects when the result was received, not when the tool+ actually ran on the external system.+ """- INVOKE_GENERIC_FUNCTION = "invoke_generic_function"- """The invoke generic function operation name."""++class OperationNameValues:+ """The operation name values."""CHAT = GenAIAttributes.GenAiOperationNameValues.CHAT.value"""The chat operation name."""@@ -146,9 +156,6 @@ class OperationNameValues:EXECUTE_TOOL = GenAIAttributes.GenAiOperationNameValues.EXECUTE_TOOL.value"""The execute tool operation name."""- EMBEDDINGS = GenAIAttributes.GenAiOperationNameValues.EMBEDDINGS.value- """The embeddings operation name."""-class ProviderNameValues:"""The provider name values."""diff --git a/src/agentscope/middleware/_tracing/_converter.py b/src/agentscope/middleware/_tracing/_converter.pynew file mode 100644index 000000000..040377d7e--- /dev/null+++ b/src/agentscope/middleware/_tracing/_converter.py@@ -0,0 +1,125 @@+# -*- coding: utf-8 -*-+"""Convert ContentBlock to OpenTelemetry GenAI part format."""++import json+from typing import Any, Dict++from ...message import (+ ContentBlock,+ TextBlock,+ ThinkingBlock,+ ToolCallBlock,+ ToolResultBlock,+ DataBlock,+ Base64Source,+ URLSource,+)++from ._utils import _serialize_to_str++# Map MIME type prefix to OTel modality name+_MEDIA_TYPE_TO_MODALITY: Dict[str, str] = {+ "image": "image",+ "audio": "audio",+ "video": "video",+}+++def _get_modality(media_type: str) -> str:+ """Derive OTel modality from a MIME type string (e.g. 'image/png')."""+ prefix = media_type.split("/")[0] if media_type else ""+ return _MEDIA_TYPE_TO_MODALITY.get(prefix, "unknown")+++def _convert_media_block(+ source: Base64Source | URLSource,+) -> Dict[str, Any] | None:+ """Convert a DataBlock source to OpenTelemetry GenAI part format.++ Args:+ source (`Base64Source | URLSource`):+ The data source of the DataBlock.++ Returns:+ `Dict[str, Any] | None`:+ Converted part Dictionary or None if the source type is invalid.+ """+ modality = _get_modality(source.media_type)++ if isinstance(source, URLSource):+ return {+ "type": "uri",+ "uri": str(source.url),+ "modality": modality,+ }++ if isinstance(source, Base64Source):+ return {+ "type": "blob",+ "content": source.data,+ "media_type": source.media_type,+ "modality": modality,+ }++ return None+++def _convert_block_to_part(block: ContentBlock) -> Dict[str, Any] | None:+ """Convert content block to OpenTelemetry GenAI part format.++ Converts text, thinking, tool_call, tool_result and data (media) blocks+ to standardized parts.++ Args:+ block (`ContentBlock`):+ The content block object to convert. Supported block types:+ - text: Text content block+ - thinking: Reasoning/thinking content block+ - tool_call: Tool call block with id, name, and input+ - tool_result: Tool result block with id and output+ - data: Binary data block (image, audio, video, etc.)++ Returns:+ `Dict[str, Any] | None`:+ Standardized part Dictionary in OpenTelemetry GenAI format,+ or None if the block type is unsupported or cannot be converted.+ """+ part: Dict[str, Any] | None = None++ if isinstance(block, TextBlock):+ part = {+ "type": "text",+ "content": block.text,+ }+ elif isinstance(block, ThinkingBlock):+ part = {+ "type": "reasoning",+ "content": block.thinking,+ }+ elif isinstance(block, ToolCallBlock):+ try:+ arguments = json.loads(block.input)+ except (json.JSONDecodeError, TypeError):+ arguments = block.input+ part = {+ "type": "tool_call",+ "id": block.id,+ "name": block.name,+ "arguments": arguments,+ }+ elif isinstance(block, ToolResultBlock):+ output = block.output+ if isinstance(output, (list, dict)):+ result = _serialize_to_str(output)+ else:+ result = str(output)++ part = {+ "type": "tool_call_response",+ "id": block.id,+ "response": result,+ }+ elif isinstance(block, DataBlock):+ part = _convert_media_block(block.source)++ return partdiff --git a/src/agentscope/tracing/_extractor.py b/src/agentscope/middleware/_tracing/_extractor.pysimilarity index 59%rename from src/agentscope/tracing/_extractor.pyrename to src/agentscope/middleware/_tracing/_extractor.pyindex 2bf0908b8..5feabbeb4 100644--- a/src/agentscope/tracing/_extractor.py+++ b/src/agentscope/middleware/_tracing/_extractor.py@@ -1,12 +1,9 @@# -*- coding: utf-8 -*-"""Extract attributes from AgentScope components for OpenTelemetry tracing."""import inspect-from typing import Any, Dict, Tuple, TYPE_CHECKING+from typing import Any, Dict, TYPE_CHECKING-from ..embedding import EmbeddingModelBase-from ..message import Msg, ToolCallBlock-from ..model import ChatModelBase-from ..tool import ToolChoice+from ...message import Msg, ToolCallBlockfrom ._attributes import (SpanAttributes,@@ -17,15 +14,9 @@ from ._converter import _convert_block_to_partfrom ._utils import _serialize_to_strif TYPE_CHECKING:- from ..agent import AgentBase- from ..formatter import FormatterBase- from ..tool import (- Toolkit,- )-else:- AgentBase = "AgentBase"- FormatterBase = "FormatterBase"- Toolkit = "Toolkit"+ from ...agent import Agent+ from ...model import ChatModelBase+ from ...tool import Toolkit, ToolChoice_CLASS_NAME_MAP = {"dashscope": ProviderNameValues.DASHSCOPE,@@ -56,37 +47,17 @@ def _get_common_attributes() -> Dict[str, str]:`Dict[str, str]`:Common span attributes including conversation ID"""+ from ._trace import _current_session_id++ session_id = _current_session_id.get()return {- SpanAttributes.GEN_AI_CONVERSATION_ID: _serialize_to_str(- # TODO: deprecate the id here- "[conversation_id_placeholder]",+ SpanAttributes.GEN_AI_CONVERSATION_ID: (+ session_id if session_id else "[no_session_id]"),}-def _get_format_target(instance: Any) -> str:- """Get format target for the given instance.-- Maps AgentScope formatter class names to format target names.-- Args:- instance (`Any`):- The formatter instance to get the format target for.-- Returns:- `str`:- Format target name (e.g., "openai", "dashscope", "anthropic")- """- classname = instance.__class__.__name__- prefix_key = (- classname.removesuffix("ChatFormatter")- .removesuffix("MultiAgentFormatter")- .lower()- )- return _CLASS_NAME_MAP.get(prefix_key, "unknown")---def _get_provider_name(instance: ChatModelBase) -> str:+def _get_provider_name(instance: "ChatModelBase") -> str:"""Get provider name from ChatModelBase instance.Maps ChatModelBase class names to provider names, with special handling@@ -136,7 +107,7 @@ def _get_provider_name(instance: ChatModelBase) -> str:def _get_tool_definitions(tools: list[dict[str, Any]] | None,- tool_choice: ToolChoice | None,+ tool_choice: "ToolChoice | None",) -> str | None:"""Extract and serialize tool definitions for tracing.@@ -197,8 +168,7 @@ def _get_tool_definitions(def _get_llm_request_attributes(- instance: ChatModelBase,- args: Tuple[Any, ...],+ instance: "ChatModelBase",kwargs: Dict[str, Any],) -> Dict[str, Any]:"""Get LLM request attributes for OpenTelemetry tracing.@@ -208,8 +178,6 @@ def _get_llm_request_attributes(Args:instance (`ChatModelBase`):The chat model instance making the request.- args (`Tuple[Any, ...]`):- Positional arguments passed to the model call.kwargs (`Dict[str, Any]`):Keyword arguments including generation parameters such astemperature, top_p, top_k, max_tokens, presence_penalty,@@ -219,7 +187,7 @@ def _get_llm_request_attributes(`Dict[str, Any]`:OpenTelemetry GenAI attributes with string values, includingoperation name, provider name, model name, generation parameters,- tool definitions, and custom AgentScope function input.+ and tool definitions."""attributes = {@@ -229,7 +197,7 @@ def _get_llm_request_attributes(# conditionally required attributesSpanAttributes.GEN_AI_REQUEST_MODEL: getattr(instance,- "model_name",+ "model","unknown_model",),# recommended attributes@@ -248,13 +216,6 @@ def _get_llm_request_attributes("stop_sequences",),SpanAttributes.GEN_AI_REQUEST_SEED: kwargs.get("seed"),- # custom attributes- SpanAttributes.AGENTSCOPE_FUNCTION_INPUT: _serialize_to_str(- {- "args": args,- "kwargs": kwargs,- },- ),}# Extract tool definitions if provided@@ -360,8 +321,8 @@ def _get_llm_response_attributes(Returns:`Dict[str, Any]`:OpenTelemetry GenAI response attributes including response ID,- finish reasons, token usage (input/output tokens), output messages,- and custom AgentScope function output.+ finish reasons, token usage (input/output tokens), and output+ messages."""attributes = {SpanAttributes.GEN_AI_RESPONSE_ID: getattr(@@ -386,9 +347,6 @@ def _get_llm_response_attributes(output_messages,)- attributes[SpanAttributes.AGENTSCOPE_FUNCTION_OUTPUT] = _serialize_to_str(- chat_response,- )return attributes@@ -430,24 +388,32 @@ def _get_agent_messages(return formatted_msgsexcept Exception:- return [- {- "role": msg.role,- "parts": [- {- "type": "text",- "content": str(msg.content) if msg.content else "",- },- ],- "name": msg.name,- "finish_reason": "stop",- },- ]+ # Fallback: try simple attribute access on the original object.+ # If msg was already converted to a list or lacks role/name, return+ # an empty list rather than raising a secondary exception.+ try:+ single = msg[0] if isinstance(msg, list) else msg+ return [+ {+ "role": single.role,+ "parts": [+ {+ "type": "text",+ "content": (+ str(single.content) if single.content else ""+ ),+ },+ ],+ "name": single.name,+ "finish_reason": "stop",+ },+ ]+ except Exception:+ return []def _get_agent_request_attributes(- instance: "AgentBase",- args: Tuple[Any, ...],+ instance: "Agent",kwargs: Dict[str, Any],) -> Dict[str, str]:"""Get agent request attributes for OpenTelemetry tracing.@@ -455,18 +421,15 @@ def _get_agent_request_attributes(Extracts agent metadata and input data into GenAI attributes.Args:- instance (`AgentBase`):+ instance (`Agent`):The agent instance making the request.- args (`Tuple[Any, ...]`):- Positional arguments passed to the agent's reply method.kwargs (`Dict[str, Any]`):Keyword arguments passed to the agent's reply method.Returns:`Dict[str, str]`:OpenTelemetry GenAI attributes including operation name, agent ID,- agent name, agent description, input messages (if provided), and- custom AgentScope function input.+ agent name, agent description, and input messages (if provided)."""attributes = {SpanAttributes.GEN_AI_OPERATION_NAME: (@@ -485,8 +448,8 @@ def _get_agent_request_attributes(}msg = None- if args and len(args) > 0:- msg = args[0]+ if "msgs" in kwargs:+ msg = kwargs["msgs"]elif "msg" in kwargs:msg = kwargs["msg"]if msg:@@ -495,13 +458,23 @@ def _get_agent_request_attributes(input_messages,)- # custom attributes- attributes[SpanAttributes.AGENTSCOPE_FUNCTION_INPUT] = _serialize_to_str(- {- "args": args,- "kwargs": kwargs,- },- )+ # Record the incoming continuation event type for HITL/external execution+ event = kwargs.get("event")+ if event is not None:+ from ...event import (+ ExternalExecutionResultEvent,+ UserConfirmResultEvent,+ )++ if isinstance(event, UserConfirmResultEvent):+ attributes[+ SpanAttributes.AGENTSCOPE_INCOMING_EVENT_TYPE+ ] = "user_confirm_result"+ elif isinstance(event, ExternalExecutionResultEvent):+ attributes[+ SpanAttributes.AGENTSCOPE_INCOMING_EVENT_TYPE+ ] = "external_execution_result"+return attributes@@ -536,16 +509,12 @@ def _get_agent_response_attributes(Returns:`Dict[str, str]`:- OpenTelemetry GenAI response attributes including output messages- and custom AgentScope function output.+ OpenTelemetry GenAI response attributes including output messages."""attributes = {SpanAttributes.GEN_AI_OUTPUT_MESSAGES: _serialize_to_str(_get_agent_messages(agent_response),),- SpanAttributes.AGENTSCOPE_FUNCTION_OUTPUT: _serialize_to_str(- agent_response,- ),}return attributes@@ -569,8 +538,8 @@ def _get_tool_request_attributes(Returns:`Dict[str, str]`:OpenTelemetry GenAI tool attributes including operation name, tool- call ID, tool name, tool description (if available), tool call- arguments, and custom AgentScope function input.+ call ID, tool name, tool description (if available), and tool call+ arguments."""attributes = {SpanAttributes.GEN_AI_OPERATION_NAME: (@@ -579,31 +548,23 @@ def _get_tool_request_attributes(}if tool_call:- tool_name = tool_call.get("name")- attributes[SpanAttributes.GEN_AI_TOOL_CALL_ID] = tool_call.get("id")+ tool_name = tool_call.name+ attributes[SpanAttributes.GEN_AI_TOOL_CALL_ID] = tool_call.idattributes[SpanAttributes.GEN_AI_TOOL_NAME] = tool_name- attributes[- SpanAttributes.GEN_AI_TOOL_CALL_ARGUMENTS- ] = _serialize_to_str(tool_call.get("input"))+ # tool_call.input is already a JSON string; pass it directly to avoid+ # double-encoding (e.g. '{"city": "Beijing"}' → '"{\\"city\\"...}"')+ attributes[SpanAttributes.GEN_AI_TOOL_CALL_ARGUMENTS] = tool_call.inputif tool_name:- if tool := getattr(instance, "tools", {}).get(tool_name):- if tool_func := getattr(tool, "json_schema", {}).get(- "function",- {},- ):+ registered = getattr(instance, "tools", {}).get(tool_name)+ if registered is not None:+ tool_obj = getattr(registered, "tool", None)+ description = getattr(tool_obj, "description", None)+ if description:attributes[SpanAttributes.GEN_AI_TOOL_DESCRIPTION- ] = tool_func.get("description", "unknown_description")+ ] = description- # custom attributes- attributes[- SpanAttributes.AGENTSCOPE_FUNCTION_INPUT- ] = _serialize_to_str(- {- "tool_call": tool_call,- },- )return attributes@@ -638,256 +599,11 @@ def _get_tool_response_attributes(Returns:`Dict[str, str]`:- OpenTelemetry GenAI response attributes including tool call result- and custom AgentScope function output.+ OpenTelemetry GenAI response attributes including tool call result."""attributes = {SpanAttributes.GEN_AI_TOOL_CALL_RESULT: _serialize_to_str(tool_response,),}-- attributes[SpanAttributes.AGENTSCOPE_FUNCTION_OUTPUT] = _serialize_to_str(- tool_response,- )- return attributes---def _get_formatter_request_attributes(- instance: "FormatterBase",- args: Tuple[Any, ...],- kwargs: Dict[str, Any],-) -> Dict[str, str]:- """Get formatter request attributes for OpenTelemetry tracing.-- Extracts formatter metadata into GenAI attributes.-- Args:- instance (`FormatterBase`):- The formatter instance being used to format messages.- args (`Tuple[Any, ...]`):- Positional arguments passed to the formatter's format method.- kwargs (`Dict[str, Any]`):- Keyword arguments passed to the formatter's format method.-- Returns:- `Dict[str, str]`:- OpenTelemetry GenAI formatter attributes including operation- name, format target (provider name), and custom AgentScope- function input.- """- attributes = {- SpanAttributes.GEN_AI_OPERATION_NAME: (OperationNameValues.FORMATTER),- SpanAttributes.AGENTSCOPE_FORMAT_TARGET: _get_format_target(instance),- SpanAttributes.AGENTSCOPE_FUNCTION_INPUT: _serialize_to_str(- {- "args": args,- "kwargs": kwargs,- },- ),- }return attributes---def _get_formatter_span_name(attributes: Dict[str, str]) -> str:- """Generate span name for formatter operations.-- Args:- attributes (`Dict[str, str]`):- Formatter request attributes dictionary containing operation name- and format target (provider name).-- Returns:- `str`:- Formatted span name in the format "{operation} {provider}",- e.g., "formatter openai".- """- return (- f"{attributes[SpanAttributes.GEN_AI_OPERATION_NAME]} "- f"{attributes[SpanAttributes.AGENTSCOPE_FORMAT_TARGET]}"- )---def _get_formatter_response_attributes(- response: Any,-) -> Dict[str, Any]:- """Get formatter response attributes for OpenTelemetry tracing.-- Args:- response (`Any`):- Response object from formatter. Typically a list of dictionaries- representing formatted messages.-- Returns:- `Dict[str, Any]`:- OpenTelemetry GenAI response attributes including custom AgentScope- function output and format count (if response is a list).- """- attributes = {- SpanAttributes.AGENTSCOPE_FUNCTION_OUTPUT: _serialize_to_str(response),- }- if isinstance(response, list):- attributes[SpanAttributes.AGENTSCOPE_FORMAT_COUNT] = len(response)-- return attributes---def _get_generic_function_request_attributes(- function_name: str,- args: Tuple[Any, ...],- kwargs: Dict[str, Any],-) -> Dict[str, str]:- """Get generic function request attributes for tracing.-- Extracts metadata from function calls into GenAI attributes.-- Args:- function_name (`str`):- Name of the function being called.- args (`Tuple[Any, ...]`):- Positional arguments passed to the function.- kwargs (`Dict[str, Any]`):- Keyword arguments passed to the function.-- Returns:- `Dict[str, str]`:- OpenTelemetry GenAI function attributes including operation name,- function name, and custom AgentScope function input.- """- attributes = {- SpanAttributes.GEN_AI_OPERATION_NAME: (- OperationNameValues.INVOKE_GENERIC_FUNCTION- ),- SpanAttributes.AGENTSCOPE_FUNCTION_NAME: function_name,- SpanAttributes.AGENTSCOPE_FUNCTION_INPUT: _serialize_to_str(- {- "args": args,- "kwargs": kwargs,- },- ),- }- return attributes---def _get_generic_function_span_name(attributes: Dict[str, str]) -> str:- """Generate span name for generic function operations.-- Args:- attributes (`Dict[str, str]`):- Generic function request attributes dictionary containing operation- name and function name.-- Returns:- `str`:- Formatted span name in the format "{operation} {function_name}",- e.g., "invoke_generic_function my_function".- """- return (- f"{attributes[SpanAttributes.GEN_AI_OPERATION_NAME]} "- f"{attributes[SpanAttributes.AGENTSCOPE_FUNCTION_NAME]}"- )---def _get_generic_function_response_attributes(- response: Any,-) -> Dict[str, str]:- """Get generic function response attributes for tracing.-- Args:- response (`Any`):- Response object returned by the generic function. Can be any- serializable object.-- Returns:- `Dict[str, str]`:- OpenTelemetry GenAI response attributes including custom AgentScope- function output.- """- attributes = {- SpanAttributes.AGENTSCOPE_FUNCTION_OUTPUT: _serialize_to_str(response),- }- return attributes---def _get_embedding_request_attributes(- instance: "EmbeddingModelBase",- args: Tuple[Any, ...],- kwargs: Dict[str, Any],-) -> Dict[str, Any]:- """Get embedding request attributes for OpenTelemetry tracing.-- Extracts embedding model metadata into GenAI attributes.-- Args:- instance (`EmbeddingModelBase`):- The embedding model instance making the request.- args (`Tuple[Any, ...]`):- Positional arguments passed to the embedding model call.- kwargs (`Dict[str, Any]`):- Keyword arguments including dimensions and other embedding- parameters.-- Returns:- `Dict[str, Any]`:- OpenTelemetry GenAI attributes including operation name,- model name, embedding dimensions count, and custom- AgentScope function input.- """- attributes = {- SpanAttributes.GEN_AI_OPERATION_NAME: OperationNameValues.EMBEDDINGS,- SpanAttributes.GEN_AI_REQUEST_MODEL: getattr(- instance,- "model_name",- "unknown_model",- ),- SpanAttributes.GEN_AI_EMBEDDINGS_DIMENSION_COUNT: kwargs.get(- "dimensions",- ),- SpanAttributes.AGENTSCOPE_FUNCTION_INPUT: _serialize_to_str(- {- "args": args,- "kwargs": kwargs,- },- ),- }- return {k: v for k, v in attributes.items() if v is not None}---def _get_embedding_span_name(attributes: Dict[str, str]) -> str:- """Generate span name for embedding operations.-- Args:- attributes (`Dict[str, str]`):- Embedding request attributes dictionary containing operation name- and model name.-- Returns:- `str`:- Formatted span name in the format "{operation} {model}",- e.g., "embeddings text-embedding-ada-002".- """- return (- f"{attributes[SpanAttributes.GEN_AI_OPERATION_NAME]} "- f"{attributes[SpanAttributes.GEN_AI_REQUEST_MODEL]}"- )---def _get_embedding_response_attributes(- response: Any,-) -> Dict[str, str]:- """Get embedding response attributes for OpenTelemetry tracing.-- Args:- response (`Any`):- Response object from embedding model. Typically a list of embedding- vectors or a similar structure.-- Returns:- `Dict[str, str]`:- OpenTelemetry GenAI response attributes including custom AgentScope- function output.- """- attributes = {- SpanAttributes.AGENTSCOPE_FUNCTION_OUTPUT: _serialize_to_str(response),- }- return {k: v for k, v in attributes.items() if v is not None}diff --git a/src/agentscope/tracing/_setup.py b/src/agentscope/middleware/_tracing/_setup.pysimilarity index 97%rename from src/agentscope/tracing/_setup.pyrename to src/agentscope/middleware/_tracing/_setup.pyindex 0c9be1cdc..8b956649a 100644--- a/src/agentscope/tracing/_setup.py+++ b/src/agentscope/middleware/_tracing/_setup.py@@ -44,6 +44,6 @@ def _get_tracer() -> Tracer:`Tracer`: The tracer with the name "agentscope" and version."""from opentelemetry import trace- from .._version import __version__+ from ..._version import __version__return trace.get_tracer("agentscope", __version__)diff --git a/src/agentscope/middleware/_tracing/_trace.py b/src/agentscope/middleware/_tracing/_trace.pynew file mode 100644index 000000000..82020fb07--- /dev/null+++ b/src/agentscope/middleware/_tracing/_trace.py@@ -0,0 +1,396 @@+# -*- coding: utf-8 -*-+"""TracingMiddleware and supporting utilities for OpenTelemetry tracing."""+import json+from typing import (+ Any,+ AsyncGenerator,+ Callable,+ Awaitable,+ Union,+ TypeVar,+ TYPE_CHECKING,+)++from contextvars import ContextVar++import aioitertools++from .._base import MiddlewareBase+from ...message import Msg++from ._attributes import SpanAttributes, OperationNameValues+from ._extractor import (+ _get_common_attributes,+ _get_agent_request_attributes,+ _get_agent_span_name,+ _get_agent_response_attributes,+ _get_llm_request_attributes,+ _get_llm_span_name,+ _get_llm_response_attributes,+ _get_tool_request_attributes,+ _get_tool_span_name,+ _get_tool_response_attributes,+)+from ._setup import _get_tracer+from ._utils import _serialize_to_str++if TYPE_CHECKING:+ from opentelemetry.trace import Span++ from ...agent import Agent+ from ...model import ChatResponse++T = TypeVar("T")++# Context variable to propagate the session ID from agent reply through+# all inner tracing spans (LLM calls, tool calls, formatter calls, etc.)+_current_session_id: ContextVar[str] = ContextVar(+ "_current_session_id",+ default="",+)+++# ---------------------------------------------------------------------------+# Utility helpers+# ---------------------------------------------------------------------------+++def _check_tracing_enabled() -> bool:+ """Check if the OpenTelemetry tracer is initialised with a real SDK+ TracerProvider (i.e. ``setup_tracing`` was called). Returns ``False``+ when only the default no-op proxy provider is active or when the SDK+ package is not installed.+ """+ try:+ from opentelemetry import trace as otel_trace+ from opentelemetry.sdk.trace import TracerProvider+ except ImportError:+ return False++ return isinstance(otel_trace.get_tracer_provider(), TracerProvider)+++def _set_span_success_status(span: "Span") -> None:+ """Set the span status to OK and end it."""+ from opentelemetry import trace as trace_api++ span.set_status(trace_api.StatusCode.OK)+ span.end()+++def _set_span_error_status(span: "Span", e: BaseException) -> None:+ """Set the span status to ERROR, record the exception and end it."""+ from opentelemetry import trace as trace_api++ span.set_status(trace_api.StatusCode.ERROR, str(e))+ span.record_exception(e)+ span.end()+++async def _trace_async_generator_wrapper(+ res: AsyncGenerator[T, None],+ span: "Span",+) -> AsyncGenerator[T, None]:+ """Wrap an async generator so that response attributes are captured from+ the last yielded chunk before the span is closed."""+ has_error = False++ try:+ last_chunk = None+ async for chunk in aioitertools.iter(res):+ last_chunk = chunk+ yield chunk++ except BaseException as e:+ has_error = True+ _set_span_error_status(span, e)+ raise++ finally:+ if not has_error:+ if (+ getattr(span, "attributes", {}).get(+ SpanAttributes.GEN_AI_OPERATION_NAME,+ )+ == OperationNameValues.CHAT+ ):+ response_attributes = _get_llm_response_attributes(last_chunk)+ elif (+ getattr(span, "attributes", {}).get(+ SpanAttributes.GEN_AI_OPERATION_NAME,+ )+ == OperationNameValues.EXECUTE_TOOL+ ):+ response_attributes = _get_tool_response_attributes(last_chunk)+ else:+ response_attributes = {}++ span.set_attributes(response_attributes)+ _set_span_success_status(span)+++# ---------------------------------------------------------------------------+# TracingMiddleware+# ---------------------------------------------------------------------------+++class TracingMiddleware(MiddlewareBase):+ """Agent middleware that adds OpenTelemetry tracing to the reply,+ model-call and tool-execution lifecycles.++ When tracing has not been configured (``setup_tracing`` was not called),+ every hook short-circuits to ``next_handler`` with near-zero overhead.++ Example::++ from agentscope.middleware import TracingMiddleware++ agent = Agent(+ ...,+ middlewares=[TracingMiddleware()],+ )+ """++ # ------------------------------------------------------------------+ # on_reply+ # ------------------------------------------------------------------+ async def on_reply(+ self,+ agent: "Agent",+ input_kwargs: dict,+ next_handler: Callable[..., AsyncGenerator],+ ) -> AsyncGenerator:+ if not _check_tracing_enabled():+ async for item in next_handler(**input_kwargs):+ yield item+ return++ session_id = getattr(+ getattr(agent, "state", None),+ "session_id",+ "",+ )+ token = _current_session_id.set(session_id or "")++ try:+ tracer = _get_tracer()+ request_attributes = _get_agent_request_attributes(+ agent,+ input_kwargs,+ )+ span_name = _get_agent_span_name(request_attributes)++ with tracer.start_as_current_span(+ name=span_name,+ attributes={+ **request_attributes,+ **_get_common_attributes(),+ },+ end_on_exit=False,+ ) as span:+ from ...event import (+ ExternalExecutionResultEvent,+ RequireExternalExecutionEvent as _RequireExtExec,+ RequireUserConfirmEvent as _RequireUserConfirm,+ ReplyStartEvent as _ReplyStart,+ )++ # Synthetic execute_tool spans for externally executed tools+ event_arg = input_kwargs.get("event")+ if isinstance(event_arg, ExternalExecutionResultEvent):+ common_attrs = _get_common_attributes()+ for result in event_arg.execution_results:+ tool_attrs: dict[str, Any] = {+ SpanAttributes.GEN_AI_OPERATION_NAME: (+ OperationNameValues.EXECUTE_TOOL+ ),+ SpanAttributes.GEN_AI_TOOL_CALL_ID: result.id,+ SpanAttributes.GEN_AI_TOOL_NAME: result.name,+ SpanAttributes.AGENTSCOPE_IS_EXTERNAL_EXECUTION: (+ True+ ),+ **common_attrs,+ }+ if result.output is not None:+ tool_attrs[+ SpanAttributes.GEN_AI_TOOL_CALL_RESULT+ ] = _serialize_to_str(result.output)+ with tracer.start_as_current_span(+ name=(+ f"{OperationNameValues.EXECUTE_TOOL}"+ f" {result.name}"+ ),+ attributes=tool_attrs,+ ):+ pass++ has_error = False+ error_exc: BaseException | None = None+ last_msg: Msg | None = None+ hitl_pending: list[str] = []+ external_pending: list[str] = []+ observed_reply_id: str | None = None++ try:+ async for item in next_handler(**input_kwargs):+ if isinstance(item, _ReplyStart):+ observed_reply_id = item.reply_id+ elif isinstance(item, _RequireUserConfirm):+ hitl_pending.extend(+ t.name for t in item.tool_calls+ )+ elif isinstance(item, _RequireExtExec):+ external_pending.extend(+ t.name for t in item.tool_calls+ )+ if isinstance(item, Msg):+ last_msg = item+ yield item+ except BaseException as e:+ has_error = True+ error_exc = e+ raise+ finally:+ reply_id = observed_reply_id or getattr(+ getattr(agent, "state", None),+ "reply_id",+ None,+ )+ if reply_id:+ span.set_attribute(+ SpanAttributes.AGENTSCOPE_REPLY_ID,+ reply_id,+ )+ if hitl_pending:+ span.set_attribute(+ SpanAttributes.AGENTSCOPE_HITL_PENDING_TOOLS,+ json.dumps(hitl_pending),+ )+ if external_pending:+ span.set_attribute(+ SpanAttributes.AGENTSCOPE_EXTERNAL_EXECUTION_PENDING_TOOLS, # noqa+ json.dumps(external_pending),+ )+ if has_error and error_exc is not None:+ _set_span_error_status(span, error_exc)+ else:+ if last_msg is not None:+ span.set_attributes(+ _get_agent_response_attributes(last_msg),+ )+ _set_span_success_status(span)+ finally:+ _current_session_id.reset(token)++ # ------------------------------------------------------------------+ # on_model_call+ # ------------------------------------------------------------------+ async def on_model_call(+ self,+ agent: "Agent",+ input_kwargs: dict,+ next_handler: Callable[+ ...,+ Awaitable["ChatResponse" | AsyncGenerator["ChatResponse", None]],+ ],+ ) -> Union["ChatResponse", AsyncGenerator["ChatResponse", None]]:+ if not _check_tracing_enabled():+ return await next_handler(**input_kwargs)++ from ...model import ChatModelBase++ tracer = _get_tracer()+ model = input_kwargs.get("current_model")+ if not isinstance(model, ChatModelBase):+ raise TypeError(+ f"Expected 'current_model' to be ChatModelBase, "+ f"got {type(model).__name__}",+ )++ combined_kwargs = {+ **getattr(model, "generate_kwargs", {}),+ **input_kwargs,+ }+ request_attributes = _get_llm_request_attributes(+ model,+ combined_kwargs,+ )+ span_name = _get_llm_span_name(request_attributes)++ with tracer.start_as_current_span(+ name=span_name,+ attributes={+ **request_attributes,+ **_get_common_attributes(),+ },+ end_on_exit=False,+ ) as span:+ try:+ result = await next_handler(**input_kwargs)++ if isinstance(result, AsyncGenerator):+ return _trace_async_generator_wrapper(result, span)++ span.set_attributes(_get_llm_response_attributes(result))+ _set_span_success_status(span)+ return result++ except BaseException as e:+ _set_span_error_status(span, e)+ raise++ # ------------------------------------------------------------------+ # on_acting+ # ------------------------------------------------------------------+ async def on_acting(+ self,+ agent: "Agent",+ input_kwargs: dict,+ next_handler: Callable[..., AsyncGenerator],+ ) -> AsyncGenerator:+ if not _check_tracing_enabled():+ async for item in next_handler(**input_kwargs):+ yield item+ return++ from ...message import ToolCallBlock++ tracer = _get_tracer()+ tool_call = input_kwargs.get("tool_call")+ if not isinstance(tool_call, ToolCallBlock):+ raise TypeError(+ f"Expected 'tool_call' to be ToolCallBlock, "+ f"got {type(tool_call).__name__}",+ )++ request_attributes = _get_tool_request_attributes(+ agent.toolkit,+ tool_call,+ )+ span_name = _get_tool_span_name(request_attributes)++ with tracer.start_as_current_span(+ name=span_name,+ attributes={+ **request_attributes,+ **_get_common_attributes(),+ },+ end_on_exit=False,+ ) as span:+ has_error = False+ last_item = None+ try:+ async for item in next_handler(**input_kwargs):+ last_item = item+ yield item+ except BaseException as e:+ has_error = True+ _set_span_error_status(span, e)+ raise+ finally:+ if not has_error:+ if last_item is not None:+ span.set_attributes(+ _get_tool_response_attributes(last_item),+ )+ _set_span_success_status(span)diff --git a/src/agentscope/tracing/_utils.py b/src/agentscope/middleware/_tracing/_utils.pysimilarity index 98%rename from src/agentscope/tracing/_utils.pyrename to src/agentscope/middleware/_tracing/_utils.pyindex 35f06ea65..b06bbbcb8 100644--- a/src/agentscope/tracing/_utils.py+++ b/src/agentscope/middleware/_tracing/_utils.py@@ -9,7 +9,7 @@ from typing import Anyfrom pydantic import BaseModel-from ..message import Msg+from ...message import Msgdef _to_serializable(diff --git a/src/agentscope/model/_anthropic/_model.py b/src/agentscope/model/_anthropic/_model.pyindex 80481cf9d..15ea53d95 100644--- a/src/agentscope/model/_anthropic/_model.py+++ b/src/agentscope/model/_anthropic/_model.py@@ -11,9 +11,8 @@ from .._model_response import ChatResponsefrom .._model_usage import ChatUsagefrom ...credential import AnthropicCredentialfrom ...formatter import FormatterBase, AnthropicChatFormatter-from ...message import ThinkingBlock, ToolCallBlock, TextBlock+from ...message import Msg, ThinkingBlock, ToolCallBlock, TextBlockfrom ...tool import ToolChoice-from ...tracing import trace_llmif TYPE_CHECKING:from anthropic.types.message import Message@@ -97,11 +96,10 @@ class AnthropicChatModel(ChatModelBase):self.parameters = parameters or self.Parameters()self.formatter = formatter or AnthropicChatFormatter()- @trace_llmasync def _call_api(self,model_name: str,- messages: list[dict[str, Any]],+ messages: list[Msg],tools: list[dict] | None = None,tool_choice: ToolChoice | None = None,**generate_kwargs: Any,diff --git a/src/agentscope/model/_dashscope/_model.py b/src/agentscope/model/_dashscope/_model.pyindex 5ffdfe520..aa4a3c845 100644--- a/src/agentscope/model/_dashscope/_model.py+++ b/src/agentscope/model/_dashscope/_model.py@@ -21,7 +21,6 @@ from ...message import (Base64Source,)from ...tool import ToolChoice-from ...tracing import trace_llmif TYPE_CHECKING:from openai.types.chat import ChatCompletion@@ -138,7 +137,6 @@ class DashScopeChatModel(ChatModelBase):self.parameters = parameters or self.Parameters()self.formatter = formatter or DashScopeChatFormatter()- @trace_llmasync def _call_api(self,model_name: str,diff --git a/src/agentscope/model/_deepseek/_model.py b/src/agentscope/model/_deepseek/_model.pyindex 29bce6dae..5ff9de68c 100644--- a/src/agentscope/model/_deepseek/_model.py+++ b/src/agentscope/model/_deepseek/_model.py@@ -11,9 +11,8 @@ from .._model_response import ChatResponsefrom .._model_usage import ChatUsagefrom ...credential import DeepSeekCredentialfrom ...formatter import FormatterBase, DeepSeekChatFormatter-from ...message import ThinkingBlock, ToolCallBlock, TextBlock+from ...message import Msg, ThinkingBlock, ToolCallBlock, TextBlockfrom ...tool import ToolChoice-from ...tracing import trace_llmif TYPE_CHECKING:from openai.types.chat import ChatCompletion@@ -107,11 +106,10 @@ class DeepSeekChatModel(ChatModelBase):self.parameters = parameters or self.Parameters()self.formatter = formatter or DeepSeekChatFormatter()- @trace_llmasync def _call_api(self,model_name: str,- messages: list[Any],+ messages: list[Msg],tools: list[dict] | None = None,tool_choice: ToolChoice | None = None,**generate_kwargs: Any,diff --git a/src/agentscope/model/_gemini/_model.py b/src/agentscope/model/_gemini/_model.pyindex 941f2d50d..4a0dc5af8 100644--- a/src/agentscope/model/_gemini/_model.py+++ b/src/agentscope/model/_gemini/_model.py@@ -14,9 +14,8 @@ from .._model_response import ChatResponsefrom .._model_usage import ChatUsagefrom ...credential import GeminiCredentialfrom ...formatter import FormatterBase, GeminiChatFormatter-from ...message import ThinkingBlock, ToolCallBlock, TextBlock+from ...message import Msg, ThinkingBlock, ToolCallBlock, TextBlockfrom ...tool import ToolChoice-from ...tracing import trace_llmfrom ..._logging import loggerif TYPE_CHECKING:@@ -164,11 +163,10 @@ class GeminiChatModel(ChatModelBase):self.parameters = parameters or self.Parameters()self.formatter = formatter or GeminiChatFormatter()- @trace_llmasync def _call_api(self,model_name: str,- messages: list[Any],+ messages: list[Msg],tools: list[dict] | None = None,tool_choice: ToolChoice | None = None,**config_kwargs: Any,diff --git a/src/agentscope/model/_moonshot/_model.py b/src/agentscope/model/_moonshot/_model.pyindex b2678ba03..de8c11ca9 100644--- a/src/agentscope/model/_moonshot/_model.py+++ b/src/agentscope/model/_moonshot/_model.py@@ -11,9 +11,8 @@ from .._model_response import ChatResponsefrom .._model_usage import ChatUsagefrom ...credential import MoonshotCredentialfrom ...formatter import FormatterBase, MoonshotChatFormatter-from ...message import ThinkingBlock, ToolCallBlock, TextBlock+from ...message import Msg, ThinkingBlock, ToolCallBlock, TextBlockfrom ...tool import ToolChoice-from ...tracing import trace_llmif TYPE_CHECKING:from openai.types.chat import ChatCompletion@@ -97,11 +96,10 @@ class MoonshotChatModel(ChatModelBase):self.parameters = parameters or self.Parameters()self.formatter = formatter or MoonshotChatFormatter()- @trace_llmasync def _call_api(self,model_name: str,- messages: list[Any],+ messages: list[Msg],tools: list[dict] | None = None,tool_choice: ToolChoice | None = None,**generate_kwargs: Any,diff --git a/src/agentscope/model/_ollama/_model.py b/src/agentscope/model/_ollama/_model.pyindex 8f8344fd5..934bc315f 100644--- a/src/agentscope/model/_ollama/_model.py+++ b/src/agentscope/model/_ollama/_model.py@@ -12,9 +12,8 @@ from .._model_response import ChatResponsefrom .._model_usage import ChatUsagefrom ...credential import OllamaCredentialfrom ...formatter import FormatterBase, OllamaChatFormatter-from ...message import ThinkingBlock, ToolCallBlock, TextBlock+from ...message import Msg, ThinkingBlock, ToolCallBlock, TextBlockfrom ...tool import ToolChoice-from ...tracing import trace_llmfrom ..._logging import loggerif TYPE_CHECKING:@@ -97,11 +96,10 @@ class OllamaChatModel(ChatModelBase):self.parameters = parameters or self.Parameters()self.formatter = formatter or OllamaChatFormatter()- @trace_llmasync def _call_api(self,model_name: str,- messages: list[Any],+ messages: list[Msg],tools: list[dict] | None = None,tool_choice: ToolChoice | None = None,**generate_kwargs: Any,diff --git a/src/agentscope/model/_openai_chat/_model.py b/src/agentscope/model/_openai_chat/_model.pyindex bd342232e..3d171f11f 100644--- a/src/agentscope/model/_openai_chat/_model.py+++ b/src/agentscope/model/_openai_chat/_model.py@@ -11,9 +11,8 @@ from .._model_response import ChatResponsefrom .._model_usage import ChatUsagefrom ...credential import OpenAICredentialfrom ...formatter import FormatterBase, OpenAIChatFormatter-from ...message import ThinkingBlock, ToolCallBlock, TextBlock+from ...message import Msg, ThinkingBlock, ToolCallBlock, TextBlockfrom ...tool import ToolChoice-from ...tracing import trace_llmif TYPE_CHECKING:from openai.types.chat import ChatCompletion@@ -113,11 +112,10 @@ class OpenAIChatModel(ChatModelBase):self.parameters = parameters or self.Parameters()self.formatter = formatter or OpenAIChatFormatter()- @trace_llmasync def _call_api(self,model_name: str,- messages: list[Any],+ messages: list[Msg],tools: list[dict] | None = None,tool_choice: ToolChoice | None = None,**generate_kwargs: Any,diff --git a/src/agentscope/model/_openai_response/_model.py b/src/agentscope/model/_openai_response/_model.pyindex d87ca496d..90b826d6f 100644--- a/src/agentscope/model/_openai_response/_model.py+++ b/src/agentscope/model/_openai_response/_model.py@@ -10,9 +10,8 @@ from .._model_response import ChatResponsefrom .._model_usage import ChatUsagefrom ...credential import OpenAICredentialfrom ...formatter import FormatterBase, OpenAIResponseFormatter-from ...message import ThinkingBlock, ToolCallBlock, TextBlock+from ...message import Msg, ThinkingBlock, ToolCallBlock, TextBlockfrom ...tool import ToolChoice-from ...tracing import trace_llmif TYPE_CHECKING:from openai.types.responses import Response@@ -105,11 +104,10 @@ class OpenAIResponseModel(ChatModelBase):self.parameters = parameters or self.Parameters()self.formatter = formatter or OpenAIResponseFormatter()- @trace_llmasync def _call_api(self,model_name: str,- messages: list[Any],+ messages: list[Msg],tools: list[dict] | None = None,tool_choice: ToolChoice | None = None,**generate_kwargs: Any,diff --git a/src/agentscope/model/_xai/_model.py b/src/agentscope/model/_xai/_model.pyindex e8c395dd9..ac57c0c84 100644--- a/src/agentscope/model/_xai/_model.py+++ b/src/agentscope/model/_xai/_model.py@@ -11,12 +11,12 @@ from .._model_usage import ChatUsagefrom ...credential import XAICredentialfrom ...formatter import XAIChatFormatterfrom ...message import (+ Msg,TextBlock,ThinkingBlock,ToolCallBlock,)from ...tool import ToolChoice-from ...tracing import trace_llmif TYPE_CHECKING:from xai_sdk import AsyncClient@@ -122,11 +122,10 @@ class XAIChatModel(ChatModelBase):self.parameters = parameters or self.Parameters()self.formatter = formatter or XAIChatFormatter()- @trace_llmasync def _call_api(self,model_name: str,- messages: list[Any],+ messages: list[Msg],tools: list[dict] | None = None,tool_choice: ToolChoice | None = None,**generate_kwargs: Any,diff --git a/src/agentscope/tool/_toolkit.py b/src/agentscope/tool/_toolkit.pyindex 0eb6c703c..1a5c1d813 100644--- a/src/agentscope/tool/_toolkit.py+++ b/src/agentscope/tool/_toolkit.py@@ -446,7 +446,6 @@ class Toolkit:", ".join(to_removed),)- # @trace_toolkitasync def call_tool(self,tool_call: ToolCallBlock,@@ -863,10 +862,8 @@ AsyncGenerator[ToolResponse, None]] | AsyncGenerator[ToolResponse, None]]`):dict currently includes ``tool_call`` (ToolCallBlock), and mayinclude additional context in future versions.- .. note:: The middleware chain is applied inside the- `call_tool_function` via the `@apply_middlewares` decorator. This- ensures that the `@trace_toolkit` decorator remains at the outermost- layer for complete observability.+ .. note:: Tracing is now handled by ``TracingMiddleware`` at the+ agent level rather than a ``@trace_toolkit`` decorator."""# Simply append the middleware to the list# The @apply_middlewares decorator will handle the executiondiff --git a/src/agentscope/tracing/__init__.py b/src/agentscope/tracing/__init__.pydeleted file mode 100644index 1f01bdaf3..000000000--- a/src/agentscope/tracing/__init__.py+++ /dev/null@@ -1,22 +0,0 @@-# -*- coding: utf-8 -*--"""The tracing interface class in agentscope."""--from ._setup import setup_tracing-from ._trace import (- trace,- trace_llm,- trace_reply,- trace_format,- trace_toolkit,- trace_embedding,-)--__all__ = [- "setup_tracing",- "trace",- "trace_llm",- "trace_reply",- "trace_format",- "trace_toolkit",- "trace_embedding",-]diff --git a/src/agentscope/tracing/_converter.py b/src/agentscope/tracing/_converter.pydeleted file mode 100644index 8f7291ffe..000000000--- a/src/agentscope/tracing/_converter.py+++ /dev/null@@ -1,125 +0,0 @@-# -*- coding: utf-8 -*--"""Convert ContentBlock to OpenTelemetry GenAI part format."""--from typing import Any, Dict--from ..message import ContentBlock--from ._utils import _serialize_to_str---def _convert_media_block(- source: Dict[str, Any],- modality: str,-) -> Dict[str, Any] | None:- """Convert media block (image/audio/video) to OpenTelemetry format.-- Args:- source (`Dict[str, Any]`):- Source Dictionary with type, url/data, and media_type.- modality (`str`):- Media modality: "image", "audio", or "video".-- Returns:- `Dict[str, Any] | None`:- Converted part Dictionary or None if source type is invalid.- """- source_type = source.get("type")-- if source_type == "url":- url = source.get("url", "")- return {- "type": "uri",- "uri": url,- "modality": modality,- }-- if source_type == "base64":- data = source.get("data", "")- media_type = source.get("media_type")- if not media_type:- default_media_types = {- "image": "image/jpeg",- "audio": "audio/wav",- "video": "video/mp4",- }- media_type = default_media_types.get(modality, "unknown")- return {- "type": "blob",- "content": data,- "media_type": media_type,- "modality": modality,- }-- return None---def _convert_block_to_part(block: ContentBlock) -> Dict[str, Any] | None:- """Convert content block to OpenTelemetry GenAI part format.-- Converts text, thinking, tool_use, tool_result, image, audio, video- blocks to standardized parts.-- Args:- block (`ContentBlock`):- The content block object to convert. Supported block types:- - text: Text content block- - thinking: Reasoning/thinking content block- - tool_use: Tool call block with id, name, and input- - tool_result: Tool result block with id and output- - image: Image block with source (url or base64)- - audio: Audio block with source (url or base64)- - video: Video block with source (url or base64)-- Returns:- `Dict[str, Any] | None`:- Standardized part Dictionary in OpenTelemetry GenAI format,- or None if the block type is invalid or cannot be converted.- """- block_type = block.get("type")- part: Dict[str, Any] | None = None-- # Handle simple text-based blocks- if block_type == "text":- part = {- "type": "text",- "content": block.get("text", ""),- }- elif block_type == "thinking":- part = {- "type": "reasoning",- "content": block.get("thinking", ""),- }- # Handle tool blocks- elif block_type == "tool_use":- part = {- "type": "tool_call",- "id": block.get("id", ""),- "name": block.get("name", ""),- "arguments": block.get("input", {}),- }- elif block_type == "tool_result":- output = block.get("output", "")- if isinstance(output, (list, Dict)):- result = _serialize_to_str(output)- else:- result = str(output)-- part = {- "type": "tool_call_response",- "id": block.get("id", ""),- "response": result,- }- # Handle media blocks (image, audio, video)- elif block_type in ("image", "audio", "video"):- source = block.get("source", {})- # Type assertion for mypy- if isinstance(source, dict):- source_dict: Dict[str, Any] = source-- part = _convert_media_block(- source_dict,- modality=block_type,- )-- return partdiff --git a/src/agentscope/tracing/_trace.py b/src/agentscope/tracing/_trace.pydeleted file mode 100644index bc878f0eb..000000000--- a/src/agentscope/tracing/_trace.py+++ /dev/null@@ -1,645 +0,0 @@-# -*- coding: utf-8 -*--"""The tracing decorators for agent, formatter, toolkit, chat and embedding-models."""-import inspect-from functools import wraps-from typing import (- Generator,- AsyncGenerator,- Callable,- Any,- Coroutine,- TypeVar,- TYPE_CHECKING,-)--import aioitertools--from ..embedding import EmbeddingModelBase, EmbeddingResponse-from .._logging import logger-from ..message import Msg, ToolCallBlock-from ..model import ChatModelBase, ChatResponse--from ._attributes import SpanAttributes, OperationNameValues-from ._extractor import (- _get_common_attributes,- _get_agent_request_attributes,- _get_agent_span_name,- _get_agent_response_attributes,- _get_llm_request_attributes,- _get_llm_span_name,- _get_llm_response_attributes,- _get_tool_request_attributes,- _get_tool_span_name,- _get_tool_response_attributes,- _get_formatter_request_attributes,- _get_formatter_span_name,- _get_formatter_response_attributes,- _get_generic_function_request_attributes,- _get_generic_function_span_name,- _get_generic_function_response_attributes,- _get_embedding_request_attributes,- _get_embedding_span_name,- _get_embedding_response_attributes,-)-from ._setup import _get_tracer--if TYPE_CHECKING:- from opentelemetry.trace import Span-- from ..agent import AgentBase- from ..formatter import FormatterBase- from ..tool import (- Toolkit,- ToolResponse,- )--else:- AgentBase = "AgentBase"- FormatterBase = "FormatterBase"- Span = "Span"- Toolkit = "Toolkit"- ToolResponse = "ToolResponse"---T = TypeVar("T")---def _check_tracing_enabled() -> bool:- """Check if the OpenTelemetry tracer is initialized in AgentScope with an- endpoint.-- TODO: We expect an OpenTelemetry official interface to check if the- tracer is initialized. Leaving this function here as a temporary- solution.- """- return True---def _set_span_success_status(span: Span) -> None:- """Set the status of the span.- Args:- span (`Span`):- The OpenTelemetry span to be used for tracing.- """- from opentelemetry import trace as trace_api-- span.set_status(trace_api.StatusCode.OK)- span.end()---def _set_span_error_status(span: Span, e: Exception) -> None:- """Set the status of the span.- Args:- span (`Span`):- The OpenTelemetry span to be used for tracing.- e (`Exception`):- The exception to be recorded.- """- from opentelemetry import trace as trace_api-- span.set_status(trace_api.StatusCode.ERROR, str(e))- span.record_exception(e)- span.end()---def _trace_sync_generator_wrapper(- res: Generator[T, None, None],- span: Span,-) -> Generator[T, None, None]:- """Trace the sync generator output with OpenTelemetry."""-- has_error = False-- try:- last_chunk = None- for chunk in res:- last_chunk = chunk- yield chunk- except Exception as e:- has_error = True- _set_span_error_status(span, e)- raise e from None-- finally:- if not has_error:- # Set the last chunk as output- span.set_attributes(- _get_generic_function_response_attributes(last_chunk),- )- _set_span_success_status(span)---async def _trace_async_generator_wrapper(- res: AsyncGenerator[T, None],- span: Span,-) -> AsyncGenerator[T, None]:- """Trace the async generator output with OpenTelemetry.-- Args:- res (`AsyncGenerator[T, None]`):- The generator or async generator to be traced.- span (`Span`):- The OpenTelemetry span to be used for tracing.-- Yields:- `T`:- The output of the async generator.- """- has_error = False-- try:- last_chunk = None- async for chunk in aioitertools.iter(res):- last_chunk = chunk- yield chunk-- except Exception as e:- has_error = True- _set_span_error_status(span, e)- raise e from None-- finally:- if not has_error:- # Set the last chunk as output-- if (- getattr(span, "attributes", {}).get(- SpanAttributes.GEN_AI_OPERATION_NAME,- )- == OperationNameValues.CHAT- ):- response_attributes = _get_llm_response_attributes(last_chunk)- elif (- getattr(span, "attributes", {}).get(- SpanAttributes.GEN_AI_OPERATION_NAME,- )- == OperationNameValues.EXECUTE_TOOL- ):- response_attributes = _get_tool_response_attributes(last_chunk)- else:- response_attributes = (- _get_generic_function_response_attributes(- last_chunk,- )- )-- span.set_attributes(response_attributes)- _set_span_success_status(span)---def trace(- name: str | None = None,-) -> Callable:- """A generic tracing decorator for synchronous and asynchronous functions.-- Args:- name (`str | None`, optional):- The name of the span to be created. If not provided,- the name of the function will be used.-- Returns:- `Callable`:- Returns a decorator that wraps the given function with- OpenTelemetry tracing.- """-- def decorator(- func: Callable,- ) -> Callable:- """A decorator that wraps the given function with OpenTelemetry tracing-- Args:- func (`Callable`):- The function to be traced, which can be sync or async function,- and returns an object or a generator.-- Returns:- `Callable`:- A wrapper function that traces the function call and handles- input/output and exceptions.- """- # Async function- if inspect.iscoroutinefunction(func):-- @wraps(func)- async def wrapper(- *args: Any,- **kwargs: Any,- ) -> Any:- """The wrapper function for tracing the sync function call."""- if not _check_tracing_enabled():- return await func(*args, **kwargs)-- tracer = _get_tracer()-- function_name = name if name else func.__name__- request_attributes = _get_generic_function_request_attributes(- function_name,- args,- kwargs,- )-- span_name = _get_generic_function_span_name(request_attributes)- with tracer.start_as_current_span(- name=span_name,- attributes=request_attributes,- end_on_exit=False,- ) as span:- try:- res = await func(*args, **kwargs)-- # If generator or async generator- if isinstance(res, AsyncGenerator):- return _trace_async_generator_wrapper(res, span)- if isinstance(res, Generator):- return _trace_sync_generator_wrapper(res, span)-- # non-generator result- span.set_attributes(- _get_generic_function_response_attributes(res),- )- _set_span_success_status(span)- return res-- except Exception as e:- _set_span_error_status(span, e)- raise e from None-- return wrapper-- # Sync function- @wraps(func)- def sync_wrapper(- *args: Any,- **kwargs: Any,- ) -> Any:- """The wrapper function for tracing the sync function call."""- if not _check_tracing_enabled():- return func(*args, **kwargs)-- tracer = _get_tracer()-- function_name = name if name else func.__name__- request_attributes = _get_generic_function_request_attributes(- function_name,- args,- kwargs,- )-- span_name = _get_generic_function_span_name(request_attributes)- with tracer.start_as_current_span(- name=span_name,- attributes=request_attributes,- end_on_exit=False,- ) as span:- try:- res = func(*args, **kwargs)-- # If generator or async generator- if isinstance(res, AsyncGenerator):- return _trace_async_generator_wrapper(res, span)- if isinstance(res, Generator):- return _trace_sync_generator_wrapper(res, span)-- # non-generator result- span.set_attributes(- _get_generic_function_response_attributes(res),- )- _set_span_success_status(span)- return res-- except Exception as e:- _set_span_error_status(span, e)- raise e from None-- return sync_wrapper-- return decorator---def trace_toolkit(- func: Callable[..., AsyncGenerator[ToolResponse, None]],-) -> Callable[..., Coroutine[Any, Any, AsyncGenerator[ToolResponse, None]]]:- """Trace the toolkit `call_tool_function` method with OpenTelemetry."""-- @wraps(func)- async def wrapper(- self: Toolkit,- tool_call: ToolCallBlock,- ) -> AsyncGenerator[ToolResponse, None]:- """The wrapper function for tracing the toolkit call_tool_function- method."""- if not _check_tracing_enabled():- return func(self, tool_call=tool_call)-- tracer = _get_tracer()-- request_attributes = _get_tool_request_attributes(self, tool_call)- span_name = _get_tool_span_name(request_attributes)- function_name = f"{self.__class__.__name__}.{func.__name__}"- with tracer.start_as_current_span(- name=span_name,- attributes={- **request_attributes,- **_get_common_attributes(),- SpanAttributes.AGENTSCOPE_FUNCTION_NAME: function_name,- },- end_on_exit=False,- ) as span:- try:- # Call the toolkit function (returns AsyncGenerator)- res = func(self, tool_call=tool_call)-- # The result must be an AsyncGenerator- # Return the wrapped generator- return _trace_async_generator_wrapper(res, span)-- except Exception as e:- _set_span_error_status(span, e)- span.end()- raise e from None-- return wrapper---def trace_reply(- func: Callable[..., Coroutine[Any, Any, Msg]],-) -> Callable[..., Coroutine[Any, Any, Msg]]:- """Trace the agent reply call with OpenTelemetry.-- Args:- func (`Callable[..., Coroutine[Any, Any, Msg]]`):- The agent async reply function to be traced.-- Returns:- `Callable[..., Coroutine[Any, Any, Msg]]`:- A wrapper function that traces the agent reply call and handles- input/output and exceptions.- """-- @wraps(func)- async def wrapper(- self: "AgentBase",- *args: Any,- **kwargs: Any,- ) -> Msg:- """The wrapper function for tracing the agent reply function call."""- if not _check_tracing_enabled():- return await func(self, *args, **kwargs)-- # from ..agent import AgentBase- #- # if not isinstance(self, AgentBase):- # logger.warning(- # "Skipping tracing for %s as the first argument"- # "is not an instance of AgentBase, but %s",- # func.__name__,- # type(self),- # )- # return await func(self, *args, **kwargs)-- tracer = _get_tracer()-- # Prepare the attributes for the span-- request_attributes = _get_agent_request_attributes(self, args, kwargs)- span_name = _get_agent_span_name(request_attributes)- function_name = f"{self.__class__.__name__}.{func.__name__}"- # Begin the llm call span- with tracer.start_as_current_span(- name=span_name,- attributes={- **request_attributes,- **_get_common_attributes(),- SpanAttributes.AGENTSCOPE_FUNCTION_NAME: function_name,- },- end_on_exit=False,- ) as span:- try:- # Call the agent reply function- res = await func(self, *args, **kwargs)-- # Set the output attribute- span.set_attributes(_get_agent_response_attributes(res))- _set_span_success_status(span)- return res-- except Exception as e:- _set_span_error_status(span, e)- raise e from None-- return wrapper---def trace_embedding(- func: Callable[..., Coroutine[Any, Any, EmbeddingResponse]],-) -> Callable[..., Coroutine[Any, Any, EmbeddingResponse]]:- """Trace the embedding call with OpenTelemetry."""-- @wraps(func)- async def wrapper(- self: EmbeddingModelBase,- *args: Any,- **kwargs: Any,- ) -> EmbeddingResponse:- """The wrapper function for tracing the embedding call."""- if not _check_tracing_enabled():- return await func(self, *args, **kwargs)-- if not isinstance(self, EmbeddingModelBase):- logger.warning(- "Skipping tracing for %s as the first argument"- "is not an instance of EmbeddingModelBase, but %s",- func.__name__,- type(self),- )- return await func(self, *args, **kwargs)-- tracer = _get_tracer()-- # Prepare the attributes for the span- request_attributes = _get_embedding_request_attributes(- self,- args,- kwargs,- )- span_name = _get_embedding_span_name(request_attributes)- function_name = f"{self.__class__.__name__}.{func.__name__}"-- with tracer.start_as_current_span(- name=span_name,- attributes={- **request_attributes,- **_get_common_attributes(),- SpanAttributes.AGENTSCOPE_FUNCTION_NAME: function_name,- },- end_on_exit=False,- ) as span:- try:- # Call the embedding function- res = await func(self, *args, **kwargs)-- # Set the output attribute- span.set_attributes(_get_embedding_response_attributes(res))- _set_span_success_status(span)- return res-- except Exception as e:- _set_span_error_status(span, e)- raise e from None-- return wrapper---def trace_format(- func: Callable[..., Coroutine[Any, Any, list[dict]]],-) -> Callable[..., Coroutine[Any, Any, list[dict]]]:- """Trace the format function of the formatter with OpenTelemetry.-- Args:- func (`Callable[..., Coroutine[Any, Any, list[dict]]]`):- The async format function to be traced.-- Returns:- `Callable[..., Coroutine[Any, Any, list[dict]]]`:- An async wrapper function that traces the format call and handles- input/output and exceptions.- """-- @wraps(func)- async def wrapper(- self: "FormatterBase",- *args: Any,- **kwargs: Any,- ) -> list[dict]:- """Wrap the formatter __call__ method with OpenTelemetry tracing."""- if not _check_tracing_enabled():- return await func(self, *args, **kwargs)-- from ..formatter import FormatterBase-- if not isinstance(self, FormatterBase):- logger.warning(- "Skipping tracing for %s as the first argument"- "is not an instance of FormatterBase, but %s",- func.__name__,- type(self),- )- return await func(self, *args, **kwargs)-- tracer = _get_tracer()-- # Prepare the attributes for the span- request_attributes = _get_formatter_request_attributes(- self,- args,- kwargs,- )- span_name = _get_formatter_span_name(request_attributes)- function_name = f"{self.__class__.__name__}.{func.__name__}"- with tracer.start_as_current_span(- name=span_name,- attributes={- **request_attributes,- **_get_common_attributes(),- SpanAttributes.AGENTSCOPE_FUNCTION_NAME: function_name,- },- end_on_exit=False,- ) as span:- try:- # Call the formatter function- res = await func(self, *args, **kwargs)-- # Set the output attribute- span.set_attributes(_get_formatter_response_attributes(res))- _set_span_success_status(span)- return res-- except Exception as e:- _set_span_error_status(span, e)- raise e from None-- return wrapper---def trace_llm(- func: Callable[- ...,- Coroutine[- Any,- Any,- ChatResponse | AsyncGenerator[ChatResponse, None],- ],- ],-) -> Callable[- ...,- Coroutine[Any, Any, ChatResponse | AsyncGenerator[ChatResponse, None]],-]:- """Trace the LLM call with OpenTelemetry.-- Args:- func (`Callable`):- The function to be traced, which should be a coroutine that- returns either a `ChatResponse` or an `AsyncGenerator`- of `ChatResponse`.-- Returns:- `Callable`:- A wrapper function that traces the LLM call and handles- input/output and exceptions.- """-- @wraps(func)- async def async_wrapper(- self: ChatModelBase,- *args: Any,- **kwargs: Any,- ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:- """The wrapper function for tracing the LLM call."""- if not _check_tracing_enabled():- return await func(self, *args, **kwargs)-- if not isinstance(self, ChatModelBase):- logger.warning(- "Skipping tracing for %s as the first argument"- "is not an instance of ChatModelBase, but %s",- func.__name__,- type(self),- )- return await func(self, *args, **kwargs)-- tracer = _get_tracer()-- # Prepare the attributes for the span- request_attributes = _get_llm_request_attributes(self, args, kwargs)- span_name = _get_llm_span_name(request_attributes)- function_name = f"{self.__class__.__name__}.__call__"- # Begin the llm call span- with tracer.start_as_current_span(- name=span_name,- attributes={- **request_attributes,- **_get_common_attributes(),- SpanAttributes.AGENTSCOPE_FUNCTION_NAME: function_name,- },- end_on_exit=False,- ) as span:- try:- # Must be an async calling- res = await func(self, *args, **kwargs)-- # If the result is a AsyncGenerator- if isinstance(res, AsyncGenerator):- return _trace_async_generator_wrapper(res, span)-- # non-generator result- span.set_attributes(_get_llm_response_attributes(res))- _set_span_success_status(span)- return res-- except Exception as e:- _set_span_error_status(span, e)- raise e from None-- return async_wrapperdiff --git a/tests/tracing_test.py b/tests/tracing_test.pynew file mode 100644index 000000000..9c4312646--- /dev/null+++ b/tests/tracing_test.py@@ -0,0 +1,846 @@+# -*- coding: utf-8 -*-+"""Unit tests for the tracing module using an in-memory OTel exporter."""+import json+from typing import Any+from unittest.async_case import IsolatedAsyncioTestCase++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 utils import MockModel++from agentscope.agent import Agent+from agentscope.event import (+ ConfirmResult,+ ExternalExecutionResultEvent,+ RequireExternalExecutionEvent,+ RequireUserConfirmEvent,+ UserConfirmResultEvent,+)+from agentscope.message import (+ TextBlock,+ ToolCallBlock,+ ToolResultBlock,+ ToolResultState,+ UserMsg,+)+from agentscope.model import ChatResponse, ChatUsage+from agentscope.permission import (+ PermissionContext,+ PermissionDecision,+ PermissionBehavior,+)+from agentscope.tool import Toolkit, ToolBase+from agentscope.middleware import TracingMiddleware+++# ---------------------------------------------------------------------------+# Shared test fixtures+# ---------------------------------------------------------------------------+++class WeatherTool(ToolBase):+ """Stub weather tool for tracing tests."""++ name: str = "get_weather"+ description: str = "Return stub weather for a city."+ input_schema: dict = {+ "type": "object",+ "properties": {"city": {"type": "string"}},+ "required": ["city"],+ }+ is_concurrency_safe: bool = True+ is_read_only: bool = True+ is_external_tool: bool = False+ is_mcp: bool = False++ async def check_permissions(+ self,+ tool_input: dict[str, Any],+ context: PermissionContext,+ ) -> PermissionDecision:+ return PermissionDecision(+ behavior=PermissionBehavior.ALLOW,+ message="always allowed",+ )++ async def execute(self, city: str) -> str:+ """Stub weather tool for tracing tests."""+ return f"{city}: sunny, 25°C."+++class HitlWeatherTool(ToolBase):+ """Weather tool that always asks user for confirmation (HITL)."""++ name: str = "get_weather"+ description: str = "Return weather for a city, requires user confirmation."+ input_schema: dict = {+ "type": "object",+ "properties": {"city": {"type": "string"}},+ "required": ["city"],+ }+ is_concurrency_safe: bool = True+ is_read_only: bool = True+ is_external_tool: bool = False+ is_mcp: bool = False++ async def check_permissions(+ self,+ tool_input: dict[str, Any],+ context: PermissionContext,+ ) -> PermissionDecision:+ return PermissionDecision(+ behavior=PermissionBehavior.ASK,+ message="user must confirm this tool call",+ )++ async def execute(self, city: str) -> str:+ """Stub weather tool for tracing tests."""+ return f"{city}: sunny, 25°C."+++class ExternalWeatherTool(ToolBase):+ """Weather tool that is always executed externally."""++ name: str = "get_weather"+ description: str = "Return weather for a city via external execution."+ input_schema: dict = {+ "type": "object",+ "properties": {"city": {"type": "string"}},+ "required": ["city"],+ }+ is_concurrency_safe: bool = True+ is_read_only: bool = True+ is_external_tool: bool = True # Mark as external+ is_mcp: bool = False++ async def check_permissions(+ self,+ tool_input: dict[str, Any],+ context: PermissionContext,+ ) -> PermissionDecision:+ return PermissionDecision(+ behavior=PermissionBehavior.ALLOW,+ message="always allowed",+ )++ async def execute(self, city: str) -> str:+ """Stub weather tool for tracing tests."""+ return f"{city}: sunny, 25°C."+++def _make_tool_call_response(tool_id: str, city: str) -> ChatResponse:+ return ChatResponse(+ content=[+ ToolCallBlock(+ id=tool_id,+ name="get_weather",+ input=json.dumps({"city": city}),+ ),+ ],+ is_last=True,+ usage=ChatUsage(input_tokens=10, output_tokens=5, time=0.05),+ )+++def _make_text_response(text: str) -> ChatResponse:+ return ChatResponse(+ content=[TextBlock(text=text)],+ is_last=True,+ usage=ChatUsage(input_tokens=15, output_tokens=8, time=0.05),+ )+++class TracingTest(IsolatedAsyncioTestCase):+ """Tests that OTel spans are emitted with correct attributes.++ The in-memory exporter is set up once per class (setUpClass) because+ the OTel global TracerProvider cannot be replaced once installed.+ setUp only creates fresh model/agent and clears the exporter.+ """++ exporter: InMemorySpanExporter++ @classmethod+ def setUpClass(cls) -> None:+ """Configure an in-memory OTel provider once for the whole class."""+ cls.exporter = InMemorySpanExporter()+ provider = TracerProvider()+ provider.add_span_processor(SimpleSpanProcessor(cls.exporter))+ otel_trace.set_tracer_provider(provider)++ def setUp(self) -> None:+ """Create a fresh agent and clear accumulated spans before each+ test."""+ self.exporter.clear()+ self.model = MockModel()+ self.agent = Agent(+ name="test-agent",+ system_prompt="You are a test assistant.",+ model=self.model,+ toolkit=Toolkit(tools=[WeatherTool()]),+ middlewares=[TracingMiddleware()],+ )++ # -----------------------------------------------------------------------+ # Helpers+ # -----------------------------------------------------------------------++ def _spans_by_name(self, fragment: str) -> list:+ return [+ s+ for s in self.exporter.get_finished_spans()+ if fragment in (s.name or "")+ ]++ def _all_conv_ids(self) -> set:+ return {+ dict(s.attributes or {}).get("gen_ai.conversation.id")+ for s in self.exporter.get_finished_spans()+ if "gen_ai.conversation.id" in (s.attributes or {})+ }++ # -----------------------------------------------------------------------+ # Tests: Agent.reply+ # -----------------------------------------------------------------------++ async def test_reply_spans_share_conversation_id(self) -> None:+ """All spans from a single reply must share the same+ conversation_id."""+ self.model.set_responses(+ [+ _make_tool_call_response("c3", "Guangzhou"),+ _make_text_response("Guangzhou is sunny."),+ ],+ )+ msg = UserMsg(name="user", content="Weather in Guangzhou?")+ await self.agent.reply(msg)++ conv_ids = self._all_conv_ids()+ self.assertEqual(+ len(conv_ids),+ 1,+ f"All spans must share exactly one conversation_id, "+ f"got: {conv_ids}",+ )++ async def test_invoke_agent_span_has_response_attributes(self) -> None:+ """invoke_agent span must carry gen_ai.output.messages attribute."""+ self.model.set_responses(+ [+ _make_tool_call_response("c4", "Wuhan"),+ _make_text_response("Wuhan weather: clear sky."),+ ],+ )+ msg = UserMsg(name="user", content="Weather in Wuhan?")+ await self.agent.reply(msg)++ agent_spans = self._spans_by_name("invoke_agent")+ self.assertEqual(+ len(agent_spans),+ 1,+ "Expected exactly one invoke_agent span",+ )+ span_attrs = dict(agent_spans[0].attributes or {})+ output_raw = span_attrs.get("gen_ai.output.messages")+ assert isinstance(+ output_raw,+ str,+ ), "invoke_agent span gen_ai.output.messages should be a string"+ output = json.loads(output_raw)+ self.assertEqual(+ output,+ [+ {+ "role": "assistant",+ "parts": [+ {+ "type": "text",+ "content": "Wuhan weather: clear sky.",+ },+ ],+ "name": "test-agent",+ "finish_reason": "stop",+ },+ ],+ )++ async def test_invoke_agent_span_has_input_attributes(self) -> None:+ """invoke_agent span must carry gen_ai.input.messages attribute."""+ self.model.set_responses(+ [+ _make_text_response("Simple answer."),+ ],+ )+ msg = UserMsg(name="user", content="Simple question?")+ await self.agent.reply(msg)++ agent_spans = self._spans_by_name("invoke_agent")+ self.assertEqual(+ len(agent_spans),+ 1,+ "Expected exactly one invoke_agent span",+ )+ span_attrs = dict(agent_spans[0].attributes or {})+ input_raw = span_attrs.get("gen_ai.input.messages")+ assert isinstance(+ input_raw,+ str,+ ), "invoke_agent span gen_ai.input.messages should be a string"+ input_msgs = json.loads(input_raw)+ self.assertEqual(+ input_msgs,+ [+ {+ "role": "user",+ "parts": [+ {"type": "text", "content": "Simple question?"},+ ],+ "name": "user",+ "finish_reason": "stop",+ },+ ],+ )++ async def test_execute_tool_span_has_tool_name_attribute(self) -> None:+ """execute_tool span must have the correct gen_ai.tool.name+ attribute."""+ self.model.set_responses(+ [+ _make_tool_call_response("c8", "Nanjing"),+ _make_text_response("Nanjing result."),+ ],+ )+ msg = UserMsg(name="user", content="Weather in Nanjing?")+ await self.agent.reply(msg)++ tool_spans = self._spans_by_name("execute_tool")+ self.assertEqual(+ len(tool_spans),+ 1,+ "Expected exactly one execute_tool span",+ )+ span_attrs = dict(tool_spans[0].attributes or {})+ self.assertEqual(+ span_attrs.get("gen_ai.tool.name"),+ "get_weather",+ "execute_tool span should have gen_ai.tool.name = get_weather",+ )++ # -----------------------------------------------------------------------+ # Tests: chat (LLM) span+ # -----------------------------------------------------------------------++ async def test_chat_span_has_model_and_provider(self) -> None:+ """chat span must carry gen_ai.request.model and+ gen_ai.provider.name."""+ self.model.set_responses(+ [_make_text_response("Hello from model.")],+ )+ msg = UserMsg(name="user", content="Hello?")+ await self.agent.reply(msg)++ chat_spans = self._spans_by_name("chat")+ self.assertEqual(len(chat_spans), 1, "Expected exactly one chat span")+ span_attrs = dict(chat_spans[0].attributes or {})+ self.assertEqual(+ span_attrs.get("gen_ai.request.model"),+ "mock-model",+ "chat span gen_ai.request.model should equal mock-model",+ )+ self.assertEqual(+ span_attrs.get("gen_ai.operation.name"),+ "chat",+ "chat span gen_ai.operation.name should equal chat",+ )++ async def test_chat_span_has_output_messages(self) -> None:+ """chat span must carry gen_ai.output.messages with response+ content."""+ self.model.set_responses(+ [_make_text_response("Weather is fine.")],+ )+ msg = UserMsg(name="user", content="How is the weather?")+ await self.agent.reply(msg)++ chat_spans = self._spans_by_name("chat")+ self.assertEqual(len(chat_spans), 1, "Expected exactly one chat span")+ span_attrs = dict(chat_spans[0].attributes or {})+ output_raw = span_attrs.get("gen_ai.output.messages")+ assert isinstance(+ output_raw,+ str,+ ), "chat span gen_ai.output.messages should be a string"+ output = json.loads(output_raw)+ self.assertEqual(+ output,+ [+ {+ "role": "assistant",+ "parts": [+ {"type": "text", "content": "Weather is fine."},+ ],+ "finish_reason": "stop",+ },+ ],+ )++ async def test_chat_span_has_usage_tokens(self) -> None:+ """chat span must carry input/output token counts from usage."""+ self.model.set_responses(+ [_make_text_response("Token test.")],+ )+ msg = UserMsg(name="user", content="Count tokens?")+ await self.agent.reply(msg)++ chat_spans = self._spans_by_name("chat")+ self.assertEqual(len(chat_spans), 1, "Expected exactly one chat span")+ span_attrs = dict(chat_spans[0].attributes or {})+ self.assertEqual(+ span_attrs.get("gen_ai.usage.input_tokens"),+ 15,+ "chat span gen_ai.usage.input_tokens should equal 15",+ )+ self.assertEqual(+ span_attrs.get("gen_ai.usage.output_tokens"),+ 8,+ "chat span gen_ai.usage.output_tokens should equal 8",+ )++ # -----------------------------------------------------------------------+ # Tests: reply_id attribute+ # -----------------------------------------------------------------------++ async def test_invoke_agent_span_has_reply_id(self) -> None:+ """invoke_agent span from a normal reply must carry reply_id.++ reply() delegates to _reply(), which is the only decorated entry+ point, so there is exactly one invoke_agent span. We search by+ attribute rather than relying on list order for robustness.+ """+ self.model.set_responses(+ [+ _make_tool_call_response("r1", "Wuhan"),+ _make_text_response("Wuhan: clear sky."),+ ],+ )+ msg = UserMsg(name="user", content="Weather in Wuhan?")+ await self.agent.reply(msg)++ agent_spans = self._spans_by_name("invoke_agent")+ self.assertEqual(+ len(agent_spans),+ 1,+ "Expected exactly one invoke_agent span",+ )+ span_attrs = dict(agent_spans[0].attributes or {})+ self.assertIn(+ "agentscope.agent.reply_id",+ span_attrs,+ "invoke_agent span should have agentscope.agent.reply_id",+ )++ # -----------------------------------------------------------------------+ # Tests: HITL (Human-in-the-loop)+ # -----------------------------------------------------------------------++ async def test_hitl_first_call_has_hitl_pending_attribute(self) -> None:+ """First call in HITL flow must have+ agentscope.agent.hitl_pending_tools."""+ hitl_agent = Agent(+ name="hitl-agent",+ system_prompt="You are a test assistant.",+ model=self.model,+ toolkit=Toolkit(tools=[HitlWeatherTool()]),+ middlewares=[TracingMiddleware()],+ )+ # The HITL tool returns ASK;+ # first call ends with RequireUserConfirmEvent+ self.model.set_responses(+ [_make_tool_call_response("h1", "Beijing")],+ )+ self.exporter.clear()++ msg = UserMsg(name="user", content="Weather in Beijing?")+ async for _ in hitl_agent.reply_stream(msg):+ pass++ first_spans = self._spans_by_name("invoke_agent")+ self.assertEqual(+ len(first_spans),+ 1,+ "Expected exactly one invoke_agent span from first HITL call",+ )+ span_attrs = dict(first_spans[0].attributes or {})+ self.assertIn(+ "agentscope.agent.hitl_pending_tools",+ span_attrs,+ "First HITL span should carry agentscope.agent.hitl_pending_tools",+ )+ pending = json.loads(span_attrs["agentscope.agent.hitl_pending_tools"])+ self.assertEqual(pending, ["get_weather"])++ async def test_hitl_spans_share_reply_id(self) -> None:+ """Both HITL calls must share the same agentscope.agent.reply_id."""+ hitl_agent = Agent(+ name="hitl-agent2",+ system_prompt="You are a test assistant.",+ model=self.model,+ toolkit=Toolkit(tools=[HitlWeatherTool()]),+ middlewares=[TracingMiddleware()],+ )++ # First call: agent asks for confirmation+ self.model.set_responses(+ [_make_tool_call_response("h2", "Shanghai")],+ )+ self.exporter.clear()++ require_confirm_event = None+ async for evt in hitl_agent.reply_stream(+ UserMsg(name="user", content="Weather in Shanghai?"),+ ):+ if isinstance(evt, RequireUserConfirmEvent):+ require_confirm_event = evt++ self.assertIsNotNone(+ require_confirm_event,+ "Expected RequireUserConfirmEvent",+ )++ first_spans = self._spans_by_name("invoke_agent")+ first_reply_ids = {+ dict(s.attributes or {}).get("agentscope.agent.reply_id")+ for s in first_spans+ if "agentscope.agent.reply_id" in (s.attributes or {})+ }+ self.assertEqual(len(first_reply_ids), 1)+ reply_id_first = next(iter(first_reply_ids))++ # Second call: user confirms+ self.model.set_responses(+ [_make_text_response("Shanghai: 18°C, raining.")],+ )+ self.exporter.clear()++ confirm_event = UserConfirmResultEvent(+ reply_id=require_confirm_event.reply_id,+ confirm_results=[+ ConfirmResult(+ confirmed=True,+ tool_call=require_confirm_event.tool_calls[0],+ ),+ ],+ )+ await hitl_agent.reply(event=confirm_event)++ second_spans = self._spans_by_name("invoke_agent")+ second_reply_ids = {+ dict(s.attributes or {}).get("agentscope.agent.reply_id")+ for s in second_spans+ if "agentscope.agent.reply_id" in (s.attributes or {})+ }+ self.assertEqual(len(second_reply_ids), 1)+ reply_id_second = next(iter(second_reply_ids))++ self.assertEqual(+ reply_id_first,+ reply_id_second,+ "Both HITL calls must share the same reply_id",+ )++ async def test_hitl_second_call_has_incoming_event_type(self) -> None:+ """Second call in HITL flow must carry+ incoming_event_type=user_confirm_result."""+ hitl_agent = Agent(+ name="hitl-agent3",+ system_prompt="You are a test assistant.",+ model=self.model,+ toolkit=Toolkit(tools=[HitlWeatherTool()]),+ middlewares=[TracingMiddleware()],+ )++ # First call: agent asks for confirmation+ self.model.set_responses(+ [_make_tool_call_response("h3", "Tianjin")],+ )+ self.exporter.clear()++ require_confirm_event = None+ async for evt in hitl_agent.reply_stream(+ UserMsg(name="user", content="Weather in Tianjin?"),+ ):+ if isinstance(evt, RequireUserConfirmEvent):+ require_confirm_event = evt++ self.assertIsNotNone(+ require_confirm_event,+ "Expected RequireUserConfirmEvent",+ )++ # Second call: user confirms+ self.model.set_responses(+ [_make_text_response("Tianjin: windy, 12°C.")],+ )+ self.exporter.clear()++ confirm_event = UserConfirmResultEvent(+ reply_id=require_confirm_event.reply_id,+ confirm_results=[+ ConfirmResult(+ confirmed=True,+ tool_call=require_confirm_event.tool_calls[0],+ ),+ ],+ )+ await hitl_agent.reply(event=confirm_event)++ agent_spans = self._spans_by_name("invoke_agent")+ self.assertEqual(+ len(agent_spans),+ 1,+ "Expected exactly one invoke_agent span from second HITL call",+ )+ span_attrs = dict(agent_spans[0].attributes or {})+ self.assertEqual(+ span_attrs.get("agentscope.agent.incoming_event_type"),+ "user_confirm_result",+ "Second HITL invoke_agent span should have "+ "incoming_event_type=user_confirm_result",+ )++ # -----------------------------------------------------------------------+ # Tests: External execution+ # -----------------------------------------------------------------------++ async def test_external_execution_first_call_has_pending_attribute(+ self,+ ) -> None:+ """First call must have+ agentscope.agent.external_execution_pending_tools."""+ ext_agent = Agent(+ name="ext-agent",+ system_prompt="You are a test assistant.",+ model=self.model,+ toolkit=Toolkit(tools=[ExternalWeatherTool()]),+ middlewares=[TracingMiddleware()],+ )+ self.model.set_responses(+ [_make_tool_call_response("e1", "Guangzhou")],+ )+ self.exporter.clear()++ async for _ in ext_agent.reply_stream(+ UserMsg(name="user", content="Weather in Guangzhou?"),+ ):+ pass++ first_spans = self._spans_by_name("invoke_agent")+ self.assertEqual(+ len(first_spans),+ 1,+ "Expected exactly one invoke_agent span",+ )+ span_attrs = dict(first_spans[0].attributes or {})+ self.assertIn(+ "agentscope.agent.external_execution_pending_tools",+ span_attrs,+ "First external-execution span should carry "+ "agentscope.agent.external_execution_pending_tools",+ )+ pending = json.loads(+ span_attrs["agentscope.agent.external_execution_pending_tools"],+ )+ self.assertEqual(pending, ["get_weather"])++ async def test_external_execution_spans_share_reply_id(self) -> None:+ """Both external-execution calls must share the same reply_id."""+ ext_agent = Agent(+ name="ext-agent-rid",+ system_prompt="You are a test assistant.",+ model=self.model,+ toolkit=Toolkit(tools=[ExternalWeatherTool()]),+ middlewares=[TracingMiddleware()],+ )++ # First call: agent requires external execution+ self.model.set_responses(+ [_make_tool_call_response("ex-r1", "Nanjing")],+ )+ self.exporter.clear()++ require_ext_event = None+ async for evt in ext_agent.reply_stream(+ UserMsg(name="user", content="Weather in Nanjing?"),+ ):+ if isinstance(evt, RequireExternalExecutionEvent):+ require_ext_event = evt++ self.assertIsNotNone(+ require_ext_event,+ "Expected RequireExternalExecutionEvent",+ )++ first_spans = self._spans_by_name("invoke_agent")+ first_reply_ids = {+ dict(s.attributes or {}).get("agentscope.agent.reply_id")+ for s in first_spans+ if "agentscope.agent.reply_id" in (s.attributes or {})+ }+ self.assertEqual(len(first_reply_ids), 1)+ reply_id_first = next(iter(first_reply_ids))++ # Second call: inject external result+ self.model.set_responses(+ [_make_text_response("Nanjing: clear, 18°C.")],+ )+ self.exporter.clear()++ ext_result = ExternalExecutionResultEvent(+ reply_id=require_ext_event.reply_id,+ execution_results=[+ ToolResultBlock(+ id=require_ext_event.tool_calls[0].id,+ name="get_weather",+ output="Nanjing: clear, 18°C.",+ state=ToolResultState.SUCCESS,+ ),+ ],+ )+ await ext_agent.reply(event=ext_result)++ second_spans = self._spans_by_name("invoke_agent")+ second_reply_ids = {+ dict(s.attributes or {}).get("agentscope.agent.reply_id")+ for s in second_spans+ if "agentscope.agent.reply_id" in (s.attributes or {})+ }+ self.assertEqual(len(second_reply_ids), 1)+ reply_id_second = next(iter(second_reply_ids))++ self.assertEqual(+ reply_id_first,+ reply_id_second,+ "Both external-execution calls must share the same reply_id",+ )++ async def test_external_execution_second_call_has_synthetic_tool_span(+ self,+ ) -> None:+ """Second call with ExternalExecutionResultEvent must produce+ execute_tool span."""+ ext_agent = Agent(+ name="ext-agent2",+ system_prompt="You are a test assistant.",+ model=self.model,+ toolkit=Toolkit(tools=[ExternalWeatherTool()]),+ middlewares=[TracingMiddleware()],+ )++ # First call+ self.model.set_responses(+ [_make_tool_call_response("e2", "Shenzhen")],+ )+ self.exporter.clear()++ require_ext_event = None+ async for evt in ext_agent.reply_stream(+ UserMsg(name="user", content="Weather in Shenzhen?"),+ ):+ if isinstance(evt, RequireExternalExecutionEvent):+ require_ext_event = evt++ self.assertIsNotNone(require_ext_event)++ # Second call: inject external result+ self.model.set_responses(+ [_make_text_response("Shenzhen: warm, 28°C.")],+ )+ self.exporter.clear()++ ext_result = ExternalExecutionResultEvent(+ reply_id=require_ext_event.reply_id,+ execution_results=[+ ToolResultBlock(+ id=require_ext_event.tool_calls[0].id,+ name="get_weather",+ output="Shenzhen: warm, 28°C.",+ state=ToolResultState.SUCCESS,+ ),+ ],+ )+ await ext_agent.reply(event=ext_result)++ tool_spans = self._spans_by_name("execute_tool")+ self.assertEqual(+ len(tool_spans),+ 1,+ "Expected exactly one synthetic execute_tool span",+ )+ span_attrs = dict(tool_spans[0].attributes or {})+ self.assertEqual(+ span_attrs.get("agentscope.agent.is_external_execution"),+ True,+ "Synthetic execute_tool span should have "+ "is_external_execution=True",+ )+ self.assertEqual(span_attrs.get("gen_ai.tool.name"), "get_weather")++ async def test_external_execution_second_call_has_incoming_event_type(+ self,+ ) -> None:+ """Second call span must have+ incoming_event_type=external_execution_result."""+ ext_agent = Agent(+ name="ext-agent3",+ system_prompt="You are a test assistant.",+ model=self.model,+ toolkit=Toolkit(tools=[ExternalWeatherTool()]),+ middlewares=[TracingMiddleware()],+ )++ # First call+ self.model.set_responses(+ [_make_tool_call_response("e3", "Chengdu")],+ )+ self.exporter.clear()++ require_ext_event = None+ async for evt in ext_agent.reply_stream(+ UserMsg(name="user", content="Weather in Chengdu?"),+ ):+ if isinstance(evt, RequireExternalExecutionEvent):+ require_ext_event = evt++ # Second call+ self.model.set_responses([_make_text_response("Chengdu: cloudy.")])+ self.exporter.clear()++ ext_result = ExternalExecutionResultEvent(+ reply_id=require_ext_event.reply_id,+ execution_results=[+ ToolResultBlock(+ id=require_ext_event.tool_calls[0].id,+ name="get_weather",+ output="Chengdu: cloudy, 15°C.",+ state=ToolResultState.SUCCESS,+ ),+ ],+ )+ await ext_agent.reply(event=ext_result)++ agent_spans = self._spans_by_name("invoke_agent")+ self.assertEqual(+ len(agent_spans),+ 1,+ "Expected exactly one invoke_agent span",+ )+ span_attrs = dict(agent_spans[0].attributes or {})+ self.assertEqual(+ span_attrs.get("agentscope.agent.incoming_event_type"),+ "external_execution_result",+ )