pyagentic-core 2.1.0a2__tar.gz → 2.2.0__tar.gz

{pyagentic_core-2.1.0a2 → pyagentic_core-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyagentic-core
-Version: 2.1.0a2
+Version: 2.2.0
 Summary: Build LLM Agents in a Pythonic way
 Author-email: Ryan Mikulec <rmikulec.dev@gmail.com>
 License: MIT
@@ -20,6 +20,7 @@ Requires-Dist: typeguard>=4.4.4
 Requires-Dist: c3linearize>=0.1.0
 Requires-Dist: anthropic>=0.62.0
 Requires-Dist: google-generativeai>=0.8.0
+Requires-Dist: transitions>=0.9.3
 Dynamic: license-file
 
 # PyAgentic

{pyagentic_core-2.1.0a2 → pyagentic_core-2.2.0}/pyagentic/_base/_agent/_agent.py

@@ -13,6 +13,7 @@ from typing import (
     Union,
 )
 
+from transitions import Machine
 from pydantic import BaseModel, ValidationError
 
 from pyagentic.logging import get_logger
@@ -126,8 +127,6 @@ class BaseAgent(metaclass=AgentMeta):
         api_key (str, optional): API key matching the model provider
         provider (LLMProvider, optional): Pre-configured provider instance. Overrides
             `model` and `api_key` if provided.
-        emitter (Callable, optional): Callback function to receive real-time updates
-            about the agent's execution (useful for WebSocket streaming)
         tracer (AgentTracer, optional): Tracer instance for observability. Defaults
             to BasicTracer if not provided.
         max_call_depth (int): Maximum number of tool calling loops per run. Defaults to 1.
@@ -167,6 +166,7 @@ class BaseAgent(metaclass=AgentMeta):
     __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
+    phases: ClassVar[list[tuple[str, str, Callable]]] = None
 
     # Generated Class Attributes (built by metaclass)
     __response_model__: ClassVar[Type[AgentResponse]] = None  # Pydantic response model
@@ -177,7 +177,6 @@ class BaseAgent(metaclass=AgentMeta):
     model: str = None
     api_key: str = None
     provider: LLMProvider = None
-    emitter: Callable[[Any], str] = None
     tracer: AgentTracer = None
     max_call_depth: int = 1
 
@@ -254,6 +253,9 @@ class BaseAgent(metaclass=AgentMeta):
         """
         self._check_llm_provider()
 
+        if self.phases:
+            self.state._build_phase_machine(self.phases)
+
         # Use BasicTracer as default if no tracer provided
         if not self.tracer:
             self.tracer = BasicTracer()
@@ -314,13 +316,18 @@ class BaseAgent(metaclass=AgentMeta):
         except Exception as e:
             # Handle inference errors gracefully
             logger.exception(e)
-            if self.emitter:
-                await _safe_run(self.emitter, EmitUpdate(status=Status.ERROR))
             # Add error message to conversation history
             self.state._messages.append(
                 Message(role="assistant", content="Failed to generate a response")
             )
-            return LLMResponse(text=f"The LLM failed to generate a response: {e}", tool_calls=[])
+            response = LLMResponse(
+                text=f"The LLM failed to generate a response: {e}", tool_calls=[]
+            )
+
+        if self.phases:
+            self.state._update_state_machine(phases=self.phases)
+
+        return response
 
     @traced(SpanKind.AGENT)
     async def _process_agent_call(self, tool_call: ToolCall) -> AgentResponse:
@@ -367,6 +374,8 @@ class BaseAgent(metaclass=AgentMeta):
         self.state._messages.append(
             self.provider.to_tool_call_result_message(result=stringified_result, id_=tool_call.id)
         )
+        if self.phases:
+            self.state._update_state_machine(phases=self.phases)
         return response
 
     @traced(SpanKind.TOOL)
@@ -402,37 +411,15 @@ class BaseAgent(metaclass=AgentMeta):
             # Handle validation errors for tool arguments
             result = f"Function Args were invalid: {str(e)}"
             compiled_args = {}
-            if self.emitter:
-                self.tracer.record_exception(str(e))
-                logger.exception(e)
-                if self.emitter:
-                    await _safe_run(
-                        self.emitter,
-                        ToolUpdate(
-                            status=Status.ERROR, tool_call=tool_call.name, tool_args=kwargs
-                        ),
-                    )
-
-        # Execute the tool, emitting status updates
+            self.tracer.record_exception(str(e))
+            logger.exception(e)
         try:
-            if self.emitter:
-                await _safe_run(
-                    self.emitter,
-                    ToolUpdate(
-                        status=Status.PROCESSING, tool_call=tool_call.name, tool_args=kwargs
-                    ),
-                )
             if compiled_args:
                 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)
-            if self.emitter:
-                await _safe_run(
-                    self.emitter,
-                    ToolUpdate(status=Status.ERROR, tool_call=tool_call.name, tool_args=kwargs),
-                )
             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.",
@@ -442,11 +429,6 @@ class BaseAgent(metaclass=AgentMeta):
             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
-            if self.emitter:
-                await _safe_run(
-                    self.emitter,
-                    ToolUpdate(status=Status.ERROR, tool_call=tool_call.name, tool_args=kwargs),
-                )
 
         stringified_result = (
             result.model_dump_json(indent=2)
@@ -458,6 +440,8 @@ class BaseAgent(metaclass=AgentMeta):
             self.provider.to_tool_call_result_message(result=stringified_result, id_=tool_call.id)
         )
 
+        if self.phases:
+            self.state._update_state_machine(phases=self.phases)
         # Build and return the structured tool response
         ToolResponseModel = self.__tool_response_models__[tool_call.name]
         return ToolResponseModel(
@@ -479,7 +463,12 @@ class BaseAgent(metaclass=AgentMeta):
         # Add all @tool decorated methods
         for tool_def in self.__tool_defs__.values():
             # Resolve StateRefs in parameters (e.g., ref.self.user_name -> actual value)
-            tool_defs.append(tool_def.resolve(self.agent_reference))
+
+            if self.phases and tool_def.phases:
+                if self.state.phase in tool_def.phases:
+                    tool_defs.append(tool_def.resolve(self.agent_reference))
+            else:
+                tool_defs.append(tool_def.resolve(self.agent_reference))
 
         # Add linked agents as tools
         for name, linked_def in self.__linked_agents__.items():
@@ -492,10 +481,12 @@ class BaseAgent(metaclass=AgentMeta):
         self, input_: str
     ) -> AsyncGenerator[Union[ToolResponse, AgentResponse, LLMResponse]]:
         """
-        Main execution loop for the agent. Processes user input through multiple rounds
-        of LLM inference and tool/agent calls until completion or max_call_depth reached.
+        Streams all intermediate responses as the agent executes. Yields LLMResponse for each
+        inference, ToolResponse for each tool execution, and finally AgentResponse with the
+        complete result.
 
-        The agent follows an agentic loop pattern:
+        This is the core execution method that enables real-time streaming and fine-grained
+        control over agent execution. The agent follows an agentic loop pattern:
         1. Send user input and conversation history to the LLM
         2. LLM decides to either call tools or respond with final output
         3. If tools are called, execute them and feed results back to LLM
@@ -504,19 +495,23 @@ class BaseAgent(metaclass=AgentMeta):
         Args:
             input_ (str): The user input/query for the agent to process
 
-        Returns:
-            AgentResponse: Structured response containing:
-                - final_output: The final text or structured output from the LLM
-                - state: Current agent state after execution
-                - tool_responses: List of all tool calls and their outputs
-                - provider_info: Information about the LLM provider used
+        Yields:
+            Union[LLMResponse, ToolResponse, AgentResponse]: Responses in sequence:
+                - LLMResponse: Yielded each time the LLM is called (may happen multiple times)
+                - ToolResponse: Yielded for each tool execution
+                - AgentResponse: Final response with complete execution summary
 
         Example:
             ```python
             agent = MyAgent(model="openai::gpt-4o", api_key=API_KEY)
-            response = await agent.run("What's the weather in San Francisco?")
-            print(response.final_output)  # LLM's final answer
-            print(response.tool_responses)  # Tools that were called
+
+            async for response in agent.step("Analyze this data"):
+                if isinstance(response, LLMResponse):
+                    print(f"LLM thinking: {response.text}")
+                elif isinstance(response, ToolResponse):
+                    print(f"Tool executed: {response.output}")
+                elif isinstance(response, AgentResponse):
+                    print(f"Final: {response.final_output}")
             ```
         """
         async with self.tracer.agent(
@@ -538,10 +533,6 @@ class BaseAgent(metaclass=AgentMeta):
             agent_responses: list = []
             processed_call_ids: set[str] = set()
 
-            # Emit initial status
-            if self.emitter:
-                await _safe_run(self.emitter, EmitUpdate(status=Status.GENERATING))
-
             # Main agentic loop: LLM -> Tools -> LLM -> ...
             depth = 0
             final_ai_output: str | None = None
@@ -584,12 +575,6 @@ class BaseAgent(metaclass=AgentMeta):
                 response = await self._process_llm_inference()
                 final_ai_output = response.parsed if response.parsed else response.text
 
-            # Emit final success status
-            if self.emitter:
-                await _safe_run(
-                    self.emitter, AiUpdate(status=Status.SUCCEDED, message=final_ai_output)
-                )
-
             # Build the structured response
             response_fields = {
                 "final_output": final_ai_output,
@@ -607,6 +592,32 @@ class BaseAgent(metaclass=AgentMeta):
             yield response
 
     async def run(self, input_: str) -> AgentResponse:
+        """
+        Executes the agent with a message string and returns the final result.
+
+        This method consumes the entire step() generator and returns only the final
+        AgentResponse. Use this when you don't need intermediate streaming responses
+        and just want the final output.
+
+        Args:
+            input_ (str): The user input/query for the agent to process
+
+        Returns:
+            AgentResponse: Structured response containing:
+                - final_output: The final text or structured output from the LLM
+                - state: Current agent state after execution
+                - tool_responses: List of all tool calls and their outputs
+                - agent_responses: List of linked agent calls (if any)
+                - provider_info: Information about the LLM provider used
+
+        Example:
+            ```python
+            agent = MyAgent(model="openai::gpt-4o", api_key=API_KEY)
+            response = await agent.run("What's the weather in San Francisco?")
+            print(response.final_output)  # LLM's final answer
+            print(response.tool_responses)  # Tools that were called
+            ```
+        """
         final_response = None
         async for res in self.step(input_):
             final_response = res
@@ -614,13 +625,57 @@ class BaseAgent(metaclass=AgentMeta):
 
     async def __call__(self, user_input: str) -> BaseModel:
         """
-        Allows the agent to be called directly as a function.
+        Customizable callable interface for the agent. Override this method to accept
+        structured, typed parameters that match your agent's purpose.
+
+        When this agent is linked to another agent, the parameters of this method become
+        the tool parameters that the LLM sees. This enables type-safe, structured agent
+        composition in multi-agent systems.
+
+        The default implementation accepts a single user_input string and forwards it to
+        run(). Override to provide a custom interface:
 
         Args:
-            user_input (str): The user input to process
+            user_input (str): The user input to process (default implementation)
 
         Returns:
             AgentResponse: The agent's response
+
+        Example (Default Usage):
+            ```python
+            agent = MyAgent(model="openai::gpt-4o", api_key=API_KEY)
+            response = await agent("What's the weather?")
+            ```
+
+        Example (Custom Implementation):
+            ```python
+            class CoursePlannerAgent(BaseAgent):
+                __system_message__ = "You design course curricula"
+                __description__ = "Creates structured course plans"
+
+                async def __call__(
+                    self,
+                    goal: str,
+                    experience: str,
+                    context: Optional[str] = None
+                ) -> CoursePlan:
+                    # Build structured prompt from parameters
+                    prompt = f"Goal: {goal}\\nExperience: {experience}"
+                    if context:
+                        prompt += f"\\nContext: {context}"
+                    return await self.run(prompt)
+
+            # Call with structured parameters
+            planner = CoursePlannerAgent(model="openai::gpt-4o", api_key=API_KEY)
+            course = await planner(
+                goal="Learn ML",
+                experience="Python beginner",
+                context="Prefer hands-on projects"
+            )
+
+            # When linked to another agent, the LLM sees:
+            # Tool: planner(goal: str, experience: str, context: Optional[str])
+            ```
         """
         return await self.run(input_=user_input)
 

{pyagentic_core-2.1.0a2 → pyagentic_core-2.2.0}/pyagentic/_base/_agent/_agent_state.py

@@ -1,9 +1,10 @@
 import asyncio
 import threading
 from typing import Any, Type, Self, Optional, ClassVar
-from pydantic import BaseModel, create_model, Field, PrivateAttr
+from pydantic import BaseModel, create_model, Field, PrivateAttr, computed_field
 from jinja2 import Template
-from typing import Optional, Literal
+from typing import Optional, Literal, Callable
+from transitions import Machine
 
 from pyagentic._base._exceptions import InvalidStateRefNotFoundInState
 from pyagentic._base._state import _StateDefinition
@@ -30,12 +31,41 @@ class _AgentState(BaseModel):
 
     instructions: str
     input_template: Optional[str] = "{{ user_message }}"
+    _machine: Machine = PrivateAttr(default=None)
     _messages: list[Message] = PrivateAttr(default_factory=list)
     _instructions_template: Template = PrivateAttr(default_factory=lambda: Template(source=""))
     _input_template: Template = PrivateAttr(
         default_factory=lambda: Template(source="{{ user_message }}")
     )
 
+    def _build_phase_machine(self, phases: list[tuple[str, str, Callable]]) -> Machine:
+        if not phases:
+            return None
+
+        states = []
+        for source, dest, _ in phases:
+            if source not in states:
+                states.append(source)
+            if dest not in states:
+                states.append(dest)
+
+        machine = Machine(states=states, initial=states[0])
+
+        for source, dest, _ in phases:
+            machine.add_transition(
+                trigger=f"{source}_to_{dest}",
+                source=source,
+                dest=dest,
+            )
+
+        self._machine = machine
+
+    def _update_state_machine(self, phases):
+        for to_, from_, condition in phases:
+            if condition(self):
+                trigger = f"{to_}_to_{from_}"
+                getattr(self._machine, trigger)()
+
     def model_post_init(self, state):
         self._instructions_template = Template(source=self.instructions)
         if self.input_template:
@@ -221,6 +251,10 @@ class _AgentState(BaseModel):
         # now build the dataclass
         return create_model(f"AgentState[{name}]", __base__=cls, **pydantic_fields)
 
+    @property
+    def phase(self) -> str:
+        return self._machine.state if self._machine else None
+
     @property
     def recent_message(self) -> Message:
         """
@@ -242,7 +276,10 @@ class _AgentState(BaseModel):
         # start with all the normal dataclass fields
 
         # now format your instruction template
-        return self._instructions_template.render(**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())
 
     @property
     def messages(self) -> list[Message]:
@@ -270,7 +307,10 @@ class _AgentState(BaseModel):
         if self.input_template:
             data = self.model_dump()
             data["user_message"] = message
-            content = self._input_template.render(**data)
+            if self.phase:
+                content = self._input_template.render(phase=self.phase, **self.model_dump())
+            else:
+                content = self._input_template.render(**self.model_dump())
         else:
             content = message
         self._messages.append(Message(role="user", content=content))

{pyagentic_core-2.1.0a2 → pyagentic_core-2.2.0}/pyagentic/_base/_tool.py

@@ -43,12 +43,14 @@ class _ToolDefinition:
         parameters: dict[str, tuple[TypeVar, ParamInfo]],
         return_type: Type[Any],
         condition: Callable[[Any], bool] = None,
+        phases: list[str] = None,
     ):
         self.name: str = name
         self.description: str = description
         self.parameters: dict[str, tuple[TypeVar, ParamInfo]] = parameters
         self.condition = condition
         self.return_type = return_type
