Skip to content

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

feat(tracing): support OTel GenAI semantic conventions (#892)

zhijianma56f6299d37c4
diff --git a/pyproject.toml b/pyproject.toml
index 211f0137a..1afd492ea 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -33,6 +33,7 @@ dependencies = [
"opentelemetry-api",
"opentelemetry-sdk",
"opentelemetry-exporter-otlp",
+ "opentelemetry-semantic-conventions",
"python-socketio",
"shortuuid",
"tiktoken",
diff --git a/src/agentscope/tracing/_attributes.py b/src/agentscope/tracing/_attributes.py
index 872404ef8..991481b5a 100644
--- a/src/agentscope/tracing/_attributes.py
+++ b/src/agentscope/tracing/_attributes.py
@@ -1,78 +1,183 @@
# -*- coding: utf-8 -*-
-"""Attributes processor for span attributes."""
-import datetime
-import enum
-import inspect
-import json
-from dataclasses import is_dataclass
-from typing import Any
+"""The tracing types class in agentscope."""
+from opentelemetry.semconv._incubating.attributes import (
+ gen_ai_attributes as GenAIAttributes,
+)
-from pydantic import BaseModel
-from ..message import Msg
+class SpanAttributes:
+ """The span attributes."""
+ # GenAI Common Attributes
+ GEN_AI_CONVERSATION_ID = GenAIAttributes.GEN_AI_CONVERSATION_ID
+ """The gen ai conversation ID."""
-def _to_serializable(
- obj: Any,
-) -> Any:
- """Convert an object to a JSON serializable type.
+ GEN_AI_OPERATION_NAME = GenAIAttributes.GEN_AI_OPERATION_NAME
+ """The gen ai operation name."""
- Args:
- obj (`Any`):
- The object to be converted to JSON serializable.
+ GEN_AI_PROVIDER_NAME = GenAIAttributes.GEN_AI_PROVIDER_NAME
+ """The gen ai provider name."""
- Returns:
- `Any`:
- The converted JSON serializable object
- """
+ # GenAI Request Attributes
+ GEN_AI_REQUEST_MODEL = GenAIAttributes.GEN_AI_REQUEST_MODEL
+ """The gen ai request model."""
- # Handle primitive types first
- if isinstance(obj, (str, int, bool, float, type(None))):
- res = obj
+ GEN_AI_REQUEST_TEMPERATURE = GenAIAttributes.GEN_AI_REQUEST_TEMPERATURE
+ """The gen ai request temperature."""
- elif isinstance(obj, (list, tuple, set, frozenset)):
- res = [_to_serializable(x) for x in obj]
+ GEN_AI_REQUEST_TOP_P = GenAIAttributes.GEN_AI_REQUEST_TOP_P
+ """The gen ai request top_p."""
- elif isinstance(obj, dict):
- res = {str(key): _to_serializable(val) for (key, val) in obj.items()}
+ GEN_AI_REQUEST_TOP_K = GenAIAttributes.GEN_AI_REQUEST_TOP_K
+ """The gen ai request top_k."""
- elif isinstance(obj, (Msg, BaseModel)) or is_dataclass(obj):
- res = repr(obj)
+ GEN_AI_REQUEST_MAX_TOKENS = GenAIAttributes.GEN_AI_REQUEST_MAX_TOKENS
+ """The gen ai request max_tokens."""
- elif inspect.isclass(obj) and issubclass(obj, BaseModel):
- res = repr(obj)
+ GEN_AI_REQUEST_PRESENCE_PENALTY = (
+ GenAIAttributes.GEN_AI_REQUEST_PRESENCE_PENALTY
+ )
+ """The gen ai request presence_penalty."""
- elif isinstance(obj, (datetime.date, datetime.datetime, datetime.time)):
- res = obj.isoformat()
+ GEN_AI_REQUEST_FREQUENCY_PENALTY = (
+ GenAIAttributes.GEN_AI_REQUEST_FREQUENCY_PENALTY
+ )
+ """The gen ai request frequency_penalty."""
- elif isinstance(obj, datetime.timedelta):
- res = obj.total_seconds()
+ GEN_AI_REQUEST_STOP_SEQUENCES = (
+ GenAIAttributes.GEN_AI_REQUEST_STOP_SEQUENCES
+ )
+ """The gen ai request stop_sequences."""
- elif isinstance(obj, enum.Enum):
- res = _to_serializable(obj.value)
+ GEN_AI_REQUEST_SEED = GenAIAttributes.GEN_AI_REQUEST_SEED
+ """The gen ai request seed."""
- else:
- res = str(obj)
+ # GenAI Response Attributes
+ GEN_AI_RESPONSE_ID = GenAIAttributes.GEN_AI_RESPONSE_ID
+ """The gen ai response ID."""
- return res
+ GEN_AI_RESPONSE_FINISH_REASONS = (
+ GenAIAttributes.GEN_AI_RESPONSE_FINISH_REASONS
+ )
+ """The gen ai response finish reasons."""
+ # GenAI Usage Attributes
+ GEN_AI_USAGE_INPUT_TOKENS = GenAIAttributes.GEN_AI_USAGE_INPUT_TOKENS
+ """The gen ai usage input tokens."""
-def _serialize_to_str(value: Any) -> str:
- """Get input attributes
+ GEN_AI_USAGE_OUTPUT_TOKENS = GenAIAttributes.GEN_AI_USAGE_OUTPUT_TOKENS
+ """The gen ai usage output tokens."""
- Args:
- value (`Any`):
- The input value
+ # GenAI Message Attributes
+ GEN_AI_INPUT_MESSAGES = GenAIAttributes.GEN_AI_INPUT_MESSAGES
+ """The gen ai input messages."""
- Returns:
- `str`:
- JSON serialized string of the input value
- """
- try:
- return json.dumps(value, ensure_ascii=False)
+ GEN_AI_OUTPUT_MESSAGES = GenAIAttributes.GEN_AI_OUTPUT_MESSAGES
+ """The gen ai output messages."""
- except TypeError:
- return json.dumps(
- _to_serializable(value),
- ensure_ascii=False,
- )
+ # GenAI Agent Attributes
+ GEN_AI_AGENT_ID = GenAIAttributes.GEN_AI_AGENT_ID
+ """The gen ai agent ID."""
+
+ GEN_AI_AGENT_NAME = GenAIAttributes.GEN_AI_AGENT_NAME
+ """The gen ai agent name."""
+
+ GEN_AI_AGENT_DESCRIPTION = GenAIAttributes.GEN_AI_AGENT_DESCRIPTION
+ """The gen ai agent description."""
+
+ 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."""
+
+ GEN_AI_TOOL_NAME = GenAIAttributes.GEN_AI_TOOL_NAME
+ """The gen ai tool name."""
+
+ GEN_AI_TOOL_DESCRIPTION = GenAIAttributes.GEN_AI_TOOL_DESCRIPTION
+ """The gen ai tool description."""
+
+ GEN_AI_TOOL_CALL_ARGUMENTS = "gen_ai.tool.call.arguments"
+ """The gen ai tool call arguments."""
+
+ GEN_AI_TOOL_CALL_RESULT = "gen_ai.tool.call.result"
+ """The gen ai tool call result."""
+
+ GEN_AI_TOOL_DEFINITIONS = "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 Extended Attributes
+ AGENTSCOPE_FORMAT_TARGET = "agentscope.format.target"
+ """The agentscope format target."""
+
+ AGENTSCOPE_FORMAT_COUNT = "agentscope.format.count"
+ """The count of formatted messages in the result."""
+
+ AGENTSCOPE_FUNCTION_NAME = "agentscope.function.name"
+ """The agentscope function name."""
+
+ AGENTSCOPE_FUNCTION_INPUT = "agentscope.function.input"
+ """The agentscope function input."""
+
+ AGENTSCOPE_FUNCTION_OUTPUT = "agentscope.function.output"
+ """The agentscope function output."""
+
+
+class OperationNameValues:
+ """The operation name values."""
+
+ FORMATTER = "format"
+ """The formatter operation name."""
+
+ INVOKE_GENERIC_FUNCTION = "invoke_generic_function"
+ """The invoke generic function operation name."""
+
+ CHAT = GenAIAttributes.GenAiOperationNameValues.CHAT.value
+ """The chat operation name."""
+
+ INVOKE_AGENT = GenAIAttributes.GenAiOperationNameValues.INVOKE_AGENT.value
+ """The invoke agent operation name."""
+
+ EXECUTE_TOOL = GenAIAttributes.GenAiOperationNameValues.EXECUTE_TOOL.value
+ """The execute tool operation name."""
+
+ EMBEDDINGS = GenAIAttributes.GenAiOperationNameValues.EMBEDDINGS.value
+ """The embeddings operation name."""
+
+
+class ProviderNameValues:
+ """The provider name values."""
+
+ DASHSCOPE = "dashscope"
+ """The dashscope provider name."""
+
+ OLLAMA = "ollama"
+ """The ollama provider name."""
+
+ DEEPSEEK = GenAIAttributes.GenAiProviderNameValues.DEEPSEEK.value
+ """The deepseek provider name."""
+
+ OPENAI = GenAIAttributes.GenAiProviderNameValues.OPENAI.value
+ """The openai provider name."""
+
+ ANTHROPIC = GenAIAttributes.GenAiProviderNameValues.ANTHROPIC.value
+ """The anthropic provider name."""
+
+ GCP_GEMINI = GenAIAttributes.GenAiProviderNameValues.GCP_GEMINI.value
+ """The gcp gemini provider name."""
+
+ MOONSHOT = "moonshot"
+ """The moonshot provider name."""
+
+ AZURE_AI_OPENAI = (
+ GenAIAttributes.GenAiProviderNameValues.AZURE_AI_OPENAI.value
+ )
+ """The azure openai provider name."""
+
+ AWS_BEDROCK = GenAIAttributes.GenAiProviderNameValues.AWS_BEDROCK.value
+ """The aws bedrock provider name."""
diff --git a/src/agentscope/tracing/_converter.py b/src/agentscope/tracing/_converter.py
new file mode 100644
index 000000000..8f7291ffe
--- /dev/null
+++ b/src/agentscope/tracing/_converter.py
@@ -0,0 +1,125 @@
+# -*- 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/_extractor.py b/src/agentscope/tracing/_extractor.py
new file mode 100644
index 000000000..64c85fd2d
--- /dev/null
+++ b/src/agentscope/tracing/_extractor.py
@@ -0,0 +1,888 @@
+# -*- coding: utf-8 -*-
+"""Extract attributes from AgentScope components for OpenTelemetry tracing."""
+import inspect
+from typing import Any, Dict, Tuple, TYPE_CHECKING
+
+from .. import _config
+from ..embedding import EmbeddingModelBase
+from ..message import Msg, ToolUseBlock
+from ..model import ChatModelBase
+
+from ._attributes import (
+ SpanAttributes,
+ OperationNameValues,
+ ProviderNameValues,
+)
+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"
+
+_CLASS_NAME_MAP = {
+ "dashscope": ProviderNameValues.DASHSCOPE,
+ "openai": ProviderNameValues.OPENAI,
+ "anthropic": ProviderNameValues.ANTHROPIC,
+ "gemini": ProviderNameValues.GCP_GEMINI,
+ "ollama": ProviderNameValues.OLLAMA,
+ "deepseek": ProviderNameValues.DEEPSEEK,
+ "trinity": ProviderNameValues.OPENAI,
+}
+
+# Map base URL fragments to provider names for OpenAI-compatible APIs
+_BASE_URL_PROVIDER_MAP = [
+ ("api.openai.com", ProviderNameValues.OPENAI),
+ ("dashscope", ProviderNameValues.DASHSCOPE),
+ ("deepseek", ProviderNameValues.DEEPSEEK),
+ ("moonshot", ProviderNameValues.MOONSHOT),
+ ("generativelanguage.googleapis.com", ProviderNameValues.GCP_GEMINI),
+ ("openai.azure.com", ProviderNameValues.AZURE_AI_OPENAI),
+ ("amazonaws.com", ProviderNameValues.AWS_BEDROCK),
+]
+
+
+def _get_common_attributes() -> Dict[str, str]:
+ """Get common attributes for all spans.
+
+ Returns:
+ `Dict[str, str]`:
+ Common span attributes including conversation ID
+ """
+ return {
+ SpanAttributes.GEN_AI_CONVERSATION_ID: _serialize_to_str(
+ _config.run_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:
+ """Get provider name from ChatModelBase instance.
+
+ Maps ChatModelBase class names to provider names, with special handling
+ for OpenAI-compatible APIs that may use different base URLs.
+ This follows the implementation pattern from agentscope-java PR #73.
+
+ Args:
+ instance (`ChatModelBase`):
+ The chat model instance to get the provider name for.
+
+ Returns:
+ `str`:
+ Provider name (e.g., "openai", "dashscope", "anthropic")
+ """
+ classname = instance.__class__.__name__
+
+ # Special handling for OpenAIChatModel - check base_url
+ if classname == "OpenAIChatModel":
+ # Try to get base_url from the client
+ base_url = None
+ if hasattr(instance, "client") and hasattr(
+ instance.client,
+ "base_url",
+ ):
+ base_url = str(instance.client.base_url)
+
+ # If base_url is None or empty, return default OpenAI
+ if not base_url:
+ return ProviderNameValues.OPENAI
+
+ # Check base_url fragments to identify provider
+ for url_fragment, provider_name in _BASE_URL_PROVIDER_MAP:
+ if url_fragment in base_url:
+ return provider_name
+
+ # If no match found, return openai as default
+ return ProviderNameValues.OPENAI
+
+ # For other model types, use direct mapping
+ prefix_key = (
+ classname.removesuffix("ChatModel")
+ .removesuffix("MultiAgentModel")
+ .lower()
+ )
+ return _CLASS_NAME_MAP.get(prefix_key, "unknown")
+
+
+def _get_tool_definitions(
+ tools: list[dict[str, Any]] | None,
+ tool_choice: str | None,
+) -> str | None:
+ """Extract and serialize tool definitions for tracing.
+
+ Converts AgentScope/OpenAI nested tool format to OpenTelemetry GenAI
+ flat format for tracing.
+
+ Args:
+ tools (`list[dict[str, Any]] | None`, optional):
+ List of tool definitions in OpenAI format with nested
+ structure: ``[{"type": "function", "function": {...}}]``
+ tool_choice (`str | None`, optional):
+ Tool choice mode. Can be "auto", "none", "any", "required",
+ or a specific tool name. If "none", returns None to indicate
+ tools should not be traced.
+
+ Returns:
+ `str | None`:
+ Serialized tool definitions in flat format:
+ ``[{"type": "function", "name": ..., "parameters": ...}]``
+ or None if tools should not be traced (e.g., tools is None/empty
+ or tool_choice is "none").
+ """
+ # No tools provided
+ if tools is None or not isinstance(tools, list) or len(tools) == 0:
+ return None
+
+ # Tool choice is explicitly "none" (model should not use tools)
+ if tool_choice == "none":
+ return None
+
+ try:
+ # Convert nested format to flat format for OpenTelemetry GenAI
+ # TODO: Currently only supports "function" type tools. If other tool
+ # types are added in the future (e.g., "retrieval", "code_interpreter",
+ # "browser"), this conversion logic needs to be updated to handle them.
+ flat_tools = []
+ for tool in tools:
+ if not isinstance(tool, dict) or "function" not in tool:
+ continue
+
+ func_def = tool["function"]
+ flat_tool = {
+ "type": tool.get("type", "function"),
+ "name": func_def.get("name"),
+ "description": func_def.get("description"),
+ "parameters": func_def.get("parameters"),
+ }
+ # Remove None values
+ flat_tool = {k: v for k, v in flat_tool.items() if v is not None}
+ flat_tools.append(flat_tool)
+
+ if flat_tools:
+ return _serialize_to_str(flat_tools)
+ return None
+
+ except Exception:
+ return None
+
+
+def _get_llm_request_attributes(
+ instance: ChatModelBase,
+ args: Tuple[Any, ...],
+ kwargs: Dict[str, Any],
+) -> Dict[str, Any]:
+ """Get LLM request attributes for OpenTelemetry tracing.
+
+ Extracts request parameters from LLM model calls into GenAI attributes.
+
+ Args:
+ instance (`ChatModelBase`):
+ The chat model instance making the request.
+ 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,
+ frequency_penalty, stop_sequences, seed, tools, and tool_choice.
+
+ Returns:
+ `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.
+ """
+
+ attributes = {
+ # required attributes
+ SpanAttributes.GEN_AI_OPERATION_NAME: OperationNameValues.CHAT,
+ SpanAttributes.GEN_AI_PROVIDER_NAME: _get_provider_name(instance),
+ # conditionally required attributes
+ SpanAttributes.GEN_AI_REQUEST_MODEL: getattr(
+ instance,
+ "model_name",
+ "unknown_model",
+ ),
+ # recommended attributes
+ SpanAttributes.GEN_AI_REQUEST_TEMPERATURE: kwargs.get("temperature"),
+ SpanAttributes.GEN_AI_REQUEST_TOP_P: kwargs.get("p")
+ or kwargs.get("top_p"),
+ SpanAttributes.GEN_AI_REQUEST_TOP_K: kwargs.get("top_k"),
+ SpanAttributes.GEN_AI_REQUEST_MAX_TOKENS: kwargs.get("max_tokens"),
+ SpanAttributes.GEN_AI_REQUEST_PRESENCE_PENALTY: kwargs.get(
+ "presence_penalty",
+ ),
+ SpanAttributes.GEN_AI_REQUEST_FREQUENCY_PENALTY: kwargs.get(
+ "frequency_penalty",
+ ),
+ SpanAttributes.GEN_AI_REQUEST_STOP_SEQUENCES: kwargs.get(
+ "stop_sequences",
+ ),
+ SpanAttributes.GEN_AI_REQUEST_SEED: kwargs.get("seed"),
+ # custom attributes
+ SpanAttributes.AGENTSCOPE_FUNCTION_INPUT: _serialize_to_str(
+ {
+ "args": args,
+ "kwargs": kwargs,
+ },
+ ),
+ }
+
+ # Extract tool definitions if provided
+ tool_definitions = _get_tool_definitions(
+ tools=kwargs.get("tools"),
+ tool_choice=kwargs.get("tool_choice"),
+ )
+ if tool_definitions:
+ attributes[SpanAttributes.GEN_AI_TOOL_DEFINITIONS] = tool_definitions
+
+ return {k: v for k, v in attributes.items() if v is not None}
+
+
+def _get_llm_span_name(attributes: Dict[str, str]) -> str:
+ """Generate span name for LLM operations.
+
+ Args:
+ attributes (`Dict[str, str]`):
+ LLM request attributes dictionary containing operation name and
+ model name.
+
+ Returns:
+ `str`:
+ Formatted span name in the format "{operation} {model}",
+ e.g., "chat gpt-4" or "chat qwen-plus".
+ """
+ return (
+ f"{attributes[SpanAttributes.GEN_AI_OPERATION_NAME]} "
+ f"{attributes[SpanAttributes.GEN_AI_REQUEST_MODEL]}"
+ )
+
+
+def _get_llm_output_messages(
+ chat_response: Any,
+) -> list[dict[str, Any]]:
+ """Extract and format LLM output messages for tracing.
+
+ Converts ChatResponse objects to standardized message format compatible
+ with OpenTelemetry GenAI specification.
+
+ Args:
+ chat_response (`Any`):
+ Chat response object with content blocks. Should be a ChatResponse
+ instance containing content blocks (text, tool_use, etc.).
+
+ Returns:
+ `list[dict[str, Any]]`:
+ List containing a single formatted message dictionary with role,
+ parts, and finish_reason. Returns the original response if it's
+ not a ChatResponse instance, or an error message format if
+ conversion fails.
+ """
+ try:
+ from agentscope.model import ChatResponse
+
+ if not isinstance(chat_response, ChatResponse):
+ return chat_response
+
+ parts = []
+ finish_reason = "stop" # Default finish reason
+
+ for block in chat_response.content:
+ part = _convert_block_to_part(block)
+ if part:
+ parts.append(part)
+
+ output_message = {
+ "role": "assistant",
+ "parts": parts,
+ "finish_reason": finish_reason,
+ }
+
+ return [output_message]
+
+ except Exception:
+ return [
+ {
+ "role": "assistant",
+ "parts": [
+ {
+ "type": "text",
+ "content": "<error processing response>",
+ },
+ ],
+ "finish_reason": "error",
+ },
+ ]
+
+
+def _get_llm_response_attributes(
+ chat_response: Any,
+) -> Dict[str, Any]:
+ """Get LLM response attributes for OpenTelemetry tracing.
+
+ Extracts response metadata and formats into GenAI attributes.
+
+ Args:
+ chat_response (`Any`):
+ Chat response object with data and usage info. Should have
+ attributes like id, usage (with input_tokens and output_tokens),
+ and content blocks.
+
+ Returns:
+ `Dict[str, Any]`:
+ OpenTelemetry GenAI response attributes including response ID,
+ finish reasons, token usage (input/output tokens), output messages,
+ and custom AgentScope function output.
+ """
+ attributes = {
+ SpanAttributes.GEN_AI_RESPONSE_ID: getattr(
+ chat_response,
+ "id",
+ "unknown_id",
+ ),
+ # FIXME: finish reason should be capture in chat response
+ SpanAttributes.GEN_AI_RESPONSE_FINISH_REASONS: '["stop"]',
+ }
+ if hasattr(chat_response, "usage") and chat_response.usage:
+ attributes[
+ SpanAttributes.GEN_AI_USAGE_INPUT_TOKENS
+ ] = chat_response.usage.input_tokens
+ attributes[
+ SpanAttributes.GEN_AI_USAGE_OUTPUT_TOKENS
+ ] = chat_response.usage.output_tokens
+
+ output_messages = _get_llm_output_messages(chat_response)
+ if output_messages:
+ attributes[SpanAttributes.GEN_AI_OUTPUT_MESSAGES] = _serialize_to_str(
+ output_messages,
+ )
+
+ attributes[SpanAttributes.AGENTSCOPE_FUNCTION_OUTPUT] = _serialize_to_str(
+ chat_response,
+ )
+ return attributes
+
+
+def _get_agent_messages(
+ msg: Msg,
+) -> dict[str, Any]:
+ """Convert AgentScope message to standardized parts format.
+
+ Transforms Msg objects into OpenTelemetry GenAI format.
+
+ Args:
+ msg (`Msg`):
+ AgentScope message object with content blocks. The message should
+ have a role, content blocks (text, image, tool_use, etc.), and
+ optionally a name.
+
+ Returns:
+ `dict[str, Any]`:
+ Formatted message dictionary with role, parts (converted content
+ blocks), name, and finish_reason. Returns a fallback text format
+ if conversion fails.
+ """
+ try:
+ parts = []
+ for block in msg.get_content_blocks():
+ part = _convert_block_to_part(block)
+ if part:
+ parts.append(part)
+
+ formatted_msg = {
+ "role": msg.role,
+ "parts": parts,
+ "name": msg.name,
+ "finish_reason": "stop",
+ }
+
+ return formatted_msg
+
+ except Exception:
+ return {
+ "role": msg.role,
+ "parts": [
+ {
+ "type": "text",
+ "content": str(msg.content) if msg.content else "",
+ },
+ ],
+ "name": msg.name,
+ "finish_reason": "stop",
+ }
+
+
+def _get_agent_request_attributes(
+ instance: "AgentBase",
+ args: Tuple[Any, ...],
+ kwargs: Dict[str, Any],
+) -> Dict[str, str]:
+ """Get agent request attributes for OpenTelemetry tracing.
+
+ Extracts agent metadata and input data into GenAI attributes.
+
+ Args:
+ instance (`AgentBase`):
+ 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.
+ """
+ attributes = {
+ SpanAttributes.GEN_AI_OPERATION_NAME: (
+ OperationNameValues.INVOKE_AGENT
+ ),
+ SpanAttributes.GEN_AI_AGENT_ID: getattr(instance, "id", "unknown"),
+ SpanAttributes.GEN_AI_AGENT_NAME: getattr(
+ instance,
+ "name",
+ "unknown_agent",
+ ),
+ SpanAttributes.GEN_AI_AGENT_DESCRIPTION: inspect.getdoc(
+ instance.__class__,
+ )
+ or "No description available",
+ }
+
+ msg = None
+ if args and len(args) > 0:
+ msg = args[0]
+ elif "msg" in kwargs:
+ msg = kwargs["msg"]
+ if msg:
+ input_messages = _get_agent_messages(msg)
+ attributes[SpanAttributes.GEN_AI_INPUT_MESSAGES] = _serialize_to_str(
+ input_messages,
+ )
+
+ # custom attributes
+ attributes[SpanAttributes.AGENTSCOPE_FUNCTION_INPUT] = _serialize_to_str(
+ {
+ "args": args,
+ "kwargs": kwargs,
+ },
+ )
+ return attributes
+
+
+def _get_agent_span_name(attributes: Dict[str, str]) -> str:
+ """Generate span name for agent operations.
+
+ Args:
+ attributes (`Dict[str, str]`):
+ Agent request attributes dictionary containing operation name and
+ agent name.
+
+ Returns:
+ `str`:
+ Formatted span name in the format "{operation} {agent_name}",
+ e.g., "invoke_agent MyAgent".
+ """
+ return (
+ f"{attributes[SpanAttributes.GEN_AI_OPERATION_NAME]} "
+ f"{attributes[SpanAttributes.GEN_AI_AGENT_NAME]}"
+ )
+
+
+def _get_agent_response_attributes(
+ agent_response: Any,
+) -> Dict[str, str]:
+ """Get agent response attributes for OpenTelemetry tracing.
+
+ Args:
+ agent_response (`Any`):
+ Response object returned by agent. Should be a Msg object with
+ content blocks.
+
+ Returns:
+ `Dict[str, str]`:
+ OpenTelemetry GenAI response attributes including output messages
+ and custom AgentScope function output.
+ """
+ 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
+
+
+def _get_tool_request_attributes(
+ instance: "Toolkit",
+ tool_call: ToolUseBlock,
+) -> Dict[str, str]:
+ """Get tool request attributes for OpenTelemetry tracing.
+
+ Extracts tool execution metadata into GenAI attributes.
+
+ Args:
+ instance (`Toolkit`):
+ Toolkit instance with tool definitions. Used to extract tool
+ description from the tool's JSON schema.
+ tool_call (`ToolUseBlock`):
+ Tool use block with call information including id, name, and input
+ arguments.
+
+ Returns:
+ `Dict[str, str]`:
+ OpenTelemetry GenAI tool attributes including operation name, tool
+ call ID, tool name, tool description (if available), tool call
+ arguments, and custom AgentScope function input.
+ """
+ attributes = {
+ SpanAttributes.GEN_AI_OPERATION_NAME: (
+ OperationNameValues.EXECUTE_TOOL
+ ),
+ }
+
+ if tool_call:
+ tool_name = tool_call.get("name")
+ attributes[SpanAttributes.GEN_AI_TOOL_CALL_ID] = tool_call.get("id")
+ attributes[SpanAttributes.GEN_AI_TOOL_NAME] = tool_name
+ attributes[
+ SpanAttributes.GEN_AI_TOOL_CALL_ARGUMENTS
+ ] = _serialize_to_str(tool_call.get("input"))
+
+ if tool_name:
+ if tool := getattr(instance, "tools", {}).get(tool_name):
+ if tool_func := getattr(tool, "json_schema", {}).get(
+ "function",
+ {},
+ ):
+ attributes[
+ SpanAttributes.GEN_AI_TOOL_DESCRIPTION
+ ] = tool_func.get("description", "unknown_description")
+
+ # custom attributes
+ attributes[
+ SpanAttributes.AGENTSCOPE_FUNCTION_INPUT
+ ] = _serialize_to_str(
+ {
+ "tool_call": tool_call,
+ },
+ )
+ return attributes
+
+
+def _get_tool_span_name(attributes: Dict[str, str]) -> str:
+ """Generate span name for tool operations.
+
+ Args:
+ attributes (`Dict[str, str]`):
+ Tool request attributes dictionary containing operation name and
+ tool name.
+
+ Returns:
+ `str`:
+ Formatted span name in the format "{operation} {tool_name}",
+ e.g., "execute_tool search".
+ """
+ return (
+ f"{attributes[SpanAttributes.GEN_AI_OPERATION_NAME]} "
+ f"{attributes[SpanAttributes.GEN_AI_TOOL_NAME]}"
+ )
+
+
+def _get_tool_response_attributes(
+ tool_response: Any,
+) -> Dict[str, str]:
+ """Get tool response attributes for OpenTelemetry tracing.
+
+ Args:
+ tool_response (`Any`):
+ Response object from tool execution. Can be any serializable object
+ returned by the tool function.
+
+ Returns:
+ `Dict[str, str]`:
+ OpenTelemetry GenAI response attributes including tool call result
+ and custom AgentScope function output.
+ """
+ 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/tracing/_setup.py
index be815a930..aef364c47 100644
--- a/src/agentscope/tracing/_setup.py
+++ b/src/agentscope/tracing/_setup.py
@@ -1,5 +1,11 @@
# -*- coding: utf-8 -*-
"""The tracing interface class in agentscope."""
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+ from opentelemetry.trace import Tracer
+else:
+ Tracer = "Tracer"
def setup_tracing(endpoint: str) -> None:
@@ -10,15 +16,26 @@ def setup_tracing(endpoint: str) -> None:
The endpoint URL for the tracing exporter.
"""
# Lazy import
+ from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
OTLPSpanExporter,
)
- from opentelemetry import trace
tracer_provider = TracerProvider()
exporter = OTLPSpanExporter(endpoint=endpoint)
span_processor = BatchSpanProcessor(exporter)
tracer_provider.add_span_processor(span_processor)
trace.set_tracer_provider(tracer_provider)
+
+
+def _get_tracer() -> Tracer:
+ """Get the tracer
+ Returns:
+ `Tracer`: The tracer with the name "agentscope" and version.
+ """
+ from opentelemetry import trace
+ from .._version import __version__
+
+ return trace.get_tracer("agentscope", __version__)
diff --git a/src/agentscope/tracing/_trace.py b/src/agentscope/tracing/_trace.py
index a44a10e29..9aaf08656 100644
--- a/src/agentscope/tracing/_trace.py
+++ b/src/agentscope/tracing/_trace.py
@@ -15,35 +15,52 @@ from typing import (
import aioitertools
-from ._attributes import _serialize_to_str
from .. import _config
-from ..embedding._embedding_base import EmbeddingModelBase
-from ..model._model_base import ChatModelBase
+from ..embedding import EmbeddingModelBase, EmbeddingResponse
from .._logging import logger
-from ._types import SpanKind, SpanAttributes
+from ..message import Msg, ToolUseBlock
+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,
)
- from ..message import (
- Msg,
- ToolUseBlock,
- )
- from ..embedding import EmbeddingResponse
- from ..model import ChatResponse
- from opentelemetry.trace import Span
+
else:
+ AgentBase = "AgentBase"
+ FormatterBase = "FormatterBase"
+ Span = "Span"
Toolkit = "Toolkit"
ToolResponse = "ToolResponse"
- Msg = "Msg"
- ToolUseBlock = "ToolUseBlock"
- EmbeddingResponse = "EmbeddingResponse"
- ChatResponse = "ChatResponse"
- Span = "Span"
T = TypeVar("T")
@@ -60,14 +77,39 @@ def _check_tracing_enabled() -> bool:
return _config.trace_enabled
+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."""
- import opentelemetry
-
has_error = False
try:
@@ -77,20 +119,16 @@ def _trace_sync_generator_wrapper(
yield chunk
except Exception as e:
has_error = True
- span.set_status(opentelemetry.trace.StatusCode.ERROR, str(e))
- span.record_exception(e)
+ _set_span_error_status(span, e)
raise e from None
finally:
if not has_error:
# Set the last chunk as output
span.set_attributes(
- {
- SpanAttributes.OUTPUT: _serialize_to_str(last_chunk),
- },
+ _get_generic_function_response_attributes(last_chunk),
)
- span.set_status(opentelemetry.trace.StatusCode.OK)
- span.end()
+ _set_span_success_status(span)
async def _trace_async_generator_wrapper(
@@ -109,8 +147,6 @@ async def _trace_async_generator_wrapper(
`T`:
The output of the async generator.
"""
- import opentelemetry
-
has_error = False
try:
@@ -121,30 +157,47 @@ async def _trace_async_generator_wrapper(
except Exception as e:
has_error = True
- span.set_status(opentelemetry.trace.StatusCode.ERROR, str(e))
- span.record_exception(e)
+ _set_span_error_status(span, e)
raise e from None
finally:
if not has_error:
# Set the last chunk as output
- span.set_attributes(
- {
- SpanAttributes.OUTPUT: _serialize_to_str(last_chunk),
- },
- )
- span.set_status(opentelemetry.trace.StatusCode.OK)
- span.end()
+
+ 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,
+ name: str | None = None,
) -> Callable:
"""A generic tracing decorator for synchronous and asynchronous functions.
Args:
- name (`str`):
- The name of the span to be created.
+ 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`:
@@ -179,27 +232,19 @@ def trace(
if not _check_tracing_enabled():
return await func(*args, **kwargs)
- import opentelemetry
-
- tracer = opentelemetry.trace.get_tracer(__name__)
+ tracer = _get_tracer()
- attributes = {
- SpanAttributes.SPAN_KIND: SpanKind.COMMON,
- SpanAttributes.PROJECT_RUN_ID: _serialize_to_str(
- _config.run_id,
- ),
- SpanAttributes.INPUT: _serialize_to_str(
- {
- "args": args,
- "kwargs": kwargs,
- },
- ),
- SpanAttributes.META: _serialize_to_str({}),
- }
+ 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=name,
- attributes=attributes,
+ name=span_name,
+ attributes=request_attributes,
end_on_exit=False,
) as span:
try:
@@ -213,19 +258,13 @@ def trace(
# non-generator result
span.set_attributes(
- {SpanAttributes.OUTPUT: _serialize_to_str(res)},
+ _get_generic_function_response_attributes(res),
)
- span.set_status(opentelemetry.trace.StatusCode.OK)
- span.end()
+ _set_span_success_status(span)
return res
except Exception as e:
- span.set_status(
- opentelemetry.trace.StatusCode.ERROR,
- str(e),
- )
- span.record_exception(e)
- span.end()
+ _set_span_error_status(span, e)
raise e from None
return wrapper
@@ -240,27 +279,19 @@ def trace(
if not _check_tracing_enabled():
return func(*args, **kwargs)
- import opentelemetry
+ tracer = _get_tracer()
- tracer = opentelemetry.trace.get_tracer(__name__)
-
- attributes = {
- SpanAttributes.SPAN_KIND: SpanKind.COMMON,
- SpanAttributes.PROJECT_RUN_ID: _serialize_to_str(
- _config.run_id,
- ),
- SpanAttributes.INPUT: _serialize_to_str(
- {
- "args": args,
- "kwargs": kwargs,
- },
- ),
- SpanAttributes.META: _serialize_to_str({}),
- }
+ 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=name,
- attributes=attributes,
+ name=span_name,
+ attributes=request_attributes,
end_on_exit=False,
) as span:
try:
@@ -274,19 +305,13 @@ def trace(
# non-generator result
span.set_attributes(
- {SpanAttributes.OUTPUT: _serialize_to_str(res)},
+ _get_generic_function_response_attributes(res),
)
- span.set_status(opentelemetry.trace.StatusCode.OK)
- span.end()
+ _set_span_success_status(span)
return res
except Exception as e:
- span.set_status(
- opentelemetry.trace.StatusCode.ERROR,
- str(e),
- )
- span.record_exception(e)
- span.end()
+ _set_span_error_status(span, e)
raise e from None
return sync_wrapper
@@ -312,29 +337,18 @@ def trace_toolkit(
if not _check_tracing_enabled():
return await func(self, tool_call=tool_call)
- import opentelemetry
-
- tracer = opentelemetry.trace.get_tracer(__name__)
-
- # Prepare the attributes for the span
- attributes = {
- SpanAttributes.SPAN_KIND: _serialize_to_str(SpanKind.TOOL),
- SpanAttributes.PROJECT_RUN_ID: _serialize_to_str(_config.run_id),
- SpanAttributes.INPUT: _serialize_to_str(
- {
- "tool_call": tool_call,
- },
- ),
- SpanAttributes.META: _serialize_to_str(
- {
- **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(
- f"{func.__name__}",
- attributes=attributes,
+ name=span_name,
+ attributes={
+ **request_attributes,
+ **_get_common_attributes(),
+ SpanAttributes.AGENTSCOPE_FUNCTION_NAME: function_name,
+ },
end_on_exit=False,
) as span:
try:
@@ -345,11 +359,7 @@ def trace_toolkit(
return _trace_async_generator_wrapper(res, span)
except Exception as e:
- span.set_status(
- opentelemetry.trace.StatusCode.ERROR,
- str(e),
- )
- span.record_exception(e)
+ _set_span_error_status(span, e)
span.end()
raise e from None
@@ -392,32 +402,21 @@ def trace_reply(
)
return await func(self, *args, **kwargs)
- import opentelemetry
-
- tracer = opentelemetry.trace.get_tracer(__name__)
+ tracer = _get_tracer()
# Prepare the attributes for the span
- agent_name = self.name if hasattr(self, "name") else None
- attributes = {
- SpanAttributes.SPAN_KIND: _serialize_to_str(SpanKind.AGENT),
- SpanAttributes.PROJECT_RUN_ID: _serialize_to_str(_config.run_id),
- SpanAttributes.INPUT: _serialize_to_str(
- {
- "args": args,
- "kwargs": kwargs,
- },
- ),
- SpanAttributes.META: _serialize_to_str(
- {
- "id": self.id,
- "name": agent_name,
- },
- ),
- }
+ 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(
- f"{self.__class__.__name__}.{func.__name__}",
- attributes=attributes,
+ name=span_name,
+ attributes={
+ **request_attributes,
+ **_get_common_attributes(),
+ SpanAttributes.AGENTSCOPE_FUNCTION_NAME: function_name,
+ },
end_on_exit=False,
) as span:
try:
@@ -425,20 +424,12 @@ def trace_reply(
res = await func(self, *args, **kwargs)
# Set the output attribute
- span.set_attributes(
- {SpanAttributes.OUTPUT: _serialize_to_str(res)},
- )
- span.set_status(opentelemetry.trace.StatusCode.OK)
- span.end()
+ span.set_attributes(_get_agent_response_attributes(res))
+ _set_span_success_status(span)
return res
except Exception as e:
- span.set_status(
- opentelemetry.trace.StatusCode.ERROR,
- str(e),
- )
- span.record_exception(e)
- span.end()
+ _set_span_error_status(span, e)
raise e from None
return wrapper
@@ -468,30 +459,24 @@ def trace_embedding(
)
return await func(self, *args, **kwargs)
- import opentelemetry
-
- tracer = opentelemetry.trace.get_tracer(__name__)
+ tracer = _get_tracer()
# Prepare the attributes for the span
- attributes = {
- SpanAttributes.SPAN_KIND: _serialize_to_str(SpanKind.EMBEDDING),
- SpanAttributes.PROJECT_RUN_ID: _serialize_to_str(_config.run_id),
- SpanAttributes.INPUT: _serialize_to_str(
- {
- "args": args,
- "kwargs": kwargs,
- },
- ),
- SpanAttributes.META: _serialize_to_str(
- {
- "model_name": self.model_name,
- },
- ),
- }
+ 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(
- f"{self.__class__.__name__}.{func.__name__}",
- attributes=attributes,
+ name=span_name,
+ attributes={
+ **request_attributes,
+ **_get_common_attributes(),
+ SpanAttributes.AGENTSCOPE_FUNCTION_NAME: function_name,
+ },
end_on_exit=False,
) as span:
try:
@@ -499,20 +484,12 @@ def trace_embedding(
res = await func(self, *args, **kwargs)
# Set the output attribute
- span.set_attributes(
- {SpanAttributes.OUTPUT: _serialize_to_str(res)},
- )
- span.set_status(opentelemetry.trace.StatusCode.OK)
- span.end()
+ span.set_attributes(_get_embedding_response_attributes(res))
+ _set_span_success_status(span)
return res
except Exception as e:
- span.set_status(
- opentelemetry.trace.StatusCode.ERROR,
- str(e),
- )
- span.record_exception(e)
- span.end()
+ _set_span_error_status(span, e)
raise e from None
return wrapper
@@ -554,26 +531,23 @@ def trace_format(
)
return await func(self, *args, **kwargs)
- import opentelemetry
-
- tracer = opentelemetry.trace.get_tracer(__name__)
+ tracer = _get_tracer()
# Prepare the attributes for the span
- attributes = {
- SpanAttributes.SPAN_KIND: _serialize_to_str(SpanKind.FORMATTER),
- SpanAttributes.PROJECT_RUN_ID: _serialize_to_str(_config.run_id),
- SpanAttributes.INPUT: _serialize_to_str(
- {
- "args": args,
- "kwargs": kwargs,
- },
- ),
- SpanAttributes.META: _serialize_to_str({}),
- }
-
+ 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(
- f"{self.__class__.__name__}.{func.__name__}",
- attributes=attributes,
+ name=span_name,
+ attributes={
+ **request_attributes,
+ **_get_common_attributes(),
+ SpanAttributes.AGENTSCOPE_FUNCTION_NAME: function_name,
+ },
end_on_exit=False,
) as span:
try:
@@ -581,20 +555,12 @@ def trace_format(
res = await func(self, *args, **kwargs)
# Set the output attribute
- span.set_attributes(
- {SpanAttributes.OUTPUT: _serialize_to_str(res)},
- )
- span.set_status(opentelemetry.trace.StatusCode.OK)
- span.end()
+ span.set_attributes(_get_formatter_response_attributes(res))
+ _set_span_success_status(span)
return res
except Exception as e:
- span.set_status(
- opentelemetry.trace.StatusCode.ERROR,
- str(e),
- )
- span.record_exception(e)
- span.end()
+ _set_span_error_status(span, e)
raise e from None
return wrapper
@@ -646,32 +612,20 @@ def trace_llm(
)
return await func(self, *args, **kwargs)
- import opentelemetry
-
- tracer = opentelemetry.trace.get_tracer(__name__)
+ tracer = _get_tracer()
# Prepare the attributes for the span
- attributes = {
- SpanAttributes.SPAN_KIND: _serialize_to_str(SpanKind.LLM),
- SpanAttributes.PROJECT_RUN_ID: _serialize_to_str(_config.run_id),
- SpanAttributes.INPUT: _serialize_to_str(
- {
- "args": args,
- "kwargs": kwargs,
- },
- ),
- SpanAttributes.META: _serialize_to_str(
- {
- "model_name": self.model_name,
- "stream": self.stream,
- },
- ),
- }
-
+ 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(
- f"{self.__class__.__name__}.__call__",
- attributes=attributes,
+ name=span_name,
+ attributes={
+ **request_attributes,
+ **_get_common_attributes(),
+ SpanAttributes.AGENTSCOPE_FUNCTION_NAME: function_name,
+ },
end_on_exit=False,
) as span:
try:
@@ -683,20 +637,12 @@ def trace_llm(
return _trace_async_generator_wrapper(res, span)
# non-generator result
- span.set_attributes(
- {SpanAttributes.OUTPUT: _serialize_to_str(res)},
- )
- span.set_status(opentelemetry.trace.StatusCode.OK)
- span.end()
+ span.set_attributes(_get_llm_response_attributes(res))
+ _set_span_success_status(span)
return res
except Exception as e:
- span.set_status(
- opentelemetry.trace.StatusCode.ERROR,
- str(e),
- )
- span.record_exception(e)
- span.end()
+ _set_span_error_status(span, e)
raise e from None
return async_wrapper
diff --git a/src/agentscope/tracing/_types.py b/src/agentscope/tracing/_types.py
deleted file mode 100644
index e67e312f1..000000000
--- a/src/agentscope/tracing/_types.py
+++ /dev/null
@@ -1,28 +0,0 @@
-# -*- coding: utf-8 -*-
-"""The tracing types class in agentscope."""
-from enum import Enum
-
-from opentelemetry import trace
-
-StatusCode = trace.StatusCode
-
-
-class SpanKind(str, Enum):
- """The span kind."""
-
- AGENT = "AGENT"
- TOOL = "TOOL"
- LLM = "LLM"
- EMBEDDING = "EMBEDDING"
- FORMATTER = "FORMATTER"
- COMMON = "COMMON"
-
-
-class SpanAttributes:
- """The span attributes."""
-
- SPAN_KIND = "span.kind"
- OUTPUT = "output"
- INPUT = "input"
- META = "metadata"
- PROJECT_RUN_ID = "project.run_id"
diff --git a/src/agentscope/tracing/_utils.py b/src/agentscope/tracing/_utils.py
new file mode 100644
index 000000000..35f06ea65
--- /dev/null
+++ b/src/agentscope/tracing/_utils.py
@@ -0,0 +1,78 @@
+# -*- coding: utf-8 -*-
+"""Serialize objects to JSON string."""
+import datetime
+import enum
+import inspect
+import json
+from dataclasses import is_dataclass
+from typing import Any
+
+from pydantic import BaseModel
+
+from ..message import Msg
+
+
+def _to_serializable(
+ obj: Any,
+) -> Any:
+ """Convert an object to a JSON serializable type.
+
+ Args:
+ obj (`Any`):
+ The object to be converted to JSON serializable.
+
+ Returns:
+ `Any`:
+ The converted JSON serializable object
+ """
+
+ # Handle primitive types first
+ if isinstance(obj, (str, int, bool, float, type(None))):
+ res = obj
+
+ elif isinstance(obj, (list, tuple, set, frozenset)):
+ res = [_to_serializable(x) for x in obj]
+
+ elif isinstance(obj, dict):
+ res = {str(key): _to_serializable(val) for (key, val) in obj.items()}
+
+ elif isinstance(obj, (Msg, BaseModel)) or is_dataclass(obj):
+ res = repr(obj)
+
+ elif inspect.isclass(obj) and issubclass(obj, BaseModel):
+ res = repr(obj)
+
+ elif isinstance(obj, (datetime.date, datetime.datetime, datetime.time)):
+ res = obj.isoformat()
+
+ elif isinstance(obj, datetime.timedelta):
+ res = obj.total_seconds()
+
+ elif isinstance(obj, enum.Enum):
+ res = _to_serializable(obj.value)
+
+ else:
+ res = str(obj)
+
+ return res
+
+
+def _serialize_to_str(value: Any) -> str:
+ """Serialize input value to JSON string.
+
+ Args:
+ value (`Any`):
+ The input value
+
+ Returns:
+ `str`:
+ JSON serialized string of the input value
+ """
+ try:
+ return json.dumps(value, ensure_ascii=False)
+
+ except TypeError:
+ return json.dumps(
+ _to_serializable(value),
+ ensure_ascii=False,
+ )
diff --git a/tests/tracing_converter_test.py b/tests/tracing_converter_test.py
new file mode 100644
index 000000000..1c6f38cdc
--- /dev/null
+++ b/tests/tracing_converter_test.py
@@ -0,0 +1,425 @@
+# -*- coding: utf-8 -*-
+"""Unittests for the message converter functionality in AgentScope tracing."""
+from typing import Any, Dict
+from unittest import TestCase
+
+from agentscope.message import (
+ TextBlock,
+ ToolUseBlock,
+ ToolResultBlock,
+ ImageBlock,
+ AudioBlock,
+ VideoBlock,
+)
+from agentscope.tracing._converter import _convert_block_to_part
+
+
+class ConverterTest(TestCase):
+ """Test cases for _convert_block_to_part converter"""
+
+ def test_convert_text_block(self) -> None:
+ """Test text block conversion"""
+ # Normal text block
+ block: TextBlock = {
+ "type": "text",
+ "text": "Hello, world!",
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["type"], "text")
+ self.assertEqual(result["content"], "Hello, world!")
+
+ # Missing text field
+ block = {"type": "text"}
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["type"], "text")
+ self.assertEqual(result["content"], "")
+
+ # Empty text
+ block = {"type": "text", "text": ""}
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["type"], "text")
+ self.assertEqual(result["content"], "")
+
+ def test_convert_thinking_block(self) -> None:
+ """Test thinking block conversion"""
+ # Normal thinking block
+ block: Dict[str, Any] = {
+ "type": "thinking",
+ "thinking": "Let me think about this...",
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["type"], "reasoning")
+ self.assertEqual(result["content"], "Let me think about this...")
+
+ # Missing thinking field
+ block = {"type": "thinking"}
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["type"], "reasoning")
+ self.assertEqual(result["content"], "")
+
+ def test_convert_tool_use_block(self) -> None:
+ """Test tool_use block conversion"""
+ # Normal tool_use block
+ block: ToolUseBlock = {
+ "type": "tool_use",
+ "id": "call_123",
+ "name": "search",
+ "input": {"query": "test query", "limit": 10},
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["type"], "tool_call")
+ self.assertEqual(result["id"], "call_123")
+ self.assertEqual(result["name"], "search")
+ self.assertEqual(
+ result["arguments"],
+ {"query": "test query", "limit": 10},
+ )
+
+ # Missing fields
+ block = {
+ "type": "tool_use",
+ "id": "",
+ "name": "",
+ "input": {},
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["type"], "tool_call")
+ self.assertEqual(result["id"], "")
+ self.assertEqual(result["name"], "")
+ self.assertEqual(result["arguments"], {})
+
+ def test_convert_tool_result_block(self) -> None:
+ """Test tool_result block conversion"""
+ # String output
+ block: ToolResultBlock = {
+ "type": "tool_result",
+ "id": "call_123",
+ "name": "search",
+ "output": "Search results here",
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["type"], "tool_call_response")
+ self.assertEqual(result["id"], "call_123")
+ self.assertEqual(result["response"], "Search results here")
+
+ # Dict output
+ block = {
+ "type": "tool_result",
+ "id": "call_123",
+ "name": "search",
+ "output": {"result": "success", "data": [1, 2, 3]},
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertIsInstance(result["response"], str)
+ self.assertIn("result", result["response"])
+ self.assertIn("success", result["response"])
+
+ # List output
+ block = {
+ "type": "tool_result",
+ "id": "call_123",
+ "name": "search",
+ "output": [
+ {"type": "text", "text": "Result 1"},
+ {"type": "text", "text": "Result 2"},
+ ],
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertIsInstance(result["response"], str)
+ self.assertIn("Result 1", result["response"])
+
+ # Numeric output
+ block = {
+ "type": "tool_result",
+ "id": "call_123",
+ "name": "calculate",
+ "output": 42,
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["response"], "42")
+
+ # Empty output
+ block = {
+ "type": "tool_result",
+ "id": "call_123",
+ "name": "search",
+ "output": "",
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["response"], "")
+
+ # None output
+ block = {
+ "type": "tool_result",
+ "id": "call_123",
+ "name": "search",
+ "output": None,
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["response"], "None")
+
+ # Missing id
+ block = {
+ "type": "tool_result",
+ "id": "",
+ "name": "search",
+ "output": "result",
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["id"], "")
+
+ def test_convert_image_block(self) -> None:
+ """Test image block conversion"""
+ # URL source
+ source: Dict[str, Any] = {
+ "type": "url",
+ "url": "https://example.com/image.jpg",
+ }
+ block: ImageBlock = {
+ "type": "image",
+ "source": source,
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["type"], "uri")
+ self.assertEqual(result["uri"], "https://example.com/image.jpg")
+ self.assertEqual(result["modality"], "image")
+
+ # Base64 source
+ source = {
+ "type": "base64",
+ "media_type": "image/png",
+ "data": "base",
+ }
+ block = {
+ "type": "image",
+ "source": source,
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["type"], "blob")
+ self.assertEqual(result["content"], source["data"])
+ self.assertEqual(result["media_type"], "image/png")
+ self.assertEqual(result["modality"], "image")
+
+ # Base64 with default media_type
+ source = {
+ "type": "base64",
+ "media_type": "image/jpeg",
+ "data": "base64data",
+ }
+ block = {
+ "type": "image",
+ "source": source,
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["media_type"], "image/jpeg")
+
+ # URL missing url field
+ block = {
+ "type": "image",
+ "source": {"type": "url"},
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["uri"], "")
+
+ # Base64 missing fields
+ block = {
+ "type": "image",
+ "source": {"type": "base64"},
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["content"], "")
+ self.assertEqual(result["media_type"], "image/jpeg")
+
+ # Invalid source type
+ block = {
+ "type": "image",
+ "source": {"type": "invalid"},
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNone(result)
+
+ # Missing source
+ block = {"type": "image"}
+ result = _convert_block_to_part(block)
+ self.assertIsNone(result)
+
+ def test_convert_audio_block(self) -> None:
+ """Test audio block conversion"""
+ # URL source
+ source: Dict[str, Any] = {
+ "type": "url",
+ "url": "https://example.com/audio.wav",
+ }
+ block: AudioBlock = {
+ "type": "audio",
+ "source": source,
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["type"], "uri")
+ self.assertEqual(result["uri"], "https://example.com/audio.wav")
+ self.assertEqual(result["modality"], "audio")
+
+ # Base64 source
+ source = {
+ "type": "base64",
+ "media_type": "audio/mpeg",
+ "data": "base64audiodata",
+ }
+ block = {
+ "type": "audio",
+ "source": source,
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["type"], "blob")
+ self.assertEqual(result["content"], "base64audiodata")
+ self.assertEqual(result["media_type"], "audio/mpeg")
+ self.assertEqual(result["modality"], "audio")
+
+ # Base64 with default media_type
+ source = {
+ "type": "base64",
+ "media_type": "audio/wav",
+ "data": "base64data",
+ }
+ block = {
+ "type": "audio",
+ "source": source,
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["media_type"], "audio/wav")
+
+ # URL missing url field
+ block = {
+ "type": "audio",
+ "source": {"type": "url"},
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["uri"], "")
+
+ # Base64 missing fields
+ block = {
+ "type": "audio",
+ "source": {"type": "base64"},
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["content"], "")
+ self.assertEqual(result["media_type"], "audio/wav")
+
+ # Invalid source type
+ block = {
+ "type": "audio",
+ "source": {"type": "invalid"},
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNone(result)
+
+ def test_convert_video_block(self) -> None:
+ """Test video block conversion"""
+ # URL source
+ source: Dict[str, Any] = {
+ "type": "url",
+ "url": "https://example.com/video.mp4",
+ }
+ block: VideoBlock = {
+ "type": "video",
+ "source": source,
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["type"], "uri")
+ self.assertEqual(result["uri"], "https://example.com/video.mp4")
+ self.assertEqual(result["modality"], "video")
+
+ # Base64 source
+ source = {
+ "type": "base64",
+ "media_type": "video/webm",
+ "data": "base64videodata",
+ }
+ block = {
+ "type": "video",
+ "source": source,
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["type"], "blob")
+ self.assertEqual(result["content"], "base64videodata")
+ self.assertEqual(result["media_type"], "video/webm")
+ self.assertEqual(result["modality"], "video")
+
+ # Base64 with default media_type
+ source = {
+ "type": "base64",
+ "media_type": "video/mp4",
+ "data": "base64data",
+ }
+ block = {
+ "type": "video",
+ "source": source,
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["media_type"], "video/mp4")
+
+ # URL missing url field
+ block = {
+ "type": "video",
+ "source": {"type": "url"},
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["uri"], "")
+
+ # Base64 missing fields
+ block = {
+ "type": "video",
+ "source": {"type": "base64"},
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNotNone(result)
+ self.assertEqual(result["content"], "")
+ self.assertEqual(result["media_type"], "video/mp4")
+
+ # Invalid source type
+ block = {
+ "type": "video",
+ "source": {"type": "invalid"},
+ }
+ result = _convert_block_to_part(block)
+ self.assertIsNone(result)
+
+ def test_convert_invalid_blocks(self) -> None:
+ """Test invalid block types"""
+ # Unknown block type
+ block = {"type": "unknown_type"}
+ result = _convert_block_to_part(block)
+ self.assertIsNone(result)
+
+ # Missing type field
+ block = {}
+ result = _convert_block_to_part(block)
+ self.assertIsNone(result)
diff --git a/tests/tracing_extractor_test.py b/tests/tracing_extractor_test.py
new file mode 100644
index 000000000..960c21fa2
--- /dev/null
+++ b/tests/tracing_extractor_test.py
@@ -0,0 +1,442 @@
+# -*- coding: utf-8 -*-
+"""Unit tests for the tracing extractor module."""
+from unittest import TestCase
+from unittest.mock import Mock
+
+from agentscope.message import Msg, TextBlock, ToolUseBlock
+from agentscope.model import ChatModelBase, ChatResponse
+from agentscope.agent import AgentBase
+from agentscope.tool import Toolkit
+from agentscope.formatter import FormatterBase
+from agentscope.embedding import EmbeddingModelBase
+from agentscope.tracing._extractor import (
+ _get_common_attributes,
+ _get_format_target,
+ _get_provider_name,
+ _get_tool_definitions,
+ _get_llm_request_attributes,
+ _get_llm_span_name,
+ _get_llm_output_messages,
+ _get_llm_response_attributes,
+ _get_agent_messages,
+ _get_agent_request_attributes,
+ _get_agent_span_name,
+ _get_agent_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 agentscope.tracing._attributes import (
+ SpanAttributes,
+ OperationNameValues,
+ ProviderNameValues,
+)
+
+
+class ExtractorTest(TestCase):
+ """Test cases for the extractor module."""
+
+ def setUp(self) -> None:
+ """Set up test fixtures."""
+ self.mock_model = Mock(spec=ChatModelBase)
+ self.mock_model.model_name = "test-model"
+ self.mock_model.__class__.__name__ = "TestChatModel"
+
+ self.mock_agent = Mock(spec=AgentBase)
+ self.mock_agent.id = "agent-1"
+ self.mock_agent.name = "TestAgent"
+ self.mock_agent.__class__.__doc__ = "Test agent description"
+
+ self.mock_formatter = Mock(spec=FormatterBase)
+ self.mock_formatter.__class__.__name__ = "OpenAIChatFormatter"
+
+ self.mock_embedding = Mock(spec=EmbeddingModelBase)
+ self.mock_embedding.model_name = "embedding-model"
+
+ def test_get_common_attributes(self) -> None:
+ """Test _get_common_attributes."""
+ from agentscope import _config
+
+ original_run_id = _config.run_id
+ _config.run_id = "test-run-id"
+
+ try:
+ attributes = _get_common_attributes()
+ self.assertIn(SpanAttributes.GEN_AI_CONVERSATION_ID, attributes)
+ self.assertEqual(
+ attributes[SpanAttributes.GEN_AI_CONVERSATION_ID],
+ '"test-run-id"',
+ )
+ finally:
+ _config.run_id = original_run_id
+
+ def test_get_format_target(self) -> None:
+ """Test _get_format_target."""
+ # Test OpenAI formatter
+ formatter = Mock()
+ formatter.__class__.__name__ = "OpenAIChatFormatter"
+ self.assertEqual(
+ _get_format_target(formatter),
+ ProviderNameValues.OPENAI,
+ )
+
+ # Test DashScope formatter
+ formatter.__class__.__name__ = "DashScopeChatFormatter"
+ self.assertEqual(
+ _get_format_target(formatter),
+ ProviderNameValues.DASHSCOPE,
+ )
+
+ # Test unknown formatter
+ formatter.__class__.__name__ = "UnknownFormatter"
+ self.assertEqual(_get_format_target(formatter), "unknown")
+
+ def test_get_provider_name(self) -> None:
+ """Test _get_provider_name."""
+ # Test OpenAI model
+ model = Mock(spec=ChatModelBase)
+ model.__class__.__name__ = "OpenAIChatModel"
+ model.client = Mock()
+ model.client.base_url = "https://api.openai.com/v1"
+ self.assertEqual(_get_provider_name(model), ProviderNameValues.OPENAI)
+
+ # Test DashScope model
+ model.__class__.__name__ = "DashScopeChatModel"
+ self.assertEqual(
+ _get_provider_name(model),
+ ProviderNameValues.DASHSCOPE,
+ )
+
+ # Test OpenAI model with custom base_url
+ model.__class__.__name__ = "OpenAIChatModel"
+ model.client.base_url = "https://api.deepseek.com/v1"
+ self.assertEqual(
+ _get_provider_name(model),
+ ProviderNameValues.DEEPSEEK,
+ )
+
+ # Test model without base_url
+ model.client.base_url = None
+ self.assertEqual(_get_provider_name(model), ProviderNameValues.OPENAI)
+
+ def test_get_tool_definitions(self) -> None:
+ """Test _get_tool_definitions."""
+ # Test with valid tools
+ tools = [
+ {
+ "type": "function",
+ "function": {
+ "name": "test_tool",
+ "description": "A test tool",
+ "parameters": {"type": "object", "properties": {}},
+ },
+ },
+ ]
+ result = _get_tool_definitions(tools, "auto")
+ self.assertIsNotNone(result)
+ self.assertIn("test_tool", result)
+
+ # Test with None tools
+ self.assertIsNone(_get_tool_definitions(None, "auto"))
+
+ # Test with empty tools
+ self.assertIsNone(_get_tool_definitions([], "auto"))
+
+ # Test with tool_choice="none"
+ self.assertIsNone(_get_tool_definitions(tools, "none"))
+
+ # Test with invalid tool format
+ invalid_tools = [{"type": "function"}]
+ self.assertIsNone(_get_tool_definitions(invalid_tools, "auto"))
+
+ def test_get_llm_request_attributes(self) -> None:
+ """Test _get_llm_request_attributes and _get_llm_span_name."""
+ args = ()
+ kwargs = {
+ "temperature": 0.7,
+ "top_p": 0.9,
+ "top_k": 40,
+ "max_tokens": 100,
+ "presence_penalty": 0.1,
+ "frequency_penalty": 0.2,
+ "stop_sequences": ["stop"],
+ "seed": 42,
+ }
+
+ attributes = _get_llm_request_attributes(self.mock_model, args, kwargs)
+
+ self.assertEqual(
+ attributes[SpanAttributes.GEN_AI_OPERATION_NAME],
+ OperationNameValues.CHAT,
+ )
+ self.assertEqual(
+ attributes[SpanAttributes.GEN_AI_REQUEST_MODEL],
+ "test-model",
+ )
+ self.assertEqual(
+ attributes[SpanAttributes.GEN_AI_REQUEST_TEMPERATURE],
+ 0.7,
+ )
+ self.assertEqual(
+ attributes[SpanAttributes.GEN_AI_REQUEST_TOP_P],
+ 0.9,
+ )
+ self.assertIn(SpanAttributes.AGENTSCOPE_FUNCTION_INPUT, attributes)
+
+ # Test span name generation
+ span_name = _get_llm_span_name(attributes)
+ self.assertEqual(span_name, "chat test-model")
+
+ def test_get_llm_response_attributes(self) -> None:
+ """Test _get_llm_response_attributes and _get_llm_output_messages."""
+ # Create a mock usage object
+ usage = Mock()
+ usage.input_tokens = 10
+ usage.output_tokens = 20
+
+ response = ChatResponse(
+ id="test-id",
+ content=[TextBlock(type="text", text="Hello")],
+ )
+ response.usage = usage
+
+ # Test output messages extraction
+ messages = _get_llm_output_messages(response)
+ self.assertEqual(len(messages), 1)
+ self.assertEqual(messages[0]["role"], "assistant")
+ self.assertIn("parts", messages[0])
+
+ # Test with non-ChatResponse
+ result = _get_llm_output_messages("not a response")
+ self.assertEqual(result, "not a response")
+
+ # Test response attributes
+ attributes = _get_llm_response_attributes(response)
+
+ self.assertEqual(
+ attributes[SpanAttributes.GEN_AI_RESPONSE_ID],
+ "test-id",
+ )
+ self.assertEqual(
+ attributes[SpanAttributes.GEN_AI_USAGE_INPUT_TOKENS],
+ 10,
+ )
+ self.assertEqual(
+ attributes[SpanAttributes.GEN_AI_USAGE_OUTPUT_TOKENS],
+ 20,
+ )
+ self.assertIn(SpanAttributes.GEN_AI_OUTPUT_MESSAGES, attributes)
+
+ def test_get_agent_request_attributes(self) -> None:
+ """Test _get_agent_messages, request_attributes and span_name."""
+ # Test agent messages conversion
+ msg = Msg(
+ "test_user",
+ [TextBlock(type="text", text="Hello")],
+ "user",
+ )
+ result = _get_agent_messages(msg)
+ self.assertEqual(result["role"], "user")
+ self.assertEqual(result["name"], "test_user")
+ self.assertIn("parts", result)
+
+ # Test request attributes
+ args = (msg,)
+ kwargs = {}
+ attributes = _get_agent_request_attributes(
+ self.mock_agent,
+ args,
+ kwargs,
+ )
+
+ self.assertEqual(
+ attributes[SpanAttributes.GEN_AI_OPERATION_NAME],
+ OperationNameValues.INVOKE_AGENT,
+ )
+ self.assertEqual(
+ attributes[SpanAttributes.GEN_AI_AGENT_ID],
+ "agent-1",
+ )
+ self.assertEqual(
+ attributes[SpanAttributes.GEN_AI_AGENT_NAME],
+ "TestAgent",
+ )
+ self.assertIn(SpanAttributes.GEN_AI_INPUT_MESSAGES, attributes)
+ self.assertIn(SpanAttributes.AGENTSCOPE_FUNCTION_INPUT, attributes)
+
+ # Test span name generation
+ span_name = _get_agent_span_name(attributes)
+ self.assertEqual(span_name, "invoke_agent TestAgent")
+
+ def test_get_agent_response_attributes(self) -> None:
+ """Test _get_agent_response_attributes."""
+ response = Msg(
+ "assistant",
+ [TextBlock(type="text", text="Hi")],
+ "assistant",
+ )
+ attributes = _get_agent_response_attributes(response)
+
+ self.assertIn(SpanAttributes.GEN_AI_OUTPUT_MESSAGES, attributes)
+ self.assertIn(SpanAttributes.AGENTSCOPE_FUNCTION_OUTPUT, attributes)
+
+ def test_get_tool_request_attributes(self) -> None:
+ """Test _get_tool_request_attributes and _get_tool_span_name."""
+ # Create a mock toolkit with tool definition
+ toolkit = Mock(spec=Toolkit)
+ tool_func = Mock()
+ tool_func.json_schema = {
+ "function": {
+ "description": "Test tool description",
+ },
+ }
+ toolkit.tools = {"test_tool": tool_func}
+
+ tool_call = ToolUseBlock(
+ type="tool_use",
+ id="call-1",
+ name="test_tool",
+ input={"arg1": "value1"},
+ )
+
+ attributes = _get_tool_request_attributes(toolkit, tool_call)
+
+ self.assertEqual(
+ attributes[SpanAttributes.GEN_AI_OPERATION_NAME],
+ OperationNameValues.EXECUTE_TOOL,
+ )
+ self.assertEqual(
+ attributes[SpanAttributes.GEN_AI_TOOL_CALL_ID],
+ "call-1",
+ )
+ self.assertEqual(
+ attributes[SpanAttributes.GEN_AI_TOOL_NAME],
+ "test_tool",
+ )
+ self.assertIn(SpanAttributes.GEN_AI_TOOL_CALL_ARGUMENTS, attributes)
+ self.assertIn(SpanAttributes.GEN_AI_TOOL_DESCRIPTION, attributes)
+
+ # Test span name generation
+ span_name = _get_tool_span_name(attributes)
+ self.assertEqual(span_name, "execute_tool test_tool")
+
+ def test_get_tool_response_attributes(self) -> None:
+ """Test _get_tool_response_attributes."""
+ response = {"result": "success"}
+ attributes = _get_tool_response_attributes(response)
+
+ self.assertIn(SpanAttributes.GEN_AI_TOOL_CALL_RESULT, attributes)
+ self.assertIn(SpanAttributes.AGENTSCOPE_FUNCTION_OUTPUT, attributes)
+
+ def test_get_formatter_request_attributes(self) -> None:
+ """Test formatter request_attributes and span_name."""
+ args = ()
+ kwargs = {}
+
+ attributes = _get_formatter_request_attributes(
+ self.mock_formatter,
+ args,
+ kwargs,
+ )
+
+ self.assertEqual(
+ attributes[SpanAttributes.GEN_AI_OPERATION_NAME],
+ OperationNameValues.FORMATTER,
+ )
+ self.assertIn(SpanAttributes.AGENTSCOPE_FORMAT_TARGET, attributes)
+ self.assertIn(SpanAttributes.AGENTSCOPE_FUNCTION_INPUT, attributes)
+
+ # Test span name generation
+ span_name = _get_formatter_span_name(attributes)
+ self.assertEqual(span_name, "format openai")
+
+ def test_get_formatter_response_attributes(self) -> None:
+ """Test _get_formatter_response_attributes."""
+ response = [{"role": "user", "content": "Hello"}]
+ attributes = _get_formatter_response_attributes(response)
+
+ self.assertIn(SpanAttributes.AGENTSCOPE_FUNCTION_OUTPUT, attributes)
+ self.assertEqual(
+ attributes[SpanAttributes.AGENTSCOPE_FORMAT_COUNT],
+ 1,
+ )
+
+ def test_get_generic_function_request_attributes(self) -> None:
+ """Test generic function request_attributes, span_name and response."""
+ args = (1, 2, 3)
+ kwargs = {"key": "value"}
+
+ attributes = _get_generic_function_request_attributes(
+ "test_function",
+ args,
+ kwargs,
+ )
+
+ self.assertEqual(
+ attributes[SpanAttributes.GEN_AI_OPERATION_NAME],
+ OperationNameValues.INVOKE_GENERIC_FUNCTION,
+ )
+ self.assertEqual(
+ attributes[SpanAttributes.AGENTSCOPE_FUNCTION_NAME],
+ "test_function",
+ )
+ self.assertIn(SpanAttributes.AGENTSCOPE_FUNCTION_INPUT, attributes)
+
+ # Test span name generation
+ span_name = _get_generic_function_span_name(attributes)
+ self.assertEqual(span_name, "invoke_generic_function test_function")
+
+ # Test response attributes
+ response = {"result": "success"}
+ response_attributes = _get_generic_function_response_attributes(
+ response,
+ )
+ self.assertIn(
+ SpanAttributes.AGENTSCOPE_FUNCTION_OUTPUT,
+ response_attributes,
+ )
+
+ def test_get_embedding_request_attributes(self) -> None:
+ """Test _get_embedding_request_attributes, span_name and response."""
+ args = ()
+ kwargs = {"dimensions": 768}
+
+ attributes = _get_embedding_request_attributes(
+ self.mock_embedding,
+ args,
+ kwargs,
+ )
+
+ self.assertEqual(
+ attributes[SpanAttributes.GEN_AI_OPERATION_NAME],
+ OperationNameValues.EMBEDDINGS,
+ )
+ self.assertEqual(
+ attributes[SpanAttributes.GEN_AI_REQUEST_MODEL],
+ "embedding-model",
+ )
+ self.assertEqual(
+ attributes[SpanAttributes.GEN_AI_EMBEDDINGS_DIMENSION_COUNT],
+ 768,
+ )
+
+ # Test span name generation
+ span_name = _get_embedding_span_name(attributes)
+ self.assertEqual(span_name, "embeddings embedding-model")
+
+ # Test response attributes
+ response = [[0.1, 0.2, 0.3]]
+ response_attributes = _get_embedding_response_attributes(response)
+ self.assertIn(
+ SpanAttributes.AGENTSCOPE_FUNCTION_OUTPUT,
+ response_attributes,
+ )
diff --git a/tests/tracer_test.py b/tests/tracing_test.py
similarity index 100%
rename from tests/tracer_test.py
rename to tests/tracing_test.py
diff --git a/tests/tracing_utils_test.py b/tests/tracing_utils_test.py
new file mode 100644
index 000000000..73e58b700
--- /dev/null
+++ b/tests/tracing_utils_test.py
@@ -0,0 +1,232 @@
+# -*- coding: utf-8 -*-
+"""Unit tests for the tracing utils module."""
+from unittest import TestCase
+import datetime
+import enum
+import json
+from dataclasses import dataclass
+
+from pydantic import BaseModel
+
+from agentscope.message import Msg, TextBlock
+from agentscope.tracing._utils import _to_serializable, _serialize_to_str
+
+
+class ExampleEnum(enum.Enum):
+ """Example enum for serialization."""
+
+ VALUE1 = "value1"
+ VALUE2 = 42
+
+
+@dataclass
+class ExampleDataClass:
+ """Example dataclass for serialization."""
+
+ name: str
+ age: int
+
+
+class ExamplePydanticModel(BaseModel):
+ """Example Pydantic model for serialization."""
+
+ name: str
+ age: int
+
+
+class UtilsTest(TestCase):
+ """Test cases for the utils module."""
+
+ def test_to_serializable_primitive_types(self) -> None:
+ """Test _to_serializable with primitive types."""
+ # Test string
+ self.assertEqual(_to_serializable("hello"), "hello")
+
+ # Test integer
+ self.assertEqual(_to_serializable(42), 42)
+
+ # Test boolean
+ self.assertEqual(_to_serializable(True), True)
+ self.assertEqual(_to_serializable(False), False)
+
+ # Test float
+ self.assertEqual(_to_serializable(3.14), 3.14)
+
+ # Test None
+ self.assertIsNone(_to_serializable(None))
+
+ def test_to_serializable_collections(self) -> None:
+ """Test _to_serializable with collections."""
+ # Test list
+ result = _to_serializable([1, 2, 3])
+ self.assertEqual(result, [1, 2, 3])
+
+ # Test tuple
+ result = _to_serializable((1, 2, 3))
+ self.assertEqual(result, [1, 2, 3])
+
+ # Test set
+ result = _to_serializable({1, 2, 3})
+ self.assertIsInstance(result, list)
+ self.assertEqual(set(result), {1, 2, 3})
+
+ # Test frozenset
+ result = _to_serializable(frozenset([1, 2, 3]))
+ self.assertIsInstance(result, list)
+ self.assertEqual(set(result), {1, 2, 3})
+
+ def test_to_serializable_dict(self) -> None:
+ """Test _to_serializable with dictionaries."""
+ # Test simple dict
+ result = _to_serializable({"key": "value", "num": 42})
+ self.assertEqual(result, {"key": "value", "num": 42})
+
+ # Test nested dict
+ result = _to_serializable({"nested": {"key": "value"}})
+ self.assertEqual(result, {"nested": {"key": "value"}})
+
+ # Test dict with non-string keys
+ result = _to_serializable({1: "one", 2: "two"})
+ self.assertEqual(result, {"1": "one", "2": "two"})
+
+ def test_to_serializable_msg(self) -> None:
+ """Test _to_serializable with Msg objects."""
+ msg = Msg("user", [TextBlock(type="text", text="Hello")], "user")
+ result = _to_serializable(msg)
+ self.assertIsInstance(result, str)
+ self.assertIn("Msg", result)
+
+ def test_to_serializable_pydantic_model(self) -> None:
+ """Test _to_serializable with Pydantic models."""
+ model = ExamplePydanticModel(name="test", age=42)
+ result = _to_serializable(model)
+ self.assertIsInstance(result, str)
+ self.assertIn("ExamplePydanticModel", result)
+
+ # Test Pydantic class
+ result = _to_serializable(ExamplePydanticModel)
+ self.assertIsInstance(result, str)
+
+ def test_to_serializable_dataclass(self) -> None:
+ """Test _to_serializable with dataclasses."""
+ obj = ExampleDataClass(name="test", age=42)
+ result = _to_serializable(obj)
+ self.assertIsInstance(result, str)
+ self.assertIn("ExampleDataClass", result)
+
+ def test_to_serializable_datetime(self) -> None:
+ """Test _to_serializable with datetime objects."""
+ # Test date
+ date_obj = datetime.date(2024, 1, 1)
+ result = _to_serializable(date_obj)
+ self.assertEqual(result, "2024-01-01")
+
+ # Test datetime
+ dt_obj = datetime.datetime(2024, 1, 1, 12, 30, 45)
+ result = _to_serializable(dt_obj)
+ self.assertEqual(result, "2024-01-01T12:30:45")
+
+ # Test time
+ time_obj = datetime.time(12, 30, 45)
+ result = _to_serializable(time_obj)
+ self.assertEqual(result, "12:30:45")
+
+ def test_to_serializable_timedelta(self) -> None:
+ """Test _to_serializable with timedelta objects."""
+ delta = datetime.timedelta(days=1, hours=2, minutes=30)
+ result = _to_serializable(delta)
+ self.assertIsInstance(result, (int, float))
+ self.assertGreater(result, 0)
+
+ def test_to_serializable_enum(self) -> None:
+ """Test _to_serializable with enum objects."""
+ result = _to_serializable(ExampleEnum.VALUE1)
+ self.assertEqual(result, "value1")
+
+ result = _to_serializable(ExampleEnum.VALUE2)
+ self.assertEqual(result, 42)
+
+ def test_to_serializable_unknown_type(self) -> None:
+ """Test _to_serializable with unknown types."""
+
+ class CustomClass:
+ """Custom class for testing."""
+
+ def __init__(self) -> None:
+ self.value = "test"
+
+ obj = CustomClass()
+ result = _to_serializable(obj)
+ self.assertIsInstance(result, str)
+
+ def test_to_serializable_nested_structures(self) -> None:
+ """Test _to_serializable with nested structures."""
+ data = {
+ "list": [1, 2, {"nested": "value"}],
+ "tuple": (1, 2, 3),
+ "set": {1, 2, 3},
+ }
+ result = _to_serializable(data)
+ self.assertIsInstance(result, dict)
+ self.assertIsInstance(result["list"], list)
+ self.assertIsInstance(result["tuple"], list)
+ self.assertIsInstance(result["set"], list)
+
+ def test_serialize_to_str_simple(self) -> None:
+ """Test _serialize_to_str with simple types."""
+ # Test string
+ result = _serialize_to_str("hello")
+ self.assertEqual(result, '"hello"')
+
+ # Test integer
+ result = _serialize_to_str(42)
+ self.assertEqual(result, "42")
+
+ # Test boolean
+ result = _serialize_to_str(True)
+ self.assertEqual(result, "true")
+
+ # Test None
+ result = _serialize_to_str(None)
+ self.assertEqual(result, "null")
+
+ def test_serialize_to_str_list(self) -> None:
+ """Test _serialize_to_str with lists."""
+ numbers = [1, 2, 3]
+ result = _serialize_to_str(numbers)
+ self.assertEqual(result, json.dumps(numbers))
+
+ strings = ["a", "b", "c"]
+ result = _serialize_to_str(strings)
+ self.assertEqual(result, json.dumps(strings))
+
+ def test_serialize_to_str_dict(self) -> None:
+ """Test _serialize_to_str with dictionaries."""
+ result = _serialize_to_str({"key": "value", "num": 42})
+ self.assertIn("key", result)
+ self.assertIn("value", result)
+ self.assertIn("num", result)
+ self.assertIn("42", result)
+
+ def test_serialize_to_str_non_serializable(self) -> None:
+ """Test _serialize_to_str with non-serializable objects."""
+ msg = Msg("user", [TextBlock(type="text", text="Hello")], "user")
+ result = _serialize_to_str(msg)
+ self.assertIsInstance(result, str)
+ self.assertIn("Msg", result)
+
+ def test_serialize_to_str_unicode(self) -> None:
+ """Test _serialize_to_str with unicode characters."""
+ result = _serialize_to_str("hi")
+ self.assertIn("hi", result)
+
+ def test_serialize_to_str_complex_nested(self) -> None:
+ """Test _serialize_to_str with complex nested structures."""
+ data = {
+ "list": [1, 2, {"nested": "value"}],
+ "datetime": datetime.datetime(2024, 1, 1),
+ "enum": ExampleEnum.VALUE1,
+ }
+ result = _serialize_to_str(data)
+ self.assertIsInstance(result, str)
+ self.assertIn("list", result)