agnt5 0.2.2__cp39-abi3-macosx_11_0_arm64.whl → 0.2.4__cp39-abi3-macosx_11_0_arm64.whl

agnt5/agent.py

@@ -1,7 +1,7 @@
 """Agent component implementation for AGNT5 SDK.
 
-Phase 1: Simple agent with external LLM integration and tool orchestration.
-Phase 2: Platform-backed agents with durable execution and multi-agent coordination.
+Provides simple agent with external LLM integration and tool orchestration.
+Future: Platform-backed agents with durable execution and multi-agent coordination.
 """
 
 from __future__ import annotations
@@ -163,13 +163,13 @@ class AgentResult:
 class Agent:
     """Autonomous LLM-driven agent with tool orchestration.
 
-    Phase 1: Simple agent with:
+    Current features:
     - LLM integration (OpenAI, Anthropic, etc.)
     - Tool selection and execution
     - Multi-turn reasoning
     - Context and state management
 
-    Phase 2 will add:
+    Future enhancements:
     - Durable execution with checkpointing
     - Multi-agent coordination
     - Platform-backed tool execution
@@ -452,148 +452,161 @@ class Agent:
                 component_type="agent",
             )
 
-        # Initialize conversation
-        messages: List[Message] = [Message.user(user_message)]
-        all_tool_calls: List[Dict[str, Any]] = []
-
-        # Reasoning loop
-        for iteration in range(self.max_iterations):
-            self.logger.info(f"Agent iteration {iteration + 1}/{self.max_iterations}")
-
-            # Build tool definitions for LLM
-            tool_defs = [
-                ToolDefinition(
-                    name=tool.name,
-                    description=tool.description,
-                    parameters=tool.input_schema,
-                )
-                for tool in self.tools.values()
-            ]
-
-            # Convert messages to dict format for lm.generate()
-            messages_dict = []
-            for msg in messages:
-                messages_dict.append({
-                    "role": msg.role.value,
-                    "content": msg.content
-                })
-
-            # Call LLM using simplified API
-            # TODO: Support tools in lm.generate() - for now using GenerateRequest internally
-            request = GenerateRequest(
-                model=self.model,
-                system_prompt=self.instructions,
-                messages=messages,
-                tools=tool_defs if tool_defs else [],
-            )
-            request.config.temperature = self.temperature
-            if self.max_tokens:
-                request.config.max_tokens = self.max_tokens
-            if self.top_p:
-                request.config.top_p = self.top_p
-
-            # Create internal LM instance for generation
-            # TODO: Use model_config when provided
-            from .lm import _LanguageModel
-            provider, model_name = self.model.split('/', 1)
-            internal_lm = _LanguageModel(provider=provider.lower(), default_model=None)
-            response = await internal_lm.generate(request)
-
-            # Add assistant response to messages
-            messages.append(Message.assistant(response.text))
-
-            # Check if LLM wants to use tools
-            if response.tool_calls:
-                self.logger.info(f"Agent calling {len(response.tool_calls)} tool(s)")
-
-                # Store current conversation in context for potential handoffs
-                context.set("_current_conversation", messages)
-
-                # Execute tool calls
-                tool_results = []
-                for tool_call in response.tool_calls:
-                    tool_name = tool_call["name"]
-                    tool_args_str = tool_call["arguments"]
-
-                    # Track tool call
-                    all_tool_calls.append(
-                        {
-                            "name": tool_name,
-                            "arguments": tool_args_str,
-                            "iteration": iteration + 1,
-                        }
+        # Create span for agent execution with trace linking
+        from ._core import create_span
+
+        with create_span(
+            self.name,
+            "agent",
+            context._runtime_context if hasattr(context, "_runtime_context") else None,
+            {
+                "agent.name": self.name,
+                "agent.model": self.model,
+                "agent.max_iterations": str(self.max_iterations),
+            },
+        ) as span:
+            # Initialize conversation
+            messages: List[Message] = [Message.user(user_message)]
+            all_tool_calls: List[Dict[str, Any]] = []
+
+            # Reasoning loop
+            for iteration in range(self.max_iterations):
+                self.logger.info(f"Agent iteration {iteration + 1}/{self.max_iterations}")
+
+                # Build tool definitions for LLM
+                tool_defs = [
+                    ToolDefinition(
+                        name=tool.name,
+                        description=tool.description,
+                        parameters=tool.input_schema,
                     )
-
-                    # Execute tool
-                    try:
-                        # Parse arguments
-                        tool_args = json.loads(tool_args_str)
-
-                        # Get tool
-                        tool = self.tools.get(tool_name)
-                        if not tool:
-                            result_text = f"Error: Tool '{tool_name}' not found"
-                        else:
-                            # Execute tool
-                            result = await tool.invoke(context, **tool_args)
-
-                            # Check if this was a handoff
-                            if isinstance(result, dict) and result.get("_handoff"):
-                                self.logger.info(
-                                    f"Handoff detected to '{result['to_agent']}', "
-                                    f"terminating current agent"
-                                )
-                                # Return immediately with handoff result
-                                return AgentResult(
-                                    output=result["output"],
-                                    tool_calls=all_tool_calls + result.get("tool_calls", []),
-                                    context=context,
-                                    handoff_to=result["to_agent"],
-                                    handoff_metadata=result,
-                                )
-
-                            result_text = json.dumps(result) if result else "null"
-
-                        tool_results.append(
-                            {"tool": tool_name, "result": result_text, "error": None}
-                        )
-
-                    except Exception as e:
-                        self.logger.error(f"Tool execution error: {e}")
-                        tool_results.append(
-                            {"tool": tool_name, "result": None, "error": str(e)}
+                    for tool in self.tools.values()
+                ]
+
+                # Convert messages to dict format for lm.generate()
+                messages_dict = []
+                for msg in messages:
+                    messages_dict.append({
+                        "role": msg.role.value,
+                        "content": msg.content
+                    })
+
+                # Call LLM using simplified API
+                # TODO: Support tools in lm.generate() - for now using GenerateRequest internally
+                request = GenerateRequest(
+                    model=self.model,
+                    system_prompt=self.instructions,
+                    messages=messages,
+                    tools=tool_defs if tool_defs else [],
+                )
+                request.config.temperature = self.temperature
+                if self.max_tokens:
+                    request.config.max_tokens = self.max_tokens
+                if self.top_p:
+                    request.config.top_p = self.top_p
+
+                # Create internal LM instance for generation
+                # TODO: Use model_config when provided
+                from .lm import _LanguageModel
+                provider, model_name = self.model.split('/', 1)
+                internal_lm = _LanguageModel(provider=provider.lower(), default_model=None)
+                response = await internal_lm.generate(request)
+
+                # Add assistant response to messages
+                messages.append(Message.assistant(response.text))
+
+                # Check if LLM wants to use tools
+                if response.tool_calls:
+                    self.logger.info(f"Agent calling {len(response.tool_calls)} tool(s)")
+
+                    # Store current conversation in context for potential handoffs
+                    context.set("_current_conversation", messages)
+
+                    # Execute tool calls
+                    tool_results = []
+                    for tool_call in response.tool_calls:
+                        tool_name = tool_call["name"]
+                        tool_args_str = tool_call["arguments"]
+
+                        # Track tool call
+                        all_tool_calls.append(
+                            {
+                                "name": tool_name,
+                                "arguments": tool_args_str,
+                                "iteration": iteration + 1,
+                            }
                         )
 
-                # Add tool results to conversation
-                results_text = "\n".join(
-                    [
-                        f"Tool: {tr['tool']}\nResult: {tr['result']}"
-                        if tr["error"] is None
-                        else f"Tool: {tr['tool']}\nError: {tr['error']}"
-                        for tr in tool_results
-                    ]
-                )
-                messages.append(Message.user(f"Tool results:\n{results_text}"))
+                        # Execute tool
+                        try:
+                            # Parse arguments
+                            tool_args = json.loads(tool_args_str)
+
+                            # Get tool
+                            tool = self.tools.get(tool_name)
+                            if not tool:
+                                result_text = f"Error: Tool '{tool_name}' not found"
+                            else:
+                                # Execute tool
+                                result = await tool.invoke(context, **tool_args)
+
+                                # Check if this was a handoff
+                                if isinstance(result, dict) and result.get("_handoff"):
+                                    self.logger.info(
+                                        f"Handoff detected to '{result['to_agent']}', "
+                                        f"terminating current agent"
+                                    )
+                                    # Return immediately with handoff result
+                                    return AgentResult(
+                                        output=result["output"],
+                                        tool_calls=all_tool_calls + result.get("tool_calls", []),
+                                        context=context,
+                                        handoff_to=result["to_agent"],
+                                        handoff_metadata=result,
+                                    )
+
+                                result_text = json.dumps(result) if result else "null"
+
+                            tool_results.append(
+                                {"tool": tool_name, "result": result_text, "error": None}
+                            )
+
+                        except Exception as e:
+                            self.logger.error(f"Tool execution error: {e}")
+                            tool_results.append(
+                                {"tool": tool_name, "result": None, "error": str(e)}
+                            )
+
+                    # Add tool results to conversation
+                    results_text = "\n".join(
+                        [
+                            f"Tool: {tr['tool']}\nResult: {tr['result']}"
+                            if tr["error"] is None
+                            else f"Tool: {tr['tool']}\nError: {tr['error']}"
+                            for tr in tool_results
+                        ]
+                    )
+                    messages.append(Message.user(f"Tool results:\n{results_text}"))
 
-                # Continue loop for agent to process results
+                    # Continue loop for agent to process results
 
-            else:
-                # No tool calls - agent is done
-                self.logger.info(f"Agent completed after {iteration + 1} iterations")
-                return AgentResult(
-                    output=response.text,
-                    tool_calls=all_tool_calls,
-                    context=context,
-                )
+                else:
+                    # No tool calls - agent is done
+                    self.logger.info(f"Agent completed after {iteration + 1} iterations")
+                    return AgentResult(
+                        output=response.text,
+                        tool_calls=all_tool_calls,
+                        context=context,
+                    )
 
-        # Max iterations reached
-        self.logger.warning(f"Agent reached max iterations ({self.max_iterations})")
-        final_output = messages[-1].content if messages else "No output generated"
-        return AgentResult(
-            output=final_output,
-            tool_calls=all_tool_calls,
-            context=context,
-        )
+            # Max iterations reached
+            self.logger.warning(f"Agent reached max iterations ({self.max_iterations})")
+            final_output = messages[-1].content if messages else "No output generated"
+            return AgentResult(
+                output=final_output,
+                tool_calls=all_tool_calls,
+                context=context,
+            )
 
     async def chat(
         self,

agnt5/client.py

@@ -42,6 +42,7 @@ class Client:
         self,
         component: str,
         input_data: Optional[Dict[str, Any]] = None,
+        component_type: str = "function",
     ) -> Dict[str, Any]:
         """Execute a component synchronously and wait for the result.
 
