pyagentic-core 2.14.1.dev1__py3-none-any.whl → 2.15.1.dev1__py3-none-any.whl

pyagentic/__init__.py

@@ -13,7 +13,7 @@ Quick Start:
     from pyagentic import BaseAgent, tool
 
     class MyAgent(BaseAgent):
-        __system_message__ = "You are a helpful assistant"
+        __instructions__ = "You are a helpful assistant"
 
         @tool("Calculate the sum of two numbers")
         def add(self, a: int, b: int) -> str:
@@ -34,6 +34,7 @@ Main Components:
     - spec: Configuration factory for state, params, and agent links
     - ref: Dynamic state reference system for tool parameters
     - AgentExtension: Base class for creating reusable agent mixins
+    - PromptEngine / LocalPromptEngine: Managed sources for agent instructions
 """
 
 from pyagentic._base._spec import spec
@@ -45,6 +46,7 @@ from pyagentic._base._tool import tool
 from pyagentic._base._state import State
 from pyagentic._base._depends import Depends
 from pyagentic._base._ref import ref
+from pyagentic._base._prompts import PromptEngine, LocalPromptEngine, PromptRef, PromptSource
 
 __all__ = [
     "BaseAgent",
@@ -56,4 +58,8 @@ __all__ = [
     "Depends",
     "MCPLink",
     "ref",
+    "PromptEngine",
+    "LocalPromptEngine",
+    "PromptRef",
+    "PromptSource",
 ]

pyagentic/_base/_agent/_agent.py

@@ -24,6 +24,7 @@ from pyagentic._base._state import _StateDefinition
 from pyagentic._base._metaclasses import AgentMeta
 from pyagentic._base._exceptions import InvalidLLMSetup, InvalidToolDefinition
 from pyagentic._base._info import _SpecInfo
+from pyagentic._base._prompts import PromptRef
 from pyagentic._base._agent._agent_state import _AgentState
 
 if TYPE_CHECKING:
@@ -91,7 +92,7 @@ class AgentExtension:
                 return f"Logged: {message}"
 
         class MyAgent(BaseAgent, LoggingMixin):
-            __system_message__ = "You are a helpful agent with logging"
+            __instructions__ = "You are a helpful agent with logging"
         ```
     """
 
@@ -127,7 +128,10 @@ 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
-      - __system_message__: Required class attribute defining the agent's system prompt
+      - __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.)
       - __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
@@ -175,7 +179,8 @@ class BaseAgent(metaclass=AgentMeta):
     __dependencies__: ClassVar[dict[str, type]]  # Depends[T] field -> dependency type
 
     # User-set Class Attributes (defined in subclass)
-    __system_message__: ClassVar[str]  # Required: system prompt for the agent
+    __instructions__: ClassVar[Union[str, PromptRef]]  # Required: the agent's instructions
+    __system_message__: ClassVar[str]  # Deprecated: old spelling of __instructions__
     __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
@@ -381,7 +386,7 @@ class BaseAgent(metaclass=AgentMeta):
         Example:
             ```python
             class DatabaseAgent(BaseAgent):
-                __system_message__ = "You query databases"
+                __instructions__ = "You query databases"
                 connection: Optional[Connection] = None
 
                 def __post_init__(self):
@@ -887,6 +892,7 @@ class BaseAgent(metaclass=AgentMeta):
                 "final_output": final_ai_output,
                 "state": self.state,
                 "provider_info": self.provider._info,
+                "prompt": self.state.prompt_source,
             }
             # Include tool/agent responses if any were called
             if self.__tool_defs__:
@@ -957,7 +963,7 @@ class BaseAgent(metaclass=AgentMeta):
         Example (Custom Implementation):
             ```python
             class CoursePlannerAgent(BaseAgent):
