Skip to content

Building AI agents, atomically

Add optional OpenInference instrumentor for agents and tools

Eigenwise84981ce51de2
diff --git a/atomic-agents/atomic_agents/observability/__init__.py b/atomic-agents/atomic_agents/observability/__init__.py
new file mode 100644
index 0000000..6fe3567
--- /dev/null
+++ b/atomic-agents/atomic_agents/observability/__init__.py
@@ -0,0 +1,98 @@
+"""
+Opt-in OpenInference tracing for Atomic Agents.
+
+Emits an AGENT span per ``AtomicAgent`` run and a TOOL span per ``BaseTool`` run, rendered by
+Arize Phoenix and any other OpenTelemetry backend. Needs the ``observability`` extra:
+``pip install "atomic-agents[observability]"``. Phoenix discovers :class:`AtomicAgentsInstrumentor`
+through the ``openinference_instrumentor`` entry point, so ``phoenix.otel.register(auto_instrument=True)``
+activates it without further code. See ``docs/guides/observability.md``.
+"""
+
+import importlib.util
+import logging
+from importlib.metadata import PackageNotFoundError, version
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+ from openinference.instrumentation import TraceConfig
+ from opentelemetry.trace import TracerProvider
+
+logger = logging.getLogger(__name__)
+
+_INSTALL_HINT = (
+ "Atomic Agents observability needs the OpenInference packages. "
+ 'Install them with: pip install "atomic-agents[observability]"'
+)
+_OPENINFERENCE_DISTRIBUTION = "openinference-instrumentation"
+_MINIMUM_OPENINFERENCE_VERSION = (0, 1, 38)
+
+
+def _openinference_is_installed() -> bool:
+ return importlib.util.find_spec("openinference") is not None
+
+
+def _openinference_is_too_old() -> bool:
+ try:
+ installed = version(_OPENINFERENCE_DISTRIBUTION)
+ except PackageNotFoundError:
+ return True
+ release = tuple(int(part) for part in installed.split(".")[:3] if part.isdigit())
+ return release < _MINIMUM_OPENINFERENCE_VERSION
+
+
+def _load_tracing_module():
+ if _openinference_is_too_old():
+ logger.warning(
+ "Atomic Agents tracing is disabled: %s %s or newer is required.",
+ _OPENINFERENCE_DISTRIBUTION,
+ ".".join(str(part) for part in _MINIMUM_OPENINFERENCE_VERSION),
+ )
+ return None
+ from atomic_agents.observability import openinference_tracing
+
+ return openinference_tracing
+
+
+class AtomicAgentsInstrumentor:
+ """
+ Installs OpenInference AGENT and TOOL spans around ``AtomicAgent`` and ``BaseTool`` calls.
+
+ The public surface mirrors OpenTelemetry's ``BaseInstrumentor`` (``instrument`` / ``uninstrument``)
+ without depending on it, because Arize Phoenix only guarantees ``opentelemetry-api`` and
+ ``openinference-instrumentation`` in an auto-instrumented environment.
+ """
+
+ def instrument(
+ self, *, tracer_provider: Optional["TracerProvider"] = None, config: Optional["TraceConfig"] = None
+ ) -> None:
+ """
+ Patch the framework classes. Safe to call more than once; a second call with different
+ arguments logs a warning and keeps the first installation.
+
+ Args:
+ tracer_provider: An OpenTelemetry ``TracerProvider``. Defaults to the global provider.
+ config: An ``openinference.instrumentation.TraceConfig`` (for example ``hide_inputs=True``).
+
+ Raises:
+ ImportError: When the ``observability`` extra is not installed.
+ """
+ if not _openinference_is_installed():
+ raise ImportError(_INSTALL_HINT)
+ tracing = _load_tracing_module()
+ if tracing is not None:
+ tracing.install(tracer_provider=tracer_provider, config=config)
+
+ def uninstrument(self) -> None:
+ """Restore the original framework methods. No-op when nothing is installed."""
+ if not self.is_instrumented_by_opentelemetry:
+ return
+ _load_tracing_module().uninstall()
+
+ @property
+ def is_instrumented_by_opentelemetry(self) -> bool:
+ if not _openinference_is_installed() or _openinference_is_too_old():
+ return False
+ return _load_tracing_module().is_installed()
+
+
+__all__ = ["AtomicAgentsInstrumentor"]
diff --git a/atomic-agents/atomic_agents/observability/openinference_tracing.py b/atomic-agents/atomic_agents/observability/openinference_tracing.py
new file mode 100644
index 0000000..7959be4
--- /dev/null
+++ b/atomic-agents/atomic_agents/observability/openinference_tracing.py
@@ -0,0 +1,475 @@
+"""
+OpenInference span emission for ``AtomicAgent`` runs and ``BaseTool`` runs.
+
+Loaded lazily by :class:`atomic_agents.observability.AtomicAgentsInstrumentor`; importing this module
+requires the ``observability`` extra.
+"""
+
+import asyncio
+import contextvars
+import functools
+import hashlib
+import inspect
+import json
+import logging
+from types import FunctionType
+from typing import TYPE_CHECKING, Any, AsyncGenerator, Callable, Dict, Generator, List, Optional, Type
+
+from openinference.instrumentation import OITracer, TraceConfig
+from openinference.semconv.trace import SpanAttributes
+from opentelemetry import context as context_api
+from opentelemetry import trace as trace_api
+from opentelemetry.trace import Status, StatusCode
+
+from atomic_agents import __version__
+from atomic_agents.agents.atomic_agent import AtomicAgent
+from atomic_agents.base.base_tool import BaseTool
+
+if TYPE_CHECKING:
+ from opentelemetry.trace import TracerProvider
+
+logger = logging.getLogger(__name__)
+
+TRACED_MARKER = "__atomic_agents_traced__"
+INHERITED_MARKER = "__atomic_agents_inherited__"
+TRACER_NAME = "atomic_agents"
+
+AGENT_SYNC_METHOD = "run"
+AGENT_ASYNC_METHOD = "run_async"
+AGENT_SYNC_STREAM_METHOD = "run_stream"
+AGENT_ASYNC_STREAM_METHOD = "run_async_stream"
+TOOL_METHOD_NAMES = ("run", "run_async", "arun")
+
+ATTR_MODEL = "atomic_agents.model"
+ATTR_MODE = "atomic_agents.mode"
+ATTR_INPUT_SCHEMA = "atomic_agents.input_schema"
+ATTR_OUTPUT_SCHEMA = "atomic_agents.output_schema"
+ATTR_HISTORY_MESSAGE_COUNT = "atomic_agents.history.message_count"
+ATTR_CONTEXT_PROVIDERS = "atomic_agents.context_providers"
+ATTR_SYSTEM_PROMPT_SHA256 = "atomic_agents.system_prompt.sha256"
+ATTR_STREAM_CLOSED_EARLY = "atomic_agents.stream.closed_early"
+
+_active_tool: contextvars.ContextVar[Optional[BaseTool]] = contextvars.ContextVar("atomic_agents_active_tool", default=None)
+
+
+class _Installation:
+ def __init__(
+ self,
+ tracer: OITracer,
+ tracer_provider: Optional["TracerProvider"],
+ config: TraceConfig,
+ original_init_subclass: classmethod,
+ ):
+ self.tracer = tracer
+ self.tracer_provider = tracer_provider
+ self.config = config
+ self.original_init_subclass = original_init_subclass
+
+
+_installation: Optional[_Installation] = None
+
+
+def is_installed() -> bool:
+ return _installation is not None
+
+
+def install(*, tracer_provider: Optional["TracerProvider"] = None, config: Optional[TraceConfig] = None) -> None:
+ global _installation
+ config = config or TraceConfig()
+ if _installation is not None:
+ _warn_if_reinstalled_differently(_installation, tracer_provider, config)
+ return
+ tracer = OITracer(trace_api.get_tracer(TRACER_NAME, __version__, tracer_provider), config=config)
+ original_init_subclass = BaseTool.__dict__["__init_subclass__"]
+ _installation = _Installation(tracer, tracer_provider, config, original_init_subclass)
+ _instrument_agent_class(tracer)
+ _instrument_existing_tool_classes(tracer)
+ _hook_future_tool_classes(tracer, original_init_subclass)
+
+
+def uninstall() -> None:
+ global _installation
+ if _installation is None:
+ return
+ setattr(BaseTool, "__init_subclass__", _installation.original_init_subclass)
+ for tool_class in _all_subclasses(BaseTool):
+ _restore_tool_class(tool_class)
+ for method_name in _AGENT_WRAPPERS:
+ _restore_method(AtomicAgent, method_name)
+ _installation = None
+
+
+def _warn_if_reinstalled_differently(
+ installed: _Installation, tracer_provider: Optional["TracerProvider"], config: TraceConfig
+) -> None:
+ same_provider = tracer_provider is None or tracer_provider is installed.tracer_provider
+ same_config = config == installed.config
+ if not (same_provider and same_config):
+ logger.warning(
+ "AtomicAgentsInstrumentor is already installed; the new tracer_provider/config are ignored. "
+ "Call uninstrument() first to change them."
+ )
+
+
+def _instrument_agent_class(tracer: OITracer) -> None:
+ for method_name, wrap in _AGENT_WRAPPERS.items():
+ original = AtomicAgent.__dict__[method_name]
+ if not getattr(original, TRACED_MARKER, False):
+ setattr(AtomicAgent, method_name, _mark_traced(wrap(tracer, method_name, original), original, False))
+
+
+def _mark_traced(wrapper: Callable, original: Callable, inherited: bool) -> Callable:
+ setattr(wrapper, TRACED_MARKER, True)
+ setattr(wrapper, INHERITED_MARKER, inherited)
+ setattr(wrapper, "__wrapped__", original)
+ return wrapper
+
+
+def _restore_method(owner: Type, method_name: str) -> None:
+ current = owner.__dict__.get(method_name)
+ if current is None or not getattr(current, TRACED_MARKER, False):
+ return
+ if getattr(current, INHERITED_MARKER, False):
+ delattr(owner, method_name)
+ else:
+ setattr(owner, method_name, current.__wrapped__)
+
+
+def _all_subclasses(base: Type) -> List[Type]:
+ found: List[Type] = []
+ pending = list(base.__subclasses__())
+ while pending:
+ current = pending.pop(0)
+ if current not in found:
+ found.append(current)
+ pending.extend(current.__subclasses__())
+ return found
+
+
+def _instrument_existing_tool_classes(tracer: OITracer) -> None:
+ for tool_class in _all_subclasses(BaseTool):
+ _instrument_tool_class(tool_class, tracer)
+
+
+def _hook_future_tool_classes(tracer: OITracer, original_init_subclass: classmethod) -> None:
+ def traced_init_subclass(cls, **kwargs):
+ original_init_subclass.__func__(cls, **kwargs)
+ _instrument_tool_class(cls, tracer)
+
+ setattr(BaseTool, "__init_subclass__", classmethod(traced_init_subclass))
+
+
+def _instrument_tool_class(tool_class: Type, tracer: OITracer) -> None:
+ for method_name in TOOL_METHOD_NAMES:
+ method = inspect.getattr_static(tool_class, method_name, None)
+ if _is_traceable_function(method):
+ inherited = method_name not in tool_class.__dict__
+ setattr(tool_class, method_name, _mark_traced(_trace_tool_method(tracer, method), method, inherited))
+
+
+def _is_traceable_function(method: Any) -> bool:
+ if not isinstance(method, FunctionType) or inspect.isasyncgenfunction(method):
+ return False
+ if getattr(method, "__isabstractmethod__", False):
+ return False
+ return not getattr(method, TRACED_MARKER, False)
+
+
+def _restore_tool_class(tool_class: Type) -> None:
+ for method_name in TOOL_METHOD_NAMES:
+ _restore_method(tool_class, method_name)
+
+
+def _agent_display_name(agent: AtomicAgent) -> str:
+ return f"{type(agent).__name__}[{agent.input_schema.__name__}, {agent.output_schema.__name__}]"
+
+
+def _agent_start_attributes(agent: AtomicAgent) -> Dict[str, Any]:
+ try:
+ return {
+ SpanAttributes.AGENT_NAME: _agent_display_name(agent),
+ ATTR_MODEL: agent.model,
+ ATTR_MODE: getattr(agent.mode, "value", str(agent.mode)),
+ ATTR_INPUT_SCHEMA: agent.input_schema.__name__,
+ ATTR_OUTPUT_SCHEMA: agent.output_schema.__name__,
+ ATTR_HISTORY_MESSAGE_COUNT: len(agent.history.history),
+ ATTR_CONTEXT_PROVIDERS: _context_provider_names(agent),
+ **_system_prompt_version(agent),
+ }
+ except Exception as error:
+ logger.warning("Could not describe agent for tracing: %s", error)
+ return {}
+
+
+def _context_provider_names(agent: AtomicAgent) -> List[str]:
+ providers = getattr(agent.system_prompt_generator, "context_providers", None) or {}
+ return sorted(str(name) for name in providers)
+
+
+def _system_prompt_version(agent: AtomicAgent) -> Dict[str, str]:
+ """Hashes only the static prompt sections, so the value identifies the prompt version across turns
+ even though context providers change the rendered prompt on every call."""
+ generator = agent.system_prompt_generator
+ sections = {name: getattr(generator, name, None) for name in ("background", "steps", "output_instructions")}
+ if agent.system_role is None or all(value is None for value in sections.values()):
+ return {}
+ digest = hashlib.sha256(json.dumps(sections, sort_keys=True, default=str).encode("utf-8")).hexdigest()
+ return {ATTR_SYSTEM_PROMPT_SHA256: digest}
+
+
+def _user_input_from_call(args: tuple, kwargs: dict) -> Any:
+ return args[0] if args else kwargs.get("user_input")
+
+
+def _set_input_safely(span: Any, value: Any) -> None:
+ if value is None:
+ return
+ try:
+ span.set_input(value)
+ except Exception as error:
+ logger.warning("Could not record span input: %s", error)
+
+
+def _set_output_safely(span: Any, value: Any) -> None:
+ if value is None:
+ return
+ try:
+ span.set_output(value)
+ except Exception as error:
+ logger.warning("Could not record span output: %s", error)
+
+
+def _finish_agent_span(span: Any, output: Any) -> None:
+ _set_output_safely(span, output)
+ span.set_status(Status(StatusCode.OK))
+
+
+def _mark_closed_early(span: Any, output: Any) -> None:
+ span.set_attribute(ATTR_STREAM_CLOSED_EARLY, True)
+ _set_output_safely(span, output)
+
+
+def _record_failure(span: Any, error: BaseException) -> None:
+ span.record_exception(error)
+ span.set_status(Status(StatusCode.ERROR, str(error)))
+
+
+def _trace_agent_call(tracer: OITracer, method_name: str, wrapped: Callable) -> Callable:
+ @functools.wraps(wrapped)
+ def traced(agent, *args, **kwargs):
+ span_name = f"{_agent_display_name(agent)}.{method_name}"
+ with tracer.start_as_current_span(
+ span_name, openinference_span_kind="agent", attributes=_agent_start_attributes(agent)
+ ) as span:
+ _set_input_safely(span, _user_input_from_call(args, kwargs))
+ response = wrapped(agent, *args, **kwargs)
+ _finish_agent_span(span, response)
+ return response
+
+ return traced
+
+
+def _trace_agent_async_call(tracer: OITracer, method_name: str, wrapped: Callable) -> Callable:
+ @functools.wraps(wrapped)
+ async def traced(agent, *args, **kwargs):
+ span_name = f"{_agent_display_name(agent)}.{method_name}"
+ with tracer.start_as_current_span(
+ span_name, openinference_span_kind="agent", attributes=_agent_start_attributes(agent)
+ ) as span:
+ _set_input_safely(span, _user_input_from_call(args, kwargs))
+ response = await wrapped(agent, *args, **kwargs)
+ _finish_agent_span(span, response)
+ return response
+
+ return traced
+
+
+def _start_agent_span(tracer: OITracer, agent: AtomicAgent, method_name: str, args: tuple, kwargs: dict) -> Any:
+ span = tracer.start_span(
+ f"{_agent_display_name(agent)}.{method_name}",
+ openinference_span_kind="agent",
+ attributes=_agent_start_attributes(agent),
+ )
+ _set_input_safely(span, _user_input_from_call(args, kwargs))
+ return span
+
+
+def _call_within_span(span: Any, function: Callable, *args: Any) -> Any:
+ token = context_api.attach(trace_api.set_span_in_context(span))
+ try:
+ return function(*args)
+ finally:
+ context_api.detach(token)
+
+
+async def _await_within_span(span: Any, awaitable: Any) -> Any:
+ token = context_api.attach(trace_api.set_span_in_context(span))
+ try:
+ return await awaitable
+ finally:
+ context_api.detach(token)
+
+
+class _SyncStreamCursor:
+ def __init__(self, span: Any, inner: Generator):
+ self.span = span
+ self.inner = inner
+ self.last: Any = None
+ self.final: Any = None
+
+ def advance(self) -> bool:
+ try:
+ self.last = _call_within_span(self.span, next, self.inner)
+ except StopIteration as stop:
+ self.final = stop.value
+ return False
+ return True
+
+ def close_early(self) -> None:
+ _call_within_span(self.span, self.inner.close)
+ _mark_closed_early(self.span, self.last)
+ self.span.set_status(Status(StatusCode.OK))
+
+
+class _AsyncStreamCursor:
+ """Async twin of :class:`_SyncStreamCursor`; async generators carry no return value, so the last partial is the output."""
+
+ def __init__(self, span: Any, inner: AsyncGenerator):
+ self.span = span
+ self.inner = inner
+ self.last: Any = None
+
+ async def advance(self) -> bool:
+ try:
+ self.last = await _await_within_span(self.span, self.inner.__anext__())
+ except StopAsyncIteration:
+ return False
+ return True
+
+ async def close_early(self) -> None:
+ await _await_within_span(self.span, self.inner.aclose())
+ _mark_closed_early(self.span, self.last)
+ self.span.set_status(Status(StatusCode.OK))
+
+ def mark_cancelled(self) -> None:
+ _mark_closed_early(self.span, self.last)
+
+
+def _trace_agent_stream(tracer: OITracer, method_name: str, wrapped: Callable) -> Callable:
+ @functools.wraps(wrapped)
+ def traced(agent, *args, **kwargs):
+ span = _start_agent_span(tracer, agent, method_name, args, kwargs)
+ cursor = _SyncStreamCursor(span, wrapped(agent, *args, **kwargs))
+ try:
+ while cursor.advance():
+ yield cursor.last
+ _finish_agent_span(span, cursor.final)
+ return cursor.final
+ except GeneratorExit:
+ cursor.close_early()
+ raise
+ except BaseException as error:
+ _record_failure(span, error)
+ raise
+ finally:
+ span.end()
+
+ return traced
+
+
+def _trace_agent_async_stream(tracer: OITracer, method_name: str, wrapped: Callable) -> Callable:
+ @functools.wraps(wrapped)
+ async def traced(agent, *args, **kwargs):
+ span = _start_agent_span(tracer, agent, method_name, args, kwargs)
+ cursor = _AsyncStreamCursor(span, wrapped(agent, *args, **kwargs))
+ try:
+ while await cursor.advance():
+ yield cursor.last
+ _finish_agent_span(span, cursor.last)
+ except GeneratorExit:
+ await cursor.close_early()
+ raise
+ except asyncio.CancelledError:
+ cursor.mark_cancelled()
+ raise
+ except BaseException as error:
+ _record_failure(span, error)
+ raise
+ finally:
+ span.end()
+
+ return traced
+
+
+def _describe_tool(span: Any, tool: BaseTool) -> None:
+ try:
+ span.set_tool(
+ name=tool.tool_name,
+ description=tool.tool_description,
+ parameters=tool.input_schema.model_json_schema(),
+ )
+ except Exception as error:
+ logger.warning("Could not describe tool %s for tracing: %s", type(tool).__name__, error)
+
+
+def _tool_input_from_call(args: tuple, kwargs: dict) -> Any:
+ return args[0] if args else kwargs.get("params")
+
+
+def _trace_tool_method(tracer: OITracer, wrapped: Callable) -> Callable:
+ if inspect.iscoroutinefunction(wrapped):
+ return _trace_tool_async_method(tracer, wrapped)
+
+ @functools.wraps(wrapped)
+ def traced(tool, *args, **kwargs):
+ if _active_tool.get() is tool:
+ return wrapped(tool, *args, **kwargs)
+ with tracer.start_as_current_span(type(tool).__name__, openinference_span_kind="tool") as span:
+ _describe_tool(span, tool)
+ _set_input_safely(span, _tool_input_from_call(args, kwargs))
+ result = _run_as_active_tool(tool, wrapped, args, kwargs)
+ _set_output_safely(span, result)
+ span.set_status(Status(StatusCode.OK))
+ return result
+
+ return traced
+
+
+def _trace_tool_async_method(tracer: OITracer, wrapped: Callable) -> Callable:
+ @functools.wraps(wrapped)
+ async def traced(tool, *args, **kwargs):
+ if _active_tool.get() is tool:
+ return await wrapped(tool, *args, **kwargs)
+ with tracer.start_as_current_span(type(tool).__name__, openinference_span_kind="tool") as span:
+ _describe_tool(span, tool)
+ _set_input_safely(span, _tool_input_from_call(args, kwargs))
+ result = await _await_as_active_tool(tool, wrapped, args, kwargs)
+ _set_output_safely(span, result)
+ span.set_status(Status(StatusCode.OK))
+ return result
+
+ return traced
+
+
+def _run_as_active_tool(tool: BaseTool, wrapped: Callable, args: tuple, kwargs: dict) -> Any:
+ token = _active_tool.set(tool)
+ try:
+ return wrapped(tool, *args, **kwargs)
+ finally:
+ _active_tool.reset(token)
+
+
+async def _await_as_active_tool(tool: BaseTool, wrapped: Callable, args: tuple, kwargs: dict) -> Any:
+ token = _active_tool.set(tool)
+ try:
+ return await wrapped(tool, *args, **kwargs)
+ finally:
+ _active_tool.reset(token)
+
+
+_AGENT_WRAPPERS: Dict[str, Callable[[OITracer, str, Callable], Callable]] = {
+ AGENT_SYNC_METHOD: _trace_agent_call,
+ AGENT_ASYNC_METHOD: _trace_agent_async_call,
+ AGENT_SYNC_STREAM_METHOD: _trace_agent_stream,
+ AGENT_ASYNC_STREAM_METHOD: _trace_agent_async_stream,
+}
diff --git a/atomic-agents/tests/observability/test_openinference_tracing.py b/atomic-agents/tests/observability/test_openinference_tracing.py
new file mode 100644
index 0000000..8bb56c4
--- /dev/null
+++ b/atomic-agents/tests/observability/test_openinference_tracing.py
@@ -0,0 +1,820 @@
+import abc
+import asyncio
+import contextvars
+import gc
+import json
+import logging
+import types
+from concurrent.futures import ThreadPoolExecutor
+from importlib.metadata import entry_points
+from typing import Dict, List
+from unittest.mock import Mock
+
+import instructor
+import pytest
+from openinference.instrumentation import TraceConfig, using_metadata, using_session
+from openinference.semconv.trace import OpenInferenceSpanKindValues, SpanAttributes
+from opentelemetry import trace as trace_api
+from opentelemetry.sdk.trace import ReadableSpan, TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+from opentelemetry.trace import StatusCode
+from pydantic import Field
+
+from atomic_agents import AgentConfig, AtomicAgent, BaseIOSchema, BaseTool
+from atomic_agents.context import BaseDynamicContextProvider, SystemPromptGenerator
+from atomic_agents.observability import AtomicAgentsInstrumentor
+import atomic_agents.observability as observability
+from atomic_agents.observability import openinference_tracing as tracing
+
+
+class QuestionSchema(BaseIOSchema):
+ """A question for the agent."""
+
+ question: str = Field(...)
+
+
+class AnswerSchema(BaseIOSchema):
+ """An answer from the agent."""
+
+ answer: str = Field(...)
+
+
+class CalculationInputSchema(BaseIOSchema):
+ """Expression to evaluate."""
+
+ expression: str = Field(...)
+
+
+class CalculationOutputSchema(BaseIOSchema):
+ """Result of the evaluation."""
+
+ result: str = Field(...)
+
+
+class CalculatorTool(BaseTool[CalculationInputSchema, CalculationOutputSchema]):
+ def run(self, params: CalculationInputSchema, precision: int = 2) -> CalculationOutputSchema:
+ return CalculationOutputSchema(result=f"{len(params.expression):.{precision}f}")
+
+
+class AsyncCalculatorTool(BaseTool[CalculationInputSchema, CalculationOutputSchema]):
+ def run(self, params: CalculationInputSchema) -> CalculationOutputSchema:
+ return asyncio.run(self.arun(params))
+
+ async def arun(self, params: CalculationInputSchema) -> CalculationOutputSchema:
+ return CalculationOutputSchema(result=str(len(params.expression)))
+
+
+class ThreadedCalculatorTool(BaseTool[CalculationInputSchema, CalculationOutputSchema]):
+ def run(self, params: CalculationInputSchema) -> CalculationOutputSchema:
+ return CalculationOutputSchema(result=str(len(params.expression)))
+
+ async def run_async(self, params: CalculationInputSchema) -> CalculationOutputSchema:
+ return await asyncio.to_thread(self.run, params)
+
+
+class RunMixin:
+ def run(self, params: CalculationInputSchema) -> CalculationOutputSchema:
+ return CalculationOutputSchema(result="mixin")
+
+
+class MixinCalculatorTool(RunMixin, BaseTool[CalculationInputSchema, CalculationOutputSchema]):
+ pass
+
+
+class StaticRunTool(BaseTool[CalculationInputSchema, CalculationOutputSchema]):
+ @staticmethod
+ def run(params: CalculationInputSchema) -> CalculationOutputSchema:
+ return CalculationOutputSchema(result="static")
+
+
+class FailingTool(BaseTool[CalculationInputSchema, CalculationOutputSchema]):
+ def run(self, params: CalculationInputSchema) -> CalculationOutputSchema:
+ raise ValueError("boom")
+
+
+class AnswerStore:
+ """Container object pydantic cannot serialize to JSON."""
+
+ def __init__(self):
+ self.values: List[int] = []
+
+
+class UnserializableInputSchema(BaseIOSchema):
+ """Input carrying an arbitrary object."""
+
+ model_config = {"arbitrary_types_allowed": True}
+ store: AnswerStore = Field(...)
+
+
+class EchoTool(BaseTool[UnserializableInputSchema, CalculationOutputSchema]):
+ def run(self, params: UnserializableInputSchema) -> CalculationOutputSchema:
+ return CalculationOutputSchema(result="echo")
+
+
+def exporter():
+ exporter = InMemorySpanExporter()
+ provider = TracerProvider()
+ provider.add_span_processor(SimpleSpanProcessor(exporter))
+ exporter.provider = provider
+ instrumentor = AtomicAgentsInstrumentor()
+ instrumentor.instrument(tracer_provider=provider)
+ yield exporter
+ instrumentor.uninstrument()
+
+
+def provider_tracer(exporter):
+ return exporter.provider.get_tracer("test")
+
+
+def sync_client(response=None, partials=None):
+ client = Mock(spec=instructor.Instructor)
+ client.chat = Mock()
+ client.chat.completions = Mock()
+ client.chat.completions.create = Mock(return_value=response or AnswerSchema(answer="42"))
+
+ def create_partial(**kwargs):
+ for partial in partials or [AnswerSchema(answer="4"), AnswerSchema(answer="42")]:
+ yield partial
+
+ client.chat.completions.create_partial = create_partial
+ return client
+
+
+def async_client(response=None, partials=None):
+ client = Mock(spec=instructor.core.client.AsyncInstructor)
+ client.chat = Mock()
+ client.chat.completions = Mock()
+
+ async def create(**kwargs):
+ return response or AnswerSchema(answer="42")
+
+ async def create_partial(**kwargs):
+ for partial in partials or [AnswerSchema(answer="4"), AnswerSchema(answer="42")]:
+ yield partial
+
+ client.chat.completions.create = create
+ client.chat.completions.create_partial = create_partial
+ return client
+
+
+def make_agent(client) -> AtomicAgent[QuestionSchema, AnswerSchema]:
+ return AtomicAgent[QuestionSchema, AnswerSchema](AgentConfig(client=client, model="test-model"))
+
+
+def spans_of(exporter) -> List[ReadableSpan]:
+ return list(exporter.get_finished_spans())
+
+
+def kind_of(span: ReadableSpan) -> str:
+ return span.attributes[SpanAttributes.OPENINFERENCE_SPAN_KIND]
+
+
+def input_json(span: ReadableSpan) -> Dict:
+ return json.loads(span.attributes[SpanAttributes.INPUT_VALUE])
+
+
+def output_json(span: ReadableSpan) -> Dict:
+ return json.loads(span.attributes[SpanAttributes.OUTPUT_VALUE])
+
+
+def test_run_emits_agent_span_with_io_and_framework_attributes(exporter):
+ agent = make_agent(sync_client())
+
+ response = agent.run(QuestionSchema(question="6*7?"))
+
+ assert response.answer == "42"
+ (span,) = spans_of(exporter)
+ assert span.name == "AtomicAgent[QuestionSchema, AnswerSchema].run"
+ assert kind_of(span) == OpenInferenceSpanKindValues.AGENT.value
+ assert span.attributes[SpanAttributes.AGENT_NAME] == "AtomicAgent[QuestionSchema, AnswerSchema]"
+ assert input_json(span) == {"question": "6*7?"}
+ assert output_json(span) == {"answer": "42"}
+ assert span.attributes[SpanAttributes.INPUT_MIME_TYPE] == "application/json"
+ assert span.attributes[SpanAttributes.OUTPUT_MIME_TYPE] == "application/json"
+ assert span.attributes[tracing.ATTR_MODEL] == "test-model"
+ assert span.attributes[tracing.ATTR_MODE] == agent.mode.value
+ assert span.attributes[tracing.ATTR_INPUT_SCHEMA] == "QuestionSchema"
+ assert span.attributes[tracing.ATTR_OUTPUT_SCHEMA] == "AnswerSchema"
+ assert span.attributes[tracing.ATTR_HISTORY_MESSAGE_COUNT] == 0
+ assert span.attributes[tracing.ATTR_CONTEXT_PROVIDERS] == ()
+ assert len(span.attributes[tracing.ATTR_SYSTEM_PROMPT_SHA256]) == 64
+ assert span.status.status_code == StatusCode.OK
+
+
+def test_second_turn_reports_history_size_entering_the_turn(exporter):
+ agent = make_agent(sync_client())
+ agent.run(QuestionSchema(question="first"))
+
+ agent.run(QuestionSchema(question="second"))
+
+ first, second = spans_of(exporter)
+ assert first.attributes[tracing.ATTR_HISTORY_MESSAGE_COUNT] == 0
+ assert second.attributes[tracing.ATTR_HISTORY_MESSAGE_COUNT] == 2
+
+
+def test_agent_without_system_role_has_no_prompt_hash(exporter):
+ agent = AtomicAgent[QuestionSchema, AnswerSchema](AgentConfig(client=sync_client(), model="m", system_role=None))
+
+ agent.run(QuestionSchema(question="?"))
+
+ (span,) = spans_of(exporter)
+ assert tracing.ATTR_SYSTEM_PROMPT_SHA256 not in span.attributes
+
+
+def test_abstract_intermediate_tool_base_is_not_wrapped(exporter):
+ class AbstractCalculator(BaseTool[CalculationInputSchema, CalculationOutputSchema]):
+ @abc.abstractmethod
+ def run(self, params: CalculationInputSchema) -> CalculationOutputSchema:
+ raise NotImplementedError
+
+ assert not hasattr(AbstractCalculator.__dict__["run"], tracing.TRACED_MARKER)
+
+
+def test_run_without_input_sets_no_input_attribute(exporter):
+ agent = make_agent(sync_client())
+
+ agent.run()
+
+ (span,) = spans_of(exporter)
+ assert SpanAttributes.INPUT_VALUE not in span.attributes
+ assert output_json(span) == {"answer": "42"}
+
+
+def test_run_failure_propagates_and_marks_span_error(exporter):
+ client = sync_client()
+ client.chat.completions.create = Mock(side_effect=RuntimeError("provider down"))
+ agent = make_agent(client)
+
+ with pytest.raises(RuntimeError, match="provider down"):
+ agent.run(QuestionSchema(question="?"))
+
+ (span,) = spans_of(exporter)
+ assert span.status.status_code == StatusCode.ERROR
+ assert [event.name for event in span.events] == ["exception"]
+
+
+def test_subclassed_agent_is_named_after_the_subclass_and_emits_one_span(exporter):
+ class ResearchAgent(AtomicAgent[QuestionSchema, AnswerSchema]):
+ def run(self, user_input=None):
+ return super().run(user_input)
+
+ agent = ResearchAgent(AgentConfig(client=sync_client(), model="test-model"))
+
+ agent.run(QuestionSchema(question="?"))
+
+ (span,) = spans_of(exporter)
+ assert span.name == "ResearchAgent[QuestionSchema, AnswerSchema].run"
+
+
+def test_agent_span_nests_under_a_user_chain_span(exporter, provider_tracer):
+ agent = make_agent(sync_client())
+
+ with provider_tracer.start_as_current_span("turn") as turn:
+ agent.run(QuestionSchema(question="?"))
+
+ agent_span, turn_span = spans_of(exporter)
+ assert agent_span.parent.span_id == turn.get_span_context().span_id
+ assert turn_span.name == "turn"
+
+
+def test_llm_call_inside_run_becomes_child_of_agent_span(exporter, provider_tracer):
+ def create(**kwargs):
+ with provider_tracer.start_as_current_span("llm"):
+ return AnswerSchema(answer="42")
+
+ client = sync_client()
+ client.chat.completions.create = create
+ agent = make_agent(client)
+
+ agent.run(QuestionSchema(question="?"))
+
+ llm_span, agent_span = spans_of(exporter)
+ assert llm_span.parent.span_id == agent_span.context.span_id
+
+
+def test_run_stream_records_final_output_and_keeps_child_context_per_step(exporter, provider_tracer):
+ current_between_yields = []
+
+ def create_partial(**kwargs):
+ yield AnswerSchema(answer="4")
+ with provider_tracer.start_as_current_span("llm-chunk"):
+ yield AnswerSchema(answer="42")
+
+ client = sync_client()
+ client.chat.completions.create_partial = create_partial
+ agent = make_agent(client)
+
+ partials = []
+ for partial in agent.run_stream(QuestionSchema(question="?")):
+ partials.append(partial.answer)
+ current_between_yields.append(trace_api.get_current_span())
+
+ assert partials == ["4", "42"]
+ assert all(span is trace_api.INVALID_SPAN for span in current_between_yields)
+ chunk_span, agent_span = spans_of(exporter)
+ assert agent_span.name == "AtomicAgent[QuestionSchema, AnswerSchema].run_stream"
+ assert chunk_span.parent.span_id == agent_span.context.span_id
+ assert output_json(agent_span) == {"answer": "42"}
+ assert agent_span.status.status_code == StatusCode.OK
+
+
+def test_run_stream_preserves_the_generator_return_value(exporter):
+ agent = make_agent(sync_client())
+
+ def consume():
+ final = yield from agent.run_stream(QuestionSchema(question="?"))
+ return final
+
+ generator = consume()
+ with pytest.raises(StopIteration) as stop:
+ while True:
+ next(generator)
+
+ assert stop.value.value.answer == "42"
+
+
+def test_run_stream_with_no_partials_ends_ok_without_output(exporter):
+ client = sync_client()
+ client.chat.completions.create_partial = lambda **kwargs: iter([])
+ agent = make_agent(client)
+
+ assert list(agent.run_stream(QuestionSchema(question="?"))) == []
+
+ (span,) = spans_of(exporter)
+ assert span.status.status_code == StatusCode.OK
+ assert SpanAttributes.OUTPUT_VALUE not in span.attributes
+
+
+def test_run_stream_closed_early_ends_span_and_closes_inner_generator(exporter):
+ inner_closed = []
+
+ def create_partial(**kwargs):
+ try:
+ yield AnswerSchema(answer="4")
+ yield AnswerSchema(answer="42")
+ finally:
+ inner_closed.append(True)
+
+ client = sync_client()
+ client.chat.completions.create_partial = create_partial
+ agent = make_agent(client)
+
+ for partial in agent.run_stream(QuestionSchema(question="?")):
+ break
+
+ assert inner_closed == [True]
+ (span,) = spans_of(exporter)
+ assert span.attributes[tracing.ATTR_STREAM_CLOSED_EARLY] is True
+ assert output_json(span) == {"answer": "4"}
+ assert span.status.status_code == StatusCode.OK
+
+
+def test_run_stream_failure_mid_stream_marks_error(exporter):
+ def create_partial(**kwargs):
+ yield AnswerSchema(answer="4")
+ raise RuntimeError("stream broke")
+
+ client = sync_client()
+ client.chat.completions.create_partial = create_partial
+ agent = make_agent(client)
+
+ with pytest.raises(RuntimeError, match="stream broke"):
+ list(agent.run_stream(QuestionSchema(question="?")))
+
+ (span,) = spans_of(exporter)
+ assert span.status.status_code == StatusCode.ERROR
+
+
+async def test_run_async_emits_agent_span(exporter):
+ agent = make_agent(async_client())
+
+ response = await agent.run_async(QuestionSchema(question="?"))
+
+ assert response.answer == "42"
+ (span,) = spans_of(exporter)
+ assert span.name == "AtomicAgent[QuestionSchema, AnswerSchema].run_async"
+ assert output_json(span) == {"answer": "42"}
+ assert span.status.status_code == StatusCode.OK
+
+
+async def test_run_async_stream_records_last_partial_and_nests_children(exporter, provider_tracer):
+ async def create_partial(**kwargs):
+ yield AnswerSchema(answer="4")
+ with provider_tracer.start_as_current_span("llm-chunk"):
+ yield AnswerSchema(answer="42")
+
+ client = async_client()
+ client.chat.completions.create_partial = create_partial
+ agent = make_agent(client)
+
+ partials = [partial.answer async for partial in agent.run_async_stream(QuestionSchema(question="?"))]
+
+ assert partials == ["4", "42"]
+ chunk_span, agent_span = spans_of(exporter)
+ assert agent_span.name == "AtomicAgent[QuestionSchema, AnswerSchema].run_async_stream"
+ assert chunk_span.parent.span_id == agent_span.context.span_id
+ assert output_json(agent_span) == {"answer": "42"}
+
+
+async def test_run_async_stream_closed_early_ends_span(exporter):
+ agent = make_agent(async_client())
+
+ stream = agent.run_async_stream(QuestionSchema(question="?"))
+ first = await stream.__anext__()
+ await stream.aclose()
+
+ assert first.answer == "4"
+ (span,) = spans_of(exporter)
+ assert span.attributes[tracing.ATTR_STREAM_CLOSED_EARLY] is True
+ assert span.status.status_code == StatusCode.OK
+
+
+async def test_concurrent_async_runs_keep_separate_spans(exporter):
+ first = make_agent(async_client(response=AnswerSchema(answer="one")))
+ second = make_agent(async_client(response=AnswerSchema(answer="two")))
+
+ await asyncio.gather(first.run_async(QuestionSchema(question="1")), second.run_async(QuestionSchema(question="2")))
+
+ outputs = {input_json(span)["question"]: output_json(span)["answer"] for span in spans_of(exporter)}
+ assert outputs == {"1": "one", "2": "two"}
+ assert all(span.parent is None for span in spans_of(exporter))
+
+
+def test_tool_defined_before_instrumentation_emits_tool_span(exporter):
+ tool = CalculatorTool()
+
+ result = tool.run(CalculationInputSchema(expression="6*7"), precision=1)
+
+ assert result.result == "3.0"
+ (span,) = spans_of(exporter)
+ assert span.name == "CalculatorTool"
+ assert kind_of(span) == OpenInferenceSpanKindValues.TOOL.value
+ assert span.attributes[SpanAttributes.TOOL_NAME] == "CalculationInputSchema"
+ assert span.attributes[SpanAttributes.TOOL_DESCRIPTION] == "Expression to evaluate."
+ assert json.loads(span.attributes[SpanAttributes.TOOL_PARAMETERS])["title"] == "CalculationInputSchema"
+ assert input_json(span) == {"expression": "6*7"}
+ assert output_json(span) == {"result": "3.0"}
+ assert span.status.status_code == StatusCode.OK
+
+
+def test_tool_accepts_keyword_params(exporter):
+ result = CalculatorTool().run(params=CalculationInputSchema(expression="1+1"))
+
+ assert result.result == "3.00"
+ (span,) = spans_of(exporter)
+ assert input_json(span) == {"expression": "1+1"}
+
+
+def test_tool_defined_after_instrumentation_emits_tool_span(exporter):
+ class LateTool(BaseTool[CalculationInputSchema, CalculationOutputSchema]):
+ def run(self, params: CalculationInputSchema) -> CalculationOutputSchema:
+ return CalculationOutputSchema(result="late")
+
+ LateTool().run(CalculationInputSchema(expression="x"))
+
+ (span,) = spans_of(exporter)
+ assert span.name == "LateTool"
+ assert LateTool().input_schema is CalculationInputSchema
+
+
+def test_subclass_calling_super_run_emits_one_span(exporter):
+ class LoudCalculatorTool(CalculatorTool):
+ def run(self, params: CalculationInputSchema, precision: int = 2) -> CalculationOutputSchema:
+ return super().run(params, precision)
+
+ LoudCalculatorTool().run(CalculationInputSchema(expression="2*2"))
+
+ (span,) = spans_of(exporter)
+ assert span.name == "LoudCalculatorTool"
+
+
+def test_sync_run_delegating_to_arun_emits_one_span(exporter):
+ AsyncCalculatorTool().run(CalculationInputSchema(expression="2*2"))
+
+ (span,) = spans_of(exporter)
+ assert span.name == "AsyncCalculatorTool"
+ assert output_json(span) == {"result": "3"}
+
+
+async def test_run_async_delegating_to_thread_emits_one_span(exporter):
+ await ThreadedCalculatorTool().run_async(CalculationInputSchema(expression="3*3"))
+
+ (span,) = spans_of(exporter)
+ assert span.name == "ThreadedCalculatorTool"
+ assert output_json(span) == {"result": "3"}
+
+
+def test_mixin_defined_run_is_traced(exporter):
+ MixinCalculatorTool().run(CalculationInputSchema(expression="x"))
+
+ (span,) = spans_of(exporter)
+ assert span.name == "MixinCalculatorTool"
+
+
+def test_static_run_is_left_alone(exporter):
+ assert StaticRunTool.run(CalculationInputSchema(expression="x")).result == "static"
+ assert spans_of(exporter) == []
+
+
+def test_tool_failure_propagates_same_exception_and_marks_error(exporter):
+ with pytest.raises(ValueError, match="boom") as raised:
+ FailingTool().run(CalculationInputSchema(expression="x"))
+
+ (span,) = spans_of(exporter)
+ assert span.status.status_code == StatusCode.ERROR
+ assert raised.value.args == ("boom",)
+
+
+def test_unserializable_input_still_returns_result(exporter, caplog):
+ with caplog.at_level(logging.WARNING):
+ result = EchoTool().run(UnserializableInputSchema(store=AnswerStore()))
+
+ assert result.result == "echo"
+ (span,) = spans_of(exporter)
+ assert span.status.status_code == StatusCode.OK
+
+
+def test_agent_run_inside_tool_nests_under_tool_span(exporter):
+ agent = make_agent(sync_client())
+
+ class AgentTool(BaseTool[CalculationInputSchema, CalculationOutputSchema]):
+ def run(self, params: CalculationInputSchema) -> CalculationOutputSchema:
+ return CalculationOutputSchema(result=agent.run(QuestionSchema(question=params.expression)).answer)
+
+ AgentTool().run(CalculationInputSchema(expression="?"))
+
+ agent_span, tool_span = spans_of(exporter)
+ assert agent_span.parent.span_id == tool_span.context.span_id
+
+
+def test_hide_inputs_and_outputs_redacts_values_and_drops_mime_types():
+ exporter = InMemorySpanExporter()
+ provider = TracerProvider()
+ provider.add_span_processor(SimpleSpanProcessor(exporter))
+ instrumentor = AtomicAgentsInstrumentor()
+ instrumentor.instrument(tracer_provider=provider, config=TraceConfig(hide_inputs=True, hide_outputs=True))
+ try:
+ make_agent(sync_client()).run(QuestionSchema(question="secret"))
+ CalculatorTool().run(CalculationInputSchema(expression="1+1"))
+ finally:
+ instrumentor.uninstrument()
+
+ for span in spans_of(exporter):
+ assert span.attributes[SpanAttributes.INPUT_VALUE] == "__REDACTED__"
+ assert span.attributes[SpanAttributes.OUTPUT_VALUE] == "__REDACTED__"
+ assert SpanAttributes.INPUT_MIME_TYPE not in span.attributes
+ assert SpanAttributes.OUTPUT_MIME_TYPE not in span.attributes
+
+
+def test_session_and_user_metadata_survive_on_agent_span(exporter):
+ agent = make_agent(sync_client())
+
+ with using_session("session-1"), using_metadata({"tenant": "acme"}):
+ agent.run(QuestionSchema(question="?"))
+
+ (span,) = spans_of(exporter)
+ assert span.attributes[SpanAttributes.SESSION_ID] == "session-1"
+ assert json.loads(span.attributes[SpanAttributes.METADATA]) == {"tenant": "acme"}
+
+
+def test_second_instrument_with_other_settings_warns_and_keeps_first(exporter, caplog):
+ other_provider = TracerProvider()
+
+ with caplog.at_level(logging.WARNING):
+ AtomicAgentsInstrumentor().instrument(tracer_provider=other_provider)
+
+ assert "already installed" in caplog.text
+ make_agent(sync_client()).run(QuestionSchema(question="?"))
+ assert len(spans_of(exporter)) == 1
+
+
+def test_uninstrument_restores_originals_and_stops_tracing():
+ original_run = AtomicAgent.__dict__["run"]
+ original_tool_run = CalculatorTool.__dict__["run"]
+ original_init_subclass = BaseTool.__dict__["__init_subclass__"]
+ exporter = InMemorySpanExporter()
+ provider = TracerProvider()
+ provider.add_span_processor(SimpleSpanProcessor(exporter))
+ instrumentor = AtomicAgentsInstrumentor()
+
+ instrumentor.instrument(tracer_provider=provider)
+ assert instrumentor.is_instrumented_by_opentelemetry
+ instrumentor.uninstrument()
+ instrumentor.uninstrument()
+
+ assert not instrumentor.is_instrumented_by_opentelemetry
+ assert AtomicAgent.__dict__["run"] is original_run
+ assert CalculatorTool.__dict__["run"] is original_tool_run
+ assert BaseTool.__dict__["__init_subclass__"] is original_init_subclass
+ assert "run" not in MixinCalculatorTool.__dict__
+
+ class AfterwardsTool(BaseTool[CalculationInputSchema, CalculationOutputSchema]):
+ def run(self, params: CalculationInputSchema) -> CalculationOutputSchema:
+ return CalculationOutputSchema(result="plain")
+
+ assert AfterwardsTool().input_schema is CalculationInputSchema
+ make_agent(sync_client()).run(QuestionSchema(question="?"))
+ AfterwardsTool().run(CalculationInputSchema(expression="x"))
+ assert spans_of(exporter) == []
+
+
+def test_phoenix_entry_point_loads_and_instruments_with_only_a_tracer_provider():
+ (entry_point,) = [point for point in entry_points(group="openinference_instrumentor") if point.name == "atomic_agents"]
+ exporter = InMemorySpanExporter()
+ provider = TracerProvider()
+ provider.add_span_processor(SimpleSpanProcessor(exporter))
+
+ instrumentor = entry_point.load()()
+ instrumentor.instrument(tracer_provider=provider)
+ try:
+ make_agent(sync_client()).run(QuestionSchema(question="?"))
+ finally:
+ instrumentor.uninstrument()
+
+ assert isinstance(instrumentor, AtomicAgentsInstrumentor)
+ assert len(spans_of(exporter)) == 1
+
+
+def test_instrument_without_openinference_raises_install_hint(monkeypatch):
+ monkeypatch.setattr(observability, "_openinference_is_installed", lambda: False)
+
+ with pytest.raises(ImportError, match="atomic-agents\\[observability\\]"):
+ AtomicAgentsInstrumentor().instrument()
+
+
+def test_uninstrument_without_openinference_is_a_no_op(monkeypatch):
+ monkeypatch.setattr(observability, "_openinference_is_installed", lambda: False)
+
+ AtomicAgentsInstrumentor().uninstrument()
+
+ assert not AtomicAgentsInstrumentor().is_instrumented_by_opentelemetry
+
+
+def test_openinference_below_the_floor_disables_tracing_with_a_warning(monkeypatch, caplog):
+ monkeypatch.setattr(observability, "version", lambda distribution: "0.1.20")
+
+ with caplog.at_level(logging.WARNING):
+ AtomicAgentsInstrumentor().instrument()
+
+ assert "0.1.38 or newer is required" in caplog.text
+ assert not AtomicAgentsInstrumentor().is_instrumented_by_opentelemetry
+ assert AtomicAgent.__dict__["run"].__name__ == "run"
+ assert not hasattr(AtomicAgent.__dict__["run"], tracing.TRACED_MARKER)
+
+
+class CountingProvider(BaseDynamicContextProvider):
+ def __init__(self):
+ super().__init__(title="Counter")
+ self.calls = 0
+
+ def get_info(self) -> str:
+ self.calls += 1
+ return f"call {self.calls}"
+
+
+def test_prompt_hash_identifies_static_sections_despite_dynamic_providers(exporter):
+ generator = SystemPromptGenerator(background=["v1"], context_providers={"counter": CountingProvider()})
+ agent = AtomicAgent[QuestionSchema, AnswerSchema](
+ AgentConfig(client=sync_client(), model="m", system_prompt_generator=generator)
+ )
+
+ agent.run(QuestionSchema(question="a"))
+ agent.run(QuestionSchema(question="b"))
+
+ first, second = spans_of(exporter)
+ assert first.attributes[tracing.ATTR_SYSTEM_PROMPT_SHA256] == second.attributes[tracing.ATTR_SYSTEM_PROMPT_SHA256]
+ assert first.attributes[tracing.ATTR_CONTEXT_PROVIDERS] == ("counter",)
+
+
+def test_prompt_hash_changes_when_static_sections_change(exporter):
+ agent = make_agent(sync_client())
+ agent.run(QuestionSchema(question="a"))
+ agent.system_prompt_generator.background = ["v2"]
+
+ agent.run(QuestionSchema(question="b"))
+
+ first, second = spans_of(exporter)
+ assert first.attributes[tracing.ATTR_SYSTEM_PROMPT_SHA256] != second.attributes[tracing.ATTR_SYSTEM_PROMPT_SHA256]
+
+
+def test_run_stream_dropped_without_close_still_ends_span(exporter):
+ agent = make_agent(sync_client())
+ stream = agent.run_stream(QuestionSchema(question="?"))
+ next(stream)
+
+ del stream
+ gc.collect()
+
+ (span,) = spans_of(exporter)
+ assert span.attributes[tracing.ATTR_STREAM_CLOSED_EARLY] is True
+
+
+async def test_run_async_stream_cancelled_mid_await_is_not_an_error(exporter):
+ release = asyncio.Event()
+
+ async def create_partial(**kwargs):
+ yield AnswerSchema(answer="4")
+ await release.wait()
+ yield AnswerSchema(answer="42")
+
+ client = async_client()
+ client.chat.completions.create_partial = create_partial
+ agent = make_agent(client)
+
+ async def consume():
+ async for _ in agent.run_async_stream(QuestionSchema(question="?")):
+ pass
+
+ task = asyncio.create_task(consume())
+ await asyncio.sleep(0.01)
+ task.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await task
+
+ (span,) = spans_of(exporter)
+ assert span.attributes[tracing.ATTR_STREAM_CLOSED_EARLY] is True
+ assert output_json(span) == {"answer": "4"}
+ assert span.status.status_code != StatusCode.ERROR
+
+
+def test_forge_style_thread_pool_tool_emits_one_span_in_the_callers_trace(exporter, provider_tracer):
+ class ForgeStyleTool(BaseTool[CalculationInputSchema, CalculationOutputSchema]):
+ def run(self, params: CalculationInputSchema) -> CalculationOutputSchema:
+ with ThreadPoolExecutor() as executor:
+ return executor.submit(contextvars.copy_context().run, asyncio.run, self.run_async(params)).result()
+
+ async def run_async(self, params: CalculationInputSchema) -> CalculationOutputSchema:
+ return CalculationOutputSchema(result="pooled")
+
+ with provider_tracer.start_as_current_span("root") as root:
+ ForgeStyleTool().run(CalculationInputSchema(expression="x"))
+
+ tool_span, root_span = spans_of(exporter)
+ assert tool_span.name == "ForgeStyleTool"
+ assert tool_span.parent.span_id == root.get_span_context().span_id
+ assert tool_span.context.trace_id == root_span.context.trace_id
+
+
+def test_mcp_style_generated_tool_class_emits_one_span(exporter):
+ async def arun(self, params):
+ return CalculationOutputSchema(result="mcp")
+
+ def run(self, params):
+ return asyncio.run(self.arun(params))
+
+ GeneratedTool = types.new_class(
+ "GeneratedTool",
+ (BaseTool[CalculationInputSchema, CalculationOutputSchema],),
+ {},
+ lambda namespace: namespace.update({"run": run, "arun": arun}),
+ )
+
+ GeneratedTool().run(CalculationInputSchema(expression="x"))
+
+ (span,) = spans_of(exporter)
+ assert span.name == "GeneratedTool"
+ assert output_json(span) == {"result": "mcp"}
+
+
+def test_async_generator_tool_method_is_left_alone(exporter):
+ class StreamingTool(BaseTool[CalculationInputSchema, CalculationOutputSchema]):
+ def run(self, params: CalculationInputSchema) -> CalculationOutputSchema:
+ return CalculationOutputSchema(result="x")
+
+ async def run_async(self, params: CalculationInputSchema):
+ yield CalculationOutputSchema(result="chunk")
+
+ assert not hasattr(StreamingTool.__dict__["run_async"], tracing.TRACED_MARKER)
+ assert hasattr(StreamingTool.__dict__["run"], tracing.TRACED_MARKER)
+
+
+def test_instrument_uninstrument_instrument_cycle_traces_tools_defined_between_cycles():
+ exporter = InMemorySpanExporter()
+ provider = TracerProvider()
+ provider.add_span_processor(SimpleSpanProcessor(exporter))
+ instrumentor = AtomicAgentsInstrumentor()
+ instrumentor.instrument(tracer_provider=provider)
+ instrumentor.uninstrument()
+
+ class BetweenCyclesTool(BaseTool[CalculationInputSchema, CalculationOutputSchema]):
+ def run(self, params: CalculationInputSchema) -> CalculationOutputSchema:
+ return CalculationOutputSchema(result="between")
+
+ original_run = BetweenCyclesTool.__dict__["run"]
+ instrumentor.instrument(tracer_provider=provider)
+ try:
+ BetweenCyclesTool().run(CalculationInputSchema(expression="x"))
+ finally:
+ instrumentor.uninstrument()
+
+ assert [span.name for span in spans_of(exporter)] == ["BetweenCyclesTool"]
+ assert BetweenCyclesTool.__dict__["run"] is original_run
diff --git a/pyproject.toml b/pyproject.toml
index b99f9d2..3db1759 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -36,6 +36,13 @@ dependencies = [
"litellm>=1.50.0,<2.0.0",
]
+[project.optional-dependencies]
+observability = [
+ "openinference-instrumentation>=0.1.38,<0.2.0",
+ "openinference-semantic-conventions>=0.1.20,<0.2.0",
+ "opentelemetry-api>=1.30.0,<2.0.0",
+]
+
[project.urls]
Homepage = "https://github.com/eigenwise/atomic-agents"
Repository = "https://github.com/eigenwise/atomic-agents"
@@ -43,6 +50,9 @@ Repository = "https://github.com/eigenwise/atomic-agents"
[project.scripts]
atomic = "atomic_assembler.main:main"
+[project.entry-points.openinference_instrumentor]
+atomic_agents = "atomic_agents.observability:AtomicAgentsInstrumentor"
+
[dependency-groups]
dev = [
"black>=24.8.0,<25.0.0",
@@ -62,6 +72,9 @@ dev = [
"beautifulsoup4>=4.12.3,<5.0.0",
"markdownify>=0.9.0,<1.0.0",
"sphinxcontrib-mermaid>=1.2.3",
+ "openinference-instrumentation>=0.1.38,<0.2.0",
+ "openinference-semantic-conventions>=0.1.20,<0.2.0",
+ "opentelemetry-sdk>=1.30.0,<2.0.0",
]
[tool.hatch.build.targets.wheel]
diff --git a/uv.lock b/uv.lock
index e0a4a4c..9f54c63 100644
--- a/uv.lock
+++ b/uv.lock
@@ -253,6 +253,13 @@ dependencies = [
{ name = "textual" },
]
+[package.optional-dependencies]
+observability = [
+ { name = "openinference-instrumentation" },
+ { name = "openinference-semantic-conventions" },
+ { name = "opentelemetry-api" },
+]
+
[package.dev-dependencies]
dev = [
{ name = "beautifulsoup4" },
@@ -261,6 +268,9 @@ dev = [
{ name = "markdownify" },
{ name = "myst-parser" },
{ name = "openai" },
+ { name = "openinference-instrumentation" },
+ { name = "openinference-semantic-conventions" },
+ { name = "opentelemetry-sdk" },
{ name = "pdoc3" },
{ name = "pre-commit" },
{ name = "pytest" },
@@ -280,6 +290,9 @@ requires-dist = [
{ name = "instructor", specifier = "==1.14.5" },
{ name = "litellm", specifier = ">=1.50.0,<2.0.0" },
{ name = "mcp", extras = ["cli"], specifier = ">=1.6.0" },
+ { name = "openinference-instrumentation", marker = "extra == 'observability'", specifier = ">=0.1.38,<0.2.0" },
+ { name = "openinference-semantic-conventions", marker = "extra == 'observability'", specifier = ">=0.1.20,<0.2.0" },
+ { name = "opentelemetry-api", marker = "extra == 'observability'", specifier = ">=1.30.0,<2.0.0" },
{ name = "pydantic", specifier = ">=2.11.0,<3.0.0" },
{ name = "pyfiglet", specifier = ">=1.0.2,<2.0.0" },
{ name = "pyyaml", specifier = ">=6.0.2,<7.0.0" },
@@ -287,6 +300,7 @@ requires-dist = [
{ name = "rich", specifier = ">=13.7.1,<14.0.0" },
{ name = "textual", specifier = ">=5.3.0,<6.0.0" },
]
+provides-extras = ["observability"]
[package.metadata.requires-dev]
dev = [
@@ -296,6 +310,9 @@ dev = [
{ name = "markdownify", specifier = ">=0.9.0,<1.0.0" },
{ name = "myst-parser", specifier = ">=2.0.0,<3.0.0" },
{ name = "openai", specifier = ">=2.0.0,<3.0.0" },
+ { name = "openinference-instrumentation", specifier = ">=0.1.38,<0.2.0" },
+ { name = "openinference-semantic-conventions", specifier = ">=0.1.20,<0.2.0" },
+ { name = "opentelemetry-sdk", specifier = ">=1.30.0,<2.0.0" },
{ name = "pdoc3", specifier = ">=0.11.1,<1.0.0" },
{ name = "pre-commit", specifier = ">=4.0.0,<5.0.0" },
{ name = "pytest", specifier = ">=8.3.3,<9.0.0" },
@@ -2712,6 +2729,30 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/12/cf/03675d8bd8ecbf4445504d8071adab19f5f993676795708e36402ab38263/openapi_pydantic-0.5.1-py3-none-any.whl", hash = "sha256:a3a09ef4586f5bd760a8df7f43028b60cafb6d9f61de2acba9574766255ab146", size = 96381, upload-time = "2025-01-08T19:29:25.275Z" },
]
+[[package]]
+name = "openinference-instrumentation"
+version = "0.1.71"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "openinference-semantic-conventions" },
+ { name = "opentelemetry-api" },
+ { name = "opentelemetry-sdk" },
+ { name = "wrapt" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/56/ec/ef1ca7e409ee6bddb7278b9760e0941f65911748f5dc84d17c115f6648f1/openinference_instrumentation-0.1.71.tar.gz", hash = "sha256:4d267b6ce8e067572a740d6a0dbf6b4d4c6e386c5a52a7e7f61e3a714a49849d", size = 46600, upload-time = "2026-10-07T20:26:41.084Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/7c/8c/330101bedf614dc937d8690462ed0ad4efd7f6c3248a76a5484ba6f885e3/openinference_instrumentation-0.1.71-py3-none-any.whl", hash = "sha256:07833fcf5d493a2ed15da16a0af70d6127d39f18ffa68f4d6827107e49fc6753", size = 54511, upload-time = "2026-10-07T20:26:39.634Z" },
+]
+
+[[package]]
+name = "openinference-semantic-conventions"
+version = "0.1.41"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/53/be/e1fe52e3ae242695101144e058edfdd8e412a58ce04e2e2b410268683b05/openinference_semantic_conventions-0.1.41.tar.gz", hash = "sha256:78d4ffd9d1f2f89cb4bd58a0afe5a460475ce3d76a4d993f50fb0ce8bf4129a3", size = 15789, upload-time = "2026-10-01T18:22:33.408Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/74/fa/a5197690b860f8a5b43e56aba4a34e0b42db6548b45dd6ceda9ab8980c63/openinference_semantic_conventions-0.1.41-py3-none-any.whl", hash = "sha256:4c55f59427436da842c7aae871965399ef92b8909b41e02c076e1092b4c12e51", size = 12678, upload-time = "2026-10-01T18:22:32.275Z" },
+]
+
[[package]]
name = "opentelemetry-api"
version = "1.38.0"
@@ -4857,6 +4898,35 @@ dev = [
{ name = "pytest-cov", specifier = ">=5.0.0,<6.0.0" },
]
+[[package]]
+name = "wrapt"
+version = "1.17.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/95/8f/aeb76c5b46e273670962298c23e7ddde79916cb74db802131d49a85e4b7d/wrapt-1.17.3.tar.gz", hash = "sha256:f66eb08feaa410fe4eebd17f2a2c8e2e46d3476e9f8c783daa8e09e0faa666d0", size = 55547, upload-time = "2025-08-12T05:53:21.714Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/9f/41/cad1aba93e752f1f9268c77270da3c469883d56e2798e7df6240dcb2287b/wrapt-1.17.3-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:ab232e7fdb44cdfbf55fc3afa31bcdb0d8980b9b95c38b6405df2acb672af0e0", size = 53998, upload-time = "2025-08-12T05:51:47.138Z" },
+ { url = "https://files.pythonhosted.org/packages/60/f8/096a7cc13097a1869fe44efe68dace40d2a16ecb853141394047f0780b96/wrapt-1.17.3-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:9baa544e6acc91130e926e8c802a17f3b16fbea0fd441b5a60f5cf2cc5c3deba", size = 39020, upload-time = "2025-08-12T05:51:35.906Z" },
+ { url = "https://files.pythonhosted.org/packages/33/df/bdf864b8997aab4febb96a9ae5c124f700a5abd9b5e13d2a3214ec4be705/wrapt-1.17.3-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:6b538e31eca1a7ea4605e44f81a48aa24c4632a277431a6ed3f328835901f4fd", size = 39098, upload-time = "2025-08-12T05:51:57.474Z" },
+ { url = "https://files.pythonhosted.org/packages/9f/81/5d931d78d0eb732b95dc3ddaeeb71c8bb572fb01356e9133916cd729ecdd/wrapt-1.17.3-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:042ec3bb8f319c147b1301f2393bc19dba6e176b7da446853406d041c36c7828", size = 88036, upload-time = "2025-08-12T05:52:34.784Z" },
+ { url = "https://files.pythonhosted.org/packages/ca/38/2e1785df03b3d72d34fc6252d91d9d12dc27a5c89caef3335a1bbb8908ca/wrapt-1.17.3-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3af60380ba0b7b5aeb329bc4e402acd25bd877e98b3727b0135cb5c2efdaefe9", size = 88156, upload-time = "2025-08-12T05:52:13.599Z" },
+ { url = "https://files.pythonhosted.org/packages/b3/8b/48cdb60fe0603e34e05cffda0b2a4adab81fd43718e11111a4b0100fd7c1/wrapt-1.17.3-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:0b02e424deef65c9f7326d8c19220a2c9040c51dc165cddb732f16198c168396", size = 87102, upload-time = "2025-08-12T05:52:14.56Z" },
+ { url = "https://files.pythonhosted.org/packages/3c/51/d81abca783b58f40a154f1b2c56db1d2d9e0d04fa2d4224e357529f57a57/wrapt-1.17.3-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:74afa28374a3c3a11b3b5e5fca0ae03bef8450d6aa3ab3a1e2c30e3a75d023dc", size = 87732, upload-time = "2025-08-12T05:52:36.165Z" },
+ { url = "https://files.pythonhosted.org/packages/9e/b1/43b286ca1392a006d5336412d41663eeef1ad57485f3e52c767376ba7e5a/wrapt-1.17.3-cp312-cp312-win32.whl", hash = "sha256:4da9f45279fff3543c371d5ababc57a0384f70be244de7759c85a7f989cb4ebe", size = 36705, upload-time = "2025-08-12T05:53:07.123Z" },
+ { url = "https://files.pythonhosted.org/packages/28/de/49493f962bd3c586ab4b88066e967aa2e0703d6ef2c43aa28cb83bf7b507/wrapt-1.17.3-cp312-cp312-win_amd64.whl", hash = "sha256:e71d5c6ebac14875668a1e90baf2ea0ef5b7ac7918355850c0908ae82bcb297c", size = 38877, upload-time = "2025-08-12T05:53:05.436Z" },
+ { url = "https://files.pythonhosted.org/packages/f1/48/0f7102fe9cb1e8a5a77f80d4f0956d62d97034bbe88d33e94699f99d181d/wrapt-1.17.3-cp312-cp312-win_arm64.whl", hash = "sha256:604d076c55e2fdd4c1c03d06dc1a31b95130010517b5019db15365ec4a405fc6", size = 36885, upload-time = "2025-08-12T05:52:54.367Z" },
+ { url = "https://files.pythonhosted.org/packages/fc/f6/759ece88472157acb55fc195e5b116e06730f1b651b5b314c66291729193/wrapt-1.17.3-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:a47681378a0439215912ef542c45a783484d4dd82bac412b71e59cf9c0e1cea0", size = 54003, upload-time = "2025-08-12T05:51:48.627Z" },
+ { url = "https://files.pythonhosted.org/packages/4f/a9/49940b9dc6d47027dc850c116d79b4155f15c08547d04db0f07121499347/wrapt-1.17.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:54a30837587c6ee3cd1a4d1c2ec5d24e77984d44e2f34547e2323ddb4e22eb77", size = 39025, upload-time = "2025-08-12T05:51:37.156Z" },
+ { url = "https://files.pythonhosted.org/packages/45/35/6a08de0f2c96dcdd7fe464d7420ddb9a7655a6561150e5fc4da9356aeaab/wrapt-1.17.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:16ecf15d6af39246fe33e507105d67e4b81d8f8d2c6598ff7e3ca1b8a37213f7", size = 39108, upload-time = "2025-08-12T05:51:58.425Z" },
+ { url = "https://files.pythonhosted.org/packages/0c/37/6faf15cfa41bf1f3dba80cd3f5ccc6622dfccb660ab26ed79f0178c7497f/wrapt-1.17.3-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:6fd1ad24dc235e4ab88cda009e19bf347aabb975e44fd5c2fb22a3f6e4141277", size = 88072, upload-time = "2025-08-12T05:52:37.53Z" },
+ { url = "https://files.pythonhosted.org/packages/78/f2/efe19ada4a38e4e15b6dff39c3e3f3f73f5decf901f66e6f72fe79623a06/wrapt-1.17.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0ed61b7c2d49cee3c027372df5809a59d60cf1b6c2f81ee980a091f3afed6a2d", size = 88214, upload-time = "2025-08-12T05:52:15.886Z" },
+ { url = "https://files.pythonhosted.org/packages/40/90/ca86701e9de1622b16e09689fc24b76f69b06bb0150990f6f4e8b0eeb576/wrapt-1.17.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:423ed5420ad5f5529db9ce89eac09c8a2f97da18eb1c870237e84c5a5c2d60aa", size = 87105, upload-time = "2025-08-12T05:52:17.914Z" },
+ { url = "https://files.pythonhosted.org/packages/fd/e0/d10bd257c9a3e15cbf5523025252cc14d77468e8ed644aafb2d6f54cb95d/wrapt-1.17.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:e01375f275f010fcbf7f643b4279896d04e571889b8a5b3f848423d91bf07050", size = 87766, upload-time = "2025-08-12T05:52:39.243Z" },
+ { url = "https://files.pythonhosted.org/packages/e8/cf/7d848740203c7b4b27eb55dbfede11aca974a51c3d894f6cc4b865f42f58/wrapt-1.17.3-cp313-cp313-win32.whl", hash = "sha256:53e5e39ff71b3fc484df8a522c933ea2b7cdd0d5d15ae82e5b23fde87d44cbd8", size = 36711, upload-time = "2025-08-12T05:53:10.074Z" },
+ { url = "https://files.pythonhosted.org/packages/57/54/35a84d0a4d23ea675994104e667ceff49227ce473ba6a59ba2c84f250b74/wrapt-1.17.3-cp313-cp313-win_amd64.whl", hash = "sha256:1f0b2f40cf341ee8cc1a97d51ff50dddb9fcc73241b9143ec74b30fc4f44f6cb", size = 38885, upload-time = "2025-08-12T05:53:08.695Z" },
+ { url = "https://files.pythonhosted.org/packages/01/77/66e54407c59d7b02a3c4e0af3783168fff8e5d61def52cda8728439d86bc/wrapt-1.17.3-cp313-cp313-win_arm64.whl", hash = "sha256:7425ac3c54430f5fc5e7b6f41d41e704db073309acfc09305816bc6a0b26bb16", size = 36896, upload-time = "2025-08-12T05:52:55.34Z" },
+ { url = "https://files.pythonhosted.org/packages/1f/f6/a933bd70f98e9cf3e08167fc5cd7aaaca49147e48411c0bd5ae701bb2194/wrapt-1.17.3-py3-none-any.whl", hash = "sha256:7171ae35d2c33d326ac19dd8facb1e82e5fd04ef8c6c0e394d7af55a55051c22", size = 23591, upload-time = "2025-08-12T05:53:20.674Z" },
+]
+
[[package]]
name = "xmltodict"
version = "1.0.4"