openinference-instrumentation-agent-framework 0.1.0__tar.gz

openinference_instrumentation_agent_framework-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+# vendored virtual environments
+.venv
+
+# gradio work directory
+.gradio

openinference_instrumentation_agent_framework-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: openinference-instrumentation-agent-framework
+Version: 0.1.0
+Summary: OpenInference span processor for Microsoft Agent Framework - transforms native OpenTelemetry spans to OpenInference format
+Project-URL: Homepage, https://github.com/Arize-ai/openinference/tree/main/python/instrumentation/openinference-instrumentation-agent-framework
+Author-email: OpenInference Authors <oss@arize.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <3.15,>=3.10
+Requires-Dist: openinference-semantic-conventions>=0.1.25
+Requires-Dist: opentelemetry-api>=1.39.0
+Requires-Dist: opentelemetry-sdk>=1.39.0
+Requires-Dist: opentelemetry-semantic-conventions>=0.52b0
+Requires-Dist: typing-extensions
+Provides-Extra: instruments
+Requires-Dist: agent-framework>=1.0.0b260130; extra == 'instruments'
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-asyncio; extra == 'test'
+Requires-Dist: pytest-recording; extra == 'test'
+Description-Content-Type: text/markdown
+
+# OpenInference Microsoft Agent Framework Instrumentation
+
+OpenInference span processor for Microsoft Agent Framework that transforms native OpenTelemetry spans to OpenInference format for compatibility with OpenInference-compliant backends like [Arize Phoenix](https://github.com/Arize-ai/phoenix).
+
+**Tested with agent-framework `1.0.0b260130` (January 30, 2026)**
+
+## Installation
+
+```bash
+pip install openinference-instrumentation-agent-framework
+```
+
+Install with agent-framework:
+```bash
+pip install openinference-instrumentation-agent-framework[instruments]
+```
+
+## Overview
+
+Microsoft Agent Framework emits telemetry using GenAI semantic conventions (`gen_ai.*` attributes). This package provides a `SpanProcessor` that transforms these spans to OpenInference format, enabling compatibility with observability tools that support the OpenInference standard.
+
+**Note:** Agent Framework is in beta and its API may change between versions. This instrumentation tracks the latest stable release.
+
+## Usage
+
+### Basic Setup
+
+```python
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
+from agent_framework.observability import enable_instrumentation
+from openinference.instrumentation.agent_framework import (
+    AgentFrameworkToOpenInferenceProcessor
+)
+
+# Create tracer provider
+tracer_provider = TracerProvider()
+
+# Add OpenInference processor to transform spans
+tracer_provider.add_span_processor(
+    AgentFrameworkToOpenInferenceProcessor()
+)
+
+# Add exporter (Console for demo, use OTLP for Phoenix)
+tracer_provider.add_span_processor(
+    SimpleSpanProcessor(ConsoleSpanExporter())
+)
+
+# Set as global tracer provider
+trace.set_tracer_provider(tracer_provider)
+
+# Enable agent-framework instrumentation
+enable_instrumentation(enable_sensitive_data=True)
+
+# Use framework normally - spans will be transformed automatically
+from agent_framework.openai import OpenAIChatClient
+
+client = OpenAIChatClient(model_id="gpt-4o-mini", api_key="your-key")
+agent = client.as_agent(name="Assistant", instructions="You are helpful.")
+response = await agent.run("Hello!")
+```
+
+### With Phoenix (Arize)
+
+```python
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from agent_framework.observability import enable_instrumentation
+from openinference.instrumentation.agent_framework import (
+    AgentFrameworkToOpenInferenceProcessor
+)
+
+# Configure Phoenix endpoint
+endpoint = "http://localhost:6006/v1/traces"
+
+# Setup tracer with OpenInference processor
+tracer_provider = TracerProvider()
+tracer_provider.add_span_processor(AgentFrameworkToOpenInferenceProcessor())
+tracer_provider.add_span_processor(
+    SimpleSpanProcessor(OTLPSpanExporter(endpoint=endpoint))
+)
+trace.set_tracer_provider(tracer_provider)
+
+# Enable instrumentation
+enable_instrumentation(enable_sensitive_data=True)
+
+# Your agent code here
+```
+
+## Transformation Details
+
+### Span Kind Mapping
+
+| MS Agent Framework Operation | OpenInference Span Kind |
+|------------------------------|-------------------------|
+| `chat` | LLM |
+| `execute_tool` | TOOL |
+| `invoke_agent` | AGENT |
+| `workflow.run` | CHAIN |
+| `executor.process` | CHAIN |
+
+### Attribute Mapping
+
+| Source (GenAI) | Target (OpenInference) |
+|----------------|------------------------|
+| `gen_ai.request.model` | `llm.model_name` |
+| `gen_ai.provider.name` | `llm.provider` |
+| `gen_ai.usage.input_tokens` | `llm.token_count.prompt` |
+| `gen_ai.usage.output_tokens` | `llm.token_count.completion` |
+| `gen_ai.input.messages` | `llm.input_messages.*` (flattened) |
+| `gen_ai.output.messages` | `llm.output_messages.*` (flattened) |
+| `gen_ai.tool.name` | `tool.name` |
+| `gen_ai.tool.call.id` | `tool.call_id` |
+| `gen_ai.tool.call.arguments` | `tool.parameters` |
+| `gen_ai.conversation.id` | `session.id` |
+
+### Message Format Transformation
+
+MS Agent Framework messages:
+```json
+{
+  "role": "user",
+  "parts": [
+    {"type": "text", "content": "Hello"}
+  ]
+}
+```
+
+Transformed to OpenInference flattened format:
+```
+llm.input_messages.0.message.role = "user"
+llm.input_messages.0.message.content = "Hello"
+```
+
+## Debug Mode
+
+Enable debug mode to log transformation details:
+
+```python
+processor = AgentFrameworkToOpenInferenceProcessor(debug=True)
+```
+
+## Requirements
+
+- Python >= 3.10, < 3.15
+- opentelemetry-api >= 1.39.0
+- opentelemetry-sdk >= 1.39.0
+- openinference-semantic-conventions >= 0.1.25
+- agent-framework >= 1.0.0b260130 (optional, install with `[instruments]` extra)
+
+## Important Notes
+
+### Agent Framework API Stability
+
+Microsoft Agent Framework is in active beta development. API changes between versions are possible:
+- This instrumentation is tested against `agent-framework==1.0.0b260130`
+- The `-latest` test variant tracks breaking changes in new releases
+- If you encounter API compatibility issues, pin to the tested version:
+  ```bash
+  pip install agent-framework==1.0.0b260130
+  ```
+
+### Sensitive Data
+
+Set `enable_sensitive_data=True` when calling `enable_instrumentation()` to capture message content in traces. This is required for full observability but may include PII.
+
+## Development
+
+### Running Tests
+
+Tests use VCR cassettes to replay recorded API interactions:
+
+```bash
+# Run with recorded cassettes (no API key needed)
+pytest tests/test_processor.py -v
+
+# Re-record cassettes (requires OPENAI_API_KEY)
+export OPENAI_API_KEY=your_key
+rm -rf tests/cassettes/
+pytest tests/test_processor.py -v --record-mode=rewrite
+```
+
+## License
+
+Apache-2.0

openinference_instrumentation_agent_framework-0.1.0/README.md

@@ -0,0 +1,188 @@
+# OpenInference Microsoft Agent Framework Instrumentation
+
+OpenInference span processor for Microsoft Agent Framework that transforms native OpenTelemetry spans to OpenInference format for compatibility with OpenInference-compliant backends like [Arize Phoenix](https://github.com/Arize-ai/phoenix).
+
+**Tested with agent-framework `1.0.0b260130` (January 30, 2026)**
+
+## Installation
+
+```bash
+pip install openinference-instrumentation-agent-framework
+```
+
+Install with agent-framework:
+```bash
+pip install openinference-instrumentation-agent-framework[instruments]
+```
+
+## Overview
+
+Microsoft Agent Framework emits telemetry using GenAI semantic conventions (`gen_ai.*` attributes). This package provides a `SpanProcessor` that transforms these spans to OpenInference format, enabling compatibility with observability tools that support the OpenInference standard.
+
+**Note:** Agent Framework is in beta and its API may change between versions. This instrumentation tracks the latest stable release.
+
+## Usage
+
+### Basic Setup
+
+```python
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
+from agent_framework.observability import enable_instrumentation
+from openinference.instrumentation.agent_framework import (
+    AgentFrameworkToOpenInferenceProcessor
+)
+
+# Create tracer provider
+tracer_provider = TracerProvider()
+
+# Add OpenInference processor to transform spans
+tracer_provider.add_span_processor(
+    AgentFrameworkToOpenInferenceProcessor()
+)
+
+# Add exporter (Console for demo, use OTLP for Phoenix)
+tracer_provider.add_span_processor(
+    SimpleSpanProcessor(ConsoleSpanExporter())
+)
+
+# Set as global tracer provider
+trace.set_tracer_provider(tracer_provider)
+
+# Enable agent-framework instrumentation
+enable_instrumentation(enable_sensitive_data=True)
+
+# Use framework normally - spans will be transformed automatically
+from agent_framework.openai import OpenAIChatClient
+
+client = OpenAIChatClient(model_id="gpt-4o-mini", api_key="your-key")
+agent = client.as_agent(name="Assistant", instructions="You are helpful.")
+response = await agent.run("Hello!")
+```
+
+### With Phoenix (Arize)
+
+```python
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from agent_framework.observability import enable_instrumentation
+from openinference.instrumentation.agent_framework import (
+    AgentFrameworkToOpenInferenceProcessor
+)
+
+# Configure Phoenix endpoint
+endpoint = "http://localhost:6006/v1/traces"
+
+# Setup tracer with OpenInference processor
+tracer_provider = TracerProvider()
+tracer_provider.add_span_processor(AgentFrameworkToOpenInferenceProcessor())
+tracer_provider.add_span_processor(
+    SimpleSpanProcessor(OTLPSpanExporter(endpoint=endpoint))
+)
+trace.set_tracer_provider(tracer_provider)
+
+# Enable instrumentation
+enable_instrumentation(enable_sensitive_data=True)
+
+# Your agent code here
+```
+
+## Transformation Details
+
+### Span Kind Mapping
+
+| MS Agent Framework Operation | OpenInference Span Kind |
+|------------------------------|-------------------------|
+| `chat` | LLM |
+| `execute_tool` | TOOL |
+| `invoke_agent` | AGENT |
+| `workflow.run` | CHAIN |
+| `executor.process` | CHAIN |
+
+### Attribute Mapping
+
+| Source (GenAI) | Target (OpenInference) |
+|----------------|------------------------|
+| `gen_ai.request.model` | `llm.model_name` |
+| `gen_ai.provider.name` | `llm.provider` |
+| `gen_ai.usage.input_tokens` | `llm.token_count.prompt` |
+| `gen_ai.usage.output_tokens` | `llm.token_count.completion` |
+| `gen_ai.input.messages` | `llm.input_messages.*` (flattened) |
+| `gen_ai.output.messages` | `llm.output_messages.*` (flattened) |
+| `gen_ai.tool.name` | `tool.name` |
+| `gen_ai.tool.call.id` | `tool.call_id` |
+| `gen_ai.tool.call.arguments` | `tool.parameters` |
+| `gen_ai.conversation.id` | `session.id` |
+
+### Message Format Transformation
+
+MS Agent Framework messages:
+```json
+{
+  "role": "user",
+  "parts": [
+    {"type": "text", "content": "Hello"}
+  ]
+}
+```
+
+Transformed to OpenInference flattened format:
+```
+llm.input_messages.0.message.role = "user"
+llm.input_messages.0.message.content = "Hello"
+```
+
+## Debug Mode
+
+Enable debug mode to log transformation details:
+
+```python
+processor = AgentFrameworkToOpenInferenceProcessor(debug=True)
+```
+
+## Requirements
+
+- Python >= 3.10, < 3.15
+- opentelemetry-api >= 1.39.0
+- opentelemetry-sdk >= 1.39.0
+- openinference-semantic-conventions >= 0.1.25
+- agent-framework >= 1.0.0b260130 (optional, install with `[instruments]` extra)
+
+## Important Notes
+
+### Agent Framework API Stability
+
+Microsoft Agent Framework is in active beta development. API changes between versions are possible:
+- This instrumentation is tested against `agent-framework==1.0.0b260130`
+- The `-latest` test variant tracks breaking changes in new releases
+- If you encounter API compatibility issues, pin to the tested version:
+  ```bash
+  pip install agent-framework==1.0.0b260130
+  ```
+
+### Sensitive Data
+
+Set `enable_sensitive_data=True` when calling `enable_instrumentation()` to capture message content in traces. This is required for full observability but may include PII.
+
+## Development
+
+### Running Tests
+
+Tests use VCR cassettes to replay recorded API interactions:
+
+```bash
+# Run with recorded cassettes (no API key needed)
+pytest tests/test_processor.py -v
+
+# Re-record cassettes (requires OPENAI_API_KEY)
+export OPENAI_API_KEY=your_key
+rm -rf tests/cassettes/
+pytest tests/test_processor.py -v --record-mode=rewrite
+```
+
+## License
+
+Apache-2.0

openinference_instrumentation_agent_framework-0.1.0/pyproject.toml

@@ -0,0 +1,95 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openinference-instrumentation-agent-framework"
+dynamic = ["version"]
+description = "OpenInference span processor for Microsoft Agent Framework - transforms native OpenTelemetry spans to OpenInference format"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10, <3.15"
+authors = [
+    { name = "OpenInference Authors", email = "oss@arize.com" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "opentelemetry-api>=1.39.0",
+    "opentelemetry-sdk>=1.39.0",
+    "opentelemetry-semantic-conventions>=0.52b0",
+    "openinference-semantic-conventions>=0.1.25",
+    "typing-extensions",
+]
+
+[project.optional-dependencies]
+instruments = [
+    "agent-framework >= 1.0.0b260130",
+]
+test = [
+    "pytest",
+    "pytest-asyncio",
+    "pytest-recording",
+]
+
+[project.urls]
+Homepage = "https://github.com/Arize-ai/openinference/tree/main/python/instrumentation/openinference-instrumentation-agent-framework"
+
+[tool.hatch.version]
+path = "src/openinference/instrumentation/agent_framework/__init__.py"
+pattern = '__version__ = "(?P<version>[^"]+)"'
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/openinference"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = [
+    "tests",
+]
+
+[tool.mypy]
+strict = true
+explicit_package_bases = true
+exclude = [
+    "examples",
+    "dist",
+    "sdist",
+    "tests",
+]
+
+[[tool.mypy.overrides]]
+ignore_missing_imports = true
+module = [
+    "agent_framework.*",
+    "openinference.instrumentation.agent_framework.*",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint.per-file-ignores]
+"*.ipynb" = ["E402", "E501"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+
+[tool.ruff.lint.isort]
+force-single-line = false

openinference_instrumentation_agent_framework-0.1.0/src/openinference/instrumentation/agent_framework/__init__.py

@@ -0,0 +1,47 @@
+"""OpenInference instrumentation for Microsoft Agent Framework.
+
+This package provides a SpanProcessor that transforms Microsoft Agent Framework's
+native OpenTelemetry spans (using GenAI semantic conventions) to OpenInference format
+for compatibility with OpenInference-compliant backends like Arize Phoenix.
+
+Usage:
+    ```python
+    from opentelemetry import trace
+    from opentelemetry.sdk.trace import TracerProvider
+    from agent_framework.observability import configure_otel_providers
+    from openinference.instrumentation.agent_framework import (
+        AgentFrameworkToOpenInferenceProcessor
+    )
+
+    # Configure MS Agent Framework's native telemetry
+    # Set OTEL_EXPORTER_OTLP_TRACES_ENDPOINT env var for Phoenix endpoint
+    configure_otel_providers(enable_sensitive_data=True)
+
+    # Add OpenInference processor to transform spans
+    tracer_provider = trace.get_tracer_provider()
+    if isinstance(tracer_provider, TracerProvider):
+        tracer_provider.add_span_processor(
+            AgentFrameworkToOpenInferenceProcessor()
+        )
+
+    # Use framework normally - spans will be transformed automatically
+    from agent_framework.openai import OpenAIChatClient
+
+    client = OpenAIChatClient(model_id="gpt-4o-mini")
+    agent = client.create_agent(name="Assistant")
+    response = await agent.run("Hello!")
+    ```
+"""
+
+__version__ = "0.1.0"
+
+from openinference.instrumentation.agent_framework.processor import (
+    AgentFrameworkToOpenInferenceProcessor,
+)
+from openinference.instrumentation.agent_framework.utils import is_openinference_span
+
+__all__ = [
+    "AgentFrameworkToOpenInferenceProcessor",
+    "is_openinference_span",
+    "__version__",
+]

openinference_instrumentation_agent_framework-0.1.0/src/openinference/instrumentation/agent_framework/package.py

@@ -0,0 +1,2 @@
+_instruments = ("agent-framework >= 0.1.0",)
+_supports_metrics = False

openinference_instrumentation_agent_framework-0.1.0/src/openinference/instrumentation/agent_framework/processor.py

@@ -0,0 +1,138 @@
+"""Microsoft Agent Framework to OpenInference Span Processor.
+
+This module provides a span processor that converts Microsoft Agent Framework's native
+OpenTelemetry spans (using GenAI semantic conventions) to OpenInference format for
+compatibility with OpenInference-compliant backends like Arize Phoenix.
+
+The processor transforms:
+- GenAI attributes (gen_ai.*) to OpenInference attributes (llm.*, tool.*, etc.)
+- Span names to OpenInference span kinds (AGENT, CHAIN, TOOL, LLM)
+- Message structures to OpenInference flattened format
+- Token usage attributes to OpenInference format
+"""
+
+import logging
+from typing import Any, Dict, Optional
+
+from opentelemetry.sdk.trace import ReadableSpan, SpanProcessor
+from opentelemetry.trace import Status, StatusCode
+
+from openinference.instrumentation.agent_framework import __version__
+from openinference.instrumentation.agent_framework.semantic_conventions import get_attributes
+from openinference.instrumentation.agent_framework.utils import SpanFilter, should_export_span
+
+logger = logging.getLogger(__name__)
+
+
+class AgentFrameworkToOpenInferenceProcessor(SpanProcessor):
+    """
+    SpanProcessor that converts Microsoft Agent Framework telemetry attributes
+    to OpenInference format for compatibility with OpenInference-compliant backends.
+
+    This processor intercepts spans on completion and transforms their attributes
+    from the GenAI semantic conventions used by Microsoft Agent Framework to the
+    OpenInference semantic conventions.
+
+    Usage:
+        ```python
+        from opentelemetry.sdk.trace import TracerProvider
+        from openinference.instrumentation.agent_framework import (
+            AgentFrameworkToOpenInferenceProcessor
+        )
+
+        provider = TracerProvider()
+        provider.add_span_processor(
+            AgentFrameworkToOpenInferenceProcessor(debug=False)
+        )
+        ```
+    """
+
+    def __init__(self, debug: bool = False, span_filter: Optional[SpanFilter] = None) -> None:
+        """
+        Initialize the processor.
+
+        Args:
+            debug: Whether to log debug information about transformations
+            span_filter: Optional filter function to determine if a span should be processed
+        """
+        super().__init__()
+        self.debug = debug
+        self._span_filter = span_filter
+
+    def on_start(self, span: ReadableSpan, parent_context: Any = None) -> None:
+        """Called when a span is started. No-op for this processor."""
+        pass
+
+    def on_end(self, span: ReadableSpan) -> None:
+        """
+        Called when a span ends. Transform the span attributes from Microsoft Agent
+        Framework GenAI format to OpenInference format.
+        """
+        if not hasattr(span, "_attributes") or not span._attributes:
+            return
+
+        try:
+            # Get span context information
+            span_id = span.get_span_context().span_id  # type: ignore[no-untyped-call]
+
+            # Get OpenInference attributes from the transformation function
+            openinference_attributes_iter = get_attributes(
+                dict(span._attributes), span.name, span_id
+            )
+            openinference_attributes = dict(openinference_attributes_iter)
+
+            # Merge with original attributes to preserve GenAI attributes that weren't transformed
+            span._attributes = {**span.attributes, **openinference_attributes}  # type: ignore[dict-item]
+
+            # MS Agent Framework only sets ERROR status, not OK - set OK for successful spans
+            if not span.status.status_code == StatusCode.ERROR:
+                span._status = Status(status_code=StatusCode.OK)
+
+            # Determine if the span should be exported
+            if should_export_span(span, self._span_filter):
+                super().on_end(span)
+
+            if self.debug:
+                logger.info(
+                    "span_name=<%s>, trans_attrs=<%d> | transformed span",
+                    span.name,
+                    len(openinference_attributes),
+                )
+
+        except Exception as e:
+            span._status = Status(status_code=StatusCode.ERROR, description=str(e))
+            logger.exception(e)
+            logger.warning(f"Error processing span in AgentFrameworkToOpenInferenceProcessor: {e}")
+
+    def shutdown(self) -> None:
+        """Shutdown the processor."""
+        pass
+
+    def force_flush(self, timeout_millis: Optional[int] = None) -> bool:
+        """Force flush any pending data."""
+        return True
+
+    def get_processor_info(self) -> Dict[str, Any]:
+        """Get information about this processor's capabilities."""
+        return {
+            "processor_name": "AgentFrameworkToOpenInferenceProcessor",
+            "version": __version__,
+            "debug_enabled": self.debug,
+            "supported_span_kinds": ["LLM", "AGENT", "CHAIN", "TOOL"],
+            "supported_operations": [
+                "chat",
+                "execute_tool",
+                "invoke_agent",
+                "create_agent",
+                "workflow.run",
+                "executor.process",
+            ],
+            "features": [
+                "Message extraction and transformation",
+                "Token usage mapping",
+                "Tool call processing",
+                "Graph node hierarchy mapping",
+                "Workflow/executor span support",
+                "Invocation parameters mapping",
+            ],
+        }

openinference_instrumentation_agent_framework-0.1.0/src/openinference/instrumentation/agent_framework/semantic_conventions.py

@@ -0,0 +1,587 @@
+"""Semantic conventions for Microsoft Agent Framework telemetry.
+
+This module defines attribute constants used by Microsoft Agent Framework's
+OpenTelemetry instrumentation and provides transformation functions to convert
+GenAI attributes to OpenInference format.
+
+Reference: agent_framework/observability.py OtelAttr enum
+"""
+
+import json
+import logging
+from typing import Any, Dict, Iterator, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
+
+# Operation names
+OPERATION = "gen_ai.operation.name"
+CHAT_COMPLETION_OPERATION = "chat"
+TOOL_EXECUTION_OPERATION = "execute_tool"
+AGENT_INVOKE_OPERATION = "invoke_agent"
+
+# Provider and system
+PROVIDER_NAME = "gen_ai.provider.name"
+
+# Request attributes
+LLM_REQUEST_MODEL = "gen_ai.request.model"
+LLM_REQUEST_MAX_TOKENS = "gen_ai.request.max_tokens"
+LLM_REQUEST_TEMPERATURE = "gen_ai.request.temperature"
+LLM_REQUEST_TOP_P = "gen_ai.request.top_p"
+
+# Response attributes
+LLM_RESPONSE_MODEL = "gen_ai.response.model"
+FINISH_REASONS = "gen_ai.response.finish_reasons"
+RESPONSE_ID = "gen_ai.response.id"
+
+# Usage attributes
+INPUT_TOKENS = "gen_ai.usage.input_tokens"
+OUTPUT_TOKENS = "gen_ai.usage.output_tokens"
+
+# Tool attributes
+TOOL_CALL_ID = "gen_ai.tool.call.id"
+TOOL_DESCRIPTION = "gen_ai.tool.description"
+TOOL_NAME = "gen_ai.tool.name"
+TOOL_DEFINITIONS = "gen_ai.tool.definitions"
+TOOL_ARGUMENTS = "gen_ai.tool.call.arguments"
+TOOL_RESULT = "gen_ai.tool.call.result"
+
+# Agent attributes
+AGENT_ID = "gen_ai.agent.id"
+AGENT_NAME = "gen_ai.agent.name"
+AGENT_DESCRIPTION = "gen_ai.agent.description"
+CONVERSATION_ID = "gen_ai.conversation.id"
+
+# Message attributes
+INPUT_MESSAGES = "gen_ai.input.messages"
+OUTPUT_MESSAGES = "gen_ai.output.messages"
+SYSTEM_INSTRUCTIONS = "gen_ai.system_instructions"
+
+# Workflow attributes
+WORKFLOW_ID = "workflow.id"
+WORKFLOW_NAME = "workflow.name"
+WORKFLOW_RUN_SPAN = "workflow.run"
+
+# Executor attributes
+EXECUTOR_ID = "executor.id"
+EXECUTOR_TYPE = "executor.type"
+EXECUTOR_PROCESS_SPAN = "executor.process"
+
+# Edge group attributes
+EDGE_GROUP_TYPE = "edge_group.type"
+EDGE_GROUP_ID = "edge_group.id"
+
+
+def safe_json_dumps(obj: Any) -> str:
+    """Safely serialize an object to JSON string.
+
+    Args:
+        obj: Object to serialize
+
+    Returns:
+        JSON string representation
+    """
+    try:
+        return json.dumps(obj, default=str, ensure_ascii=False)
+    except (TypeError, ValueError):
+        return str(obj)
+
+
+def get_attributes(
+    attrs: Dict[str, Any], span_name: str, span_id: int
+) -> Iterator[Tuple[str, Any]]:
+    """
+    Extract OpenInference attributes from Microsoft Agent Framework GenAI attributes.
+
+    Args:
+        attrs: Original span attributes with GenAI semantic conventions
+        span_name: The span name
+        span_id: The span context ID
+
+    Returns:
+        Iterator of (key, value) pairs for OpenInference attributes
+    """
+    # Determine span kind first as it affects other attribute extraction
+    span_kind = _determine_span_kind(span_name, attrs)
+    yield "openinference.span.kind", span_kind
+
+    # Extract graph node attributes for visualization hierarchy
+    yield from _extract_graph_node_attributes(span_id, attrs, span_kind)
+
+    # Extract model and provider info
+    yield from _extract_model_info(attrs)
+
+    # Extract messages (input and output)
+    input_messages, output_messages = _extract_messages(attrs)
+
+    # Extract token usage
+    yield from _extract_token_usage(attrs)
+
+    # Extract span-kind specific attributes
+    if span_kind in ["LLM", "AGENT"]:
+        yield from _extract_llm_agent_attributes(attrs, input_messages, output_messages, span_kind)
+    elif span_kind == "TOOL":
+        yield from _extract_tool_attributes(attrs)
+    elif span_kind == "CHAIN":
+        yield from _extract_chain_attributes(attrs, input_messages, output_messages)
+
+    # Extract session and invocation parameters
+    yield from _extract_session_info(attrs)
+    yield from _extract_invocation_parameters(attrs)
+
+    # Add remaining attributes as metadata
+    yield from _extract_metadata(attrs)
+
+
+def _determine_span_kind(span_name: str, attrs: Dict[str, Any]) -> str:
+    """Determine the OpenInference span kind based on MS Agent Framework operation."""
+    operation = attrs.get(OPERATION, "")
+
+    if operation == CHAT_COMPLETION_OPERATION:
+        return "LLM"
+    elif operation == TOOL_EXECUTION_OPERATION:
+        return "TOOL"
+    elif operation == AGENT_INVOKE_OPERATION:
+        return "AGENT"
+
+    if span_name.startswith("chat "):
+        return "LLM"
+    elif span_name.startswith("execute_tool "):
+        return "TOOL"
+    elif span_name.startswith("invoke_agent "):
+        return "AGENT"
+    elif span_name.startswith(WORKFLOW_RUN_SPAN):
+        return "CHAIN"
+    elif span_name.startswith(EXECUTOR_PROCESS_SPAN):
+        return "CHAIN"
+
+    if attrs.get(AGENT_NAME) or attrs.get(AGENT_ID):
+        return "AGENT"
+    if attrs.get(WORKFLOW_ID) or attrs.get(WORKFLOW_NAME):
+        return "CHAIN"
+    if attrs.get(EXECUTOR_ID) or attrs.get(EXECUTOR_TYPE):
+        return "CHAIN"
+
+    return "CHAIN"
+
+
+def _extract_graph_node_attributes(
+    span_id: int, attrs: Dict[str, Any], span_kind: str
+) -> Iterator[Tuple[str, Any]]:
+    """Set graph node attributes for visualization hierarchy."""
+    if span_kind == "AGENT":
+        agent_id = attrs.get(AGENT_ID, span_id)
+        yield "graph.node.id", f"agent_{agent_id}"
+        if agent_name := attrs.get(AGENT_NAME):
+            yield "graph.node.name", agent_name
+
+    elif span_kind == "LLM":
+        yield "graph.node.id", f"llm_{span_id}"
+        if agent_id := attrs.get(AGENT_ID):
+            yield "graph.node.parent_id", f"agent_{agent_id}"
+
+    elif span_kind == "TOOL":
+        tool_name = attrs.get(TOOL_NAME, "unknown_tool")
+        yield "graph.node.id", f"tool_{tool_name}_{span_id}"
+        yield "graph.node.name", tool_name
+
+    elif span_kind == "CHAIN":
+        if workflow_id := attrs.get(WORKFLOW_ID):
+            yield "graph.node.id", f"workflow_{workflow_id}"
+            if workflow_name := attrs.get(WORKFLOW_NAME):
+                yield "graph.node.name", workflow_name
+        elif executor_id := attrs.get(EXECUTOR_ID):
+            yield "graph.node.id", f"executor_{executor_id}"
+            if executor_type := attrs.get(EXECUTOR_TYPE):
+                yield "graph.node.name", executor_type
+        elif edge_group_id := attrs.get(EDGE_GROUP_ID):
+            yield "graph.node.id", f"edge_group_{edge_group_id}"
+            if edge_group_type := attrs.get(EDGE_GROUP_TYPE):
+                yield "graph.node.name", edge_group_type
+        else:
+            yield "graph.node.id", f"chain_{span_id}"
+
+
+def _extract_model_info(attrs: Dict[str, Any]) -> Iterator[Tuple[str, Any]]:
+    """Map model and provider information to OpenInference format."""
+    model_name = attrs.get(LLM_REQUEST_MODEL) or attrs.get(LLM_RESPONSE_MODEL)
+    if model_name:
+        yield "llm.model_name", model_name
+
+    if provider := attrs.get(PROVIDER_NAME):
+        yield "llm.provider", provider
+
+
+def _extract_messages(attrs: Dict[str, Any]) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
+    """Extract input and output messages from attributes."""
+    input_messages: List[Dict[str, Any]] = []
+    output_messages: List[Dict[str, Any]] = []
+
+    if input_msgs_raw := attrs.get(INPUT_MESSAGES):
+        input_messages = _parse_messages(input_msgs_raw)
+    if output_msgs_raw := attrs.get(OUTPUT_MESSAGES):
+        output_messages = _parse_messages(output_msgs_raw)
+
+    return input_messages, output_messages
+
+
+def _parse_messages(messages_raw: Any) -> List[Dict[str, Any]]:
+    """Parse messages from MS Agent Framework format."""
+    messages: List[Dict[str, Any]] = []
+
+    try:
+        if isinstance(messages_raw, str):
+            messages_data = json.loads(messages_raw)
+        else:
+            messages_data = messages_raw
+
+        if not isinstance(messages_data, list):
+            return messages
+
+        for msg in messages_data:
+            if not isinstance(msg, dict):
+                continue
+
+            parsed_msg = _parse_single_message(msg)
+            if parsed_msg:
+                messages.append(parsed_msg)
+
+    except (json.JSONDecodeError, TypeError) as e:
+        logger.debug(f"Failed to parse messages: {e}")
+
+    return messages
+
+
+def _parse_single_message(msg: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """Parse a single message from MS Agent Framework format to OpenInference format."""
+    role = msg.get("role", "user")
+    parts = msg.get("parts") or []
+
+    result: Dict[str, Any] = {"message.role": role}
+
+    text_content: List[str] = []
+    tool_calls: List[Dict[str, Any]] = []
+
+    for part in parts:
+        if not isinstance(part, dict):
+            continue
+
+        part_type = part.get("type", "")
+
+        if part_type == "text":
+            if content := part.get("content"):
+                text_content.append(str(content))
+
+        elif part_type == "reasoning":
+            if content := part.get("content"):
+                text_content.append(str(content))
+
+        elif part_type == "tool_call":
+            tool_call = {
+                "tool_call.id": part.get("id", ""),
+                "tool_call.function.name": part.get("name", ""),
+                "tool_call.function.arguments": safe_json_dumps(part.get("arguments", {})),
+            }
+            tool_calls.append(tool_call)
+
+        elif part_type == "tool_call_response":
+            result["message.role"] = "tool"
+            result["message.tool_call_id"] = part.get("id", "")
+            response = part.get("response", {})
+            if isinstance(response, dict):
+                text_content.append(safe_json_dumps(response))
+            else:
+                text_content.append(str(response))
+
+    if text_content:
+        result["message.content"] = " ".join(text_content)
+    if tool_calls:
+        result["message.tool_calls"] = tool_calls
+
+    if "message.content" not in result and "message.tool_calls" not in result:
+        return None
+
+    return result
+
+
+def _extract_token_usage(attrs: Dict[str, Any]) -> Iterator[Tuple[str, Any]]:
+    """Map token usage from GenAI format to OpenInference format."""
+    input_tokens = attrs.get(INPUT_TOKENS)
+    if input_tokens is not None:
+        yield "llm.token_count.prompt", input_tokens
+    output_tokens = attrs.get(OUTPUT_TOKENS)
+    if output_tokens is not None:
+        yield "llm.token_count.completion", output_tokens
+    if input_tokens is not None and output_tokens is not None:
+        yield "llm.token_count.total", input_tokens + output_tokens
+
+
+def _extract_llm_agent_attributes(
+    attrs: Dict[str, Any],
+    input_messages: List[Dict[str, Any]],
+    output_messages: List[Dict[str, Any]],
+    span_kind: str,
+) -> Iterator[Tuple[str, Any]]:
+    """Handle LLM and AGENT span attributes."""
+    if input_messages:
+        yield "llm.input_messages", safe_json_dumps(input_messages)
+        yield from _flatten_messages(input_messages, "llm.input_messages")
+
+    if output_messages:
+        yield "llm.output_messages", safe_json_dumps(output_messages)
+        yield from _flatten_messages(output_messages, "llm.output_messages")
+
+    yield from _create_input_output_values(attrs, input_messages, output_messages, span_kind)
+
+    if attrs.get(SYSTEM_INSTRUCTIONS) or attrs.get(AGENT_NAME):
+        yield "llm.system", "microsoft.agent_framework"
+
+    if tool_defs := attrs.get(TOOL_DEFINITIONS):
+        yield from _map_tools(tool_defs)
+
+
+def _flatten_messages(messages: List[Dict[str, Any]], key_prefix: str) -> Iterator[Tuple[str, Any]]:
+    """Flatten messages to dotted attribute notation for OpenInference."""
+    for idx, msg in enumerate(messages):
+        for key, value in msg.items():
+            clean_key = key.replace("message.", "") if key.startswith("message.") else key
+            dotted_key = f"{key_prefix}.{idx}.message.{clean_key}"
+
+            if clean_key == "tool_calls" and isinstance(value, list):
+                for tool_idx, tool_call in enumerate(value):
+                    if isinstance(tool_call, dict):
+                        for tool_key, tool_val in tool_call.items():
+                            tool_dotted_key = (
+                                f"{key_prefix}.{idx}.message.tool_calls.{tool_idx}.{tool_key}"
+                            )
+                            yield tool_dotted_key, _serialize_value(tool_val)
+            else:
+                yield dotted_key, _serialize_value(value)
+
+
+def _create_input_output_values(
+    attrs: Dict[str, Any],
+    input_messages: List[Dict[str, Any]],
+    output_messages: List[Dict[str, Any]],
+    span_kind: str,
+) -> Iterator[Tuple[str, Any]]:
+    """Create input.value and output.value attributes."""
+    model_name = attrs.get(LLM_REQUEST_MODEL, "unknown")
+
+    if span_kind in ["LLM", "AGENT"]:
+        if input_messages:
+            if len(input_messages) == 1 and input_messages[0].get("message.role") == "user":
+                yield "input.value", input_messages[0].get("message.content", "")
+                yield "input.mime_type", "text/plain"
+            else:
+                input_structure = {"messages": input_messages, "model": model_name}
+                yield "input.value", safe_json_dumps(input_structure)
+                yield "input.mime_type", "application/json"
+
+        if output_messages:
+            last_message = output_messages[-1]
+            content = last_message.get("message.content", "")
+
+            if span_kind == "LLM":
+                finish_reasons = attrs.get(FINISH_REASONS)
+                finish_reason = "stop"
+                if finish_reasons:
+                    try:
+                        reasons = (
+                            json.loads(finish_reasons)
+                            if isinstance(finish_reasons, str)
+                            else finish_reasons
+                        )
+                        if isinstance(reasons, list) and reasons:
+                            finish_reason = reasons[0]
+                    except (json.JSONDecodeError, TypeError):
+                        pass
+
+                # Get token counts if available
+                completion_tokens = attrs.get(OUTPUT_TOKENS)
+                prompt_tokens = attrs.get(INPUT_TOKENS)
+                total_tokens = None
+                if completion_tokens is not None and prompt_tokens is not None:
+                    total_tokens = completion_tokens + prompt_tokens
+
+                output_structure = {
+                    "choices": [
+                        {
+                            "finish_reason": finish_reason,
+                            "index": 0,
+                            "message": {
+                                "content": content,
+                                "role": last_message.get("message.role", "assistant"),
+                            },
+                        }
+                    ],
+                    "model": model_name,
+                    "usage": {
+                        "completion_tokens": completion_tokens,
+                        "prompt_tokens": prompt_tokens,
+                        "total_tokens": total_tokens,
+                    },
+                }
+                yield "output.value", safe_json_dumps(output_structure)
+                yield "output.mime_type", "application/json"
+            else:
+                yield "output.value", content
+                yield "output.mime_type", "text/plain"
+
+
+def _extract_tool_attributes(attrs: Dict[str, Any]) -> Iterator[Tuple[str, Any]]:
+    """Handle TOOL span attributes."""
+    if tool_name := attrs.get(TOOL_NAME):
+        yield "tool.name", tool_name
+    if tool_call_id := attrs.get(TOOL_CALL_ID):
+        yield "tool.call_id", tool_call_id
+    if tool_desc := attrs.get(TOOL_DESCRIPTION):
+        yield "tool.description", tool_desc
+
+    if tool_args := attrs.get(TOOL_ARGUMENTS):
+        if isinstance(tool_args, str):
+            yield "tool.parameters", tool_args
+            yield "input.value", tool_args
+        else:
+            yield "tool.parameters", safe_json_dumps(tool_args)
+            yield "input.value", safe_json_dumps(tool_args)
+        yield "input.mime_type", "application/json"
+
+    if tool_result := attrs.get(TOOL_RESULT):
+        if isinstance(tool_result, str):
+            yield "output.value", tool_result
+        else:
+            yield "output.value", safe_json_dumps(tool_result)
+        yield "output.mime_type", "text/plain"
+
+
+def _extract_chain_attributes(
+    attrs: Dict[str, Any],
+    input_messages: List[Dict[str, Any]],
+    output_messages: List[Dict[str, Any]],
+) -> Iterator[Tuple[str, Any]]:
+    """Handle CHAIN span attributes (workflows, executors)."""
+    if input_messages:
+        for msg in input_messages:
+            if msg.get("message.role") == "user":
+                if content := msg.get("message.content"):
+                    yield "input.value", content
+                    yield "input.mime_type", "text/plain"
+                    break
+
+    if output_messages:
+        for msg in reversed(output_messages):
+            if msg.get("message.role") == "assistant":
+                if content := msg.get("message.content"):
+                    yield "output.value", content
+                    yield "output.mime_type", "text/plain"
+                    break
+
+
+def _extract_session_info(attrs: Dict[str, Any]) -> Iterator[Tuple[str, Any]]:
+    """Map session and conversation info."""
+    if conversation_id := attrs.get(CONVERSATION_ID):
+        yield "session.id", conversation_id
+
+
+def _extract_invocation_parameters(attrs: Dict[str, Any]) -> Iterator[Tuple[str, Any]]:
+    """Map invocation parameters to OpenInference format."""
+    params: Dict[str, Any] = {}
+
+    param_mappings = {
+        LLM_REQUEST_MAX_TOKENS: "max_tokens",
+        LLM_REQUEST_TEMPERATURE: "temperature",
+        LLM_REQUEST_TOP_P: "top_p",
+    }
+
+    for attr_key, param_key in param_mappings.items():
+        if attr_key in attrs:
+            params[param_key] = attrs[attr_key]
+
+    if params:
+        yield "llm.invocation_parameters", safe_json_dumps(params)
+
+
+def _map_tools(tools_data: Any) -> Iterator[Tuple[str, Any]]:
+    """Map tool definitions to OpenInference format."""
+    try:
+        if isinstance(tools_data, str):
+            tools_data = json.loads(tools_data)
+
+        if not isinstance(tools_data, list):
+            return
+
+        for idx, tool in enumerate(tools_data):
+            if isinstance(tool, dict):
+                if name := tool.get("name"):
+                    yield f"llm.tools.{idx}.tool.name", name
+                if desc := tool.get("description"):
+                    yield f"llm.tools.{idx}.tool.description", desc
+                # Handle function schema
+                if "function" in tool:
+                    func = tool["function"]
+                    if isinstance(func, dict):
+                        if fname := func.get("name"):
+                            yield f"llm.tools.{idx}.tool.name", fname
+                        if fdesc := func.get("description"):
+                            yield f"llm.tools.{idx}.tool.description", fdesc
+                        if params := func.get("parameters"):
+                            yield f"llm.tools.{idx}.tool.json_schema", safe_json_dumps(params)
+                elif params := tool.get("parameters"):
+                    yield f"llm.tools.{idx}.tool.json_schema", safe_json_dumps(params)
+                elif input_schema := tool.get("input_schema"):
+                    yield f"llm.tools.{idx}.tool.json_schema", safe_json_dumps(input_schema)
+
+    except (json.JSONDecodeError, TypeError) as e:
+        logger.debug(f"Failed to parse tools: {e}")
+
+
+def _extract_metadata(attrs: Dict[str, Any]) -> Iterator[Tuple[str, Any]]:
+    """Add remaining attributes as metadata."""
+    metadata: Dict[str, Any] = {}
+    skip_keys = {
+        OPERATION,
+        PROVIDER_NAME,
+        LLM_REQUEST_MODEL,
+        LLM_RESPONSE_MODEL,
+        INPUT_TOKENS,
+        OUTPUT_TOKENS,
+        INPUT_MESSAGES,
+        OUTPUT_MESSAGES,
+        TOOL_NAME,
+        TOOL_CALL_ID,
+        TOOL_ARGUMENTS,
+        TOOL_RESULT,
+        TOOL_DESCRIPTION,
+        TOOL_DEFINITIONS,
+        AGENT_ID,
+        AGENT_NAME,
+        AGENT_DESCRIPTION,
+        CONVERSATION_ID,
+        FINISH_REASONS,
+        RESPONSE_ID,
+        SYSTEM_INSTRUCTIONS,
+        LLM_REQUEST_MAX_TOKENS,
+        LLM_REQUEST_TEMPERATURE,
+        LLM_REQUEST_TOP_P,
+        WORKFLOW_ID,
+        WORKFLOW_NAME,
+        EXECUTOR_ID,
+        EXECUTOR_TYPE,
+        EDGE_GROUP_ID,
+        EDGE_GROUP_TYPE,
+    }
+
+    for key, value in attrs.items():
+        if key not in skip_keys:
+            metadata[key] = _serialize_value(value)
+
+    if metadata:
+        yield "metadata", safe_json_dumps(metadata)
+
+
+def _serialize_value(value: Any) -> Any:
+    """Serialize a value for span attributes."""
+    if isinstance(value, (str, int, float, bool)) or value is None:
+        return value
+    return safe_json_dumps(value)

openinference_instrumentation_agent_framework-0.1.0/src/openinference/instrumentation/agent_framework/utils.py

@@ -0,0 +1,23 @@
+from typing import Callable, Optional
+
+from opentelemetry.sdk.trace import ReadableSpan
+
+from openinference.semconv.trace import SpanAttributes
+
+# Define types for span filtering
+SpanFilter = Callable[[ReadableSpan], bool]
+
+
+def is_openinference_span(span: ReadableSpan) -> bool:
+    """Check if a span is an OpenInference span."""
+    if span.attributes is None:
+        return False
+    return SpanAttributes.OPENINFERENCE_SPAN_KIND in span.attributes
+
+
+def should_export_span(span: ReadableSpan, span_filter: Optional[SpanFilter] = None) -> bool:
+    """Determine if a span should be exported based on a filter."""
+    if span_filter is None:
+        return True
+
+    return span_filter(span)