agentic-layer-sdk 0.13.2__py3-none-any.whl

agentic_layer_sdk-0.13.2.dist-info/METADATA

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: agentic-layer-sdk
+Version: 0.13.2
+Requires-Python: <3.15,>=3.14
+Requires-Dist: a2a-sdk
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc
+Requires-Dist: opentelemetry-exporter-otlp-proto-http
+Requires-Dist: opentelemetry-instrumentation-httpx
+Requires-Dist: opentelemetry-instrumentation-starlette
+Requires-Dist: pydantic>=2
+Requires-Dist: starlette
+Description-Content-Type: text/markdown
+
+# agentic-layer-sdk
+
+Framework-independent shared utilities for the Agentic Layer SDK.
+
+This package contains common code used by all agent framework adapters:
+- Configuration models (`SubAgent`, `McpTool`)
+- Constants
+- Logging setup (loguru)
+- OpenTelemetry setup
+- Starlette OpenTelemetry instrumentation

agentic_layer_sdk-0.13.2.dist-info/RECORD

@@ -0,0 +1,9 @@
+agenticlayer/_otel.py,sha256=K2qoSbC7kV7mkubuTtlh0QYUQKKKMpyaq51lT4JwRY0,4123
+agenticlayer/config.py,sha256=mL7rinG2Uv5bn5xxN6Ap2FB6dE5BWKjKSWMCRRfiABc,1998
+agenticlayer/constants.py,sha256=pdY0MPJp-nYHFHvok3slQLg7GVCfYXXYDjtcdY_e9ro,347
+agenticlayer/loguru_config.py,sha256=muEe9Jiy2DwZDWwqx4Wtu1oeQao6HXgXYGG_ZqPj734,4282
+agenticlayer/otel_starlette.py,sha256=akDLnoFWjM0xunO8eh1dvP2SWZpgbeTvL2tW1B7dlJM,3822
+agenticlayer/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentic_layer_sdk-0.13.2.dist-info/METADATA,sha256=v2X-dU9K12LehM0iexWAPawZRoEl33gi4gLob8qIFS0,759
+agentic_layer_sdk-0.13.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+agentic_layer_sdk-0.13.2.dist-info/RECORD,,

agentic_layer_sdk-0.13.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agenticlayer/_otel.py

@@ -0,0 +1,98 @@
+"""Framework-independent OpenTelemetry setup."""
+
+import logging
+import os
+
+import httpx
+from opentelemetry import metrics, trace
+from opentelemetry._logs import set_logger_provider
+from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
+from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
+from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
+from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
+from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+_logger = logging.getLogger(__name__)
+
+
+def _is_text_content(content_type: str) -> bool:
+    """Check if content type is text-based and safe to log."""
+    text_types = ("application/json", "application/xml", "text/", "application/x-www-form-urlencoded")
+    return any(ct in content_type.lower() for ct in text_types)
+
+
+def _decode_body(body: bytes) -> str:
+    """Decode body bytes to string."""
+    return body.decode("utf-8", errors="replace")
+
+
+def request_hook(span: trace.Span, request: httpx.Request) -> None:
+    """Hook to log request body at DEBUG level."""
+    try:
+        # Skip streaming requests to avoid consuming the stream
+        if hasattr(request, "stream") and request.stream is not None:
+            return
+
+        content_type = request.headers.get("content-type", "")
+        if _is_text_content(content_type) and hasattr(request, "content") and request.content:
+            _logger.debug("HTTP request body: %s", _decode_body(request.content))
+    except Exception:
+        _logger.exception("Failed to log request body")
+
+
+def response_hook(span: trace.Span, request: httpx.Request, response: httpx.Response) -> None:
+    """Hook to log response body at DEBUG level."""
+    try:
+        # Skip streaming responses to avoid consuming the stream
+        if hasattr(response, "is_stream_consumed") and not response.is_stream_consumed:
+            return
+
+        content_type = response.headers.get("content-type", "")
+        if _is_text_content(content_type) and hasattr(response, "content") and response.content:
+            _logger.debug("HTTP response body: %s", _decode_body(response.content))
+    except Exception:
+        _logger.exception("Failed to log response body")
+
+
+def setup_otel() -> None:
+    """Set up OpenTelemetry tracing, logging and metrics (framework-independent)."""
+    # Set log level for urllib to WARNING to reduce noise (like sending logs to OTLP)
+    logging.getLogger("urllib3").setLevel(logging.WARNING)
+
+    # Traces
+    trace_provider = TracerProvider()
+    if os.environ.get("OTEL_EXPORTER_OTLP_PROTOCOL", "grpc") == "grpc":
+        from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter as OTLPSpanExporterGrpc
+
+        trace_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporterGrpc()))
+    else:
+        from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter as OTLPSpanExporterHttp
+
+        trace_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporterHttp()))
+    trace.set_tracer_provider(trace_provider)
+
+    # Instrument HTTPX clients (this also transfers the trace context automatically)
+    HTTPXClientInstrumentor().instrument(
+        request_hook=request_hook,
+        response_hook=response_hook,
+    )
+
+    # Logs
+    logger_provider = LoggerProvider()
+    logger_provider.add_log_record_processor(BatchLogRecordProcessor(OTLPLogExporter()))
+    # Sets the global default logger provider
+    set_logger_provider(logger_provider)
+
+    # Attach OTLP handler to root logger
+    logging.getLogger().addHandler(LoggingHandler(level=logging.NOTSET, logger_provider=logger_provider))
+
+    # Sets the global default meter provider
+    metrics.set_meter_provider(
+        MeterProvider(
+            metric_readers=[PeriodicExportingMetricReader(OTLPMetricExporter())],
+        )
+    )

