pyagentic-core 2.15.1.dev1__tar.gz → 2.16.0a1__tar.gz

{pyagentic_core-2.15.1.dev1 → pyagentic_core-2.16.0a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyagentic-core
-Version: 2.15.1.dev1
+Version: 2.16.0a1
 Summary: Build LLM Agents in a Pythonic way
 Author-email: Ryan Mikulec <rmikulec.dev@gmail.com>
 License: MIT

{pyagentic_core-2.15.1.dev1 → pyagentic_core-2.16.0a1}/docs/inheritance.md

@@ -4,27 +4,47 @@ PyAgentic supports standard Python inheritance, allowing you to build agent hier
 
 ## How Inheritance Works
 
-Agent inheritance follows Python's standard rules with some PyAgentic-specific behaviors. When you inherit from an agent, you get all its tools, context items, and linked agents. However, each agent must define its own instructions to maintain clear identity and purpose.
+Agent inheritance follows Python's standard rules with some PyAgentic-specific behaviors. When you inherit from an agent, you get all its tools, context items, linked agents, and instructions.
 
 PyAgentic builds the complete agent schema at class definition time, combining inherited elements with new ones to create a fully-typed, predictable agent interface.
 
 ### Inheritance Rules
 
-PyAgentic follows specific rules about what gets inherited and what must be redefined:
-
-#### What Gets Inherited ✅
+Everything inherits by default:
 
 - **Tools** - All `@tool` methods are inherited and can be overridden
 - **State Fields** - `State` fields inherit with their defaults and types
 - **Linked Agents** - Agent references are inherited, child classes can add more
 - **Properties** - Dynamic properties are inherited and overridable
+- **Instructions** - `__instructions__` is inherited from the nearest ancestor when not declared; somewhere in the hierarchy it must be declared
+
+When a child declares its own `__instructions__`, it fully replaces the parent's — unless it opts back in with `{{ super }}` (see below).
+
+### Inheriting and Extending Instructions
+
+A child that doesn't declare `__instructions__` simply uses its parent's:
+
+```python
+class SupportAgent(BaseAgent):
+    __instructions__ = "You help customers troubleshoot {{ product }} issues."
 
-#### What Must Be Redefined ❌
+    product: State[str] = spec.State(default="our product")
 
-- **Instructions** - Each agent must define its own `__instructions__` to maintain clear identity
-- **Input Templates** - `__input_template__` is not inherited, allowing agent-specific formatting
+class BillingSupportAgent(SupportAgent):
+    # No __instructions__ — inherits SupportAgent's
+    ...
+```
+
+A child that overrides can embed the parent's fully rendered instructions with `{{ super }}`, mirroring Jinja's template inheritance:
+
+```python
+class BillingSupportAgent(SupportAgent):
+    __instructions__ = """{{ super }}
+
+You specialize in billing: refunds, invoices, and subscription changes."""
+```
 
-This design ensures that while agents can share functionality, each maintains its own distinct purpose and behavior.
+`{{ super }}` is the parent's instructions rendered with the *same* state, so templates like `{{ product }}` in the parent interpolate as usual. Chains fold through multiple levels — a grandchild's `{{ super }}` includes the parent's `{{ super }}` expansion, and so on. If there is no parent to inherit from, `{{ super }}` renders as an empty string.
 
 ## Basic Inheritance
 

{pyagentic_core-2.15.1.dev1 → pyagentic_core-2.16.0a1}/mkdocs.yml

@@ -10,6 +10,7 @@ nav:
     - Execution Modes: execution-modes.md
     - Tools: tools.md
     - State Management: states.md
+    - Prompt Management: prompts.md
     - Phases: phases.md
     - Policies:
       - Overview: policies/index.md

{pyagentic_core-2.15.1.dev1 → pyagentic_core-2.16.0a1}/pyagentic/_base/_agent/_agent.py

@@ -128,10 +128,12 @@ class BaseAgent(metaclass=AgentMeta):
 
     Agent definition requires the use of special decorators and class attributes:
       - @tool: Declares a method as a tool callable by the LLM
-      - __instructions__: Required class attribute defining the agent's instructions,
-            either as a string or a PromptRef from a PromptEngine. Rendered with state
-            into the system message sent to the LLM. (__system_message__ is the
-            deprecated spelling.)
+      - __instructions__: Class attribute defining the agent's instructions, either as
+            a string or a PromptRef from a PromptEngine. Rendered with state into the
+            system message sent to the LLM. Inherited from the nearest ancestor when
+            not declared; an overriding declaration can embed the parent's rendered
+            instructions with `{{ super }}`. Required somewhere in the hierarchy.
+            (__system_message__ is the deprecated spelling.)
       - __description__: Optional description used when agent is linked to another agent
       - __input_template__: Optional template for formatting user input
       - __response_format__: Optional Pydantic model for structured output
@@ -179,8 +181,11 @@ class BaseAgent(metaclass=AgentMeta):
     __dependencies__: ClassVar[dict[str, type]]  # Depends[T] field -> dependency type
 
     # User-set Class Attributes (defined in subclass)
-    __instructions__: ClassVar[Union[str, PromptRef]]  # Required: the agent's instructions
+    __instructions__: ClassVar[Union[str, PromptRef]]  # The agent's instructions (inheritable)
     __system_message__: ClassVar[str]  # Deprecated: old spelling of __instructions__
+    # Overridden ancestor instructions, oldest first (set by metaclass); rendered
+    # into __instructions__ as `{{ super }}`
+    __parent_instructions__: ClassVar[tuple[Union[str, PromptRef], ...]] = ()
     __description__: ClassVar[str]  # Optional: description for linked agents
     __input_template__: ClassVar[str] = None  # Optional: template for user input
     __response_format__: ClassVar[Type[BaseModel]] = None  # Optional: structured output format

{pyagentic_core-2.15.1.dev1 → pyagentic_core-2.16.0a1}/pyagentic/_base/_agent/_agent_state.py

@@ -36,6 +36,10 @@ class _AgentState(BaseModel):
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
     instructions: str | PromptRef
+    # Instructions of overridden ancestors, oldest first; rendered into the
+    # template as `{{ super }}`. Excluded from dumps so it never leaks into
+    # template context or serialized state.
+    parent_instructions: tuple = Field(default=(), exclude=True)
     input_template: Optional[str] = "{{ user_message }}"
 
     _machine: Machine = PrivateAttr(default=None)
@@ -44,6 +48,7 @@ class _AgentState(BaseModel):
     _last_usage: Optional[UsageInfo] = PrivateAttr(default=None)
     _prompt_source: Optional[PromptSource] = PrivateAttr(default=None)
     _instructions_template: Template = PrivateAttr(default_factory=lambda: Template(source=""))
+    _parent_templates: list[Template] = PrivateAttr(default_factory=list)
     _input_template: Template = PrivateAttr(
         default_factory=lambda: Template(source="{{ user_message }}")
     )
@@ -91,6 +96,14 @@ class _AgentState(BaseModel):
             )
 
         self._instructions_template = Template(source=self.instructions)
