pyagentic-core 2.14.1.dev1__tar.gz → 2.15.1.dev1__tar.gz

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

@@ -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 → pyagentic_core-2.15.1.dev1}/docs/agent-linking.md

@@ -16,14 +16,14 @@ The simplest way to link agents is by declaring them as typed attributes in your
 from pyagentic import BaseAgent, Link, tool
 
 class DatabaseAgent(BaseAgent):
-    __system_message__ = "I query databases"
+    __instructions__ = "I query databases"
     __description__ = "Retrieves and analyzes data from databases"
 
     @tool("Execute SQL query")
     def query(self, sql: str) -> str: ...
 
 class ReportAgent(BaseAgent):
-    __system_message__ = "I generate business reports"
+    __instructions__ = "I generate business reports"
 
     # Using Link[T] (recommended for advanced features)
     database: Link[DatabaseAgent]
@@ -45,15 +45,15 @@ Real-world applications often require coordination between multiple specialized
 
 ```python
 class EmailAgent(BaseAgent):
-    __system_message__ = "I send emails"
+    __instructions__ = "I send emails"
     __description__ = "Sends and manages email communications"
 
 class CalendarAgent(BaseAgent):
-    __system_message__ = "I manage calendars"
+    __instructions__ = "I manage calendars"
     __description__ = "Schedules meetings and manages calendar events"
 
 class AssistantAgent(BaseAgent):
-    __system_message__ = "I help with daily tasks"
+    __instructions__ = "I help with daily tasks"
 
     email: EmailAgent
     calendar: CalendarAgent
@@ -75,14 +75,14 @@ Provide a default agent instance that will be used if none is provided during in
 from pyagentic import BaseAgent, Link, spec
 
 class AnalysisAgent(BaseAgent):
-    __system_message__ = "I analyze data"
+    __instructions__ = "I analyze data"
     __description__ = "Performs data analysis"
 
 # Create a pre-configured analyzer
 default_analyzer = AnalysisAgent(model="gpt-4", api_key="sk-...")
 
 class ReportAgent(BaseAgent):
-    __system_message__ = "I generate reports"
+    __instructions__ = "I generate reports"
 
     # Will use default_analyzer if no analyzer is provided
     analyzer: Link[AnalysisAgent] = spec.AgentLink(default=default_analyzer)
@@ -104,7 +104,7 @@ Use `default_factory` to create agent instances on-demand, similar to how `spec.
 
 ```python
 class SearchAgent(BaseAgent):
-    __system_message__ = "I search databases"
+    __instructions__ = "I search databases"
     __description__ = "Database search specialist"
 
 def create_searcher():
@@ -116,7 +116,7 @@ def create_searcher():
     )
 
 class DataAgent(BaseAgent):
-    __system_message__ = "I manage data operations"
+    __instructions__ = "I manage data operations"
 
     # Automatically creates a searcher if not provided
     searcher: Link[SearchAgent] = spec.AgentLink(default_factory=create_searcher)
@@ -139,11 +139,11 @@ Link agents conditionally based on runtime state, enabling dynamic agent composi
 from pyagentic import State
 
 class ExpertAgent(BaseAgent):
-    __system_message__ = "I provide expert analysis"
+    __instructions__ = "I provide expert analysis"
     __description__ = "Expert consultant for complex problems"
 
 class SmartAgent(BaseAgent):
-    __system_message__ = "I handle tasks with optional expert help"
+    __instructions__ = "I handle tasks with optional expert help"
 
     # State field to control expert availability
     needs_expert: State[bool] = spec.State(default=False)
@@ -203,7 +203,7 @@ calls — for example so the parent can read the linked agent's state through
 from pyagentic import BaseAgent, Link, spec
 
 class Orchestrator(BaseAgent):
-    __system_message__ = "I coordinate a stateful researcher."
+    __instructions__ = "I coordinate a stateful researcher."
 
     # One persistent researcher; its state survives across calls and is
     # readable via ref.researcher.<field>.
@@ -226,13 +226,13 @@ Overriding the `__call__` method gives you complete control over how your linked
 
 ```python
 class AnalysisAgent(BaseAgent):
