Skip to content

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

refactor(tracing): refactor the tracing module into an agent middleware (#1579)

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