+
+        # Templates for overridden ancestor instructions (oldest first); each may
+        # itself be a PromptRef, resolved here just like the main instructions
+        self._parent_templates = [
+            Template(source=parent.resolve().text if isinstance(parent, PromptRef) else parent)
+            for parent in self.parent_instructions
+        ]
+
         if self.input_template:
             self._input_template = Template(source=self.input_template)
 
@@ -417,16 +430,23 @@ class _AgentState(BaseModel):
         """
         Returns the current formatted system message with state fields interpolated.
 
+        When the agent overrides an ancestor's instructions, the ancestor chain is
+        rendered first (with the same state context) and exposed to each template
+        as `{{ super }}`, mirroring template inheritance in Jinja.
+
         Returns:
             str: The rendered system message with state values
         """
-        # start with all the normal dataclass fields
-
-        # now format your instruction template
+        context = self.model_dump()
         if self.phase:
-            return self._instructions_template.render(phase=self.phase, **self.model_dump())
-        else:
-            return self._instructions_template.render(**self.model_dump())
+            context["phase"] = self.phase
+
+        # Fold the ancestor chain oldest-to-newest so each template's `{{ super }}`
+        # is its own parent's fully rendered instructions
+        rendered = ""
+        for template in (*self._parent_templates, self._instructions_template):
+            rendered = template.render(**{**context, "super": rendered})
+        return rendered
 
     @property
     def messages(self) -> list[Message]:

{pyagentic_core-2.15.1.dev1 → pyagentic_core-2.16.0a1}/pyagentic/_base/_exceptions.py

@@ -18,12 +18,13 @@ class InvalidToolDefinition(Exception):
 class InstructionsNotDeclared(Exception):
     """
     Exception raised when an Agent subclass is created without declaring __instructions__
-    (or the deprecated __system_message__).
+    (or the deprecated __system_message__) and no ancestor declares one to inherit.
     """
 
     def __init__(self):
         super().__init__(
-            "Instructions not declared on agent. Agent must be declared with `__instructions__`"
+            "Instructions not declared on agent. Agent must be declared with "
+            "`__instructions__` or inherit one from a parent agent"
         )
 
 