-    __system_message__ = "I analyze data"
+    __instructions__ = "I analyze data"
     __description__ = "Performs statistical analysis on datasets"
 
     async def __call__(self, data: str, analysis_type: str = "basic") -> str: ...
 
 class ReportAgent(BaseAgent):
-    __system_message__ = "I generate reports"
+    __instructions__ = "I generate reports"
     analyzer: AnalysisAgent
 
 # The LLM can now call the analyzer with specific parameters
@@ -254,7 +254,7 @@ class SearchParams(BaseModel):
     include_metadata: bool = Field(default=True, description="Whether to include metadata in results")
 
 class SearchAgent(BaseAgent):
-    __system_message__ = "I search databases"
+    __instructions__ = "I search databases"
     __description__ = "Searches databases with advanced filtering"
 
     async def __call__(self, params: SearchParams) -> str:
@@ -263,7 +263,7 @@ class SearchAgent(BaseAgent):
         return f"Found {len(results)} results for '{params.query}'"
 
 class DataAgent(BaseAgent):
-    __system_message__ = "I manage data operations"
+    __instructions__ = "I manage data operations"
     searcher: SearchAgent
 
 # The LLM can now call the searcher with structured parameters

{pyagentic_core-2.14.1.dev1 → pyagentic_core-2.15.1.dev1}/docs/api/creating-an-app.md

@@ -69,7 +69,7 @@ agent class, exactly where you'd otherwise put `State[...]`:
 from pyagentic import BaseAgent, State, Depends
 
 class ResearchAgent(BaseAgent):
-    __system_message__ = "You research topics."
+    __instructions__ = "You research topics."
 
     topic: State[Topic]        # client-provided per session
     db:    Depends[Database]    # injected server-side, never sent by clients

{pyagentic_core-2.14.1.dev1 → pyagentic_core-2.15.1.dev1}/docs/api/index.md

@@ -26,7 +26,7 @@ from pyagentic.api import create_app
 
 
 class AssistantAgent(BaseAgent):
-    __system_message__ = "You are a helpful assistant."
+    __instructions__ = "You are a helpful assistant."
 
     @tool("Add two numbers")
     def add(self, a: int, b: int) -> str:

{pyagentic_core-2.14.1.dev1 → pyagentic_core-2.15.1.dev1}/docs/execution-modes.md

@@ -35,7 +35,7 @@ The real power of `__call__` is that you can override it to accept typed paramet
 from typing import Optional
 
 class CoursePlannerAgent(BaseAgent):
-    __system_message__ = "You design course curricula"
+    __instructions__ = "You design course curricula"
     __description__ = "Creates structured course plans based on learning goals"
     __response_format__ = CoursePlan
 
@@ -79,7 +79,7 @@ When you link an agent to another agent, PyAgentic extracts the parameters from
 
 ```python
 class AssistantAgent(BaseAgent):
-    __system_message__ = "You help students with learning plans"
+    __instructions__ = "You help students with learning plans"
 
     # Link the course planner
     planner: CoursePlannerAgent

{pyagentic_core-2.14.1.dev1 → pyagentic_core-2.15.1.dev1}/docs/getting-started.md

@@ -91,13 +91,15 @@ from pyagentic import BaseAgent
 class ResearchAgent(BaseAgent):
     """An AI assistant for managing and analyzing research papers."""
 
-    __system_message__ = """
+    __instructions__ = """
     You are a research assistant that helps organize and analyze academic papers.
     You maintain a collection of research papers and can answer questions about them.
     You are knowledgeable, precise, and helpful in academic contexts.
     """
 ```
 
+The `__instructions__` attribute defines the agent's system prompt — it can be a plain string like this, a Jinja template rendered with the agent's state, or a reference to a prompt managed outside your code (see [Prompt Management](prompts.md)).
+
 This creates a basic conversational agent, but it can't do much beyond chat. Let's add some memory and capabilities.
 
 ## Step 2: Adding State with State Fields
@@ -114,7 +116,7 @@ from arxiv import Result as Paper
 class ResearchAgent(BaseAgent):
     """An AI assistant for managing and analyzing research papers."""
 
-    __system_message__ = """
+    __instructions__ = """
     You are a research assistant that helps organize and analyze academic papers.
     You have full access to the Arxiv
 
