Skip to content

Building AI agents, atomically

Map the observability package, Phoenix example and forge context propagation

Eigenwiseffca7a311919
diff --git a/.claude/.codebase-info/.map-state.json b/.claude/.codebase-info/.map-state.json
index 52efcd4..9ef7c2c 100644
--- a/.claude/.codebase-info/.map-state.json
+++ b/.claude/.codebase-info/.map-state.json
@@ -1,9 +1,9 @@
{
"schemaVersion": 1,
"tool": "codebase-mapper",
- "version": "2.14.4",
- "mappedAt": "2026-08-11",
- "gitCommit": "c80c7520a703018d36abc97f2199dcaf3d9c29a3",
+ "version": "2.15.10",
+ "mappedAt": "2026-10-15",
+ "gitCommit": "4801bcfcd92ed3f36ea4d3e8213413de147f6f3a",
"documents": [
"architecture.md",
"coding-style.md",
@@ -17,14 +17,14 @@
"tech-landscape.md"
],
"hashes": {
- "INDEX.md": "50e7beb7784d3d01f8ce0e85b842889f5c033ca98cbb30981fd0b532c1495c8f",
- "architecture.md": "8e6be8d2795231ea5919d7cdc23a201595f9fed9724b635e6cc686b2bf24581f",
+ "INDEX.md": "40401c94518aebe4bf68dfffb3ea6f8d7e4ce873930a2a87e3e3d7533439358e",
+ "architecture.md": "59d1265c89d3b42671b7c47165408625018537c016a72df421113cae3f80bb70",
"coding-style.md": "b63e8dff06d16a2d882f02624c62f490291317aec8b3032f6d79b3ee035e8567",
- "communication.md": "6c73cad50151b73a6be63c8f0745d3f7a6653a861d37afce660c512ac30b8819",
- "dependencies.md": "b445a920c121e27006fec824add6865d01cf71212a517e5ff8b2058d3999037a",
- "directory-structure.md": "ca200817789c4d1fdc41d1683c37740c9837bf323b18881cb2351ef8a56c4926",
- "entry-points.md": "62fd8ff478fc27c3658776626059bdd4101cab12a74a48cdd8787f9ca7b83f97",
- "modules.md": "7a8772e5f31be0070003c9a7ce78eca5df95dfb6a1c9dd471a6be97df81084aa",
+ "communication.md": "7cf34aaf643a8bfc6dfeb1f0ec070121c76c76859dbd6377f815bf21e0c29c3b",
+ "dependencies.md": "837fe41809eb2753be100ae244fec53423846867b16d91471ec3b5ae03f74e90",
+ "directory-structure.md": "31ea7434131d4e3529948b174d7f009838cfe46a71f1f9470703f3b3010c74af",
+ "entry-points.md": "3c94fd8a821fc76789794b6d3f4d89cc88a7903055755d97437f9f3ca6193cb6",
+ "modules.md": "cfe0b05069039074e488880093844fc1cdcabd01ee4c80de08ca7c86492a8e0b",
"onboarding.md": "3d28c671dc095a2aadb297bd7ab200c677779a99c7534e03e55a3d64c935f07e",
"patterns.md": "f3a339a7bc711c4586062139d135e1d79129653cf82fc430cd256028d25e2dcc",
"tech-landscape.md": "700b3ba7bb5e47ec14086e2b94ad65ad956c0bfbe1c463f96c39493143e0c912"
diff --git a/.claude/.codebase-info/INDEX.md b/.claude/.codebase-info/INDEX.md
index cbf4927..03ec62d 100644
--- a/.claude/.codebase-info/INDEX.md
+++ b/.claude/.codebase-info/INDEX.md
@@ -1,12 +1,12 @@
# Codebase Map — Atomic Agents
-*Last Updated: 2026-08-11*
+*Last Updated: 2026-10-15*
Atomic Agents is a lightweight, modular Python framework for building agentic AI applications as
composable, schema-driven building blocks (built on Instructor + Pydantic). This repository is a
`uv`-workspace **monorepo**: the core framework, a TUI tool installer, a tool library, and examples.
-**Stack:** Python ≥3.12 · Instructor · Pydantic v2 · LiteLLM · MCP · Textual · uv + Hatchling · Pyright · `VideoURL` multimodal content
+**Stack:** Python ≥3.12 · Instructor · Pydantic v2 · LiteLLM · MCP · Textual · uv + Hatchling · Pyright · `VideoURL` multimodal content · optional OpenInference tracing (Phoenix)
**Shape:** Monorepo — `atomic-agents/` (core lib) · `atomic-assembler/` (CLI) · `atomic-forge/` (tools) · `atomic-examples/` (examples)
**Package:** `atomic-agents` v2.10.3 on PyPI · core import package is `atomic_agents`
diff --git a/.claude/.codebase-info/architecture.md b/.claude/.codebase-info/architecture.md
index 9cc9cbd..4db0b97 100644
--- a/.claude/.codebase-info/architecture.md
+++ b/.claude/.codebase-info/architecture.md
@@ -1,6 +1,6 @@
# Architecture
-*Last Updated: 2026-08-11*
+*Last Updated: 2026-10-15*
## Summary
@@ -50,6 +50,7 @@ Tool install (atomic-assembler TUI):
| Context | `atomic-agents/atomic_agents/context/` | `SystemPromptGenerator`, `BaseDynamicContextProvider`, `BaseChatHistory` (pluggable memory contract) + `ChatHistory` with Instructor media and `VideoURL` |
| Connectors | `atomic-agents/atomic_agents/connectors/mcp/` | Model Context Protocol tools / resources / prompts |
| Utils | `atomic-agents/atomic_agents/utils/` | Token counting (LiteLLM), tool-message formatting |
+| Observability (opt-in) | `atomic-agents/atomic_agents/observability/` | OpenInference AGENT/TOOL spans for Phoenix / OpenTelemetry; `observability` extra + `openinference_instrumentor` entry point |
| Assembler (CLI) | `atomic-assembler/atomic_assembler/` | Textual TUI to fetch/install forge tools |
| Forge (tools) | `atomic-forge/tools/` | 13 standalone tools, each `BaseTool`-based |
diff --git a/.claude/.codebase-info/communication.md b/.claude/.codebase-info/communication.md
index 86aa7b8..8a3b4a8 100644
--- a/.claude/.codebase-info/communication.md
+++ b/.claude/.codebase-info/communication.md
@@ -1,6 +1,6 @@
# Communication & Integrations
-*Last Updated: 2026-08-11*
+*Last Updated: 2026-10-15*
The framework exposes no HTTP API of its own; "communication" here means how it talks to LLM
providers and external tools.
@@ -33,6 +33,14 @@ providers and external tools.
- Built on Instructor's hook system: `register_hook(event, handler)`, `unregister_hook`,
`clear_hooks`. Events include `parse:error`, `completion:kwargs`, `completion:response`,
`token:counted`. See the `hooks-example` example and `docs/guides/hooks.md`.
+- OpenInference tracing (`atomic_agents.observability`, optional `observability` extra): an AGENT span per
+ `AtomicAgent` run and a TOOL span per `BaseTool` run, auto-activated by `phoenix.otel.register(auto_instrument=True)`
+ through the `openinference_instrumentor` entry point, or by `AtomicAgentsInstrumentor().instrument(tracer_provider=...)`
+ for any OTLP backend. LLM spans come from the provider's own OpenInference instrumentor and nest under the agent
+ span. See `docs/guides/observability.md` and the `phoenix-tracing` example.
+- Forge tools that run their async body through a `ThreadPoolExecutor` submit via
+ `contextvars.copy_context().run` so the caller's OpenTelemetry context (and the tracing re-entrancy guard)
+ survives in the pool thread.
## Assembler ↔ GitHub
- `atomic-assembler` clones `https://github.com/eigenwise/atomic-agents.git` (via GitPython), reads
diff --git a/.claude/.codebase-info/dependencies.md b/.claude/.codebase-info/dependencies.md
index 0eba7a8..e3c4ccf 100644
--- a/.claude/.codebase-info/dependencies.md
+++ b/.claude/.codebase-info/dependencies.md
@@ -1,6 +1,6 @@
# Dependencies
-*Last Updated: 2026-06-13*
+*Last Updated: 2026-10-15*
Declared in `pyproject.toml` (Hatchling build, `uv` workspace; versions locked in `uv.lock`).
@@ -12,6 +12,16 @@ Declared in `pyproject.toml` (Hatchling build, `uv` workspace; versions locked i
| litellm (≥1.50,<2) | Provider-agnostic token counting & model metadata |
| rich (≥13.7.1,<14) | Console formatting |
+## Optional extra — `observability`
+| Package | Purpose |
+|---------|---------|
+| openinference-instrumentation (≥0.1.38,<0.2) | `OITracer` / `TraceConfig` used by `atomic_agents.observability` |
+| openinference-semantic-conventions (≥0.1.20,<0.2) | Span attribute names (`agent.name` needs ≥0.1.20) |
+| opentelemetry-api (≥1.30,<2) | Tracer / context API |
+
+Also listed in the dev group (plus `opentelemetry-sdk`) so CI runs the observability tests. `arize-phoenix-otel`
+already brings the two OpenInference packages, so the Phoenix auto path works without the extra.
+
## Runtime — CLI / tooling
| Package | Purpose |
|---------|---------|
diff --git a/.claude/.codebase-info/directory-structure.md b/.claude/.codebase-info/directory-structure.md
index d9473c7..8b800ca 100644
--- a/.claude/.codebase-info/directory-structure.md
+++ b/.claude/.codebase-info/directory-structure.md
@@ -1,6 +1,6 @@
# Directory Structure
-*Last Updated: 2026-08-11*
+*Last Updated: 2026-10-15*
## Root Layout
@@ -12,14 +12,15 @@ atomic-agents/ # repo root (uv workspace)
│ ├── base/ # BaseIOSchema, BaseTool, BaseResource, BasePrompt, VideoURL
│ ├── context/ # SystemPromptGenerator, BaseChatHistory/ChatHistory, context providers
│ ├── connectors/mcp/ # Model Context Protocol integration
-│ └── utils/ # token counter, tool-message formatting
-│ └── tests/ # pytest suite (agents/, base/, context/, connectors/, utils/; VideoURL tests in base/)
+│ ├── utils/ # token counter, tool-message formatting
+│ └── observability/ # opt-in OpenInference instrumentor (Phoenix / OpenTelemetry)
+│ └── tests/ # pytest suite (agents/, base/, context/, connectors/, observability/, utils/)
├── atomic-assembler/ # Textual TUI (`atomic` command) to install forge tools
│ └── atomic_assembler/ # main.py, app.py, screens/, widgets/, utils.py, constants.py
├── atomic-forge/ # library of standalone tools (NOT a package)
│ ├── tools/<tool>/ # one folder per tool: tool/<tool>.py, tests/, pyproject.toml
│ └── guides/ # tool authoring guides (e.g. tool_structure.md)
-├── atomic-examples/ # 16 runnable example apps (each its own project)
+├── atomic-examples/ # 17 runnable example apps (each its own project)
├── claude-plugin/atomic-agents/ # AI-assistant plugin: 7 skills + 2 subagents (Claude Code plugin,
│ # also installable cross-tool via `npx skills add eigenwise/atomic-agents`)
├── .claude-plugin/ # marketplace.json — plugin marketplace manifest (drives npx skills discovery)
@@ -54,7 +55,7 @@ and copies a selected tool into the user's project.
`pyproject.toml`/`requirements.txt`. Tools are copied into user projects, not pip-installed.
### `atomic-examples/`
-16 standalone example apps (`quickstart`, `rag-chatbot`, `deep-research`, `web-search-agent`,
+17 standalone example apps (`quickstart`, `rag-chatbot`, `deep-research`, `web-search-agent`, `phoenix-tracing`,
`mcp-agent`, `fastapi-memory`, `persistent-memory`, `youtube-summarizer`, …), each with its own
`pyproject.toml`. These are excluded from the workspace build.
diff --git a/.claude/.codebase-info/entry-points.md b/.claude/.codebase-info/entry-points.md
index ebccf30..4d15221 100644
--- a/.claude/.codebase-info/entry-points.md
+++ b/.claude/.codebase-info/entry-points.md
@@ -1,6 +1,6 @@
# Entry Points
-*Last Updated: 2026-08-11*
+*Last Updated: 2026-10-15*
## 1. Library API (the primary entry point)
@@ -49,6 +49,7 @@ MCP server tools/resources/prompts become agent components via `atomic_agents.co
| `fastapi-memory` | multi-user / multi-session memory behind a FastAPI service |
| `persistent-memory` | custom `BaseChatHistory` backend: cross-session recall via stdlib `sqlite3` (no extra deps) |
| `hooks-example` | monitoring, error handling, retry via hooks |
+| `phoenix-tracing` | Arize Phoenix traces: planner agent -> calculator tool -> answer agent under one CHAIN span, via `register(auto_instrument=True)` |
| `basic-multimodal` / `nested-multimodal` | images / PDFs in (nested) schemas |
| `basic-pdf-analysis` | PDF analysis with a multimodal model |
| `youtube-summarizer` / `youtube-to-recipe` | transcript → summary / structured recipe |
diff --git a/.claude/.codebase-info/modules.md b/.claude/.codebase-info/modules.md
index 40d733e..c16558f 100644
--- a/.claude/.codebase-info/modules.md
+++ b/.claude/.codebase-info/modules.md
@@ -1,6 +1,6 @@
# Key Modules
-*Last Updated: 2026-08-11*
+*Last Updated: 2026-10-15*
## Core framework — `atomic-agents/atomic_agents/`
@@ -44,6 +44,22 @@
- **Key files:** `token_counter.py` (`TokenCounter` via LiteLLM; `get_context_token_count`),
`format_tool_message.py`.
+### observability (opt-in)
+- **Location:** `atomic-agents/atomic_agents/observability/`
+- **Purpose:** OpenInference tracing for Arize Phoenix and any OpenTelemetry backend. `AtomicAgentsInstrumentor`
+ (`__init__.py`, stdlib-only imports) lazily loads `openinference_tracing.py`, which patches the four
+ `AtomicAgent.run*` methods into AGENT spans and every `BaseTool` subclass's `run`/`run_async`/`arun` into TOOL
+ spans (existing classes via a `__subclasses__` walk, future ones via a wrapped `BaseTool.__init_subclass__`).
+- **Contract:** `instrument(tracer_provider=, config=TraceConfig)` / `uninstrument()` /
+ `is_instrumented_by_opentelemetry`; idempotent and fully reversible. Needs the `observability` extra
+ (`openinference-instrumentation>=0.1.38`); older versions are refused with a warning so Phoenix's
+ `register(auto_instrument=True)` (which loads the `openinference_instrumentor` entry point) never fails.
+- **Span facts:** `agent.name` = `Class[InputSchema, OutputSchema]`; namespaced `atomic_agents.*` attributes
+ (model, mode, schema names, history size, context provider names, SHA-256 of the static prompt sections);
+ streams record the final/last partial and `atomic_agents.stream.closed_early`; a `ContextVar` re-entrancy guard
+ keeps `run -> arun` / `to_thread` delegation to one TOOL span. Nothing in `atomic_agents/__init__.py` imports it.
+- **Tests:** `atomic-agents/tests/observability/` (in-memory span exporter).
+
## Subprojects
### atomic-assembler (CLI)