agenticlayer/config.py

@@ -0,0 +1,75 @@
+"""
+Configuration parsing for sub-agents and tools.
+Parses JSON configurations to create RemoteA2aAgents, AgentTools and McpToolsets.
+"""
+
+import json
+from enum import Enum
+
+from pydantic import AnyHttpUrl, BaseModel
+
+
+class InteractionType(str, Enum):
+    TOOL_CALL = "tool_call"
+    TRANSFER = "transfer"
+
+
+class SubAgent(BaseModel):
+    name: str
+    url: AnyHttpUrl
+    interaction_type: InteractionType = InteractionType.TOOL_CALL
+
+
+class McpTool(BaseModel):
+    name: str
+    url: AnyHttpUrl
+    timeout: int = 30
+    propagate_headers: list[str] = []
+
+
+def parse_sub_agents(sub_agents_config: str) -> list[SubAgent]:
+    """
+    Get sub agents from JSON string.
+    Format: {"agent_name": {"url": "http://agent_url", "interaction_type", "transfer|tool_call"}, ...}
+
+    :return: A tuple of:
+        - list of sub agents for transfer interaction type
+        - list of agent tools for tool_call interaction type
+    """
+
+    try:
+        agents_map = json.loads(sub_agents_config)
+    except json.JSONDecodeError as e:
+        raise ValueError("Warning: Invalid JSON in SUB_AGENTS environment variable: " + sub_agents_config, e)
+
+    return [
+        SubAgent(
+            name=agent_name,
+            url=config["url"],
+            interaction_type=InteractionType(config.get("interaction_type", "tool_call")),
+        )
+        for agent_name, config in agents_map.items()
+    ]
+
+
+def parse_tools(tools_config: str) -> list[McpTool]:
+    """
+    Get tools from JSON string.
+    Format: {"tool_name": {"url": "http://tool_url", "timeout": 30}, ...}
+
+    :return: A list of McpToolset tools
+    """
+
+    try:
+        tools_map = json.loads(tools_config)
+    except json.JSONDecodeError as e:
+        raise ValueError("Warning: Invalid JSON in AGENT_TOOLS environment variable: " + tools_config, e)
+
+    return [
+        McpTool(
+            name=name,
+            url=config["url"],
+            timeout=config.get("timeout", 30),
+        )
+        for name, config in tools_map.items()
+    ]

agenticlayer/constants.py

