Skip to content

Building AI agents, atomically

Document generic schema resolution and hook pausing (#329)

Kenny Vaneetvelde14cf8eb65d84
diff --git a/.claude/.codebase-info/.map-state.json b/.claude/.codebase-info/.map-state.json
index b020de2..00d0e52 100644
--- a/.claude/.codebase-info/.map-state.json
+++ b/.claude/.codebase-info/.map-state.json
@@ -2,8 +2,8 @@
"schemaVersion": 1,
"tool": "codebase-mapper",
"version": "2.15.10",
- "mappedAt": "2026-10-21",
- "gitCommit": "b8506eb910c0b1c07a5e8dd21e0ce7397154545f",
+ "mappedAt": "2026-10-24",
+ "gitCommit": "ea7c09aae6ced82dd0b5df6935f2cb0804246c88",
"documents": [
"architecture.md",
"coding-style.md",
@@ -20,13 +20,13 @@
"INDEX.md": "91bb80710a6b08c0bb9be27178d9fbf52f1d32a3cdea58b7bdb07ec295e60b68",
"architecture.md": "0ff15b04928495b48cdcf40845b5bf9e3bb548c602b734321c4b10f630d83150",
"coding-style.md": "b63e8dff06d16a2d882f02624c62f490291317aec8b3032f6d79b3ee035e8567",
- "communication.md": "0a61b6090f5e67341ad605517111270bdd04caede037e70ec6565de8dcdf5f28",
+ "communication.md": "2de7556dd0cd55fef9fd56d4cbc6c96dd8b89a29a76b1f7a97356b446a2b8093",
"dependencies.md": "abadb58027b4092afaaa0efcaec92893eac7bb598318f7f54a542fd77d607dc1",
"directory-structure.md": "c8d654506843622fd394e0a998fddba769e4ec534449ccd6755d312192184bfd",
"entry-points.md": "65ebc321a35f1ae36f587adce8b7b04b71cc4006ec7d518f4c092836c2984705",
"modules.md": "e1185cdddfbcc7a05a69b80661a6c720aa2a1fc10bc445e319983fffb875524e",
"onboarding.md": "3d28c671dc095a2aadb297bd7ab200c677779a99c7534e03e55a3d64c935f07e",
- "patterns.md": "09d04b9b8d079ac4ce9e1f5ddafabb6f3faf53b5ef48dca1c2d62d0875e149b0",
+ "patterns.md": "bd2ea1b37b5bddf1eed1e85cdb6916ac12abf18632c9f67400dc3d588d4420fe",
"tech-landscape.md": "8a4459f7309dd13fa9e2425507fec35d21b8b3f691bc6a39b6626fffb8d1744d"
}
}
diff --git a/.claude/.codebase-info/communication.md b/.claude/.codebase-info/communication.md
index b4fbce3..ee1c18e 100644
--- a/.claude/.codebase-info/communication.md
+++ b/.claude/.codebase-info/communication.md
@@ -1,6 +1,6 @@
# Communication & Integrations
-*Last Updated: 2026-10-21*
+*Last Updated: 2026-10-24*
The framework exposes no HTTP API of its own; "communication" here means how it talks to LLM
providers and external tools.
@@ -37,6 +37,8 @@ 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`.
+- `disable_hooks()` detaches this agent's registered Instructor callbacks. Registrations made while disabled stay
+ paused; `enable_hooks()` restores the remaining callbacks. Direct client callbacks and tracing hooks remain independent.
- OpenTelemetry tracing (`atomic_agents.observability`, `observability` extra = `opentelemetry-api` only): an AGENT
span per `AtomicAgent` run, a TOOL span per `BaseTool` run and one CLIENT `chat` span per Instructor attempt
(driven by Instructor hooks registered once per client), all with OpenTelemetry GenAI attributes; OpenInference
diff --git a/.claude/.codebase-info/patterns.md b/.claude/.codebase-info/patterns.md
index 3bbbd01..c8640a6 100644
--- a/.claude/.codebase-info/patterns.md
+++ b/.claude/.codebase-info/patterns.md
@@ -1,6 +1,6 @@
# Patterns & Conventions
-*Last Updated: 2026-10-20*
+*Last Updated: 2026-10-24*
## Atomicity
Build with small, single-purpose, composable parts ("LEGO blocks"): each agent, tool, and context
@@ -11,6 +11,8 @@ the next's input. See `atomic-examples/deep-research` and `orchestration-agent`.
- Every input and output is a `BaseIOSchema` (Pydantic) subclass with a **required docstring** (used
as the LLM-facing description). Naming: `<Thing>InputSchema` / `<Thing>OutputSchema`.
- Agents are parameterized by schemas via PEP 695 generics: `AtomicAgent[InputSchema, OutputSchema]`.
+- Fully specialized generic agent subclasses resolve their concrete schemas through intermediate bases per instance.
+ Different specializations keep independent input/output bindings; untyped agents retain the basic chat defaults.
- Structured output is enforced by Instructor through `response_model=OutputSchema`.
- Streaming completion accepts field names when reconstructing output schemas with aliases.
- Tool messages use Pydantic JSON-mode serialization, including JSON-only field serializers.