Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
feat(tracing): add OpenTelemetry-based tracing as a middleware (#1633)
qbce572c5dcd2fe
diff --git a/src/agentscope/middleware/__init__.py b/src/agentscope/middleware/__init__.pyindex d898ddea4..3b501bd79 100644--- a/src/agentscope/middleware/__init__.py+++ b/src/agentscope/middleware/__init__.py@@ -2,7 +2,9 @@"""Middleware system for AgentScope agents."""from ._base import MiddlewareBase+from ._tracing import TracingMiddleware__all__ = ["MiddlewareBase",+ "TracingMiddleware",]diff --git a/src/agentscope/middleware/_tracing/__init__.py b/src/agentscope/middleware/_tracing/__init__.pynew file mode 100644index 000000000..9fad1ded9--- /dev/null+++ b/src/agentscope/middleware/_tracing/__init__.py@@ -0,0 +1,8 @@+# -*- coding: utf-8 -*-+"""The tracing interface class in agentscope."""++from ._trace import TracingMiddleware++__all__ = [+ "TracingMiddleware",+]diff --git a/src/agentscope/middleware/_tracing/_attributes.py b/src/agentscope/middleware/_tracing/_attributes.pynew file mode 100644index 000000000..ed3d336be--- /dev/null+++ b/src/agentscope/middleware/_tracing/_attributes.py@@ -0,0 +1,201 @@+# -*- coding: utf-8 -*-+"""The tracing types class in agentscope."""+from opentelemetry.semconv._incubating.attributes import (+ gen_ai_attributes as GenAIAttributes,+)+++class SpanAttributes:+ """The span attributes."""++ # GenAI Common Attributes+ GEN_AI_CONVERSATION_ID = GenAIAttributes.GEN_AI_CONVERSATION_ID+ """The gen ai conversation ID."""++ GEN_AI_OPERATION_NAME = GenAIAttributes.GEN_AI_OPERATION_NAME+ """The gen ai operation name."""++ GEN_AI_PROVIDER_NAME = GenAIAttributes.GEN_AI_PROVIDER_NAME+ """The gen ai provider name."""++ # GenAI Request Attributes+ GEN_AI_REQUEST_MODEL = GenAIAttributes.GEN_AI_REQUEST_MODEL+ """The gen ai request model."""++ GEN_AI_REQUEST_TEMPERATURE = GenAIAttributes.GEN_AI_REQUEST_TEMPERATURE+ """The gen ai request temperature."""++ GEN_AI_REQUEST_TOP_P = GenAIAttributes.GEN_AI_REQUEST_TOP_P+ """The gen ai request top_p."""++ GEN_AI_REQUEST_TOP_K = GenAIAttributes.GEN_AI_REQUEST_TOP_K+ """The gen ai request top_k."""++ GEN_AI_REQUEST_MAX_TOKENS = GenAIAttributes.GEN_AI_REQUEST_MAX_TOKENS+ """The gen ai request max_tokens."""++ GEN_AI_REQUEST_PRESENCE_PENALTY = (+ GenAIAttributes.GEN_AI_REQUEST_PRESENCE_PENALTY+ )+ """The gen ai request presence_penalty."""++ GEN_AI_REQUEST_FREQUENCY_PENALTY = (+ GenAIAttributes.GEN_AI_REQUEST_FREQUENCY_PENALTY+ )+ """The gen ai request frequency_penalty."""++ GEN_AI_REQUEST_STOP_SEQUENCES = (+ GenAIAttributes.GEN_AI_REQUEST_STOP_SEQUENCES+ )+ """The gen ai request stop_sequences."""++ GEN_AI_REQUEST_SEED = GenAIAttributes.GEN_AI_REQUEST_SEED+ """The gen ai request seed."""++ # GenAI Response Attributes+ GEN_AI_RESPONSE_ID = GenAIAttributes.GEN_AI_RESPONSE_ID+ """The gen ai response ID."""++ GEN_AI_RESPONSE_FINISH_REASONS = (+ GenAIAttributes.GEN_AI_RESPONSE_FINISH_REASONS+ )+ """The gen ai response finish reasons."""++ # GenAI Usage Attributes+ GEN_AI_USAGE_INPUT_TOKENS = GenAIAttributes.GEN_AI_USAGE_INPUT_TOKENS+ """The gen ai usage input tokens."""++ GEN_AI_USAGE_OUTPUT_TOKENS = GenAIAttributes.GEN_AI_USAGE_OUTPUT_TOKENS+ """The gen ai usage output tokens."""++ # GenAI Message Attributes+ GEN_AI_INPUT_MESSAGES = GenAIAttributes.GEN_AI_INPUT_MESSAGES+ """The gen ai input messages."""++ GEN_AI_OUTPUT_MESSAGES = GenAIAttributes.GEN_AI_OUTPUT_MESSAGES+ """The gen ai output messages."""++ # GenAI Agent Attributes+ GEN_AI_AGENT_ID = GenAIAttributes.GEN_AI_AGENT_ID+ """The gen ai agent ID."""++ GEN_AI_AGENT_NAME = GenAIAttributes.GEN_AI_AGENT_NAME+ """The gen ai agent name."""++ GEN_AI_AGENT_DESCRIPTION = GenAIAttributes.GEN_AI_AGENT_DESCRIPTION+ """The gen ai agent description."""++ # GenAI Tool Attributes+ GEN_AI_TOOL_CALL_ID = GenAIAttributes.GEN_AI_TOOL_CALL_ID+ """The gen ai tool call ID."""++ GEN_AI_TOOL_NAME = GenAIAttributes.GEN_AI_TOOL_NAME+ """The gen ai tool name."""++ GEN_AI_TOOL_DESCRIPTION = GenAIAttributes.GEN_AI_TOOL_DESCRIPTION+ """The gen ai tool description."""++ GEN_AI_TOOL_CALL_ARGUMENTS = GenAIAttributes.GEN_AI_TOOL_CALL_ARGUMENTS+ """The gen ai tool call arguments."""++ GEN_AI_TOOL_CALL_RESULT = GenAIAttributes.GEN_AI_TOOL_CALL_RESULT+ """The gen ai tool call result."""++ GEN_AI_TOOL_DEFINITIONS = GenAIAttributes.GEN_AI_TOOL_DEFINITIONS+ """The gen ai tool definitions."""++ AGENTSCOPE_CACHE_INPUT_TOKENS = "agentscope.usage.cache_input_tokens"+ """The number of input tokens read from prompt cache."""++ AGENTSCOPE_CACHE_CREATION_INPUT_TOKENS = (+ "agentscope.usage.cache_creation_input_tokens"+ )+ """The number of input tokens used to create prompt cache."""++ AGENTSCOPE_REPLY_ID = "agentscope.agent.reply_id"+ """The reply ID of the current agent reply.++ 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_HITL_PENDING_TOOLS = "agentscope.agent.hitl_pending_tools"+ """JSON list of tool names that are waiting for human confirmation.++ Set on the first ``invoke_agent`` span when the agent pauses due to a+ ``RequireUserConfirmEvent``.+ """++ AGENTSCOPE_EXTERNAL_EXECUTION_PENDING_TOOLS = (+ "agentscope.agent.external_execution_pending_tools"+ )+ """JSON list of tool names submitted for external execution.++ 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.++ 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``).++ The timestamp reflects when the result was received, not when the tool+ actually ran on the external system.+ """+++class OperationNameValues:+ """The operation name values."""++ CHAT = GenAIAttributes.GenAiOperationNameValues.CHAT.value+ """The chat operation name."""++ INVOKE_AGENT = GenAIAttributes.GenAiOperationNameValues.INVOKE_AGENT.value+ """The invoke agent operation name."""++ EXECUTE_TOOL = GenAIAttributes.GenAiOperationNameValues.EXECUTE_TOOL.value+ """The execute tool operation name."""+++class ProviderNameValues:+ """The provider name values."""++ DASHSCOPE = "dashscope"+ """The dashscope provider name."""++ OLLAMA = "ollama"+ """The ollama provider name."""++ DEEPSEEK = GenAIAttributes.GenAiProviderNameValues.DEEPSEEK.value+ """The deepseek provider name."""++ OPENAI = GenAIAttributes.GenAiProviderNameValues.OPENAI.value+ """The openai provider name."""++ ANTHROPIC = GenAIAttributes.GenAiProviderNameValues.ANTHROPIC.value+ """The anthropic provider name."""++ GCP_GEMINI = GenAIAttributes.GenAiProviderNameValues.GCP_GEMINI.value+ """The gcp gemini provider name."""++ MOONSHOT = "moonshot"+ """The moonshot provider name."""++ AZURE_AI_OPENAI = (+ GenAIAttributes.GenAiProviderNameValues.AZURE_AI_OPENAI.value+ )+ """The azure openai provider name."""++ AWS_BEDROCK = GenAIAttributes.GenAiProviderNameValues.AWS_BEDROCK.value+ """The aws bedrock provider name."""++ XAI = GenAIAttributes.GenAiProviderNameValues.X_AI.value+ """The xAI (Grok) provider name."""diff --git a/src/agentscope/middleware/_tracing/_converter.py b/src/agentscope/middleware/_tracing/_converter.pynew file mode 100644index 000000000..f69cf7e9a--- /dev/null+++ b/src/agentscope/middleware/_tracing/_converter.py@@ -0,0 +1,121 @@+# -*- 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++# Valid OTel GenAI modality values for multimodal content parts.+_VALID_MODALITIES = frozenset({"image", "audio", "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 prefix if prefix in _VALID_MODALITIES else "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/middleware/_tracing/_extractor.py b/src/agentscope/middleware/_tracing/_extractor.pynew file mode 100644index 000000000..788253c97--- /dev/null+++ b/src/agentscope/middleware/_tracing/_extractor.py@@ -0,0 +1,608 @@+# -*- coding: utf-8 -*-+"""Extract attributes from AgentScope components for OpenTelemetry tracing."""+import inspect+from typing import Any, Dict, TYPE_CHECKING++from ...message import Msg, ToolCallBlock++from ._attributes import (+ SpanAttributes,+ OperationNameValues,+ ProviderNameValues,+)+from ._converter import _convert_block_to_part+from ._utils import _serialize_to_str+from ...model import ChatResponse, ChatModelBase+from ...event import (+ ExternalExecutionResultEvent,+ UserConfirmResultEvent,+)++if TYPE_CHECKING:+ from ...agent import Agent+ from ...tool import Toolkit, ToolChoice++_CLASS_NAME_MAP = {+ "dashscope": ProviderNameValues.DASHSCOPE,+ "openai": ProviderNameValues.OPENAI,+ "anthropic": ProviderNameValues.ANTHROPIC,+ "gemini": ProviderNameValues.GCP_GEMINI,+ "ollama": ProviderNameValues.OLLAMA,+ "deepseek": ProviderNameValues.DEEPSEEK,+ "xai": ProviderNameValues.XAI,+ "moonshot": ProviderNameValues.MOONSHOT,+}++# Map base URL fragments to provider names for OpenAI-compatible APIs+_BASE_URL_PROVIDER_MAP = [+ ("api.openai.com", ProviderNameValues.OPENAI),+ ("dashscope", ProviderNameValues.DASHSCOPE),+ ("deepseek", ProviderNameValues.DEEPSEEK),+ ("moonshot", ProviderNameValues.MOONSHOT),+ ("generativelanguage.googleapis.com", ProviderNameValues.GCP_GEMINI),+ ("openai.azure.com", ProviderNameValues.AZURE_AI_OPENAI),+ ("amazonaws.com", ProviderNameValues.AWS_BEDROCK),+ ("api.x.ai", ProviderNameValues.XAI),+]+++def _get_common_attributes(session_id: str = "") -> Dict[str, str]:+ """Get common attributes for all spans.++ Args:+ session_id (`str`):+ The session ID to set as conversation ID.++ Returns:+ `Dict[str, str]`:+ Common span attributes including conversation ID.+ """+ return {+ SpanAttributes.GEN_AI_CONVERSATION_ID: (+ session_id if session_id else "[no_session_id]"+ ),+ }+++def _get_provider_name(instance: "ChatModelBase") -> str:+ """Get provider name from ChatModelBase instance.++ Maps ChatModelBase class names to provider names, with special handling+ for OpenAI-compatible APIs that may use different base URLs.+ This follows the implementation pattern from agentscope-java PR #73.++ Args:+ instance (`ChatModelBase`):+ The chat model instance to get the provider name for.++ Returns:+ `str`:+ Provider name (e.g., "openai", "dashscope", "anthropic")+ """+ classname = instance.__class__.__name__++ # For other model types, use direct mapping+ prefix_key = (+ classname.removesuffix("ChatModel")+ .removesuffix("MultiAgentModel")+ .removesuffix("ResponseModel")+ .lower()+ )++ # Special handling for OpenAI-compatible models — inspect base_url+ # from credential to distinguish the actual provider.+ if prefix_key == "openai":+ base_url = getattr(instance.credential, "base_url", None)+ if base_url:+ base_url = str(base_url)+ for url_fragment, provider_name in _BASE_URL_PROVIDER_MAP:+ if url_fragment in base_url:+ return provider_name+ return ProviderNameValues.OPENAI++ return _CLASS_NAME_MAP.get(prefix_key, "unknown")+++def _get_tool_definitions(+ tools: list[dict[str, Any]] | None,+ tool_choice: "ToolChoice | None",+) -> str | None:+ """Extract and serialize tool definitions for tracing.++ Converts AgentScope/OpenAI nested tool format to OpenTelemetry GenAI+ flat format for tracing.++ Args:+ tools (`list[dict[str, Any]] | None`, optional):+ List of tool definitions in OpenAI format with nested+ structure: ``[{"type": "function", "function": {...}}]``+ tool_choice (`ToolChoice | None`, optional):+ Tool choice configuration with ``mode`` and optional ``tools``+ fields. If mode is ``"none"``, returns None to indicate tools+ should not be traced.++ Returns:+ `str | None`:+ Serialized tool definitions in flat format:+ ``[{"type": "function", "name": ..., "parameters": ...}]``+ or None if tools should not be traced (e.g., tools is None/empty+ or tool_choice is "none").+ """+ # No tools provided+ if tools is None or not isinstance(tools, list) or len(tools) == 0:+ return None++ # Tool choice is explicitly "none" (model should not use tools)+ if tool_choice is not None and tool_choice.mode == "none":+ return None++ try:+ # Convert nested format to flat format for OpenTelemetry GenAI+ # TODO: Currently only supports "function" type tools. If other tool+ # types are added in the future (e.g., "retrieval", "code_interpreter",+ # "browser"), this conversion logic needs to be updated to handle them.+ flat_tools = []+ for tool in tools:+ if not isinstance(tool, dict) or "function" not in tool:+ continue++ func_def = tool["function"]+ flat_tool = {+ "type": tool.get("type", "function"),+ "name": func_def.get("name"),+ "description": func_def.get("description"),+ "parameters": func_def.get("parameters"),+ }+ # Remove None values+ flat_tool = {k: v for k, v in flat_tool.items() if v is not None}+ flat_tools.append(flat_tool)++ if flat_tools:+ return _serialize_to_str(flat_tools)+ return None++ except Exception:+ return None+++def _get_llm_request_attributes(+ instance: "ChatModelBase",+ kwargs: Dict[str, Any],+) -> Dict[str, Any]:+ """Get LLM request attributes for OpenTelemetry tracing.++ Extracts request parameters from LLM model calls into GenAI attributes.++ Args:+ instance (`ChatModelBase`):+ The chat model instance making the request.+ kwargs (`Dict[str, Any]`):+ Keyword arguments including generation parameters such as+ temperature, top_p, top_k, max_tokens, presence_penalty,+ frequency_penalty, stop_sequences, seed, tools, and tool_choice.++ Returns:+ `Dict[str, Any]`:+ OpenTelemetry GenAI attributes with mixed-type values (``str``,+ ``int``, ``float``, or ``list``), including operation name,+ provider name, model name, generation parameters (e.g.+ temperature, max_tokens, stop_sequences), and tool definitions.+ """++ attributes = {+ # required attributes+ SpanAttributes.GEN_AI_OPERATION_NAME: OperationNameValues.CHAT,+ SpanAttributes.GEN_AI_PROVIDER_NAME: _get_provider_name(instance),+ # conditionally required attributes+ SpanAttributes.GEN_AI_REQUEST_MODEL: instance.model,+ # recommended attributes+ SpanAttributes.GEN_AI_REQUEST_TEMPERATURE: kwargs.get("temperature"),+ SpanAttributes.GEN_AI_REQUEST_TOP_P: kwargs.get("p")+ or kwargs.get("top_p"),+ SpanAttributes.GEN_AI_REQUEST_TOP_K: kwargs.get("top_k"),+ SpanAttributes.GEN_AI_REQUEST_MAX_TOKENS: kwargs.get("max_tokens"),+ SpanAttributes.GEN_AI_REQUEST_PRESENCE_PENALTY: kwargs.get(+ "presence_penalty",+ ),+ SpanAttributes.GEN_AI_REQUEST_FREQUENCY_PENALTY: kwargs.get(+ "frequency_penalty",+ ),+ SpanAttributes.GEN_AI_REQUEST_STOP_SEQUENCES: kwargs.get(+ "stop_sequences",+ ),+ SpanAttributes.GEN_AI_REQUEST_SEED: kwargs.get("seed"),+ }++ # Extract tool definitions if provided+ tool_definitions = _get_tool_definitions(+ tools=kwargs.get("tools"),+ tool_choice=kwargs.get("tool_choice"),+ )+ if tool_definitions:+ attributes[SpanAttributes.GEN_AI_TOOL_DEFINITIONS] = tool_definitions++ return {k: v for k, v in attributes.items() if v is not None}+++def _get_llm_span_name(attributes: Dict[str, str]) -> str:+ """Generate span name for LLM operations.++ Args:+ attributes (`Dict[str, str]`):+ LLM request attributes dictionary containing operation name and+ model name.++ Returns:+ `str`:+ Formatted span name in the format "{operation} {model}",+ e.g., "chat gpt-4" or "chat qwen-plus".+ """+ return (+ f"{attributes[SpanAttributes.GEN_AI_OPERATION_NAME]} "+ f"{attributes[SpanAttributes.GEN_AI_REQUEST_MODEL]}"+ )+++def _get_llm_output_messages(+ chat_response: ChatResponse | None,+) -> list[dict[str, Any]]:+ """Extract and format LLM output messages for tracing.++ Converts ChatResponse objects to standardized message format compatible+ with OpenTelemetry GenAI specification.++ Args:+ chat_response (` ChatResponse | None`):+ Chat response object with content blocks. Should be a ChatResponse+ instance containing content blocks (text, tool_use, etc.).++ Returns:+ `list[dict[str, Any]]`:+ List containing a single formatted message dictionary with role,+ parts, and finish_reason. Returns the original response if it's+ not a ChatResponse instance, or an error message format if+ conversion fails.+ """+ try:+ if not isinstance(chat_response, ChatResponse):+ return [+ {+ "role": "assistant",+ "parts": [+ {+ "type": "text",+ "content": str(chat_response),+ },+ ],+ "finish_reason": "unknown",+ },+ ]++ parts = []+ finish_reason = "stop" # Default finish reason++ for block in chat_response.content:+ part = _convert_block_to_part(block)+ if part:+ parts.append(part)++ output_message = {+ "role": "assistant",+ "parts": parts,+ "finish_reason": finish_reason,+ }++ return [output_message]++ except Exception:+ return [+ {+ "role": "assistant",+ "parts": [+ {+ "type": "text",+ "content": "<error processing response>",+ },+ ],+ "finish_reason": "error",+ },+ ]+++def _get_llm_response_attributes(+ chat_response: ChatResponse | None,+) -> Dict[str, Any]:+ """Get LLM response attributes for OpenTelemetry tracing.++ Extracts response metadata and formats into GenAI attributes.++ Args:+ chat_response (`ChatResponse | None`):+ Chat response object with data and usage info. Should have+ attributes like id, usage (with input_tokens and output_tokens),+ and content blocks.++ Returns:+ `Dict[str, Any]`:+ OpenTelemetry GenAI response attributes including response ID,+ finish reasons, token usage (input/output tokens), and output+ messages.+ """+ attributes = {+ SpanAttributes.GEN_AI_RESPONSE_ID: getattr(+ chat_response,+ "id",+ "unknown_id",+ ),+ # FIXME: finish reason should be capture in chat response+ SpanAttributes.GEN_AI_RESPONSE_FINISH_REASONS: '["stop"]',+ }+ if hasattr(chat_response, "usage") and chat_response.usage:+ usage = chat_response.usage+ attributes[+ SpanAttributes.GEN_AI_USAGE_INPUT_TOKENS+ ] = usage.input_tokens+ attributes[+ SpanAttributes.GEN_AI_USAGE_OUTPUT_TOKENS+ ] = usage.output_tokens++ cache_input = usage.cache_input_tokens+ if cache_input:+ attributes[+ SpanAttributes.AGENTSCOPE_CACHE_INPUT_TOKENS+ ] = cache_input++ cache_creation = usage.cache_creation_input_tokens+ if cache_creation:+ attributes[+ SpanAttributes.AGENTSCOPE_CACHE_CREATION_INPUT_TOKENS+ ] = cache_creation++ output_messages = _get_llm_output_messages(chat_response)+ if output_messages:+ attributes[SpanAttributes.GEN_AI_OUTPUT_MESSAGES] = _serialize_to_str(+ output_messages,+ )++ return attributes+++def _get_agent_messages(+ msg: Msg | list[Msg],+) -> list[dict[str, Any]]:+ """Convert AgentScope message(s) to standardized parts format.++ Transforms Msg objects into OpenTelemetry GenAI format.++ Args:+ msg (`Msg | list[Msg]`):+ AgentScope message object or list of message objects with+ content blocks.++ Returns:+ `list[dict[str, Any]]`:+ List of formatted message dictionaries with role, parts, name,+ and finish_reason.+ """+ try:+ if isinstance(msg, Msg):+ msg = [msg]++ formatted_msgs = []+ for m in msg:+ parts = []+ for block in m.get_content_blocks():+ part = _convert_block_to_part(block)+ if part:+ parts.append(part)+ formatted_msg = {+ "role": m.role,+ "parts": parts,+ "name": m.name,+ "finish_reason": "stop",+ }+ formatted_msgs.append(formatted_msg)++ return formatted_msgs+ except Exception:+ # 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: "Agent",+ kwargs: Dict[str, Any],+) -> Dict[str, str]:+ """Get agent request attributes for OpenTelemetry tracing.++ Extracts agent metadata and input data into GenAI attributes.++ Args:+ instance (`Agent`):+ The agent instance making the request.+ 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, and input messages (if provided).+ """+ attributes = {+ SpanAttributes.GEN_AI_OPERATION_NAME: (+ OperationNameValues.INVOKE_AGENT+ ),+ SpanAttributes.GEN_AI_AGENT_NAME: instance.name,+ SpanAttributes.GEN_AI_AGENT_DESCRIPTION: inspect.getdoc(+ instance.__class__,+ )+ or "No description available",+ }++ inputs = kwargs.get("inputs")+ if inputs is not None:+ if isinstance(inputs, (Msg, list)):+ input_messages = _get_agent_messages(inputs)+ attributes[+ SpanAttributes.GEN_AI_INPUT_MESSAGES+ ] = _serialize_to_str(input_messages)+ elif isinstance(inputs, UserConfirmResultEvent):+ attributes[+ SpanAttributes.AGENTSCOPE_INCOMING_EVENT_TYPE+ ] = "user_confirm_result"+ elif isinstance(inputs, ExternalExecutionResultEvent):+ attributes[+ SpanAttributes.AGENTSCOPE_INCOMING_EVENT_TYPE+ ] = "external_execution_result"++ return attributes+++def _get_agent_span_name(attributes: Dict[str, str]) -> str:+ """Generate span name for agent operations.++ Args:+ attributes (`Dict[str, str]`):+ Agent request attributes dictionary containing operation name and+ agent name.++ Returns:+ `str`:+ Formatted span name in the format "{operation} {agent_name}",+ e.g., "invoke_agent MyAgent".+ """+ return (+ f"{attributes[SpanAttributes.GEN_AI_OPERATION_NAME]} "+ f"{attributes[SpanAttributes.GEN_AI_AGENT_NAME]}"+ )+++def _get_agent_response_attributes(+ agent_response: Msg,+) -> Dict[str, str]:+ """Get agent response attributes for OpenTelemetry tracing.++ Args:+ agent_response (`Msg`):+ Response message returned by agent, containing content blocks.++ Returns:+ `Dict[str, str]`:+ OpenTelemetry GenAI response attributes including output messages.+ """+ attributes = {+ SpanAttributes.GEN_AI_OUTPUT_MESSAGES: _serialize_to_str(+ _get_agent_messages(agent_response),+ ),+ }+ return attributes+++def _get_tool_request_attributes(+ instance: "Toolkit",+ tool_call: ToolCallBlock,+) -> Dict[str, str]:+ """Get tool request attributes for OpenTelemetry tracing.++ Extracts tool execution metadata into GenAI attributes.++ Args:+ instance (`Toolkit`):+ Toolkit instance with tool definitions. Used to extract tool+ description from the tool's JSON schema.+ tool_call (`ToolCallBlock`):+ Tool use block with call information including id, name, and input+ arguments.++ Returns:+ `Dict[str, str]`:+ OpenTelemetry GenAI tool attributes including operation name, tool+ call ID, tool name, tool description (if available), and tool call+ arguments.+ """+ attributes = {+ SpanAttributes.GEN_AI_OPERATION_NAME: (+ OperationNameValues.EXECUTE_TOOL+ ),+ }++ if tool_call:+ tool_name = tool_call.name+ attributes[SpanAttributes.GEN_AI_TOOL_CALL_ID] = tool_call.id+ attributes[SpanAttributes.GEN_AI_TOOL_NAME] = tool_name+ # 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.input++ if tool_name:+ 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+ ] = description++ return attributes+++def _get_tool_span_name(attributes: Dict[str, str]) -> str:+ """Generate span name for tool operations.++ Args:+ attributes (`Dict[str, str]`):+ Tool request attributes dictionary containing operation name and+ tool name.++ Returns:+ `str`:+ Formatted span name in the format "{operation} {tool_name}",+ e.g., "execute_tool search".+ """+ return (+ f"{attributes[SpanAttributes.GEN_AI_OPERATION_NAME]} "+ f"{attributes[SpanAttributes.GEN_AI_TOOL_NAME]}"+ )+++def _get_tool_response_attributes(+ tool_response: Any,+) -> Dict[str, str]:+ """Get tool response attributes for OpenTelemetry tracing.++ Args:+ tool_response (`Any`):+ Response object from tool execution. Can be any serializable object+ returned by the tool function.++ Returns:+ `Dict[str, str]`:+ OpenTelemetry GenAI response attributes including tool call result.+ """+ attributes = {+ SpanAttributes.GEN_AI_TOOL_CALL_RESULT: _serialize_to_str(+ tool_response,+ ),+ }+ return attributesdiff --git a/src/agentscope/middleware/_tracing/_setup.py b/src/agentscope/middleware/_tracing/_setup.pynew file mode 100644index 000000000..5aaedd536--- /dev/null+++ b/src/agentscope/middleware/_tracing/_setup.py@@ -0,0 +1,19 @@+# -*- coding: utf-8 -*-+"""The tracing interface class in agentscope."""+from typing import TYPE_CHECKING++if TYPE_CHECKING:+ from opentelemetry.trace import Tracer+else:+ Tracer = "Tracer"+++def _get_tracer() -> Tracer:+ """Get the tracer+ Returns:+ `Tracer`: The tracer with the name "agentscope" and version.+ """+ from opentelemetry import trace+ 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..d8c3fb3af--- /dev/null+++ b/src/agentscope/middleware/_tracing/_trace.py@@ -0,0 +1,348 @@+# -*- coding: utf-8 -*-+"""TracingMiddleware and supporting utilities for OpenTelemetry tracing."""+import json+from typing import (+ Any,+ AsyncGenerator,+ Callable,+ Awaitable,+ Union,+ TypeVar,+ TYPE_CHECKING,+)++import aioitertools++from opentelemetry import trace as otel_trace+from opentelemetry.trace import StatusCode++from .._base import MiddlewareBase+from ...event import (+ ExternalExecutionResultEvent,+ RequireExternalExecutionEvent,+ RequireUserConfirmEvent,+ ReplyStartEvent,+)+from ...message import Msg, ToolCallBlock+from ...model import ChatModelBase++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")+++# ---------------------------------------------------------------------------+# 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.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."""+ span.set_status(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."""+ span.set_status(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:+ response_attributes = _get_llm_response_attributes(last_chunk)+ 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 = agent.state.session_id+ common_attrs = _get_common_attributes(session_id)++ 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,+ **common_attrs,+ },+ end_on_exit=False,+ ) as span:+ # Synthetic execute_tool spans for externally executed tools+ event_arg = input_kwargs.get("inputs")+ if isinstance(event_arg, ExternalExecutionResultEvent):+ 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, ReplyStartEvent):+ observed_reply_id = item.reply_id+ elif isinstance(item, RequireUserConfirmEvent):+ hitl_pending.extend(t.name for t in item.tool_calls)+ elif isinstance(item, RequireExternalExecutionEvent):+ 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 agent.state.reply_id+ 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, ensure_ascii=False),+ )+ if external_pending:+ span.set_attribute(+ SpanAttributes.AGENTSCOPE_EXTERNAL_EXECUTION_PENDING_TOOLS, # noqa+ json.dumps(external_pending, ensure_ascii=False),+ )+ 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)++ # ------------------------------------------------------------------+ # 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)++ model = input_kwargs.get("current_model")+ if not isinstance(model, ChatModelBase):+ return await next_handler(**input_kwargs)++ tracer = _get_tracer()++ 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(agent.state.session_id),+ },+ 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++ tool_call = input_kwargs.get("tool_call")+ if not isinstance(tool_call, ToolCallBlock):+ async for item in next_handler(**input_kwargs):+ yield item+ return++ tracer = _get_tracer()++ 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(agent.state.session_id),+ },+ 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/middleware/_tracing/_utils.py b/src/agentscope/middleware/_tracing/_utils.pynew file mode 100644index 000000000..b06bbbcb8--- /dev/null+++ b/src/agentscope/middleware/_tracing/_utils.py@@ -0,0 +1,78 @@+# -*- coding: utf-8 -*-+"""Serialize objects to JSON string."""+import datetime+import enum+import inspect+import json+from dataclasses import is_dataclass+from typing import Any++from pydantic import BaseModel++from ...message import Msg+++def _to_serializable(+ obj: Any,+) -> Any:+ """Convert an object to a JSON serializable type.++ Args:+ obj (`Any`):+ The object to be converted to JSON serializable.++ Returns:+ `Any`:+ The converted JSON serializable object+ """++ # Handle primitive types first+ if isinstance(obj, (str, int, bool, float, type(None))):+ res = obj++ elif isinstance(obj, (list, tuple, set, frozenset)):+ res = [_to_serializable(x) for x in obj]++ elif isinstance(obj, dict):+ res = {str(key): _to_serializable(val) for (key, val) in obj.items()}++ elif isinstance(obj, (Msg, BaseModel)) or is_dataclass(obj):+ res = repr(obj)++ elif inspect.isclass(obj) and issubclass(obj, BaseModel):+ res = repr(obj)++ elif isinstance(obj, (datetime.date, datetime.datetime, datetime.time)):+ res = obj.isoformat()++ elif isinstance(obj, datetime.timedelta):+ res = obj.total_seconds()++ elif isinstance(obj, enum.Enum):+ res = _to_serializable(obj.value)++ else:+ res = str(obj)++ return res+++def _serialize_to_str(value: Any) -> str:+ """Serialize input value to JSON string.++ Args:+ value (`Any`):+ The input value++ Returns:+ `str`:+ JSON serialized string of the input value+ """+ try:+ return json.dumps(value, ensure_ascii=False)++ except TypeError:+ return json.dumps(+ _to_serializable(value),+ ensure_ascii=False,+ )diff --git a/tests/tracing_test.py b/tests/tracing_test.pynew file mode 100644index 000000000..762df421a--- /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(inputs=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(inputs=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(inputs=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(inputs=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(inputs=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",+ )