@@ -0,0 +1,6 @@
+"""Constants shared across the agenticlayer package."""
+
+# Prefix used to store propagated HTTP headers in ADK session state as flat primitive keys.
+# Each header is stored as a separate string entry: f"{HTTP_HEADERS_SESSION_KEY}.{header_name_lower}"
+# e.g. "http_headers.authorization" -> "Bearer token"
+HTTP_HEADERS_SESSION_KEY = "http_headers"

agenticlayer/loguru_config.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import inspect
+import json
+import logging
+import os
+import sys
+import traceback
+from logging import Logger
+from typing import Callable, NotRequired, TextIO, TypedDict, Union
+
+import loguru
+from loguru import logger
+
+
+class JsonRecord(TypedDict):
+    timestamp: str
+    name: str | None
+    level: str
+    message: str
+    function: str
+    module: str
+    line: int
+    exception: NotRequired[dict[str, str]]
+
+
+def _serialize(record: loguru.Record) -> str:
+    log: JsonRecord = {
+        "timestamp": record["time"].isoformat(),
+        "name": record["name"],
+        "level": record["level"].name,
+        "message": record["message"],
+        "function": record["function"],
+        "module": record["module"],
+        "line": record["line"],
+    }
+
+    if record["exception"] is not None:
+        log["exception"] = {
+            "stack": "".join(
+                traceback.format_exception(
+                    record["exception"].type,
+                    record["exception"].value,
+                    record["exception"].traceback,
+                )
+            ),
+            "kind": getattr(record["exception"].type, "__name__", "None"),
+            "message": str(record["exception"].value),
+        }
+
+    return json.dumps(log)
+
+
+def _json_sink(message: loguru.Message) -> None:
+    serialized = _serialize(message.record)
+    sys.stderr.write(serialized + "\n")
+
+
+def _configure_loguru() -> None:
+    sink: Union[TextIO, Callable[[loguru.Message], None]]
+    log_format = os.environ.get("LOG_FORMAT", "Text")
+    if log_format == "JSON":
+        sink = _json_sink
+    else:
+        sink = sys.stderr
+
+    log_level = os.environ.get("LOGLEVEL", "INFO")
+
+    logger.remove()
+    logger.add(
+        sink,
+        # Log INFO by default
+        filter={
+            "": log_level,
+            # Reduce verbosity of some noisy loggers
+            "a2a.utils.telemetry": "INFO",
+        },
+    )
+
+
+def setup_logging() -> None:
+    """Initializes the application so that logging is handled by loguru"""
+
+    _configure_loguru()
+
+    # Some libraries we use log to standard logging and not to loguru. To also get the logs from these frameworks, we
+    # add a handler to the root logger of standard logging, that converts the log entries to loguru. This way
+    # loguru has the final say regarding logging, and we don't get a mixture of both logging frameworks
+    logging.basicConfig(handlers=[InterceptHandler()], level=logging.NOTSET, force=True)
+
+    # We have to replace the existing handlers from the loggers we want to intercept as well.
+    for _log, _logger in logging.root.manager.loggerDict.items():
+        # print("Checking logger: ", _log, " ", _logger)
+        if not isinstance(_logger, Logger) or len(_logger.handlers) == 0:
+            # logger not yet created or no custom handlers. Skipping
+            continue
+        for handler in _logger.handlers:
+            if not isinstance(handler, logging.StreamHandler):
+                # We only replace stream handlers, which write to the console
+                # NullHandlers and other handlers are not replaced
+                continue
+            _logger.removeHandler(handler)
+            _logger.addHandler(InterceptHandler())
+
+            # Prevent duplicate logs
+            if _logger.propagate:
+                logger.debug("Disable propagate for logger {}", _log)
+                _logger.propagate = False
+
+
+class InterceptHandler(logging.Handler):
+    """
+    A Handler for the standard python logging that sends all incoming logs to loguru. Taken from the loguru documentation
+    https://loguru.readthedocs.io/en/stable/overview.html
+    """
+
+    def emit(self, record: logging.LogRecord) -> None:
+        # Get corresponding Loguru level if it exists.
+        level: str | int
+        try:
+            level = logger.level(record.levelname).name
+        except ValueError:
+            level = record.levelno
+
+        # Find caller from where originated the logged message.
+        frame, depth = inspect.currentframe(), 0
+        while frame and (depth == 0 or frame.f_code.co_filename == logging.__file__):
+            frame = frame.f_back
+            depth += 1
+
+        logger.opt(depth=depth, exception=record.exc_info).log(level, record.getMessage())

