Skip to content

Build and run agents you can see, understand and trust.

feat(tracing): add OpenTelemetry-based tracing as a middleware (#1633)

qbce572c5dcd2fe
diff --git a/src/agentscope/middleware/__init__.py b/src/agentscope/middleware/__init__.py
index 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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 part
diff --git a/src/agentscope/middleware/_tracing/_extractor.py b/src/agentscope/middleware/_tracing/_extractor.py
new file mode 100644
index 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 attributes
diff --git a/src/agentscope/middleware/_tracing/_setup.py b/src/agentscope/middleware/_tracing/_setup.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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",
+ )