-                __system_message__ = "You design course curricula"
+                __instructions__ = "You design course curricula"
                 __description__ = "Creates structured course plans"
 
                 async def __call__(

pyagentic/_base/_agent/_agent_linking.py

@@ -21,11 +21,11 @@ class Link(Generic[T]):
     Example:
         ```python
         class ResearchAgent(BaseAgent):
-            __system_message__ = "You research topics deeply"
+            __instructions__ = "You research topics deeply"
             __description__ = "Research agent for gathering detailed information"
 
         class OrchestratorAgent(BaseAgent):
-            __system_message__ = "You coordinate research tasks"
+            __instructions__ = "You coordinate research tasks"
 
             # Link research agent as a tool
             researcher: Link[ResearchAgent]

pyagentic/_base/_agent/_agent_state.py

@@ -1,13 +1,14 @@
 import asyncio
 import threading
 from typing import Any, Type, Self, Optional, ClassVar
-from pydantic import BaseModel, create_model, Field, PrivateAttr, computed_field
+from pydantic import BaseModel, ConfigDict, create_model, Field, PrivateAttr
 from jinja2 import Template
 from typing import Optional, Literal, Callable
 from transitions import Machine
 
 from pyagentic._base._exceptions import InvalidStateRefNotFoundInState
 from pyagentic._base._state import _StateDefinition
+from pyagentic._base._prompts import PromptRef, PromptSource, _inline_source
 from pyagentic.policies._policy import Policy
 from pyagentic.policies._events import Event, EventKind, GetEvent, SetEvent, CompileEvent
 from pyagentic.policies._list import PolicyList
@@ -30,14 +31,18 @@ class _AgentState(BaseModel):
         ("background", EventKind.APPEND): "background_append",
     }
     __policies__: ClassVar[dict[str, list[Policy]]] = {}
+    __agent_name__: ClassVar[str] = ""
 
-    instructions: str
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    instructions: str | PromptRef
     input_template: Optional[str] = "{{ user_message }}"
 
     _machine: Machine = PrivateAttr(default=None)
     _messages: list[Message] = PrivateAttr(default_factory=list)
     _context: list[Message] = PrivateAttr(default_factory=list)
     _last_usage: Optional[UsageInfo] = PrivateAttr(default=None)
+    _prompt_source: Optional[PromptSource] = PrivateAttr(default=None)
     _instructions_template: Template = PrivateAttr(default_factory=lambda: Template(source=""))
     _input_template: Template = PrivateAttr(
         default_factory=lambda: Template(source="{{ user_message }}")
@@ -73,6 +78,18 @@ class _AgentState(BaseModel):
                     getattr(self._machine, trigger)()
 
     def model_post_init(self, state):
+        # Instructions declared as a PromptRef resolve here, at instantiation, so
+        # every new agent instance (and every fork) picks up the latest prompt.
+        # Plain strings get an "inline" PromptSource so every run still carries
+        # versioned prompt metadata.
+        if isinstance(self.instructions, PromptRef):
+            self._prompt_source = self.instructions.resolve()
+            self.instructions = self._prompt_source.text
+        else:
+            self._prompt_source = _inline_source(
+                self.instructions, source=self.__agent_name__ or type(self).__name__
+            )
+
         self._instructions_template = Template(source=self.instructions)
         if self.input_template:
             self._input_template = Template(source=self.input_template)
@@ -364,7 +381,10 @@ class _AgentState(BaseModel):
                 raise RuntimeError(f"Unexpected ctx_map entry for {_name!r}: {definition!r}")
 
         # now build the dataclass
-        return create_model(f"AgentState[{name}]", __base__=cls, **pydantic_fields)
+        model = create_model(f"AgentState[{name}]", __base__=cls, **pydantic_fields)
+        # Used as the PromptSource `source` for inline (plain string) instructions
+        model.__agent_name__ = name
+        return model
 
     @property
     def phase(self) -> str:
@@ -380,6 +400,18 @@ class _AgentState(BaseModel):
         """
         return self._messages[-1]
 
+    @property
+    def prompt_source(self) -> PromptSource:
+        """
+        Returns metadata about the prompt behind the instructions: the engine it
+        was loaded from (source_type "local", ...), or an "inline" source named
+        after the agent for instructions declared as a plain string.
+
+        Returns:
+            PromptSource: The prompt text plus source, version, and load-time metadata.
+        """
+        return self._prompt_source
+
     @property
     def system_message(self) -> str:
         """

pyagentic/_base/_depends.py

@@ -28,7 +28,7 @@ class Depends(Generic[T]):
         from pyagentic import BaseAgent, State, Depends
 
         class ResearchAgent(BaseAgent):
-            __system_message__ = "You research topics"
+            __instructions__ = "You research topics"
 
             topic: State[TopicState]      # client-provided per session
             db:    Depends[Database]      # injected by the developer, by type

pyagentic/_base/_exceptions.py

@@ -15,17 +15,36 @@ class InvalidToolDefinition(Exception):
         super().__init__(message)
 
 
-class SystemMessageNotDeclared(Exception):
+class InstructionsNotDeclared(Exception):
     """
-    Exception raised when an Agent subclass is created without declaring __system_message__.
+    Exception raised when an Agent subclass is created without declaring __instructions__
+    (or the deprecated __system_message__).
     """
 
     def __init__(self):
         super().__init__(
-            "System message not declared on agent. Agent must be declared with `__system_message__`"  # noqa E501
+            "Instructions not declared on agent. Agent must be declared with `__instructions__`"
         )
 
 
+# Deprecated alias, kept for backwards compatibility with the old dunder name
+SystemMessageNotDeclared = InstructionsNotDeclared
+
+
+class PromptNotFound(Exception):
+    """
+    Exception raised when a PromptEngine cannot find a prompt for the given key.
+
+    Args:
+        key (str): The prompt key that was requested
+        source (str): Where the engine looked (e.g. the root directory)
+    """
+
+    def __init__(self, key, source):
+        message = f"Prompt '{key}' not found in {source}"
+        super().__init__(message)
+
+
 class UnexpectedStateItemType(Exception):
     """
     Exception raised when a state item is initialized with a value of an unexpected type.

pyagentic/_base/_mcp.py

@@ -27,7 +27,7 @@ class MCPLink:
     Example:
         ```python
         class MyAgent(BaseAgent):
-            __system_message__ = "You are helpful"
+            __instructions__ = "You are helpful"
 
             fs: MCPLink = spec.MCPLink(
                 "npx",

pyagentic/_base/_metaclasses.py

@@ -11,7 +11,7 @@ from pydantic import BaseModel, Field, create_model
 
 from pyagentic._base._info import _SpecInfo, ParamInfo, AgentInfo, MCPInfo
 from pyagentic._base._validation import _AgentConstructionValidator
-from pyagentic._base._exceptions import SystemMessageNotDeclared, UnexpectedStateItemType
+from pyagentic._base._exceptions import InstructionsNotDeclared, UnexpectedStateItemType
 from pyagentic._base._agent._agent_state import _AgentState
 from pyagentic._base._tool import _ToolDefinition, tool
 from pyagentic._base._state import State, StateInfo, _StateDefinition
@@ -35,7 +35,7 @@ class Agent:
 class AgentMeta(type):
     """
     Metaclass that applies only to Agent subclasses:
-      - Ensures __system_message__ was declared
+      - Ensures __instructions__ (or the deprecated __system_message__) was declared
       - Collects @tool definitions and State field attributes
       - Initializes class __tool_defs__ and __state_defs__
       - Dynamically injects an __init__ signature based on class __annotations__
@@ -608,9 +608,9 @@ class AgentMeta(type):
                 else:
                     compiled[name] = definition.info.get_default()
 
-            # Create the state object with system message and state fields
+            # Create the state object with instructions and state fields
             self.state = self.__state_class__(
-                instructions=self.__system_message__,
+                instructions=self.__instructions__,
                 input_template=self.__input_template__,
                 **compiled,
             )
@@ -665,7 +665,7 @@ class AgentMeta(type):
 
         Inheritance is respected in MRO order. Tools, state attributes, and linked agents
         can all be inherited from other agents or mixins.
-        __system_message__ and __input_template__ are *not* inherited.
+        __instructions__ and __input_template__ are *not* inherited.
 
         Args:
             name (str): Name of the new class
@@ -677,7 +677,8 @@ class AgentMeta(type):
             type: The newly created Agent subclass
 
         Raises:
-            SystemMessageNotDeclared: If __system_message__ is not defined in the class
+            InstructionsNotDeclared: If neither __instructions__ nor the deprecated
+                __system_message__ is defined in the class
         """
 
         # Create an inherited namespace by combining all bases in MRO order
@@ -699,9 +700,22 @@ class AgentMeta(type):
                 mcs.__BaseAgent__ = cls
                 return cls
             cls.__abstract_base__ = False
-            # Verify system message is set (not inherited)
-            if "__system_message__" not in namespace:
-                raise SystemMessageNotDeclared()
+            # Verify instructions are set (not inherited); __system_message__ is
+            # the deprecated spelling and normalizes onto __instructions__
+            if "__instructions__" in namespace:
+                cls.__instructions__ = namespace["__instructions__"]
+            elif "__system_message__" in namespace:
+                warnings.warn(
+                    f"`__system_message__` on {name} is deprecated; "
+                    "declare `__instructions__` instead",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+                cls.__instructions__ = namespace["__system_message__"]
+            else:
+                raise InstructionsNotDeclared()
+            # Keep the deprecated attribute readable for backwards compatibility
+            cls.__system_message__ = cls.__instructions__
 
         # Extract and attach Agent attributes:
         #

pyagentic/_base/_prompts.py

@@ -0,0 +1,243 @@
+"""
+Prompt management for agents.
+
+A `PromptEngine` is a source agents can pull managed instructions from (local files,
+a database, a prompt-management service, ...). Engines load prompt text by key and
+return it as a `PromptSource` carrying version metadata. `PromptEngine.ref(key)`
+produces a deferred `PromptRef` that can be assigned to `__instructions__`; the agent
+resolves it at instantiation time, so every new instance (and every fork) picks up
+the latest version of the prompt.
+"""
+
+import hashlib
+import re
+from abc import ABC, abstractmethod
+from datetime import datetime, timezone
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from pyagentic._base._exceptions import PromptNotFound
+
+
+class PromptSource(BaseModel):
+    """
+    A loaded prompt along with metadata about where and when it was loaded.
+
+    Attributes:
+        text (str): The prompt text itself.
+        source (str): Identifier of where the prompt came from (e.g. a file path).
+        source_type (str): The kind of engine that loaded it (e.g. "local").
+        version (str): Version identifier for the loaded text (e.g. a content hash).
+        loaded_at (datetime): When the prompt was loaded.
+    """
+
+    text: str
+    source: str
+    source_type: str
+    version: str
+    loaded_at: datetime
+
+
+def _version_hash(text: str) -> str:
+    """Content hash used as the version identifier for prompt text."""
+    return hashlib.sha256(text.encode()).hexdigest()[:12]
+
+
+def _inline_source(text: str, source: str) -> PromptSource:
+    """Build a PromptSource for instructions declared inline as a plain string."""
+    return PromptSource(
+        text=text,
+        source=source,
+        source_type="inline",
+        version=_version_hash(text),
+        loaded_at=datetime.now(timezone.utc),
+    )
+
+
+class PromptRef:
+    """
+    A deferred pointer to a prompt in a `PromptEngine`.
+
+    Created via `PromptEngine.ref(key)` and assigned to `__instructions__`; resolved
+    at agent instantiation, so each new instance (and each fork) reloads the prompt.
+    """
+
+    def __init__(self, engine: "PromptEngine", key: str, version: str | None = None):
+        self.engine = engine
+        self.key = key
+        self.version = version
+
+    def resolve(self) -> PromptSource:
+        """
+        Load the referenced prompt from its engine.
+
+        Returns:
+            PromptSource: The loaded prompt text plus metadata.
+
+        Raises:
+            PromptNotFound: If the engine has no prompt for the key.
+        """
+        return self.engine.load(self.key, version=self.version)
+
+    def __repr__(self) -> str:
+        return f"PromptRef(engine={self.engine!r}, key={self.key!r}, version={self.version!r})"
+
+
+class PromptEngine(ABC):
+    """
+    Base class for prompt engines, designed to be extended to support multiple
+    different source types (local files, databases, managed prompt services, ...).
+    """
+
+    @abstractmethod
+    def load(self, key: str, version: str | None = None) -> PromptSource:
+        """
+        Load a prompt by key.
+
+        Args:
+            key (str): Engine-specific identifier for the prompt.
+            version (str | None): Specific version to load; the engine's latest
+                when omitted.
+
+        Returns:
+            PromptSource: The loaded prompt text plus metadata.
+
+        Raises:
+            PromptNotFound: If no prompt exists for the key (or version).
+        """
+
+    def ref(self, key: str, version: str | None = None) -> PromptRef:
+        """
+        Create a deferred reference to a prompt, resolved at agent instantiation.
+
+        Args:
+            key (str): Engine-specific identifier for the prompt.
+            version (str | None): Pin a specific version; the engine's latest
+                when omitted.
+
+        Returns:
+            PromptRef: A reference that loads the prompt when resolved.
+        """
+        return PromptRef(self, key, version=version)
+
+
+def _natural_sort_key(version: str) -> list:
+    """Sort key treating digit runs numerically, so e.g. v10 orders after v2."""
+    return [int(part) if part.isdigit() else part for part in re.split(r"(\d+)", version)]
+
+
+class LocalPromptEngine(PromptEngine):
+    """
+    Prompt engine backed by the local file system.
+
+    A `pattern` defines how prompt files are laid out under the root directory
+    (default `.prompts/` in the current working directory). The pattern is a
+    template with a required `{key}` placeholder and an optional `{version}`
+    placeholder:
+
+      - Without `{version}` (default `"{key}.md"`): the key maps to a single file
+        and the prompt is versioned by content hash.
+      - With `{version}` (e.g. `"{key}/{version}.md"`): the directory structure
+        holds the versions. `load(key)` picks the latest version (natural sort,
+        so `v10` > `v2`); `load(key, version="v1")` pins one. The path's version
+        segment becomes `PromptSource.version`.
+
+    Example:
+        ```python
+        # .prompts/researcher/v1.md, .prompts/researcher/v2.md, ...
+        prompts = LocalPromptEngine(".prompts", pattern="{key}/{version}.md")
+
+        class ResearchAgent(BaseAgent):
+            __instructions__ = prompts.ref("researcher")  # latest version
+        ```
+    """
+
+    def __init__(self, path: str | Path | None = None, pattern: str = "{key}.md"):
+        """
+        Args:
+            path (str | Path | None): Root directory holding prompt files. Defaults
+                to `.prompts/` under the current working directory.
+            pattern (str): File layout template relative to the root. Must contain
+                `{key}`; may contain `{version}` to derive versions from the file
+                structure. Defaults to `"{key}.md"`.
+
+        Raises:
+            ValueError: If the pattern does not contain a `{key}` placeholder.
+        """
+        if "{key}" not in pattern:
+            raise ValueError(
+                f"LocalPromptEngine pattern {pattern!r} must contain a '{{key}}' placeholder"
+            )
+        self.root = Path(path) if path else Path.cwd() / ".prompts"
+        self.pattern = pattern
+        self.versioned = "{version}" in pattern
+
+    def _resolve_versioned(self, key: str, version: str | None) -> tuple[Path, str]:
+        """Resolve path and version for a versioned pattern; latest version when unpinned."""
+        if version is not None:
+            path = self.root / self.pattern.format(key=key, version=version)
+            if not path.is_file():
+                raise PromptNotFound(key=f"{key} (version {version})", source=str(self.root))
+            return path, version
+
+        # Glob for every version of the key, then parse the version segment back
+        # out of each path with a regex built from the pattern
+        regex = re.compile(
+            re.escape(self.pattern)
+            .replace(re.escape("{key}"), re.escape(key))
+            .replace(re.escape("{version}"), r"(?P<version>[^/]+)")
+        )
+        found: dict[str, Path] = {}
+        for path in self.root.glob(self.pattern.format(key=key, version="*")):
+            match = regex.fullmatch(path.relative_to(self.root).as_posix())
+            if match:
+                found[match.group("version")] = path
+
+        if not found:
+            raise PromptNotFound(key=key, source=str(self.root))
+        latest = max(found, key=_natural_sort_key)
+        return found[latest], latest
+
+    def load(self, key: str, version: str | None = None) -> PromptSource:
+        """
+        Load a prompt from a file laid out per the engine's pattern.
+
+        Args:
+            key (str): Prompt identifier substituted into the pattern's `{key}`.
+            version (str | None): Specific version to load. Only valid for
+                versioned patterns; the latest version is used when omitted.
+
+        Returns:
+            PromptSource: The file contents. Versioned patterns take the version
+                from the file structure; unversioned patterns use a content hash.
+
+        Raises:
+            PromptNotFound: If no matching file exists under the root.
+            ValueError: If a version is requested but the pattern has no
+                `{version}` placeholder.
+        """
+        if self.versioned:
+            path, resolved_version = self._resolve_versioned(key, version)
+        else:
+            if version is not None:
+                raise ValueError(
+                    f"Engine pattern {self.pattern!r} has no '{{version}}' placeholder; "
+                    "a specific version cannot be requested"
+                )
+            path = self.root / self.pattern.format(key=key)
+            if not path.is_file():
+                raise PromptNotFound(key=key, source=str(self.root))
+            resolved_version = None
+
+        text = path.read_text()
+        return PromptSource(
+            text=text,
+            source=str(path),
+            source_type="local",
+            version=resolved_version or _version_hash(text),
+            loaded_at=datetime.now(timezone.utc),
+        )
+
+    def __repr__(self) -> str:
+        return f"LocalPromptEngine(root={str(self.root)!r}, pattern={self.pattern!r})"

pyagentic/_base/_ref.py

@@ -79,7 +79,7 @@ class _RefRoot:
         from pyagentic import ref
 
         class Agent(BaseAgent):
-            __system_message__ = "You are helpful"
+            __instructions__ = "You are helpful"
             conversation: State[Conversation]
 
             @tool("Continue the conversation")

pyagentic/_base/_spec.py

@@ -26,7 +26,7 @@ class spec:
             email: str
 
         class MyAgent(BaseAgent):
-            __system_message__ = "You are a helpful assistant"
+            __instructions__ = "You are a helpful assistant"
 
             # State with default factory
             profile: State[UserProfile] = spec.State(

pyagentic/_base/_state.py

@@ -27,7 +27,7 @@ class State(Generic[T]):
             message_count: int = 0
 
         class ChatAgent(BaseAgent):
-            __system_message__ = "You are a chatbot"
+            __instructions__ = "You are a chatbot"
 
             # Simple state field
             conversation: State[ConversationState]

pyagentic/_base/_tool.py

@@ -256,7 +256,7 @@ def tool(description: str, condition: Callable[[Any], bool] = None, phases: list
     Example:
         ```python
         class FileAgent(BaseAgent):
-            __system_message__ = "You help manage files"
+            __instructions__ = "You help manage files"
 
             @tool("Read the contents of a file given its path")
             def read_file(self, path: str) -> str:

pyagentic/models/response.py

@@ -2,6 +2,7 @@ from pydantic import BaseModel, Field, create_model
 from typing import Type, Self, Union, Any, Literal, Optional
 
 from pyagentic._base._tool import _ToolDefinition
+from pyagentic._base._prompts import PromptSource
 from pyagentic._base._agent._agent_state import _AgentState
 
 from pyagentic._utils._typing import TypeCategory, analyze_type
@@ -97,6 +98,14 @@ class AgentResponse(BaseModel):
 
     final_output: Union[str, Type[BaseModel]]
     provider_info: ProviderInfo
+    prompt: Optional[PromptSource] = Field(
+        default=None,
+        description=(
+            "The prompt behind the agent's instructions: loaded from a PromptEngine "
+            "(e.g. source_type 'local'), or an 'inline' source named after the agent "
+            "for instructions declared as a plain string."
+        ),
+    )
 
     @classmethod
     def from_agent_class(

pyagentic/policies/_policy.py

@@ -69,7 +69,7 @@ class Policy(Protocol[T]):
 
         # Use in agent
         class CounterAgent(BaseAgent):
-            __system_message__ = "You manage a counter"
+            __instructions__ = "You manage a counter"
             counter: State[int] = spec.State(default=0, policies=[ValidationPolicy()])
         ```
     """

pyagentic/policies/messages.py

@@ -4,7 +4,7 @@ Prewritten message-context policies for managing agent context growth.
 Attach these to an agent via the `__message_policies__` class attribute:
 
     class MyAgent(BaseAgent):
-        __system_message__ = "..."
+        __instructions__ = "..."
         __message_policies__ = [
             ToolOutputClipPolicy(max_chars=8000),
             ToolEvictionPolicy(keep_last_n=5),

{pyagentic_core-2.14.1.dev1.dist-info → pyagentic_core-2.15.1.dev1.dist-info}/METADATA

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

{pyagentic_core-2.14.1.dev1.dist-info → pyagentic_core-2.15.1.dev1.dist-info}/RECORD

@@ -1,22 +1,23 @@
-pyagentic/__init__.py,sha256=S1nJnbbDZzkH0AbKYWIAWCPhZJW2a2Ml2zdxi91WSPk,2012
+pyagentic/__init__.py,sha256=eHUKxFTSj5UH8ncFubnmXpS1TomGgHHrwRlFnNzl_3U,2265
 pyagentic/_version_scheme.py,sha256=hUYPvGhWz5L7RSuVxIqW3h10i4zNjfYXMofmoIk8ZBM,1569
 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=O59cvg4uc4feDrPjn9HqryrMGzqNyulyv8intAmQ8PE,2188
-pyagentic/_base/_exceptions.py,sha256=r_wcuWgc_Y3g_D7DwLQL8NbTphIAeeNpIp-WDHMvvOk,3746
+pyagentic/_base/_depends.py,sha256=e9j6GiYvPJAmFExTHMeg-xcFGYvvfF9KtCstX5HDS7Y,2186
+pyagentic/_base/_exceptions.py,sha256=Z1AvSEGJu0s8dE6F8iNGBHcNOmwlaS1gA1R15ezQYg4,4298
 pyagentic/_base/_info.py,sha256=LeXn3VbEJkP4KmMpjY6bqXjHYnE-ZHLuKoRcrmrqqhs,3020
-pyagentic/_base/_mcp.py,sha256=YPRaqVFrgKDA5BZtvVrcScyADjo66cdB4_h6nXpRJBI,8329
-pyagentic/_base/_metaclasses.py,sha256=4Ge9d4TDmQdrIGmVLKAif94Yt-wKbRB12prsxT5FgC0,36292
-pyagentic/_base/_ref.py,sha256=Ez1Iexxl7NLBK91frcgz_eFbrXfLZpm9fvkYHMFWA_w,3179
-pyagentic/_base/_spec.py,sha256=jV0iJZycJEG8fUi9qcH0NxpxoRHiB8M_YrRrmoMwSGQ,7672
-pyagentic/_base/_state.py,sha256=swjMl22rOgaIVEuqyL1bG7gpYpumuOZ6ytNImV_2lGw,1794
-pyagentic/_base/_tool.py,sha256=6Zkd20iwQX1uS-rw4i9IA8doM8qjchEZ3EmMk5Li9SE,11040
+pyagentic/_base/_mcp.py,sha256=jclmFb5yB1szg9PTskPE2hLO3fvnFKJQFnnwTLdf0IY,8327
+pyagentic/_base/_metaclasses.py,sha256=jvDuFoz2DAaVxu2vFkAbyT6W61euaDyKW3V0w5dS3kI,37067
+pyagentic/_base/_prompts.py,sha256=aSUptdlKhUuJVrIb20FOvICzxp6pcmeb65Xf2goFpvk,9118
+pyagentic/_base/_ref.py,sha256=E-1DGVoM2xub476BrHOkxTqzdw-8t_N6XuEerXDYYE8,3177
+pyagentic/_base/_spec.py,sha256=Mx8tXF8ERpsuxizRXuq3wJavbXvCCGUn17YbjiOKP9Y,7670
+pyagentic/_base/_state.py,sha256=-xYVIaKiaU9ERuPf-33nbUhbvI3DgIp36y1bYdYTwJU,1792
+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=DLsrCeSuD9kvL2yiIEs2GuGSR0v89sK0uWYQNPaRQF4,43268
-pyagentic/_base/_agent/_agent_linking.py,sha256=gSHQkbH-BeKG8moROKDZiLs0ktLzW9bOVo0DFq3UNs8,1841
-pyagentic/_base/_agent/_agent_state.py,sha256=NJ4WOkP7_UuQ5ycGz7oOKwMd5waD8QcpZucgkCaNOHw,17161
+pyagentic/_base/_agent/_agent.py,sha256=eyPqISReeTC-yOjva5BNFTs5dr3Qtw-is_yNyt6JWo0,43659
+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/_utils/_typing.py,sha256=5aRZZOVzR0ZgnBfejkw__1yoARhn70P5QzA81sxUkls,3681
 pyagentic/_utils/_warnings.py,sha256=mjlBiYHGnnh5599Gsq5ke8mBFS6WsdhNa7jk20TT9_U,1330
 pyagentic/api/__init__.py,sha256=7CklNYjxVj5XOyqTWvvWKZU6IYuU8CAfpOhNeGMH1d4,1712
@@ -44,21 +45,21 @@ pyagentic/llm/_mock.py,sha256=X_Rj7DP_RV_hKJth6exjl90bJGHC3xTy8-7da6lOg3k,3282
 pyagentic/llm/_openai.py,sha256=y1rY35O2X78fbDgj8XNVRs6JDEvtBQ2w3NdXyb9_BbA,5994
 pyagentic/llm/_provider.py,sha256=McxbFcRD7UTtpnmGwYieGGBrHb6JfzZMkfnFxhj6Vrw,2508
 pyagentic/models/llm.py,sha256=hx8x4d2SJGxlqGSiN7Ewdopvo87IUyJELoR3wR8KV0s,5126
-pyagentic/models/response.py,sha256=Zs4_yLKyZue3ysKrGQcjECmPAXJi_NJ_bEP8tINBVJo,5894
+pyagentic/models/response.py,sha256=nnSEzuH-DpFTWhV5mC5WZstX_Gm44YxZ96V3Zq7qeQU,6281
 pyagentic/models/tracing.py,sha256=5_cGxOAb5I9qjLVwSdvIcxUzrZy56OUe5fxlxOkud_w,1218
 pyagentic/policies/__init__.py,sha256=WCgpEA1KZ23iJW5bkT32sfP8jLSLso21xJY5ZUKJVTQ,451
 pyagentic/policies/_events.py,sha256=hTZH4VT9n2Ba4ICNiec32CMPGptyO02tjsui01XEqUY,2586
 pyagentic/policies/_list.py,sha256=Whz4T5lxodzKqZNrr7opolJPvfMhYfM6gn-0GTwuqeQ,5865
-pyagentic/policies/_policy.py,sha256=WvPO-vWWt3MyQK3TG1AQrZx-TCGPNLMv4mRVjd95Ems,3907
-pyagentic/policies/messages.py,sha256=45RYHmOC6ihF0YmS10MNOaYmlicfZ9Ni1hQx-FuxKSc,8192
+pyagentic/policies/_policy.py,sha256=xsvm3NBraTBcNr8RcHRAasmvc6ttiAF1qCKFvG-kkRQ,3905
+pyagentic/policies/messages.py,sha256=RVIr9GwUXjw3We1fZaXPxjByqZIvu4uNYcFti5YT6V4,8190
 pyagentic/tracing/__init__.py,sha256=ddMOl_-Nf3WOhu-PYxSJ3kqHZ3eQXAOM5aySn9YmDtA,150
 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.14.1.dev1.dist-info/licenses/LICENSE,sha256=wcOzTj82hOc96HztJk2VzLB2hFHpdIGpjz8vvbpP1_s,1069
-pyagentic_core-2.14.1.dev1.dist-info/METADATA,sha256=k5LET3i9sSG9rDltFkrXpg-o8FsThvRZ1MHsZEzqYoc,8212
-pyagentic_core-2.14.1.dev1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-pyagentic_core-2.14.1.dev1.dist-info/scm_file_list.json,sha256=4jMpoLHxqkHhsscGA4biTgu0XoDt9d60_L6EAX-ebJQ,4790
-pyagentic_core-2.14.1.dev1.dist-info/scm_version.json,sha256=LgdOXfNRMrVAcA2OqftqGPpJxBZLgZJj52D5CpLNopk,162
-pyagentic_core-2.14.1.dev1.dist-info/top_level.txt,sha256=lAWfd-ay434uEpSg2FM0ySN0o4vgNGE6D9dJkIhGyfY,10
-pyagentic_core-2.14.1.dev1.dist-info/RECORD,,
+pyagentic_core-2.15.1.dev1.dist-info/licenses/LICENSE,sha256=wcOzTj82hOc96HztJk2VzLB2hFHpdIGpjz8vvbpP1_s,1069
+pyagentic_core-2.15.1.dev1.dist-info/METADATA,sha256=KY3iq_69tHikWHrDebuiW-f_br1APh1m4P80R_Rdhws,8212
+pyagentic_core-2.15.1.dev1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+pyagentic_core-2.15.1.dev1.dist-info/scm_file_list.json,sha256=8UMtz5WpdhOSRNM1zB-dxNzobbueYJYYqfBJoM4n6_w,4883
+pyagentic_core-2.15.1.dev1.dist-info/scm_version.json,sha256=ALVMEOHx9YqLEgimG8GUehjgTfSpP-8g_W6SqxQYmSE,162
+pyagentic_core-2.15.1.dev1.dist-info/top_level.txt,sha256=lAWfd-ay434uEpSg2FM0ySN0o4vgNGE6D9dJkIhGyfY,10
+pyagentic_core-2.15.1.dev1.dist-info/RECORD,,

{pyagentic_core-2.14.1.dev1.dist-info → pyagentic_core-2.15.1.dev1.dist-info}/scm_file_list.json

@@ -16,6 +16,7 @@
     "docs/tools.md",
     "docs/execution-modes.md",
     "docs/structured-output.md",
+    "docs/prompts.md",
     "docs/agent-linking.md",
     "docs/index.md",
     "docs/inheritance.md",
@@ -75,6 +76,7 @@
     "tests/_base/test_policy_list.py",
     "tests/_base/test_params.py",
     "tests/_base/test_agent_forking.py",
+    "tests/_base/test_prompts.py",
     "tests/_base/test_state.py",
     "tests/_base/test_agent_provider.py",
     "pyagentic/__init__.py",
@@ -128,6 +130,7 @@
     "pyagentic/_base/_state.py",
     "pyagentic/_base/_exceptions.py",
     "pyagentic/_base/_ref.py",
+    "pyagentic/_base/_prompts.py",
     "pyagentic/_base/_validation.py",
     "pyagentic/_base/_depends.py",
     "pyagentic/_base/_agent/__init__.py",

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

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

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

@@ -1,8 +0,0 @@
-{
-  "tag": "2.14.0a1",
-  "distance": 1,
-  "node": "g2629fed5f4a99c79b17abf20d6df0918a0a8bf83",
-  "dirty": true,
-  "branch": "main",
-  "node_date": "2026-07-06"
-}