pyagentic-core 2.11.1.dev1__py3-none-any.whl → 2.12.1.dev2__py3-none-any.whl

pyagentic/_base/_agent/_agent.py

@@ -1,3 +1,4 @@
+import copy
 import inspect
 import json
 import asyncio
@@ -29,7 +30,7 @@ if TYPE_CHECKING:
     from pyagentic._base._agent._agent_linking import _LinkedAgentDefinition
     from pyagentic._base._mcp import _MCPDefinition
 
-from pyagentic.models.response import ToolResponse, AgentResponse
+from pyagentic.models.response import ToolResponse, AgentResponse, ErrorResponse
 from pyagentic.models.llm import Message, ToolCall, LLMResponse
 from pyagentic.models.tracing import SpanKind
 
@@ -410,6 +411,42 @@ class BaseAgent(metaclass=AgentMeta):
 
         return {"self": self.state.model_dump(), **linked_agent_references}
 
+    def fork(self) -> "BaseAgent":
+        """Create a fresh, isolated copy of this agent for a single invocation.
+
+        Used to call a non-shared linked agent without races or context
+        pollution. The fork shares this agent's provider, dependency-injected
+        (``Depends``) fields, linked sub-agent templates, and any connected MCP
+        clients, but gets its own conversation state reset to construction time
+        (an empty message history), so concurrent or repeated calls stay isolated.
+
+        Returns:
+            BaseAgent: A new instance of the same class sharing immutable
+                resources with this agent but holding fresh, independent state.
+        """
+        state_kwargs = {
+            name: copy.deepcopy(value)
+            for name, value in self.__initial_state_values__.items()
+        }
+        clone = type(self)(provider=self.provider, **state_kwargs, **self.__construct_args__)
+        # Share already-connected MCP clients so forks don't reconnect per call.
+        if getattr(self, "_mcp_connected", False):
+            clone._mcp_connected = True
+            clone._mcp_clients = self._mcp_clients
+            clone._mcp_tool_routing = self._mcp_tool_routing
+            clone.__tool_defs__ = self.__tool_defs__
+            clone.__tool_response_models__ = self.__tool_response_models__
+        return clone
+
+    @staticmethod
+    def _get_call_lock(agent: "BaseAgent") -> asyncio.Lock:
+        """Return (creating on first use) the lock serializing a shared agent's calls."""
+        lock = agent.__dict__.get("_call_lock")
+        if lock is None:
+            lock = asyncio.Lock()
+            agent.__dict__["_call_lock"] = lock
+        return lock
+
     @traced(SpanKind.INFERENCE)
     async def _process_llm_inference(
         self,
@@ -478,22 +515,31 @@ class BaseAgent(metaclass=AgentMeta):
         # Add tool call message to conversation history
         self.state._messages.append(self.provider.to_tool_call_message(tool_call))
 
-        # Get the linked agent instance and share tracer
-        agent = getattr(self, tool_call.name)
+        # By default each call runs on a fresh, isolated fork of the linked agent
+        # so concurrent/repeated calls neither race nor pollute one another. A
+        # `shared=True` link keeps one persistent instance (calls are serialized).
+        linked_def = self.__linked_agents__[tool_call.name]
+        template = getattr(self, tool_call.name)
+        shared = bool(linked_def.info and getattr(linked_def.info, "shared", False))
+        agent = template if shared else template.fork()
         agent.tracer = self.tracer
 
         try:
             # Parse arguments and call the linked agent
             kwargs = json.loads(tool_call.arguments)
             self.tracer.set_attributes(**kwargs)
-            response = await agent(**kwargs)
+            if shared:
+                async with self._get_call_lock(template):
+                    response = await agent(**kwargs)
+            else:
+                response = await agent(**kwargs)
             result = f"Agent {tool_call.name}: {response.final_output}"
             self.tracer.set_attributes(result=response.model_dump())
         except Exception as e:
             # Handle agent execution errors
             self.tracer.record_exception(str(e))
             result = f"Agent `{tool_call.name}` failed: {e}. Please kindly state to the user that is failed, provide state, and ask if they want to try again."  # noqa E501
-            response = AgentResponse(final_output=result, provider_info=agent.provider._info)
+            response = ErrorResponse(name=tool_call.name, kind="agent", error=result)
 
         # Add agent result to conversation history
         stringified_result = (
@@ -540,44 +586,55 @@ class BaseAgent(metaclass=AgentMeta):
 
         # Parse and validate tool arguments
         kwargs = json.loads(tool_call.arguments)
+        error: str | None = None
+        compiled_args = None
         try:
             # Compile args converts raw JSON to typed parameters (e.g., dict -> Pydantic models)
             compiled_args = tool_def.compile_args(**kwargs)
         except ValidationError as e:
             # Handle validation errors for tool arguments
-            result = f"Function Args were invalid: {str(e)}"
-            compiled_args = None
+            error = f"Function Args were invalid: {str(e)}"
             self.tracer.record_exception(str(e))
             logger.exception(e)
-        try:
-            if compiled_args is not None:
+        if compiled_args is not None:
+            try:
                 result = await _safe_run(handler, **compiled_args)
                 self.tracer.set_attributes(result=result)
-        except TypeError as e:
-            self.tracer.record_exception(str(e))
-            logger.exception(e)
-            raise InvalidToolDefinition(
-                tool_name=tool_call.name,
-                message=f"Tool must have a serializable return type; {tool_def.return_type} failed to be casted to a string.",
+            except TypeError as e:
+                self.tracer.record_exception(str(e))
+                logger.exception(e)
+                raise InvalidToolDefinition(
+                    tool_name=tool_call.name,
+                    message=f"Tool must have a serializable return type; {tool_def.return_type} failed to be casted to a string.",
+                )
+            except Exception as e:
+                # Handle any other tool execution errors
+                self.tracer.record_exception(str(e))
+                logger.exception(e)
+                error = f"Tool `{tool_call.name}` failed: {e}. Please kindly state to the user that is failed, provide state, and ask if they want to try again."  # noqa E501
+
+        # Add the tool result (or the error) to conversation history for the LLM
+        if error is not None:
+            message = error
+        else:
+            message = (
+                result.model_dump_json(indent=2)
+                if issubclass(result.__class__, BaseModel)
+                else str(result)
             )
-        except Exception as e:
-            # Handle any other tool execution errors
-            self.tracer.record_exception(str(e))
-            logger.exception(e)
-            result = f"Tool `{tool_call.name}` failed: {e}. Please kindly state to the user that is failed, provide state, and ask if they want to try again."  # noqa E501
-
-        stringified_result = (
-            result.model_dump_json(indent=2)
-            if issubclass(result.__class__, BaseModel)
-            else str(result)
-        )
-        # Add tool result to conversation history for LLM
         self.state._messages.append(
-            self.provider.to_tool_call_result_message(result=stringified_result, id_=tool_call.id)
+            self.provider.to_tool_call_result_message(result=message, id_=tool_call.id)
         )
 
         if self.phases:
             self.state._update_state_machine(phases=self.phases)
+
+        # A failed call (bad args or a raising handler) returns a typed ErrorResponse
+        # rather than a half-built ToolResponse (avoids unpacking None compiled_args).
+        if error is not None:
+            return ErrorResponse(
+                name=tool_call.name, kind="tool", error=error, call_depth=call_depth
+            )
         # Build and return the structured tool response
         ToolResponseModel = self.__tool_response_models__[tool_call.name]
         return ToolResponseModel(
@@ -601,6 +658,7 @@ class BaseAgent(metaclass=AgentMeta):
         client, original_name = self._mcp_tool_routing[tool_call.name]
         kwargs = json.loads(tool_call.arguments)
 
+        error: str | None = None
         try:
             mcp_result = await client.call_tool(original_name, kwargs)
             # CallToolResult has .content (list of content blocks)
@@ -615,16 +673,22 @@ class BaseAgent(metaclass=AgentMeta):
         except Exception as e:
             self.tracer.record_exception(str(e))
             logger.exception(e)
-            result = f"MCP tool `{tool_call.name}` failed: {e}. Please kindly state to the user that it failed, provide state, and ask if they want to try again."  # noqa E501
+            error = f"MCP tool `{tool_call.name}` failed: {e}. Please kindly state to the user that it failed, provide state, and ask if they want to try again."  # noqa E501
 
-        # Add result to conversation history
+        # Add result (or error) to conversation history
         self.state._messages.append(
-            self.provider.to_tool_call_result_message(result=result, id_=tool_call.id)
+            self.provider.to_tool_call_result_message(
+                result=error if error is not None else result, id_=tool_call.id
+            )
         )
 
         if self.phases:
             self.state._update_state_machine(phases=self.phases)
 
+        if error is not None:
+            return ErrorResponse(
+                name=tool_call.name, kind="tool", error=error, call_depth=call_depth
+            )
         # Return a base ToolResponse (not a class-time typed subclass,
         # since MCP tools are discovered at runtime)
         return ToolResponse(

pyagentic/_base/_info.py

@@ -48,6 +48,7 @@ class AgentInfo(_SpecInfo):
 
     condition: MaybeRef[Callable] | None = None
     phases: list[str] | None = None
+    shared: bool = False
 
 
 @dataclass

pyagentic/_base/_metaclasses.py

@@ -1,3 +1,4 @@
+import copy
 import inspect
 import threading
 import warnings
@@ -626,6 +627,19 @@ class AgentMeta(type):
                     continue  # State fields already set on state object
                 setattr(self, name, val)
 
+            # Capture the construction recipe so the agent can fork() fresh,
+            # isolated copies for non-shared linked-agent calls: a deep snapshot
+            # of the construct-time state, plus the shared linked templates,
+            # dependencies, and provider config to re-pass.
+            self.__initial_state_values__ = {
+                name: copy.deepcopy(compiled[name]) for name in self.__state_defs__
+            }
+            construct_args = {name: compiled[name] for name in self.__linked_agents__}
+            for name in (*self.__dependencies__, "model", "api_key", "max_call_depth"):
+                if name in bound.arguments:
+                    construct_args[name] = bound.arguments[name]
+            self.__construct_args__ = construct_args
+
             # Call post-initialization hook
             self.__post_init__()
 

pyagentic/_base/_spec.py

@@ -121,6 +121,7 @@ class spec:
         default_factory: Callable = None,
         condition: Callable = None,
         phases: list[str] | None = None,
+        shared: bool = False,
     ) -> AgentInfo:
         """
         Creates an AgentInfo descriptor for configuring linked agent fields.
@@ -131,12 +132,21 @@ class spec:
             condition (Callable, optional): A callable determining when this agent link is active
             phases (list[str], optional): A list of phases of when this agent will be available.
                 When None, will show for all phases. Defaults to None.
+            shared (bool): If False (default), each call to the linked agent runs on a fresh,
+                isolated fork (its own conversation state, reset to construction time), so
+                concurrent or repeated calls neither race nor pollute each other. If True, all
+                calls share one persistent instance whose state accumulates across calls — use
+                this when the parent needs to read the linked agent's state via ``ref``.
 
         Returns:
             AgentInfo: A configured AgentInfo descriptor
         """
         return AgentInfo(
-            default=default, default_factory=default_factory, condition=condition, phases=phases
+            default=default,
+            default_factory=default_factory,
+            condition=condition,
+            phases=phases,
+            shared=shared,
         )
 
     @staticmethod

pyagentic/models/response.py

@@ -1,5 +1,5 @@
 from pydantic import BaseModel, Field, create_model
-from typing import Type, Self, Union, Any
+from typing import Type, Self, Union, Any, Literal, Optional
 
 from pyagentic._base._tool import _ToolDefinition
 from pyagentic._base._agent._agent_state import _AgentState
@@ -65,6 +65,27 @@ class ToolResponse(BaseModel):
         )
 
 
+class ErrorResponse(BaseModel):
+    """A failed tool or linked-agent call.
+
+    Returned in place of a ToolResponse / AgentResponse when a tool or linked
+    agent raises, so a failure does not have to masquerade as a successful result
+    (whose schema — a structured ``final_output``, a populated ``state`` — a
+    failure cannot satisfy). It is included in both the ``tool_responses`` and
+    ``agent_responses`` unions of every generated agent response model, so either
+    kind of failure validates.
+    """
+
+    name: str = Field(description="Name of the tool or linked agent that failed.")
+    kind: Literal["tool", "agent"] = Field(
+        description="Whether the failure was a tool or a linked-agent call."
+    )
+    error: str = Field(description="The failure message, as surfaced to the model.")
+    call_depth: Optional[int] = Field(
+        default=None, description="Tool-calling loop depth at failure (tools only)."
+    )
+
+
 class AgentResponse(BaseModel):
     """
     Agent response class that captures the final output from an pyagentic agent and the raw
@@ -102,11 +123,14 @@ class AgentResponse(BaseModel):
         """
         fields = {}
         if tool_response_models:
-            # Include base ToolResponse so runtime-discovered tools (e.g. MCP) pass validation
-            ToolResult = Union[tuple([*tool_response_models, ToolResponse])]
+            # Include base ToolResponse so runtime-discovered tools (e.g. MCP) pass
+            # validation, and ErrorResponse so a failed tool call validates.
+            ToolResult = Union[tuple([*tool_response_models, ToolResponse, ErrorResponse])]
             fields["tool_responses"] = (list[ToolResult], ...)
         if linked_agents_response_models:
-            AgentResult = Union[tuple(linked_agents_response_models)]
+            # Include ErrorResponse so a failed linked-agent call — which yields an
+            # ErrorResponse, not the linked agent's own response type — validates.
+            AgentResult = Union[tuple([*linked_agents_response_models, ErrorResponse])]
             fields["agent_responses"] = (list[AgentResult], ...)
         if ResponseFormat:
             fields["final_output"] = (ResponseFormat, ...)

pyagentic/tracing/_tracer.py

@@ -183,7 +183,15 @@ class AgentTracer(ABC):
             self._record_exception(span, e)
             raise
         finally:
-            _current_span.reset(token)
+            try:
+                _current_span.reset(token)
+            except ValueError:
+                # The token can belong to a different context than the one we are
+                # unwinding in — e.g. when a span is opened inside a concurrently
+                # scheduled task (linked-agent calls run via asyncio.create_task) or
+                # is torn down across an async-generator boundary. Restore the parent
+                # span directly instead of resetting a foreign token.
+                _current_span.set(parent)
             self.end_span(span)
 
     @asynccontextmanager

{pyagentic_core-2.11.1.dev1.dist-info → pyagentic_core-2.12.1.dev2.dist-info}/METADATA

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

{pyagentic_core-2.11.1.dev1.dist-info → pyagentic_core-2.12.1.dev2.dist-info}/RECORD

@@ -5,16 +5,16 @@ 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/_info.py,sha256=2bY9_Ua9N7m94hcv6gLJCBZ2guxXTJf3YVOuJAyG4ns,2995
+pyagentic/_base/_info.py,sha256=LeXn3VbEJkP4KmMpjY6bqXjHYnE-ZHLuKoRcrmrqqhs,3020
 pyagentic/_base/_mcp.py,sha256=YPRaqVFrgKDA5BZtvVrcScyADjo66cdB4_h6nXpRJBI,8329
-pyagentic/_base/_metaclasses.py,sha256=0PQ3ipidOPKo6xE5Ra2ZBhme74s3Ss9BLj9O0RehueA,34452
+pyagentic/_base/_metaclasses.py,sha256=MWwW6uGJQYAm8wmbUyE86iGFbL76iTjBjkYqZCZAYxw,35241
 pyagentic/_base/_ref.py,sha256=Ez1Iexxl7NLBK91frcgz_eFbrXfLZpm9fvkYHMFWA_w,3179
-pyagentic/_base/_spec.py,sha256=TH-DZTYFcxXmzxGympH4vATPPlpI2o88Wlv6S7UuNlQ,7112
+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/_validation.py,sha256=BBscZMrXB09LNNP17pYOAY6I4iCW8r2GBVStqBd-9f8,3833
 pyagentic/_base/_agent/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pyagentic/_base/_agent/_agent.py,sha256=P35dpRp4Ihpc7AzGLW8bo_aj1pR2orvxu3a5777NIL8,39549
+pyagentic/_base/_agent/_agent.py,sha256=VyvTfjobGncz8XZU4NWSGqK9BBdhDElXi0eY9e_HHAU,42596
 pyagentic/_base/_agent/_agent_linking.py,sha256=gSHQkbH-BeKG8moROKDZiLs0ktLzW9bOVo0DFq3UNs8,1841
 pyagentic/_base/_agent/_agent_state.py,sha256=gvx0rQ1gaWfZHHAONX4YNsO_HE0xYQ14_GBKMP4Af-o,11507
 pyagentic/_utils/_typing.py,sha256=5aRZZOVzR0ZgnBfejkw__1yoARhn70P5QzA81sxUkls,3681
@@ -45,7 +45,7 @@ pyagentic/llm/_openai.py,sha256=NSM7Xd0N0P779ooU2bmUtfmVeHdgsSzndtiH02aEhK8,6105
 pyagentic/llm/_openaiv1.py,sha256=_E_Z-Fo9rdpmohT85kNpjNyiOowfYjDmfZh4mFbtLz4,8168
 pyagentic/llm/_provider.py,sha256=A3BDEJlLwMTdXnU1_GdaOjcFCYx_YKVHAdRhk2lBV9E,3265
 pyagentic/models/llm.py,sha256=QSTXIqkcnAC52I7m0ifebJeKdeAG90c6uqofIrOH2qU,2386
-pyagentic/models/response.py,sha256=pH_1WF9PPMYmxPhN7SoQszKJG-qq7gapTIyC3hBFH20,4660
+pyagentic/models/response.py,sha256=Zs4_yLKyZue3ysKrGQcjECmPAXJi_NJ_bEP8tINBVJo,5894
 pyagentic/models/tracing.py,sha256=5_cGxOAb5I9qjLVwSdvIcxUzrZy56OUe5fxlxOkud_w,1218
 pyagentic/policies/__init__.py,sha256=M5XQ4xubSjTFdUBVaRb65T_O7b9lxluJVyo4baoZgjY,68
 pyagentic/policies/_events.py,sha256=PZRGhMr8LMR1CFA7OAOZgZOqgQJ97T2r92NiaWuUvHE,1604
@@ -53,9 +53,9 @@ pyagentic/policies/_policy.py,sha256=9oLMyEJlCIudbItuXILDZHUAi29vGF18BgH-RZue3Wc
 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=HMisWfRLAQ9sdcjOvImiLij6OASd3siM8K-7nUfM3xs,7656
-pyagentic_core-2.11.1.dev1.dist-info/licenses/LICENSE,sha256=wcOzTj82hOc96HztJk2VzLB2hFHpdIGpjz8vvbpP1_s,1069
-pyagentic_core-2.11.1.dev1.dist-info/METADATA,sha256=GOf2IQSJPjEu105ZiXEf0WfET_7YC2la3d1LH1_Y77I,8212
-pyagentic_core-2.11.1.dev1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-pyagentic_core-2.11.1.dev1.dist-info/top_level.txt,sha256=lAWfd-ay434uEpSg2FM0ySN0o4vgNGE6D9dJkIhGyfY,10
-pyagentic_core-2.11.1.dev1.dist-info/RECORD,,
+pyagentic/tracing/_tracer.py,sha256=0uQeqJxPRjfQtvgglF2BPDQM_1fpLBxWB0PpU6KY1eA,8157
+pyagentic_core-2.12.1.dev2.dist-info/licenses/LICENSE,sha256=wcOzTj82hOc96HztJk2VzLB2hFHpdIGpjz8vvbpP1_s,1069
+pyagentic_core-2.12.1.dev2.dist-info/METADATA,sha256=sNURBjbhlVa4Tg7_CDu-BLnvzJMaC0RPuPMyrO03F1o,8212
+pyagentic_core-2.12.1.dev2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pyagentic_core-2.12.1.dev2.dist-info/top_level.txt,sha256=lAWfd-ay434uEpSg2FM0ySN0o4vgNGE6D9dJkIhGyfY,10
+pyagentic_core-2.12.1.dev2.dist-info/RECORD,,