agnt5 0.2.2__cp39-abi3-manylinux_2_34_aarch64.whl → 0.2.6__cp39-abi3-manylinux_2_34_aarch64.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
@@ -13,7 +13,7 @@ from typing import Any, Callable, Dict, List, Optional
 
 from .context import Context
 from . import lm
-from .lm import GenerateRequest, GenerateResponse, Message, ModelConfig, ToolDefinition
+from .lm import GenerateRequest, GenerateResponse, LanguageModel, Message, ModelConfig, ToolDefinition
 from .tool import Tool, ToolRegistry
 from ._telemetry import setup_module_logger
 
@@ -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
@@ -201,7 +201,7 @@ class Agent:
     def __init__(
         self,
         name: str,
-        model: str,
+        model: Any,  # Can be string like "openai/gpt-4o-mini" OR LanguageModel instance
         instructions: str,
         tools: Optional[List[Any]] = None,
         handoffs: Optional[List[Handoff]] = None,
@@ -210,12 +210,13 @@ class Agent:
         top_p: Optional[float] = None,
         model_config: Optional[ModelConfig] = None,
         max_iterations: int = 10,
+        model_name: Optional[str] = None,  # For backwards compatibility with tests
     ):
         """Initialize agent.
 
         Args:
             name: Agent name/identifier
-            model: Model string with provider prefix (e.g., "openai/gpt-4o-mini")
+            model: Model string with provider prefix (e.g., "openai/gpt-4o-mini") OR LanguageModel instance
             instructions: System instructions for the agent
             tools: List of tools available to the agent (functions, Tool instances, or Agent instances)
             handoffs: List of Handoff configurations for agent-to-agent delegation
@@ -224,9 +225,9 @@ class Agent:
             top_p: Nucleus sampling parameter
             model_config: Optional advanced configuration (custom endpoints, headers, etc.)
             max_iterations: Maximum reasoning iterations
+            model_name: Optional model name (for backwards compatibility, used when model is a LanguageModel instance)
         """
         self.name = name
-        self.model = model
         self.instructions = instructions
         self.temperature = temperature
         self.max_tokens = max_tokens
@@ -234,6 +235,20 @@ class Agent:
         self.model_config = model_config
         self.max_iterations = max_iterations
 
+        # Support both string model names and LanguageModel instances
+        if isinstance(model, str):
+            # New API: model is a string like "openai/gpt-4o-mini"
+            self.model = model
+            self.model_name = model_name or model
+            self._language_model = None  # Will create on demand
+        elif isinstance(model, LanguageModel):
+            # Old API (for tests): model is a LanguageModel instance
+            self._language_model = model
+            self.model = model  # Keep for backwards compatibility
+            self.model_name = model_name or "mock-model"
+        else:
+            raise TypeError(f"model must be a string or LanguageModel instance, got {type(model)}")
+
         # Store handoffs for building handoff tools
         self.handoffs = handoffs or []
 
@@ -377,13 +392,16 @@ class Agent:
             if handoff_config.pass_full_history:
                 # Get current conversation from the agent's run loop
                 # (This will be set when we detect the handoff in run())
-                conversation_history = ctx.get("_current_conversation", [])
+                conversation_history = getattr(ctx, '_agent_data', {}).get("_current_conversation", [])
+
                 if conversation_history:
                     ctx.logger.info(
                         f"Passing {len(conversation_history)} messages to target agent"
                     )
                     # Store in context for target agent to optionally use
-                    ctx.set("_handoff_conversation_history", conversation_history)
+                    if not hasattr(ctx, '_agent_data'):
+                        ctx._agent_data = {}
+                    ctx._agent_data["_handoff_conversation_history"] = conversation_history
 
             # Execute target agent with the message and shared context
             result = await target_agent.run(message, context=ctx)
@@ -398,7 +416,9 @@ class Agent:
                 "tool_calls": result.tool_calls,
             }
 
-            ctx.set("_handoff_result", handoff_data)
+            if not hasattr(ctx, '_agent_data'):
+                ctx._agent_data = {}
+            ctx._agent_data["_handoff_result"] = handoff_data
 
             # Return the handoff data (will be detected in run() loop)
             return handoff_data
@@ -449,151 +469,164 @@ class Agent:
 
             context = Context(
                 run_id=f"agent-{self.name}-{uuid.uuid4().hex[:8]}",
-                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):
+                # 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.debug(f"Agent calling {len(response.tool_calls)} tool(s)")
+
+                    # Store current conversation in context for potential handoffs
+                    # Use a simple dict attribute since we don't need full state persistence for this
+                    if not hasattr(context, '_agent_data'):
+                        context._agent_data = {}
+                    context._agent_data["_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}\n\nPlease provide your final answer based on these results."))
 
-                # 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.debug(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,
@@ -623,7 +656,6 @@ class Agent:
 
             context = Context(
                 run_id=f"agent-chat-{self.name}-{uuid.uuid4().hex[:8]}",
-                component_type="agent",
             )
 
         # Add user message

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