{pyagentic_core-2.15.1.dev1 → pyagentic_core-2.16.0a1}/pyagentic/_base/_metaclasses.py

@@ -611,6 +611,7 @@ class AgentMeta(type):
             # Create the state object with instructions and state fields
             self.state = self.__state_class__(
                 instructions=self.__instructions__,
+                parent_instructions=self.__parent_instructions__,
                 input_template=self.__input_template__,
                 **compiled,
             )
@@ -665,7 +666,10 @@ class AgentMeta(type):
 
         Inheritance is respected in MRO order. Tools, state attributes, and linked agents
         can all be inherited from other agents or mixins.
-        __instructions__ and __input_template__ are *not* inherited.
+        __instructions__ is inherited from the nearest ancestor when not declared. When a
+        subclass declares its own __instructions__, the ancestor chain is recorded on
+        __parent_instructions__ so the template can embed the parent's rendered
+        instructions via `{{ super }}`.
 
         Args:
             name (str): Name of the new class
@@ -700,10 +704,11 @@ class AgentMeta(type):
                 mcs.__BaseAgent__ = cls
                 return cls
             cls.__abstract_base__ = False
-            # Verify instructions are set (not inherited); __system_message__ is
-            # the deprecated spelling and normalizes onto __instructions__
+            # Resolve instructions; __system_message__ is the deprecated spelling
+            # and normalizes onto __instructions__
+            declared = None
             if "__instructions__" in namespace:
-                cls.__instructions__ = namespace["__instructions__"]
+                declared = namespace["__instructions__"]
             elif "__system_message__" in namespace:
                 warnings.warn(
                     f"`__system_message__` on {name} is deprecated; "
@@ -711,7 +716,27 @@ class AgentMeta(type):
                     DeprecationWarning,
                     stacklevel=2,
                 )
-                cls.__instructions__ = namespace["__system_message__"]
+                declared = namespace["__system_message__"]
+
+            inherited_instructions = inherited_namespace.get(
+                "__instructions__", inherited_namespace.get("__system_message__")
+            )
+            if declared is not None:
+                cls.__instructions__ = declared
+                # When overriding an ancestor's instructions, record the ancestor
+                # chain (oldest first) so the template can embed the parent's
+                # rendered instructions via `{{ super }}`
+                if inherited_instructions is not None:
+                    cls.__parent_instructions__ = (
+                        *inherited_namespace.get("__parent_instructions__", ()),
+                        inherited_instructions,
+                    )
+                else:
+                    cls.__parent_instructions__ = ()
+            elif inherited_instructions is not None:
+                # Instructions are inherited from the nearest ancestor;
+                # __parent_instructions__ resolves to the declaring ancestor's chain
+                cls.__instructions__ = inherited_instructions
             else:
                 raise InstructionsNotDeclared()
             # Keep the deprecated attribute readable for backwards compatibility

{pyagentic_core-2.15.1.dev1 → pyagentic_core-2.16.0a1}/pyagentic_core.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyagentic-core
-Version: 2.15.1.dev1
+Version: 2.16.0a1
 Summary: Build LLM Agents in a Pythonic way
 Author-email: Ryan Mikulec <rmikulec.dev@gmail.com>
 License: MIT

pyagentic_core-2.16.0a1/pyagentic_core.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "2.15.2.dev2",
+  "distance": 1,
+  "node": "gadae32f31efb39fd485e1da58335278a0b1e6cd0",
+  "dirty": true,
+  "branch": "feat/inherited-instructions",
+  "node_date": "2026-07-09"
+}

{pyagentic_core-2.15.1.dev1 → pyagentic_core-2.16.0a1}/tests/_base/test_agent_inheritance.py

@@ -2,7 +2,9 @@ import pytest
 from pydantic import BaseModel
 
 from pyagentic import BaseAgent, AgentExtension, tool, spec, State
-from pyagentic._base._exceptions import SystemMessageNotDeclared
+from pyagentic._base._exceptions import InstructionsNotDeclared, SystemMessageNotDeclared
+
+_PROVIDER_KWARGS = {"model": "openai::validation", "api_key": "validation"}
 
 
 class TestBasicInheritance:
@@ -128,6 +130,134 @@ class TestAgentExtension:
         assert "cache" in MyAgent.__tool_defs__
 
 