+        self.phases = phases if phases else []
 
     def resolve(self, agent_reference: dict) -> Self:
         new_parameters = {}
@@ -67,6 +69,7 @@ class _ToolDefinition:
             parameters=new_parameters,
             condition=self.condition,
             return_type=self.return_type,
+            phases=self.phases,
         )
 
     def to_openai_spec(self) -> dict:
@@ -210,10 +213,7 @@ class _ToolDefinition:
         return compiled_args
 
 
-def tool(
-    description: str,
-    condition: Callable[[Any], bool] = None,
-):
+def tool(description: str, condition: Callable[[Any], bool] = None, phases: list[str] = None):
     """
     Decorator to mark an agent method as a tool that the LLM can call.
 
@@ -281,6 +281,7 @@ def tool(
             parameters=params,
             condition=condition,
             return_type=return_type,
+            phases=phases,
         )
         return fn
 

{pyagentic_core-2.1.0a2 → pyagentic_core-2.2.0}/pyagentic_core.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyagentic-core
-Version: 2.1.0a2
+Version: 2.2.0
 Summary: Build LLM Agents in a Pythonic way
 Author-email: Ryan Mikulec <rmikulec.dev@gmail.com>
 License: MIT
@@ -20,6 +20,7 @@ Requires-Dist: typeguard>=4.4.4
 Requires-Dist: c3linearize>=0.1.0
 Requires-Dist: anthropic>=0.62.0
 Requires-Dist: google-generativeai>=0.8.0
+Requires-Dist: transitions>=0.9.3
 Dynamic: license-file
 
 # PyAgentic

{pyagentic_core-2.1.0a2 → pyagentic_core-2.2.0}/pyagentic_core.egg-info/requires.txt

@@ -8,3 +8,4 @@ typeguard>=4.4.4
 c3linearize>=0.1.0
 anthropic>=0.62.0
 google-generativeai>=0.8.0
+transitions>=0.9.3

{pyagentic_core-2.1.0a2 → pyagentic_core-2.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyagentic-core"
-version = "2.1.0-a.2"
+version = "2.2.0"
 description = "Build LLM Agents in a Pythonic way"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -23,6 +23,7 @@ dependencies = [
     "c3linearize>=0.1.0",
     "anthropic>=0.62.0",
     "google-generativeai>=0.8.0",
+    "transitions>=0.9.3",
 ]
 
 [dependency-groups]
@@ -105,4 +106,4 @@ include = ["pyagentic*"]
 compile-diagrams = "for file in docs/diagrams/source/*.d2; do d2 --layout elk \"$file\" \"docs/diagrams/$(basename \"$file\" .d2).svg\"; done"
 build-docs  = "task compile-diagrams && mkdocs build --clean"
 serve-docs  = "task compile-diagrams && mkdocs serve"
-deploy-docs = "task compile-diagrams && mkdocs gh-deploy --force"
+deploy-docs = "task compile-diagrams && mkdocs gh-deploy --force"