Local Registries for Persistent Dynamic Agents

[ashenfad]

Enable dynamically created agents (like in dogfood.py) to survive process boundaries through persistent local registries.

Problem:
Currently, dynamic agent creation breaks when crossing process boundaries. The dogfood.py pattern works within a single process but fails when state is persisted and reloaded:

# This breaks across process restarts
math_solver = create_specialist("solve math problems")
# task_fn fails when loaded in new process - agent not in registry

Root Cause:
Two global registries are cleared when processes end:

1. Agent Registry (_AGENT_REGISTRY) - stores agent instances by fingerprint
2. Dynamic Dataclass Registry - stores input dataclass definitions for serialization

Dynamic agents can't be resolved when these registries are lost.

Solution: Local Registries in Agent State

Store "recipes" for recreating dynamic agents in the parent agent's persistent state instead of relying on global registries.

Core Concept:

# Parent agent state contains agent recipes
state.set("__local_agent_registry__", {
    "math_solver_123": {
        "primer": "You are a math solver...",
        "capabilities": [
            {"type": "module", "name": "math"},     # Symbolic reference
            {"type": "class", "name": "Agent"}      # Not direct object
        ],
        "task_definitions": {
            "solve_math_problem": {
                "docstring": "Solve mathematical equations",
                "signature": {...}
            }
        }
    }
})

Cross-Process Execution Flow:

1. Task function carries parent agent fingerprint + local agent ID
2. Resolve parent agent from global registry (it's static)
3. Load parent's state and local registries
4. Reconstruct dynamic agent using symbolic references
5. Register needed dataclasses globally
6. Execute task

Hierarchical Support:
Leverage existing Namespaced state system for nested dynamic agents:

architect_state = Namespaced(base_state, "architect")
math_solver_state = Namespaced(base_state, "architect/math_solver")
equation_parser_state = Namespaced(base_state, "architect/math_solver/equation_parser")

Implementation Changes:

• Add local registry storage to BaseAgent
• Modify TaskMixin.task() to detect dynamic creation context
• Update task function resolution to check local registries first
• Extend dataclass handling for proper serialization
• Add agent reconstruction from symbolic references

Benefits:

• Persistent Dynamic Agents: dogfood.py pattern works across process boundaries
• Unlimited Nesting: Agents creating agents creating agents
• Security Preservation: Capability inheritance through symbolic references
• Zero Breaking Changes: All existing APIs work exactly as before
• Infrastructure Reuse: Built on existing Namespaced/Versioned systems

Strategic Impact:
Transforms dynamic agents from "cool demo" to production-ready pattern for:

• Server restart survival
• Distributed system deployment
• Long-running agent architectures
• Complex hierarchical agent systems

Related:

• Complements contextual primers (Contextual, Capability-Driven Primers #1) for automatic guidance
• Enables advanced agent orchestration patterns