pyagentic-core 2.15.2.dev2__py3-none-any.whl → 2.16.1.dev1__py3-none-any.whl

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/_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/_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/_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.2.dev2.dist-info → pyagentic_core-2.16.1.dev1.dist-info}/METADATA

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

{pyagentic_core-2.15.2.dev2.dist-info → pyagentic_core-2.16.1.dev1.dist-info}/RECORD

@@ -4,10 +4,10 @@ pyagentic/logging.py,sha256=vWLKGx0jZurWQT5pMr6fLH5NgJnZd_eaB97geBnqlwI,1718
 pyagentic/updates.py,sha256=JrBxbmTRxS-4tfSrai_wPK-dxSyCiNrYwC5MgrzGj54,870
 pyagentic/_base/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pyagentic/_base/_depends.py,sha256=e9j6GiYvPJAmFExTHMeg-xcFGYvvfF9KtCstX5HDS7Y,2186
-pyagentic/_base/_exceptions.py,sha256=Z1AvSEGJu0s8dE6F8iNGBHcNOmwlaS1gA1R15ezQYg4,4298
+pyagentic/_base/_exceptions.py,sha256=2LVKYKjrjcow1rVuWK_CO49npdWP0ii090t0jEJbXHs,4388
 pyagentic/_base/_info.py,sha256=LeXn3VbEJkP4KmMpjY6bqXjHYnE-ZHLuKoRcrmrqqhs,3020
 pyagentic/_base/_mcp.py,sha256=jclmFb5yB1szg9PTskPE2hLO3fvnFKJQFnnwTLdf0IY,8327
-pyagentic/_base/_metaclasses.py,sha256=jvDuFoz2DAaVxu2vFkAbyT6W61euaDyKW3V0w5dS3kI,37067
+pyagentic/_base/_metaclasses.py,sha256=r51jGJJMXKtO19xJFf1lsjiuhDjIpRZr3YjxJySBIPg,38408
 pyagentic/_base/_prompts.py,sha256=aSUptdlKhUuJVrIb20FOvICzxp6pcmeb65Xf2goFpvk,9118
 pyagentic/_base/_ref.py,sha256=E-1DGVoM2xub476BrHOkxTqzdw-8t_N6XuEerXDYYE8,3177
 pyagentic/_base/_spec.py,sha256=Mx8tXF8ERpsuxizRXuq3wJavbXvCCGUn17YbjiOKP9Y,7670
@@ -15,9 +15,9 @@ pyagentic/_base/_state.py,sha256=-xYVIaKiaU9ERuPf-33nbUhbvI3DgIp36y1bYdYTwJU,179
 pyagentic/_base/_tool.py,sha256=03VQmY_Q_2NkNJxrHFkAzJJ09679Fb00h8ZHYrYDGUU,11038
 pyagentic/_base/_validation.py,sha256=BBscZMrXB09LNNP17pYOAY6I4iCW8r2GBVStqBd-9f8,3833
 pyagentic/_base/_agent/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pyagentic/_base/_agent/_agent.py,sha256=eyPqISReeTC-yOjva5BNFTs5dr3Qtw-is_yNyt6JWo0,43659
+pyagentic/_base/_agent/_agent.py,sha256=VkWA5Br3d3sFCXAQKZcle-ptO88FY15HyuVRmpKEr8c,44066
 pyagentic/_base/_agent/_agent_linking.py,sha256=2lVICn9SSk2dgDmdk_awIS7NaSLp-LXvpF_9L3Jaud8,1837
-pyagentic/_base/_agent/_agent_state.py,sha256=0YkbUZT-dWHWgBUoMaPjTJ3rNxE-cX0_pIqrLa7nLWM,18628
+pyagentic/_base/_agent/_agent_state.py,sha256=PP3ucelYul87SKe_LWxvoInGxXhz9Zp-wz-RSk9n838,19688
 pyagentic/_utils/_typing.py,sha256=5aRZZOVzR0ZgnBfejkw__1yoARhn70P5QzA81sxUkls,3681
 pyagentic/_utils/_warnings.py,sha256=mjlBiYHGnnh5599Gsq5ke8mBFS6WsdhNa7jk20TT9_U,1330
 pyagentic/api/__init__.py,sha256=7CklNYjxVj5XOyqTWvvWKZU6IYuU8CAfpOhNeGMH1d4,1712
@@ -56,10 +56,10 @@ pyagentic/tracing/__init__.py,sha256=ddMOl_-Nf3WOhu-PYxSJ3kqHZ3eQXAOM5aySn9YmDtA
 pyagentic/tracing/_basic.py,sha256=jUBKdkOPveCjBzEhHKS_Rvp5l38iZg-5nFIl6xEwOVk,8906
 pyagentic/tracing/_langfuse.py,sha256=5b5tdT-gyRJP5HDcvCS4tn_k3AFDI6eNsXOd6On5gKQ,13986
 pyagentic/tracing/_tracer.py,sha256=0uQeqJxPRjfQtvgglF2BPDQM_1fpLBxWB0PpU6KY1eA,8157
-pyagentic_core-2.15.2.dev2.dist-info/licenses/LICENSE,sha256=wcOzTj82hOc96HztJk2VzLB2hFHpdIGpjz8vvbpP1_s,1069
-pyagentic_core-2.15.2.dev2.dist-info/METADATA,sha256=9gHYz_wiYEPKnw7LsMxfEGbZ_3nARC_z6MVAeHt8if4,8212
-pyagentic_core-2.15.2.dev2.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-pyagentic_core-2.15.2.dev2.dist-info/scm_file_list.json,sha256=8UMtz5WpdhOSRNM1zB-dxNzobbueYJYYqfBJoM4n6_w,4883
-pyagentic_core-2.15.2.dev2.dist-info/scm_version.json,sha256=6JpJoV9gMgof65-_u6VVITIfQ_efcmI6r_PulZFbolA,165
-pyagentic_core-2.15.2.dev2.dist-info/top_level.txt,sha256=lAWfd-ay434uEpSg2FM0ySN0o4vgNGE6D9dJkIhGyfY,10
-pyagentic_core-2.15.2.dev2.dist-info/RECORD,,
+pyagentic_core-2.16.1.dev1.dist-info/licenses/LICENSE,sha256=wcOzTj82hOc96HztJk2VzLB2hFHpdIGpjz8vvbpP1_s,1069
+pyagentic_core-2.16.1.dev1.dist-info/METADATA,sha256=xC2nazJjni31ytTVBGZMG9oAqC9Ny12yGpimToki9-o,8212
+pyagentic_core-2.16.1.dev1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+pyagentic_core-2.16.1.dev1.dist-info/scm_file_list.json,sha256=8UMtz5WpdhOSRNM1zB-dxNzobbueYJYYqfBJoM4n6_w,4883
+pyagentic_core-2.16.1.dev1.dist-info/scm_version.json,sha256=QBBjEtu7R-9HQ2WE9LnqyJBz06pTR4xHOgjvxXvfNAA,162
+pyagentic_core-2.16.1.dev1.dist-info/top_level.txt,sha256=lAWfd-ay434uEpSg2FM0ySN0o4vgNGE6D9dJkIhGyfY,10
+pyagentic_core-2.16.1.dev1.dist-info/RECORD,,

pyagentic_core-2.16.1.dev1.dist-info/scm_version.json

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

pyagentic_core-2.15.2.dev2.dist-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "2.15.1.dev1",
-  "distance": 2,
-  "node": "g1f06860189326b8709a205b89bbdeb8308b82d07",
-  "dirty": true,
-  "branch": "main",
-  "node_date": "2026-07-09"
-}