agenticlayer/otel_starlette.py

@@ -0,0 +1,94 @@
+"""OpenTelemetry instrumentation for Starlette applications."""
+
+import logging
+import os
+from typing import Any, Dict
+
+from a2a.utils.constants import AGENT_CARD_WELL_KNOWN_PATH
+from opentelemetry import trace
+from starlette.applications import Starlette
+
+from ._otel import _decode_body, _is_text_content
+
+_logger = logging.getLogger(__name__)
+
+
+def _starlette_server_request_hook(span: trace.Span, scope: Dict[str, Any]) -> None:
+    """Hook to log Starlette request body at DEBUG level if enabled.
+
+    Note: This captures the body from the ASGI scope's cached body if available.
+    It does not consume the request stream to avoid breaking request handling.
+    """
+
+    try:
+        # Only process HTTP requests
+        if scope.get("type") != "http":
+            return
+
+        # Check if body is cached in scope (some middleware/frameworks cache it)
+        # Don't try to read the stream directly as it would consume it
+        if "body" in scope:
+            body = scope["body"]
+            if body:
+                # Get content type from headers
+                headers = dict(scope.get("headers", []))
+                content_type = headers.get(b"content-type", b"").decode("latin1")
+
+                if _is_text_content(content_type):
+                    _logger.debug("Starlette request body: %s", _decode_body(body))
+    except Exception:
+        _logger.exception("Failed to log Starlette request body")
+
+
+def _starlette_client_request_hook(span: trace.Span, scope: Dict[str, Any], message: Dict[str, Any]) -> None:
+    """Hook to log Starlette client request body at DEBUG level if enabled."""
+    try:
+        # Capture body from the message if available and it's the body message
+        if message.get("type") == "http.request" and "body" in message:
+            body = message["body"]
+            if body:
+                # Get content type from scope headers
+                headers = dict(scope.get("headers", []))
+                content_type = headers.get(b"content-type", b"").decode("latin1")
+
+                if _is_text_content(content_type):
+                    _logger.debug("Starlette client request body: %s", _decode_body(body))
+    except Exception:
+        _logger.exception("Failed to log Starlette client request body")
+
+
+def _starlette_client_response_hook(span: trace.Span, scope: Dict[str, Any], message: Dict[str, Any]) -> None:
+    """Hook to log Starlette client response body at DEBUG level if enabled."""
+
+    try:
+        # Capture body from response message
+        if message.get("type") == "http.response.body" and "body" in message:
+            body = message["body"]
+            if body:
+                _logger.debug("Starlette client response body: %s", _decode_body(body))
+    except Exception:
+        _logger.exception("Failed to log Starlette client response body")
+
+
+def instrument_starlette_app(app: Starlette) -> None:
+    """Instrument a Starlette application with OpenTelemetry.
+
+    Args:
+        app: The Starlette application to instrument
+
+    Note:
+        This should be called after setup_otel() has been called to set up the tracer provider.
+        Body logging for Starlette is limited compared to HTTPX as it must avoid consuming
+        request/response streams. Bodies are only captured when already buffered in the ASGI scope.
+    """
+
+    # env needs to be set here since _excluded_urls is initialized at module import time
+    os.environ.setdefault("OTEL_PYTHON_STARLETTE_EXCLUDED_URLS", AGENT_CARD_WELL_KNOWN_PATH)
+    from opentelemetry.instrumentation.starlette import StarletteInstrumentor
+
+    StarletteInstrumentor().instrument_app(
+        app,
+        server_request_hook=_starlette_server_request_hook,
+        client_request_hook=_starlette_client_request_hook,
+        client_response_hook=_starlette_client_response_hook,
+    )