@@ -200,7 +202,7 @@ class ResearchState(BaseModel):
         return [paper.get_short_id() for paper in self.papers.get(self.current_topic, [])]
 
 class ResearchAgent(BaseAgent):
-    # ... system message ...
+    # ... instructions ...
 
     state: State[ResearchState] = spec.State(default_factory=ResearchState)
 
@@ -266,7 +268,7 @@ class ResearchState(BaseModel):
 class ResearchAgent(BaseAgent):
     """An AI assistant for managing and analyzing research papers."""
 
-    __system_message__ = """
+    __instructions__ = """
     You are a research assistant that helps organize and analyze academic papers.
     You have full access to the Arxiv
 

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

@@ -4,7 +4,7 @@ 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 system message 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, and linked agents. However, each agent must define its own instructions to maintain clear identity and purpose.
 
 PyAgentic builds the complete agent schema at class definition time, combining inherited elements with new ones to create a fully-typed, predictable agent interface.
 
@@ -21,7 +21,7 @@ PyAgentic follows specific rules about what gets inherited and what must be rede
 
 #### What Must Be Redefined ❌
 
-- **System Messages** - Each agent must define its own `__system_message__` to maintain clear identity
+- **Instructions** - Each agent must define its own `__instructions__` to maintain clear identity
 - **Input Templates** - `__input_template__` is not inherited, allowing agent-specific formatting
 
 This design ensures that while agents can share functionality, each maintains its own distinct purpose and behavior.
@@ -32,7 +32,7 @@ Extend agents using normal Python inheritance to build specialized capabilities
 
 ```python
 class BaseAssistantAgent(BaseAgent):
-    __system_message__ = "I am a helpful AI assistant"
+    __instructions__ = "I am a helpful AI assistant"
 
     user_name: State[str] = spec.State(default="User")
     session_id: State[str] = spec.State(default="")
@@ -48,7 +48,7 @@ class BaseAssistantAgent(BaseAgent):
     def update_context(self, new_context: str) -> str: ...
 
 class CodeAssistantAgent(BaseAssistantAgent):
-    __system_message__ = "I help with programming tasks and code review"
+    __instructions__ = "I help with programming tasks and code review"
 
     # Inherit user_name, session_id, conversation_context, and basic tools
     # Add coding-specific state
@@ -69,7 +69,7 @@ Inheritance also works with tool overriding to enhance parent functionality:
 
 ```python
 class AdvancedCodeAssistantAgent(CodeAssistantAgent):
-    __system_message__ = "I provide advanced programming assistance with security analysis"
+    __instructions__ = "I provide advanced programming assistance with security analysis"
 
     # Override parent tool with enhanced functionality
     @tool("Format and validate code snippet")
@@ -110,7 +110,7 @@ Simply include extensions in your agent's inheritance list:
 
 ```python
 class ResearchAgent(BaseAgent, FileOperationsExtension, WebSearchExtension):
-    __system_message__ = "I help with research by searching the web and managing files"
+    __instructions__ = "I help with research by searching the web and managing files"
 
     research_topic: State[str] = spec.State(default="")
 
@@ -134,7 +134,7 @@ class ConversationExtension(AgentExtension):
     def remember(self, info: str) -> str: ...
 
 class ChatbotAgent(BaseAgent, MemoryExtension, ConversationExtension):
-    __system_message__ = "I am a conversational AI"
+    __instructions__ = "I am a conversational AI"
 
 # MRO: ChatbotAgent -> MemoryExtension -> ConversationExtension -> BaseAgent
 # The MemoryExtension.remember() method will be used

{pyagentic_core-2.14.1.dev1 → pyagentic_core-2.15.1.dev1}/docs/observability.md

@@ -36,7 +36,7 @@ The BasicTracer is the simplest way to get started with tracing. It stores all t
 from pyagentic import BaseAgent
 
 class YourAgent(BaseAgent):
-    __system_message__ = "Your agent description"
+    __instructions__ = "Your agent description"
     # ... your agent implementation ...
 
 # Create an agent - The BasicTracer is the default tracer of any declared agent
@@ -93,7 +93,7 @@ from pyagentic import BaseAgent
 from pyagentic.tracing import LangfuseTracer
 
 class YourAgent(BaseAgent):
-    __system_message__ = "Your agent description"
+    __instructions__ = "Your agent description"
     # ... your agent implementation ...
 
 # Create an agent with the tracer

{pyagentic_core-2.14.1.dev1 → pyagentic_core-2.15.1.dev1}/docs/phases.md

@@ -20,7 +20,7 @@ Define phases on your agent class using the `phases` class variable:
 from pyagentic import BaseAgent, tool, spec
 
 class ResearchAgent(BaseAgent):
-    __system_message__ = """
+    __instructions__ = """
     You are a research agent.
     Current phase: {{ phase }}
     {% if phase == "planning" %}
@@ -120,19 +120,19 @@ Linked agents can be restricted to specific phases using the `phases` parameter
 from pyagentic import BaseAgent, tool, spec, Link
 
 class PlannerAgent(BaseAgent):
-    __system_message__ = "I create detailed plans"
+    __instructions__ = "I create detailed plans"
     __description__ = "Planning specialist for strategy development"
 
 class ExecutorAgent(BaseAgent):
-    __system_message__ = "I execute plans"
+    __instructions__ = "I execute plans"
     __description__ = "Execution specialist for implementing plans"
 
 class ReviewerAgent(BaseAgent):
-    __system_message__ = "I review completed work"
+    __instructions__ = "I review completed work"
     __description__ = "Quality assurance and review specialist"
 
 class ProjectAgent(BaseAgent):
-    __system_message__ = """
+    __instructions__ = """
     You manage projects through phases: {{ phase }}
     """
 
@@ -178,7 +178,7 @@ You can access the current phase in several ways:
 Use the `{{ phase }}` variable in your system message template:
 
 ```python
