Add Arize Phoenix / OpenInference tracing for agents and tools

[Eigenwise]

What this adds

Opt-in OpenInference tracing so Atomic Agents apps show up properly in Arize Phoenix (and any other OpenTelemetry backend). Until now you could install openinference-instrumentation-openai and get a flat list of chat completions. This PR adds the framework layer on top:

• an AGENT span per AtomicAgent.run / run_async / run_stream / run_async_stream, named Class[InputSchema, OutputSchema].run, with input/output as JSON plus atomic_agents.* attributes (model, mode, schema names, history size entering the turn, context provider names, SHA-256 of the static prompt sections)
• a TOOL span per BaseTool run / run_async / arun, including MCP-generated tools, with tool.name, tool.description, tool.parameters and I/O
• LLM spans still come from the provider instrumentor and nest under the agent span

Phoenix picks it up with zero code through the openinference_instrumentor entry point:

from phoenix.otel import register
register(project_name="my-app", auto_instrument=True)

Manual setup for any OTLP backend: AtomicAgentsInstrumentor().instrument(tracer_provider=..., config=TraceConfig(...)).

Scope

• atomic_agents.observability (new, nothing in core imports it) + 45 tests
• observability extra in pyproject.toml and the entry point; dev group carries the deps so CI runs the tests
• 8 forge tools: ThreadPoolExecutor.submit now goes through contextvars.copy_context().run. Without that the pool thread dropped the current span and the re-entrancy guard, which gave a second orphaned TOOL span per call
• atomic-examples/phoenix-tracing: planner agent -> calculator tool -> answer agent under one CHAIN span
• docs/guides/observability.md plus index/README/logging-guide links
• codebase map refresh

Things worth knowing

• The entry point is on the core package, so anyone already running register(auto_instrument=True) with atomic-agents installed starts exporting agent and tool payloads after upgrading. OPENINFERENCE_HIDE_INPUTS / OPENINFERENCE_HIDE_OUTPUTS redact them. The guide says this.
• The entry-point module imports only stdlib and refuses openinference-instrumentation below 0.1.38 with a warning, so a Phoenix environment can never crash on load.
• Streams record the final response (or the last partial with atomic_agents.stream.closed_early=true on early break or cancellation). The system prompt text stays on the LLM span; the agent span carries a hash of the static sections so you can tell prompt versions apart even with inputs hidden.
• Agent subclasses that override run without calling super() are not traced (documented).

Verification

• uv run pytest --cov=atomic_agents atomic-agents: 453 passed, 3 skipped; the new module is at 97% coverage
• same observability tests pass at the floor versions (openinference-instrumentation==0.1.38, openinference-semantic-conventions==0.1.20)
• black / flake8 clean across all four dirs; every new function has cyclomatic complexity 4 or lower
• wheel metadata checked: Provides-Extra: observability and the [openinference_instrumentor] group are present
• the 8 touched forge tools' suites: 214 passed, 1 pre-existing failure that needs a real BOCHA_API_KEY (fails identically on main)
• the example was import-checked with a dummy key; a full run needs an OpenAI key and a Phoenix server, I did not run that

The plan and the implementation each went through three independent reviews (OpenInference maintainer angle, Atomic Agents maintainer angle, adversarial user/test angle); everything they flagged as blocking or should-fix is in.

🤖 Generated with Claude Code