+class TestInstructionInheritance:
+    """Test that __instructions__ are inherited and composable via {{ super }}."""
+
+    def test_child_inherits_parent_instructions(self):
+        """Test that a child without __instructions__ uses the parent's."""
+
+        class ParentAgent(BaseAgent):
+            __instructions__ = "I am a parent agent"
+
+        class ChildAgent(ParentAgent):
+            pass
+
+        assert ChildAgent.__instructions__ == "I am a parent agent"
+        child = ChildAgent(**_PROVIDER_KWARGS)
+        assert child.state.system_message == "I am a parent agent"
+
+    def test_no_instructions_anywhere_raises(self):
+        """Test that an agent hierarchy with no instructions at all still raises."""
+
+        with pytest.raises(InstructionsNotDeclared):
+
+            class NoInstructionsAgent(BaseAgent):
+                pass
+
+    def test_override_injects_parent_via_super(self):
+        """Test that an overriding child can embed the parent's instructions."""
+
+        class ParentAgent(BaseAgent):
+            __instructions__ = "I am a parent agent."
+
+        class ChildAgent(ParentAgent):
+            __instructions__ = "{{ super }} I also review code."
+
+        child = ChildAgent(**_PROVIDER_KWARGS)
+        assert child.state.system_message == "I am a parent agent. I also review code."
+
+    def test_override_without_super_replaces(self):
+        """Test that overriding without {{ super }} fully replaces the parent's."""
+
+        class ParentAgent(BaseAgent):
+            __instructions__ = "I am a parent agent."
+
+        class ChildAgent(ParentAgent):
+            __instructions__ = "I am my own agent."
+
+        child = ChildAgent(**_PROVIDER_KWARGS)
+        assert child.state.system_message == "I am my own agent."
+
+    def test_super_renders_parent_with_state(self):
+        """Test that state fields interpolate inside the injected parent template."""
+
+        class ParentAgent(BaseAgent):
+            __instructions__ = "I help the {{ team }} team."
+
+            team: State[str] = spec.State(default="core")
+
+        class ChildAgent(ParentAgent):
+            __instructions__ = "{{ super }} I specialize in {{ language }}."
+
+            language: State[str] = spec.State(default="python")
+
+        child = ChildAgent(team="data", **_PROVIDER_KWARGS)
+        assert child.state.system_message == "I help the data team. I specialize in python."
+
+    def test_super_chains_through_grandparent(self):
+        """Test that {{ super }} folds through multiple overriding levels."""
+
+        class GrandparentAgent(BaseAgent):
+            __instructions__ = "Level 1."
+
+        class ParentAgent(GrandparentAgent):
+            __instructions__ = "{{ super }} Level 2."
+
+        class ChildAgent(ParentAgent):
+            __instructions__ = "{{ super }} Level 3."
+
+        child = ChildAgent(**_PROVIDER_KWARGS)
+        assert child.state.system_message == "Level 1. Level 2. Level 3."
+
+    def test_super_chain_skips_non_declaring_level(self):
+        """Test that a non-declaring middle class passes its parent's chain through."""
+
+        class GrandparentAgent(BaseAgent):
+            __instructions__ = "Level 1."
+
+        class ParentAgent(GrandparentAgent):
+            pass
+
+        class ChildAgent(ParentAgent):
+            __instructions__ = "{{ super }} Level 3."
+
+        child = ChildAgent(**_PROVIDER_KWARGS)
+        assert child.state.system_message == "Level 1. Level 3."
+
+    def test_super_empty_without_parent(self):
+        """Test that {{ super }} renders empty when there is nothing to inherit."""
+
+        class RootAgent(BaseAgent):
+            __instructions__ = "{{ super }}Root."
+
+        agent = RootAgent(**_PROVIDER_KWARGS)
+        assert agent.state.system_message == "Root."
+
+    def test_fork_preserves_inherited_instructions(self):
+        """Test that forked agents render the same composed system message."""
+
+        class ParentAgent(BaseAgent):
+            __instructions__ = "I am a parent agent."
+
+        class ChildAgent(ParentAgent):
+            __instructions__ = "{{ super }} I also review code."
+
+        child = ChildAgent(**_PROVIDER_KWARGS)
+        fork = child.fork()
+        assert fork.state.system_message == child.state.system_message
+
+    def test_deprecated_system_message_inherits(self):
+        """Test that the deprecated __system_message__ spelling still inherits."""
+
+        class ParentAgent(BaseAgent):
+            __system_message__ = "I am a parent agent"
+
+        class ChildAgent(ParentAgent):
+            pass
+
+        assert ChildAgent.__instructions__ == "I am a parent agent"
+
+
 class TestComplexInheritance:
     """Test complex inheritance scenarios."""
 

pyagentic_core-2.15.1.dev1/pyagentic_core.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "2.15.0a1",
-  "distance": 1,
-  "node": "g26af3c3b63e03e136fae8fa6570e033dfc025e82",
-  "dirty": true,
-  "branch": "main",
-  "node_date": "2026-07-09"
-}