-__system_message__ = """
+__instructions__ = """
 You are in the {{ phase }} phase.
 {% if phase == "planning" %}
 Create a detailed plan.

{pyagentic_core-2.14.1.dev1 → pyagentic_core-2.15.1.dev1}/docs/policies/built-in.md

@@ -19,7 +19,7 @@ Attach them to an agent with the `__message_policies__` class attribute:
 
 ```python
 class ResearchAgent(BaseAgent):
-    __system_message__ = "You research topics using tools."
+    __instructions__ = "You research topics using tools."
     __message_policies__ = [
         ToolOutputClipPolicy(max_chars=8000),
         ToolEvictionPolicy(keep_last_n=5),

{pyagentic_core-2.14.1.dev1 → pyagentic_core-2.15.1.dev1}/docs/policies/custom.md

@@ -55,7 +55,7 @@ class RangePolicy(Policy[int]):
 
 
 class GameAgent(BaseAgent):
-    __system_message__ = "You run a text adventure."
+    __instructions__ = "You run a text adventure."
 
     score: State[int] = spec.State(
         default=0,
@@ -141,7 +141,7 @@ class NoEmptyStrings(Policy):
 
 
 class NotesAgent(BaseAgent):
-    __system_message__ = "You keep notes."
+    __instructions__ = "You keep notes."
 
     notes: State[list] = spec.State(default_factory=list, policies=[NoEmptyStrings()])
 
@@ -333,7 +333,7 @@ LLM saw) versus `agent.state._messages` (what actually happened):
 @pytest.mark.asyncio
 async def test_budget_policy_in_agent():
     class _Agent(BaseAgent):
-        __system_message__ = "test"
+        __instructions__ = "test"
         __message_policies__ = [AgentResultBudgetPolicy(max_chars=100)]
 
     agent = _Agent(model="_mock::test-model", api_key="k")

{pyagentic_core-2.14.1.dev1 → pyagentic_core-2.15.1.dev1}/docs/policies/index.md

@@ -18,7 +18,7 @@ from pyagentic import BaseAgent, State, spec
 from pyagentic.policies import ToolEvictionPolicy, CompactionPolicy
 
 class SupportAgent(BaseAgent):
-    __system_message__ = "You help customers with {{ product }}."
+    __instructions__ = "You help customers with {{ product }}."
 
     # Message policies: keep the LLM context bounded
     __message_policies__ = [
@@ -85,7 +85,7 @@ whether by your code, a tool body, or the autogenerated `get_*`/`set_*` tools.
 
 ```python
 class GameAgent(BaseAgent):