@@ -50,6 +51,7 @@ class Client:
         Args:
             component: Name of the component to execute
             input_data: Input data for the component (will be sent as JSON body)
+            component_type: Type of component - "function", "workflow", "agent", "tool" (default: "function")
 
         Returns:
             Dictionary containing the component's output
@@ -60,9 +62,12 @@ class Client:
 
         Example:
             ```python
-            # Simple function call
+            # Simple function call (default)
             result = client.run("greet", {"name": "Alice"})
 
+            # Workflow execution (explicit)
+            result = client.run("order_fulfillment", {"order_id": "123"}, component_type="workflow")
+
             # No input data
             result = client.run("get_status")
             ```
@@ -70,8 +75,8 @@ class Client:
         if input_data is None:
             input_data = {}
 
-        # Build URL
-        url = urljoin(self.gateway_url + "/", f"run/{component}")
+        # Build URL with component type
+        url = urljoin(self.gateway_url + "/", f"v1/run/{component_type}/{component}")
 
         # Make request
         response = self._client.post(
@@ -81,6 +86,17 @@ class Client:
         )
 
         # Handle errors
+        if response.status_code == 404:
+            try:
+                error_data = response.json()
+                raise RunError(
+                    error_data.get("error", "Component not found"),
+                    run_id=error_data.get("runId"),
+                )
+            except ValueError:
+                # JSON parsing failed
+                raise RunError(f"Component '{component}' not found")
+
         if response.status_code == 503:
             error_data = response.json()
             raise RunError(
@@ -127,6 +143,7 @@ class Client:
         self,
         component: str,
         input_data: Optional[Dict[str, Any]] = None,
+        component_type: str = "function",
     ) -> str:
         """Submit a component for async execution and return immediately.
 
@@ -136,6 +153,7 @@ class Client:
         Args:
             component: Name of the component to execute
             input_data: Input data for the component (will be sent as JSON body)
+            component_type: Type of component - "function", "workflow", "agent", "tool" (default: "function")
 
         Returns:
             String containing the run ID
@@ -145,10 +163,13 @@ class Client:
 
         Example:
             ```python
-            # Submit async task
+            # Submit async function (default)
             run_id = client.submit("process_video", {"url": "https://..."})
             print(f"Submitted: {run_id}")
 
+            # Submit workflow
+            run_id = client.submit("order_fulfillment", {"order_id": "123"}, component_type="workflow")
+
             # Check status later
             status = client.get_status(run_id)
             if status["status"] == "completed":
@@ -158,8 +179,8 @@ class Client:
         if input_data is None:
             input_data = {}
 
-        # Build URL
-        url = urljoin(self.gateway_url + "/", f"submit/{component}")
+        # Build URL with component type
+        url = urljoin(self.gateway_url + "/", f"v1/submit/{component_type}/{component}")
 
         # Make request
         response = self._client.post(
@@ -200,7 +221,7 @@ class Client:
             print(f"Status: {status['status']}")
             ```
         """
