agentrun-sdk 0.1.2__py3-none-any.whl

agentrun_sdk/session/session_manager.py

@@ -0,0 +1,73 @@
+"""Session manager interface for agent session management."""
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+from ..hooks.events import AfterInvocationEvent, AgentInitializedEvent, MessageAddedEvent
+from ..hooks.registry import HookProvider, HookRegistry
+from ..types.content import Message
+
+if TYPE_CHECKING:
+    from ..agent.agent import Agent
+
+
+class SessionManager(HookProvider, ABC):
+    """Abstract interface for managing sessions.
+
+    A session manager is in charge of persisting the conversation and state of an agent across its interaction.
+    Changes made to the agents conversation, state, or other attributes should be persisted immediately after
+    they are changed. The different methods introduced in this class are called at important lifecycle events
+    for an agent, and should be persisted in the session.
+    """
+
+    def register_hooks(self, registry: HookRegistry, **kwargs: Any) -> None:
+        """Register hooks for persisting the agent to the session."""
+        # After the normal Agent initialization behavior, call the session initialize function to restore the agent
+        registry.add_callback(AgentInitializedEvent, lambda event: self.initialize(event.agent))
+
+        # For each message appended to the Agents messages, store that message in the session
+        registry.add_callback(MessageAddedEvent, lambda event: self.append_message(event.message, event.agent))
+
+        # Sync the agent into the session for each message in case the agent state was updated
+        registry.add_callback(MessageAddedEvent, lambda event: self.sync_agent(event.agent))
+
+        # After an agent was invoked, sync it with the session to capture any conversation manager state updates
+        registry.add_callback(AfterInvocationEvent, lambda event: self.sync_agent(event.agent))
+
+    @abstractmethod
+    def redact_latest_message(self, redact_message: Message, agent: "Agent", **kwargs: Any) -> None:
+        """Redact the message most recently appended to the agent in the session.
+
+        Args:
+            redact_message: New message to use that contains the redact content
+            agent: Agent to apply the message redaction to
+            **kwargs: Additional keyword arguments for future extensibility.
+        """
+
+    @abstractmethod
+    def append_message(self, message: Message, agent: "Agent", **kwargs: Any) -> None:
+        """Append a message to the agent's session.
+
+        Args:
+            message: Message to add to the agent in the session
+            agent: Agent to append the message to
+            **kwargs: Additional keyword arguments for future extensibility.
+        """
+
+    @abstractmethod
+    def sync_agent(self, agent: "Agent", **kwargs: Any) -> None:
+        """Serialize and sync the agent with the session storage.
+
+        Args:
+            agent: Agent who should be synchronized with the session storage
+            **kwargs: Additional keyword arguments for future extensibility.
+        """
+
+    @abstractmethod
+    def initialize(self, agent: "Agent", **kwargs: Any) -> None:
+        """Initialize an agent with a session.
+
+        Args:
+            agent: Agent to initialize
+            **kwargs: Additional keyword arguments for future extensibility.
+        """

agentrun_sdk/session/session_repository.py

@@ -0,0 +1,51 @@
+"""Session repository interface for agent session management."""
+
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+
+from ..types.session import Session, SessionAgent, SessionMessage
+
+
+class SessionRepository(ABC):
+    """Abstract repository for creating, reading, and updating Sessions, AgentSessions, and AgentMessages."""
+
+    @abstractmethod
+    def create_session(self, session: Session, **kwargs: Any) -> Session:
+        """Create a new Session."""
+
+    @abstractmethod
+    def read_session(self, session_id: str, **kwargs: Any) -> Optional[Session]:
+        """Read a Session."""
+
+    @abstractmethod
+    def create_agent(self, session_id: str, session_agent: SessionAgent, **kwargs: Any) -> None:
+        """Create a new Agent in a Session."""
+
+    @abstractmethod
+    def read_agent(self, session_id: str, agent_id: str, **kwargs: Any) -> Optional[SessionAgent]:
+        """Read an Agent."""
+
+    @abstractmethod
+    def update_agent(self, session_id: str, session_agent: SessionAgent, **kwargs: Any) -> None:
+        """Update an Agent."""
+
+    @abstractmethod
+    def create_message(self, session_id: str, agent_id: str, session_message: SessionMessage, **kwargs: Any) -> None:
+        """Create a new Message for the Agent."""
+
+    @abstractmethod
+    def read_message(self, session_id: str, agent_id: str, message_id: int, **kwargs: Any) -> Optional[SessionMessage]:
+        """Read a Message."""
+
+    @abstractmethod
+    def update_message(self, session_id: str, agent_id: str, session_message: SessionMessage, **kwargs: Any) -> None:
+        """Update a Message.
+
+        A message is usually only updated when some content is redacted due to a guardrail.
+        """
+
+    @abstractmethod
+    def list_messages(
+        self, session_id: str, agent_id: str, limit: Optional[int] = None, offset: int = 0, **kwargs: Any
+    ) -> list[SessionMessage]:
+        """List Messages from an Agent with pagination."""

