pyagentic-core 2.1.0a2__tar.gz → 2.1.0a3__tar.gz

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

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

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

@@ -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")
@@ -402,37 +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)
                 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 +415,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)
@@ -492,10 +460,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 +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(
@@ -538,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
@@ -584,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,
@@ -607,6 +571,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 +604,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.1.0a3}/pyagentic_core.egg-info/PKG-INFO

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

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

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