-        url = urljoin(self.gateway_url + "/", f"status/{run_id}")
+        url = urljoin(self.gateway_url + "/", f"v1/status/{run_id}")
 
         response = self._client.get(url)
         response.raise_for_status()
@@ -234,7 +255,7 @@ class Client:
                     print(f"Run failed: {e}")
             ```
         """
-        url = urljoin(self.gateway_url + "/", f"result/{run_id}")
+        url = urljoin(self.gateway_url + "/", f"v1/result/{run_id}")
 
         response = self._client.get(url)
 
@@ -351,7 +372,7 @@ class Client:
             input_data = {}
 
         # Build URL
-        url = urljoin(self.gateway_url + "/", f"stream/{component}")
+        url = urljoin(self.gateway_url + "/", f"v1/stream/{component}")
 
         # Use streaming request
         with self._client.stream(
@@ -511,10 +532,11 @@ class EntityProxy:
             Callable that executes the entity method
         """
 
-        def method_caller(**kwargs) -> Any:
+        def method_caller(*args, **kwargs) -> Any:
             """Call an entity method with the given parameters.
 
             Args:
+                *args: Positional arguments (not recommended, use kwargs)
                 **kwargs: Method parameters as keyword arguments
 
             Returns:
@@ -522,11 +544,27 @@ class EntityProxy:
 
             Raises:
                 RunError: If the method execution fails
+                ValueError: If both positional and keyword arguments are provided
             """
-            # Build URL: /entity/:entityType/:key/:method
+            # Convert positional args to kwargs if provided
+            if args and kwargs:
+                raise ValueError(
+                    f"Cannot mix positional and keyword arguments when calling entity method '{method_name}'. "
+                    "Please use keyword arguments only."
+                )
+
+            # If positional args provided, we can't convert them without knowing parameter names
+            # Raise helpful error
+            if args:
+                raise ValueError(
+                    f"Entity method '{method_name}' requires keyword arguments, but got {len(args)} positional arguments. "
+                    f"Example: .{method_name}(param1=value1, param2=value2)"
+                )
+
+            # Build URL: /v1/entity/:entityType/:key/:method
             url = urljoin(
                 self._client.gateway_url + "/",
-                f"entity/{self._entity_type}/{self._key}/{method_name}",
+                f"v1/entity/{self._entity_type}/{self._key}/{method_name}",
             )
 
             # Make request with method parameters as JSON body