agentrun_sdk/telemetry/__init__.py

@@ -0,0 +1,21 @@
+"""Telemetry module.
+
+This module provides metrics and tracing functionality.
+"""
+
+from .config import StrandsTelemetry
+from .metrics import EventLoopMetrics, MetricsClient, Trace, metrics_to_string
+from .tracer import Tracer, get_tracer
+
+__all__ = [
+    # Metrics
+    "EventLoopMetrics",
+    "Trace",
+    "metrics_to_string",
+    "MetricsClient",
+    # Tracer
+    "Tracer",
+    "get_tracer",
+    # Telemetry Setup
+    "StrandsTelemetry",
+]

agentrun_sdk/telemetry/config.py

@@ -0,0 +1,194 @@
+"""OpenTelemetry configuration and setup utilities for Strands agents.
+
+This module provides centralized configuration and initialization functionality
+for OpenTelemetry components and other telemetry infrastructure shared across Strands applications.
+"""
+
+import logging
+from importlib.metadata import version
+from typing import Any
+
+import opentelemetry.metrics as metrics_api
+import opentelemetry.sdk.metrics as metrics_sdk
+import opentelemetry.trace as trace_api
+from opentelemetry import propagate
+from opentelemetry.baggage.propagation import W3CBaggagePropagator
+from opentelemetry.propagators.composite import CompositePropagator
+from opentelemetry.sdk.metrics.export import ConsoleMetricExporter, PeriodicExportingMetricReader
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider as SDKTracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter, SimpleSpanProcessor
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+
+logger = logging.getLogger(__name__)
+
+
+def get_otel_resource() -> Resource:
+    """Create a standard OpenTelemetry resource with service information.
+
+    Returns:
+        Resource object with standard service information.
+    """
+    resource = Resource.create(
+        {
+            "service.name": "strands-agents",
+            "service.version": version("strands-agents"),
+            "telemetry.sdk.name": "opentelemetry",
+            "telemetry.sdk.language": "python",
+        }
+    )
+
+    return resource
+
+
+class StrandsTelemetry:
+    """OpenTelemetry configuration and setup for Strands applications.
+
+    Automatically initializes a tracer provider with text map propagators.
+    Trace exporters (console, OTLP) can be set up individually using dedicated methods
+    that support method chaining for convenient configuration.
+
+    Args:
+        tracer_provider: Optional pre-configured SDKTracerProvider. If None,
+            a new one will be created and set as the global tracer provider.
+
+    Environment Variables:
+        Environment variables are handled by the underlying OpenTelemetry SDK:
+        - OTEL_EXPORTER_OTLP_ENDPOINT: OTLP endpoint URL
+        - OTEL_EXPORTER_OTLP_HEADERS: Headers for OTLP requests
+
+    Examples:
+        Quick setup with method chaining:
+        >>> StrandsTelemetry().setup_console_exporter().setup_otlp_exporter()
+
+        Using a custom tracer provider:
+        >>> StrandsTelemetry(tracer_provider=my_provider).setup_console_exporter()
+
+        Step-by-step configuration:
+        >>> telemetry = StrandsTelemetry()
+        >>> telemetry.setup_console_exporter()
+        >>> telemetry.setup_otlp_exporter()
+
+        To setup global meter provider
+        >>> telemetry.setup_meter(enable_console_exporter=True, enable_otlp_exporter=True) # default are False
+
+    Note:
+        - The tracer provider is automatically initialized upon instantiation
+        - When no tracer_provider is provided, the instance sets itself as the global provider
+        - Exporters must be explicitly configured using the setup methods
+        - Failed exporter configurations are logged but do not raise exceptions
+        - All setup methods return self to enable method chaining
+    """
+
+    def __init__(
+        self,
+        tracer_provider: SDKTracerProvider | None = None,
+    ) -> None:
+        """Initialize the StrandsTelemetry instance.
+
+        Args:
+            tracer_provider: Optional pre-configured tracer provider.
+                If None, a new one will be created and set as global.
+
+        The instance is ready to use immediately after initialization, though
+        trace exporters must be configured separately using the setup methods.
+        """
+        self.resource = get_otel_resource()
+        if tracer_provider:
+            self.tracer_provider = tracer_provider
+        else:
+            self._initialize_tracer()
+
+    def _initialize_tracer(self) -> None:
+        """Initialize the OpenTelemetry tracer."""
+        logger.info("Initializing tracer")
+
+        # Create tracer provider
+        self.tracer_provider = SDKTracerProvider(resource=self.resource)
+
+        # Set as global tracer provider
+        trace_api.set_tracer_provider(self.tracer_provider)
+
+        # Set up propagators
+        propagate.set_global_textmap(
+            CompositePropagator(
+                [
+                    W3CBaggagePropagator(),
+                    TraceContextTextMapPropagator(),
+                ]
+            )
+        )
+
+    def setup_console_exporter(self, **kwargs: Any) -> "StrandsTelemetry":
+        """Set up console exporter for the tracer provider.
+
+        Args:
+            **kwargs: Optional keyword arguments passed directly to
+                OpenTelemetry's ConsoleSpanExporter initializer.
+
+        Returns:
+            self: Enables method chaining.
+
+        This method configures a SimpleSpanProcessor with a ConsoleSpanExporter,
+        allowing trace data to be output to the console. Any additional keyword
+        arguments provided will be forwarded to the ConsoleSpanExporter.
+        """
+        try:
+            logger.info("Enabling console export")
+            console_processor = SimpleSpanProcessor(ConsoleSpanExporter(**kwargs))
+            self.tracer_provider.add_span_processor(console_processor)
+        except Exception as e:
+            logger.exception("error=<%s> | Failed to configure console exporter", e)
+        return self
+
+    def setup_otlp_exporter(self, **kwargs: Any) -> "StrandsTelemetry":
+        """Set up OTLP exporter for the tracer provider.
+
+        Args:
+            **kwargs: Optional keyword arguments passed directly to
+                OpenTelemetry's OTLPSpanExporter initializer.
+
+        Returns:
+            self: Enables method chaining.
+
+        This method configures a BatchSpanProcessor with an OTLPSpanExporter,
+        allowing trace data to be exported to an OTLP endpoint. Any additional
+        keyword arguments provided will be forwarded to the OTLPSpanExporter.
+        """
+        from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+
+        try:
+            otlp_exporter = OTLPSpanExporter(**kwargs)
+            batch_processor = BatchSpanProcessor(otlp_exporter)
+            self.tracer_provider.add_span_processor(batch_processor)
+            logger.info("OTLP exporter configured")
+        except Exception as e:
+            logger.exception("error=<%s> | Failed to configure OTLP exporter", e)
+        return self
+
+    def setup_meter(
+        self, enable_console_exporter: bool = False, enable_otlp_exporter: bool = False
+    ) -> "StrandsTelemetry":
+        """Initialize the OpenTelemetry Meter."""
+        logger.info("Initializing meter")
+        metrics_readers = []
+        try:
+            if enable_console_exporter:
+                logger.info("Enabling console metrics exporter")
+                console_reader = PeriodicExportingMetricReader(ConsoleMetricExporter())
+                metrics_readers.append(console_reader)
+            if enable_otlp_exporter:
+                logger.info("Enabling OTLP metrics exporter")
+                from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
+
+                otlp_reader = PeriodicExportingMetricReader(OTLPMetricExporter())
+                metrics_readers.append(otlp_reader)
+        except Exception as e:
+            logger.exception("error=<%s> | Failed to configure OTLP metrics exporter", e)
+
+        self.meter_provider = metrics_sdk.MeterProvider(resource=self.resource, metric_readers=metrics_readers)
+
+        # Set as global tracer provider
+        metrics_api.set_meter_provider(self.meter_provider)
+        logger.info("Strands Meter configured")
+        return self