Atomic Agents Files

Features

• Tracing now runs on opentelemetry-api alone and emits OpenTelemetry GenAI semantic-convention spans, so any OTLP backend reads them: a plain collector, Grafana Tempo, Sentry, Datadog, Honeycomb, PostHog, Jaeger, Arize Phoenix, Langfuse. Phoenix and the OpenInference packages are no longer required.
• One chat {model} CLIENT span per Instructor attempt, driven by Instructor hooks: per-attempt and total usage (input, output, cached and reasoning tokens) for both chat-completion and Responses shapes, gen_ai.response.model, attempt count, validation errors as events, error.type on failures. Totals also land on the agent span.
• AgentConfig(name=...) gives agents a stable span name (invoke_agent {name}); using_conversation(conversation_id) sets gen_ai.conversation.id on everything inside the block.
• TracingConfig(hide_inputs, hide_outputs, max_attribute_length, openinference_attributes, llm_spans) replaces ad-hoc keyword options, with environment equivalents ATOMIC_AGENTS_TRACE_HIDE_INPUTS, ATOMIC_AGENTS_TRACE_HIDE_OUTPUTS, ATOMIC_AGENTS_TRACE_MAX_ATTRIBUTE_LENGTH and ATOMIC_AGENTS_TRACE_LLM_SPANS. The OPENINFERENCE_HIDE_* variables still work as a fallback.
• Hiding is applied before serialization and wins over truncation. Under hide_outputs every exception is reduced to <Type>: <N> attempts (__REDACTED__) and traceback frames carry no source lines, so retry exhaustion cannot leak model output.
• Cancellation (CancelledError, GeneratorExit) is recorded as atomic_agents.cancelled=true with status UNSET on agent and tool spans, never as an error.
• A second instrument() call with different explicit values replaces the installed provider or config in place with a WARNING; None keeps the installed value. AtomicAgent.clear_hooks() removes only the agent's own handlers.

Packaging

• atomic-agents[observability] now installs only opentelemetry-api.
• New atomic-agents[phoenix] extra adds openinference-instrumentation and openinference-semantic-conventions. OpenInference attributes switch on automatically when those packages are importable, or explicitly with TracingConfig(openinference_attributes=True).
• Phoenix users on register(auto_instrument=True) keep working after switching to the phoenix extra. When a provider instrumentor (OpenAI, Anthropic) also emits LLM spans, set ATOMIC_AGENTS_TRACE_LLM_SPANS=false to avoid duplicates.

Docs

• docs/guides/observability.md rewritten OTLP-first with per-backend recipes (recipes nobody has run against a live backend are marked as such), a privacy section and the LLM attempt span contract.
• README gained an Observability section; the phoenix-tracing example now installs the phoenix extra.

Verification

• Merged-tree gate: 806 core tests passed, about 200 observability tests including 24 real-Instructor cases over httpx.MockTransport across TOOLS, JSON, JSON_SCHEMA and RESPONSES_TOOLS modes, pyright 0 errors, Black and Flake8 clean, Sphinx builds.
• CI fresh-install job installs the wheel with [observability] plus opentelemetry-sdk, proves openinference is absent, runs a real Instructor client over a mock transport and asserts the GenAI keys, usage totals and gen_ai.conversation.id, and the absence of every OpenInference key. The lowest-versions job compiles both extras.
• Reviewed and probed by an external consumer (Sentry and Grafana Tempo targets, no OpenInference installed): 59 of 60 checks passed on the review head, the remaining item fixed before merge.

Tests used synthetic inputs and local or mock transports. No live model or remote tracing-backend calls.

Full changelog: https://github.com/Eigenwise/atomic-agents/compare/v2.14.0...v2.15.0