pyagentic-core 2.0.2__tar.gz → 2.1.0__tar.gz

{pyagentic_core-2.0.2 → pyagentic_core-2.1.0}/PKG-INFO

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

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

@@ -4,13 +4,13 @@ from functools import wraps
 from typing import (
     Callable,
     Any,
-    TypeVar,
+    AsyncGenerator,
     ClassVar,
     Type,
-    Self,
     dataclass_transform,
     Optional,
     TYPE_CHECKING,
+    Union,
 )
 
 from pydantic import BaseModel, ValidationError
@@ -126,8 +126,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.
@@ -177,7 +175,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
 
@@ -314,8 +311,6 @@ 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")
@@ -359,8 +354,13 @@ class BaseAgent(metaclass=AgentMeta):
             response = AgentResponse(final_output=result, provider_info=agent.provider._info)
 
         # Add agent result to conversation history
+        stringified_result = (
+            result.model_dump_json(indent=2)
+            if issubclass(result.__class__, BaseModel)
+            else str(result)
+        )
         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=stringified_result, id_=tool_call.id)
         )
         return response
 
@@ -397,38 +397,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)
-                result = str(result)
                 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.",
@@ -438,15 +415,15 @@ 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)
+            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=result, id_=tool_call.id)
+            self.provider.to_tool_call_result_message(result=stringified_result, id_=tool_call.id)
         )
 
         # Build and return the structured tool response
@@ -479,12 +456,16 @@ class BaseAgent(metaclass=AgentMeta):
 
         return tool_defs
 
-    async def run(self, input_: str) -> BaseModel:
+    async def step(
+        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
@@ -493,19 +474,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(
@@ -527,10 +512,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
@@ -538,6 +519,7 @@ class BaseAgent(metaclass=AgentMeta):
             while depth < self.max_call_depth:
                 # Ask the LLM what to do next (may return tool calls or final text)
                 response = await self._process_llm_inference(tool_defs=tool_defs)
+                yield response
 
                 # If the model produced final text without tool calls, we're done
                 if not response.tool_calls:
@@ -557,10 +539,12 @@ class BaseAgent(metaclass=AgentMeta):
                     if tool_call.name in self.__tool_defs__:
                         result = await self._process_tool_call(tool_call, call_depth=depth)
                         tool_responses.append(result)
+                        yield result
 
                     elif tool_call.name in self.__linked_agents__:
                         result = await self._process_agent_call(tool_call)
                         agent_responses.append(result)
+                        yield result
 
                 # Increment depth and continue loop (LLM will see tool results next iteration)
                 depth += 1
@@ -570,12 +554,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,
@@ -590,17 +568,93 @@ class BaseAgent(metaclass=AgentMeta):
 
             response = self.__response_model__(**response_fields)
             self.tracer.set_attributes(output=response)
-            return response
+            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
+        return final_response
 
     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.0.2 → pyagentic_core-2.1.0}/pyagentic/_base/_agent/_agent_state.py

@@ -32,7 +32,9 @@ class _AgentState(BaseModel):
     input_template: Optional[str] = "{{ user_message }}"
     _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 }}"))
+    _input_template: Template = PrivateAttr(
+        default_factory=lambda: Template(source="{{ user_message }}")
+    )
 
     def model_post_init(self, state):
         self._instructions_template = Template(source=self.instructions)

{pyagentic_core-2.0.2 → pyagentic_core-2.1.0}/pyagentic/models/response.py

@@ -60,7 +60,9 @@ class ToolResponse(BaseModel):
                 case _:
                     raise Exception(f"Unsupported type: {param_type}")
 
-        return create_model(f"ToolResponse[{tool_def.name}]", __base__=cls, **fields)
+        return create_model(
+            f"ToolResponse[{tool_def.name}]", __base__=cls, output=tool_def.return_type, **fields
+        )
 
 
 class AgentResponse(BaseModel):

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

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

{pyagentic_core-2.0.2 → pyagentic_core-2.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyagentic-core"
-version = "2.0.2"
+version = "2.1.0"
 description = "Build LLM Agents in a Pythonic way"
 readme = "README.md"
 requires-python = ">=3.13"