-    __system_message__ = "You run a text adventure."
+    __instructions__ = "You run a text adventure."
 
     score: State[int] = spec.State(default=0, policies=[RangePolicy(0, 100)])
 ```
@@ -109,7 +109,7 @@ and results) and once more over the whole list right before each LLM call.
 
 ```python
 class ResearchAgent(BaseAgent):
-    __system_message__ = "You research topics using tools."
+    __instructions__ = "You research topics using tools."
     __message_policies__ = [
         ToolOutputClipPolicy(max_chars=8000),
         ToolEvictionPolicy(keep_last_n=5),

pyagentic_core-2.15.1.dev1/docs/prompts.md

@@ -0,0 +1,140 @@
+# Prompt Management
+
+Every agent declares its instructions — the system prompt the LLM receives — with the `__instructions__` class attribute. Instructions can be a plain string, but as agents mature, prompts tend to outgrow the code: they get edited more often than the logic around them, they need versioning, and non-developers may need to change them. PyAgentic's prompt engines let agents pull their instructions from a managed source instead of a hardcoded string.
+
+## Naming
+
+Two terms, one for each side of the rendering step:
+
+- **Instructions** — the raw template you declare: a string or a prompt-engine reference. Available at runtime as `agent.state.instructions`.
+- **System message** — the rendered result actually sent to the LLM, with state interpolated into the template. Available as `agent.state.system_message`.
+
+```python
+class ResearchAgent(BaseAgent):
+    __instructions__ = "You research {{ topic }}"
+
+    topic: State[str] = spec.State(default="transformers")
+
+agent.state.instructions    # "You research {{ topic }}"
+agent.state.system_message  # "You research transformers"
+```
+
+!!! note "Deprecated: `__system_message__`"
+    Older versions used `__system_message__` for what is now `__instructions__`. The old name still works but emits a `DeprecationWarning` — new code should declare `__instructions__`.
+
+## Prompt Engines
+
+A `PromptEngine` is a source of managed prompts. Engines load prompt text by key and return a `PromptSource` carrying the text plus metadata (where it came from, which version, when it was loaded). Instead of assigning a string, assign a reference:
+
+```python
+from pyagentic import BaseAgent, LocalPromptEngine
+
+prompts = LocalPromptEngine(".prompts")
+
+class ResearchAgent(BaseAgent):
+    __instructions__ = prompts.ref("researcher")
+```
+
+`ref(key)` returns a `PromptRef` — a deferred pointer that is resolved **when the agent is instantiated**, not when the class is defined:
+
+- Every `ResearchAgent(...)` re-reads the prompt, so edits are picked up by new instances without restarting anything.
+- The prompt is stable for the lifetime of an instance — it never changes mid-conversation.
+- `agent.fork()` re-resolves too, so forked linked-agent calls also get the latest version.
+
+To pin a specific version instead of tracking the latest:
+
+```python
+__instructions__ = prompts.ref("researcher", version="v2")
+```
+
+## LocalPromptEngine
+
+`LocalPromptEngine` serves prompts from files on the local file system. A **pattern** defines how your prompt storage is laid out under the root directory (default: `.prompts/` in the working directory). The pattern is a template with a required `{key}` placeholder and an optional `{version}` placeholder.
+
+### Flat layout (default)
+
+The default pattern is `"{key}.md"` — one file per prompt, versioned by content hash:
+
+```
+.prompts/
+├── researcher.md
+└── summarizer.md
+```
+
+```python
+prompts = LocalPromptEngine(".prompts")
+prompts.load("researcher")  # reads .prompts/researcher.md
+```
+
+Any flat layout works by changing the pattern, e.g. `pattern="{key}.txt"` or `pattern="agents/{key}/prompt.md"`.
+
+### Versioned layout
+
+When the pattern contains `{version}`, the file structure holds the versions and the engine derives versioning from it:
+
+```
+.prompts/
+└── researcher/
+    ├── v1.md
+    ├── v2.md
+    └── v10.md
+```
+
+```python
+prompts = LocalPromptEngine(".prompts", pattern="{key}/{version}.md")
+
+prompts.load("researcher")                # latest → v10
+prompts.load("researcher", version="v1")  # pinned
+```
+
+An unpinned load picks the latest version using natural sorting, so `v10` correctly orders after `v2`. Version names are up to you — `v1`, `2026-07-08`, `1.0.3` all work. Flat versioned layouts like `pattern="{key}_{version}.md"` work the same way.
+
+A missing key (or pinned version) raises `PromptNotFound`. Requesting a `version` on a pattern without `{version}` raises `ValueError`.
+
+## Prompt provenance on responses
+
+Every agent response records which prompt produced it in the `prompt` field, as a `PromptSource`:
+
+```python
+response = await agent.run("hello")
+
+response.prompt.text         # the raw template that was loaded
+response.prompt.source       # ".prompts/researcher/v2.md"
+response.prompt.source_type  # "local"
+response.prompt.version      # "v2"
+response.prompt.loaded_at    # when it was resolved
+```
+
+This works for plain-string instructions too: they produce an `inline` source named after the agent, with a content-hash version:
+
+```python
+class PlainAgent(BaseAgent):
+    __instructions__ = "You are plain"
+
+response.prompt.source_type  # "inline"
+response.prompt.source       # "PlainAgent"
+response.prompt.version      # "3f2a9c1b04de" (content hash)
+```
+
+Because the version is always populated — from the file structure or a content hash — you can group or diff runs by prompt version regardless of where the prompt lives. The same metadata is available on the agent as `agent.state.prompt_source`.
+
+## Writing a custom engine
+
+Engines for other backends (a database, object storage, a prompt-management service) subclass `PromptEngine` and implement one method:
+
+```python
+from pyagentic import PromptEngine, PromptSource
+
+class MyServiceEngine(PromptEngine):
+    def load(self, key: str, version: str | None = None) -> PromptSource:
+        record = my_service.get_prompt(key, version=version or "latest")
+        return PromptSource(
+            text=record.text,
+            source=f"my-service/{key}",
+            source_type="my-service",
+            version=record.version,
+            loaded_at=record.fetched_at,
+        )
+```
+
+`ref()`, instantiation-time resolution, and response provenance all come from the base class — a custom engine only decides how to fetch text and what to call a version.

{pyagentic_core-2.14.1.dev1 → pyagentic_core-2.15.1.dev1}/docs/reference/modules.md

@@ -48,3 +48,21 @@ Complete API documentation for PyAgentic's public interfaces.
 ### ref
 
 ::: pyagentic.ref
+
+## Prompt Management
+
+### PromptEngine
+
+::: pyagentic.PromptEngine
+
+### LocalPromptEngine
+
+::: pyagentic.LocalPromptEngine
+
+### PromptRef
+
+::: pyagentic.PromptRef
+
+### PromptSource
+
+::: pyagentic.PromptSource

{pyagentic_core-2.14.1.dev1 → pyagentic_core-2.15.1.dev1}/docs/responses.md

@@ -9,6 +9,7 @@ Every agent response is a Pydantic model with a predictable structure:
 - `final_output: str` - The natural language response from the LLM
 - `tool_responses: List[ToolResponse]` - Details of any tools called (if agent has tools)
 - `agent_responses: List[AgentResponse]` - Responses from linked agents (if agent has linked agents)
+- `prompt: PromptSource` - The prompt behind the agent's instructions, with source and version metadata
 
 The response model is predetermined when the agent class is defined. Each agent automatically gets its own response class that knows exactly what tools and linked agents it can use. This means you get full type safety and IDE autocompletion before you ever run the agent.
 
@@ -88,3 +89,17 @@ response.agent_responses[0].final_output # Database agent response
 ```
 
 This nested structure lets you trace exactly what each agent did and access the results of any sub-agent calls. The parent agent's response includes both its own tool calls and the complete responses from any linked agents it used.
+
+## Prompt Provenance
+
+Every response records which prompt produced it in the `prompt` field. For instructions loaded from a [prompt engine](prompts.md), the version comes from the engine; plain-string instructions get an `inline` source named after the agent, versioned by content hash:
+
+```python
+response = await agent.run("hello")
+
+response.prompt.source       # ".prompts/researcher/v2.md" or "ResearchAgent"
+response.prompt.source_type  # "local" or "inline"
+response.prompt.version      # "v2" or a content hash
+```
+
+Since the version is always populated, you can group or diff runs by prompt version — useful when evaluating prompt changes across a set of conversations.