aip-agents-binary 0.5.25b9__py3-none-any.whl → 0.6.1__py3-none-any.whl

aip_agents/sandbox/template_builder.py

@@ -0,0 +1,131 @@
+"""Template builder for PTC sandbox templates.
+
+This module provides utilities for creating and managing E2B sandbox templates
+for programmatic tool calling (PTC) environments.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from e2b import Template, default_build_logger
+
+from aip_agents.sandbox.validation import validate_package_names
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def create_ptc_template(base_template: str, ptc_packages: list[str] | None) -> Template:
+    """Create a PTC template definition based on a base template.
+
+    Args:
+        base_template: Base template alias to build from (e.g., "code-interpreter-v1").
+        ptc_packages: List of packages to install in the template.
+            If None or empty, skips pip install step.
+
+    Returns:
+        Template: A configured template ready to be built.
+    """
+    logger.info(f"Creating template from base: {base_template}")
+    template = Template().from_template(base_template)
+
+    if ptc_packages:
+        # Validate all packages before constructing command
+        validate_package_names(ptc_packages)
+
+        # Note: packages_str is safe because ptc_packages is a controlled list from
+        # configuration, not user input. Template.run_cmd() only accepts str.
+        packages_str = " ".join(ptc_packages)
+        logger.info(f"Installing packages: {packages_str}")
+        template.run_cmd(f"pip install -q {packages_str}")
+
+    return template
+
+
+def _template_exists(template_id: str) -> bool:
+    """Check if a template alias exists.
+
+    Args:
+        template_id: The template alias to check.
+
+    Returns:
+        bool: True if alias exists, False otherwise.
+    """
+    try:
+        return Template.alias_exists(template_id)
+    except Exception:
+        logger.warning(f"Template alias check failed for: {template_id}")
+        return False
+
+
+def _build_template(template: Template, template_id: str) -> bool:
+    """Build a template with the given alias.
+
+    Args:
+        template: The template to build.
+        template_id: The alias to assign to the built template.
+
+    Returns:
+        bool: True if build succeeded, False otherwise.
+    """
+    try:
+        logger.info(f"Building template: {template_id}")
+        Template.build(
+            template,
+            alias=template_id,
+            on_build_logs=default_build_logger(),
+        )
+        logger.info(f"Template built successfully: {template_id}")
+        return True
+    except Exception as e:
+        logger.warning(f"Template build failed for {template_id}: {e}")
+        return False
+
+
+def ensure_ptc_template(
+    template_id: str,
+    base_template: str,
+    ptc_packages: list[str] | None,
+    force_rebuild: bool = False,
+) -> str | None:
+    """Ensure a PTC sandbox template exists, creating it if necessary.
+
+    This is an explicit helper that apps can call at startup to ensure the
+    template exists. It is never run implicitly by the SDK.
+
+    Args:
+        template_id: Unique alias for the template (e.g., "aip-agents-ptc-v1").
+        base_template: Base template alias to build from
+            (e.g., "code-interpreter-v1").
+        ptc_packages: List of packages to install in the template.
+            If None or empty, skips pip install step.
+        force_rebuild: If True, rebuild even if alias exists.
+
+    Returns:
+        The template_id on success, None if creation failed.
+        Never raises exceptions.
+    """
+    # Fast path: template already exists and we're not forcing rebuild
+    if not force_rebuild and _template_exists(template_id):
+        logger.info(f"Template already exists: {template_id}")
+        return template_id
+
+    # Create and build the template
+    try:
+        template = create_ptc_template(base_template, ptc_packages)
+    except Exception as e:
+        logger.warning(f"Template creation failed for {template_id}: {e}")
+        return None
+
+    # Build the template
+    is_success = _build_template(template, template_id)
+    if is_success:
+        return template_id
+
+    # Build failed. Check if template exists anyway (race condition: another
+    # process may have built it while we were trying)
+    if _template_exists(template_id):
+        logger.info(f"Template already exists after failed build: {template_id}")
+        return template_id
+
+    return None

aip_agents/sandbox/template_builder.pyi

@@ -0,0 +1,36 @@
+from _typeshed import Incomplete
+from aip_agents.sandbox.validation import validate_package_names as validate_package_names
+from aip_agents.utils.logger import get_logger as get_logger
+from e2b import Template
+
+logger: Incomplete
+
+def create_ptc_template(base_template: str, ptc_packages: list[str] | None) -> Template:
+    '''Create a PTC template definition based on a base template.
+
+    Args:
+        base_template: Base template alias to build from (e.g., "code-interpreter-v1").
+        ptc_packages: List of packages to install in the template.
+            If None or empty, skips pip install step.
+
+    Returns:
+        Template: A configured template ready to be built.
+    '''
+def ensure_ptc_template(template_id: str, base_template: str, ptc_packages: list[str] | None, force_rebuild: bool = False) -> str | None:
+    '''Ensure a PTC sandbox template exists, creating it if necessary.
+
+    This is an explicit helper that apps can call at startup to ensure the
+    template exists. It is never run implicitly by the SDK.
+
+    Args:
+        template_id: Unique alias for the template (e.g., "aip-agents-ptc-v1").
+        base_template: Base template alias to build from
+            (e.g., "code-interpreter-v1").
+        ptc_packages: List of packages to install in the template.
+            If None or empty, skips pip install step.
+        force_rebuild: If True, rebuild even if alias exists.
+
+    Returns:
+        The template_id on success, None if creation failed.
+        Never raises exceptions.
+    '''

aip_agents/sandbox/types.py

@@ -0,0 +1,24 @@
+"""Sandbox execution result types.
+
+This module defines types for sandbox execution results.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class SandboxExecutionResult:
+    """Result of a sandbox code execution.
+
+    Attributes:
+        stdout: Standard output from the execution.
+        stderr: Standard error from the execution.
+        exit_code: Exit code (0 for success, non-zero for failure).
+    """
+
+    stdout: str
+    stderr: str
+    exit_code: int

aip_agents/sandbox/types.pyi

@@ -0,0 +1,14 @@
+from dataclasses import dataclass
+
+@dataclass
+class SandboxExecutionResult:
+    """Result of a sandbox code execution.
+
+    Attributes:
+        stdout: Standard output from the execution.
+        stderr: Standard error from the execution.
+        exit_code: Exit code (0 for success, non-zero for failure).
+    """
+    stdout: str
+    stderr: str
+    exit_code: int

aip_agents/sandbox/validation.py

@@ -0,0 +1,50 @@
+"""Validation utilities for sandbox operations.
+
+This module provides validation functions for sandbox-related operations
+such as package name validation.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+import re
+
+_PACKAGE_SPEC_PATTERN = re.compile(
+    r"^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?"
+    r"(?:\[[A-Za-z0-9._-]+(?:,[A-Za-z0-9._-]+)*\])?"
+    r"(?:"
+    r"(?:==|!=|<=|>=|~=|<|>)[0-9][A-Za-z0-9.*+!_-]*"
+    r"(?:,(?:==|!=|<=|>=|~=|<|>)[0-9][A-Za-z0-9.*+!_-]*)*"
+    r")?$"
+)
+
+
+def validate_package_name(package: str) -> bool:
+    """Validate package name/specifier format for pip install.
+
+    Allows standard pip formats: package, package==version, package[extra].
+
+    Args:
+        package: Package name or specifier to validate.
+
+    Returns:
+        True if package name is valid, False otherwise.
+    """
+    if not package:
+        return False
+
+    return bool(_PACKAGE_SPEC_PATTERN.fullmatch(package))
+
+
+def validate_package_names(packages: list[str]) -> None:
+    """Validate all package names in a list.
+
+    Args:
+        packages: List of package names or specifiers to validate.
+
+    Raises:
+        ValueError: If any package name is invalid.
+    """
+    for pkg in packages:
+        if not validate_package_name(pkg):
+            raise ValueError(f"Invalid package name format: {pkg}")

aip_agents/sandbox/validation.pyi

@@ -0,0 +1,20 @@
+def validate_package_name(package: str) -> bool:
+    """Validate package name/specifier format for pip install.
+
+    Allows standard pip formats: package, package==version, package[extra].
+
+    Args:
+        package: Package name or specifier to validate.
+
+    Returns:
+        True if package name is valid, False otherwise.
+    """
+def validate_package_names(packages: list[str]) -> None:
+    """Validate all package names in a list.
+
+    Args:
+        packages: List of package names or specifiers to validate.
+
+    Raises:
+        ValueError: If any package name is invalid.
+    """

aip_agents/tools/__init__.py

@@ -46,8 +46,10 @@ _register_optional("aip_agents.tools.code_sandbox", "E2BCodeSandboxTool")
 _register_optional("aip_agents.tools.document_loader", "DocxReaderTool")
 _register_optional("aip_agents.tools.document_loader", "ExcelReaderTool")
 _register_optional("aip_agents.tools.document_loader", "PDFReaderTool")
+_register_optional("aip_agents.tools.execute_ptc_code", "create_execute_ptc_code_tool")
 
 if TYPE_CHECKING:
     from aip_agents.tools.browser_use import BrowserUseTool
     from aip_agents.tools.code_sandbox import E2BCodeSandboxTool
     from aip_agents.tools.document_loader import DocxReaderTool, ExcelReaderTool, PDFReaderTool
+    from aip_agents.tools.execute_ptc_code import create_execute_ptc_code_tool

aip_agents/tools/__init__.pyi

@@ -1,9 +1,10 @@
 from aip_agents.tools.browser_use import BrowserUseTool as BrowserUseTool
 from aip_agents.tools.code_sandbox import E2BCodeSandboxTool as E2BCodeSandboxTool
 from aip_agents.tools.document_loader import DocxReaderTool as DocxReaderTool, ExcelReaderTool as ExcelReaderTool, PDFReaderTool as PDFReaderTool
+from aip_agents.tools.execute_ptc_code import create_execute_ptc_code_tool as create_execute_ptc_code_tool
 from aip_agents.tools.gl_connector import GLConnectorTool as GLConnectorTool
 from aip_agents.tools.gl_connector_tools import BOSA_AUTOMATED_TOOLS as BOSA_AUTOMATED_TOOLS, GL_CONNECTORS_AUTOMATED_TOOLS as GL_CONNECTORS_AUTOMATED_TOOLS
 from aip_agents.tools.time_tool import TimeTool as TimeTool
 from aip_agents.tools.web_search import GoogleSerperTool as GoogleSerperTool
 
-__all__ = ['BOSA_AUTOMATED_TOOLS', 'GL_CONNECTORS_AUTOMATED_TOOLS', 'GLConnectorTool', 'GoogleSerperTool', 'TimeTool', 'BrowserUseTool', 'E2BCodeSandboxTool', 'DocxReaderTool', 'ExcelReaderTool', 'PDFReaderTool']
+__all__ = ['BOSA_AUTOMATED_TOOLS', 'GL_CONNECTORS_AUTOMATED_TOOLS', 'GLConnectorTool', 'GoogleSerperTool', 'TimeTool', 'BrowserUseTool', 'E2BCodeSandboxTool', 'DocxReaderTool', 'ExcelReaderTool', 'PDFReaderTool', 'create_execute_ptc_code_tool']

aip_agents/tools/browser_use/browser_use_tool.py

@@ -93,6 +93,7 @@ References:
 """
 
 import asyncio
+import copy
 import json
 from collections.abc import Callable
 from typing import Any, Literal
@@ -556,13 +557,20 @@ class BrowserUseTool(BaseTool):
             iframe_event = yield_iframe_activity(streaming_state.debug_url, "Receive streaming URL")
             self._log_stream_event("iframe_start", iframe_event)
             yield iframe_event
+            last_done_event: dict | None = None
             async for event in self._stream_agent_with_markers(agent, streaming_state, recorder):
                 self._log_stream_event("agent_event", event)
+                tool_info = event.get("tool_info") if isinstance(event, dict) else None
+                tool_calls = tool_info.get("tool_calls", []) if isinstance(tool_info, dict) else []
+                if any(call.get("name") == "done" for call in tool_calls if isinstance(call, dict)):
+                    last_done_event = event
                 yield event
             recording_event = self._recording_event(streaming_state)
             if recording_event:
                 self._log_stream_event("recording_event", recording_event)
                 yield recording_event
+                if last_done_event:
+                    yield copy.deepcopy(last_done_event)
         finally:
             await self._release_session(session, client)
 

aip_agents/tools/browser_use/streaming.py

@@ -223,6 +223,8 @@ def create_step_response(
     if is_done:
         final_tool = _get_done_tool_for_final_response(agent, tool_calls_dict)
         final_output = final_tool.get("output") or TASK_COMPLETED_MESSAGE
+        if not any(call.get("name") == "done" for call in tool_calls_dict):
+            tool_calls_dict.append(final_tool)
         tool_info = {
             "name": PRIMARY_TOOL_NAME,
             "args": final_tool.get("args", {}),

aip_agents/tools/execute_ptc_code.py

@@ -0,0 +1,305 @@
+"""Execute PTC Code Tool.
+
+This module provides a LangChain tool for executing Python code with MCP tool access
+inside an E2B sandbox. The tool is designed for LLM-generated code that needs to call
+multiple MCP tools programmatically.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+import asyncio
+import concurrent.futures
+import json
+from typing import TYPE_CHECKING, Any
+
+from langchain_core.callbacks import (
+    AsyncCallbackManagerForToolRun,
+    CallbackManagerForToolRun,
+)
+from langchain_core.tools import BaseTool
+
+from aip_agents.ptc.naming import sanitize_function_name
+from aip_agents.tools.tool_config_injector import TOOL_CONFIGS_KEY
+from aip_agents.utils.logger import get_logger
+
+if TYPE_CHECKING:
+    from aip_agents.mcp.client.base_mcp_client import BaseMCPClient
+    from aip_agents.ptc.executor import PTCSandboxConfig, PTCSandboxExecutor
+    from aip_agents.sandbox.e2b_runtime import E2BSandboxRuntime
+
+logger = get_logger(__name__)
+
+
+def _merge_config_layer(
+    merged: dict[str, dict[str, Any]],
+    source: dict[str, Any],
+    skip_tool_configs_key: bool = True,
+) -> None:
+    """Merge a single layer of tool configs into the merged dict.
+
+    Args:
+        merged: Target dict to merge into (modified in place).
+        source: Source dict containing tool configs.
+        skip_tool_configs_key: Whether to skip the TOOL_CONFIGS_KEY entry.
+    """
+    for name, config in source.items():
+        if skip_tool_configs_key and name == TOOL_CONFIGS_KEY:
+            continue
+        if not isinstance(config, dict):
+            continue
+
+        sanitized = sanitize_function_name(name)
+        if sanitized in merged:
+            merged[sanitized].update(config)
+        else:
+            merged[sanitized] = dict(config)
+
+
+def merge_tool_configs(
+    agent_configs: dict[str, Any] | None,
+    runtime_configs: dict[str, Any] | None,
+) -> dict[str, dict[str, Any]]:
+    """Merge agent-level and runtime tool configs with sanitized keys.
+
+    Merges tool configurations from two sources:
+    1. Agent-level defaults (from agent.tool_configs)
+    2. Runtime overrides (from RunnableConfig.metadata["tool_configs"])
+
+    Both sources support two formats (matching LangGraphReactAgent behavior):
+    - Direct per-tool keys: {"time_tool": {"timezone": "UTC"}}
+    - Nested structure: {"tool_configs": {"time_tool": {"timezone": "UTC"}}}
+
+    The nested "tool_configs" key has higher precedence than direct keys.
+    Tool names are sanitized to match sandbox expectations (e.g., "Time Tool" -> "time_tool").
+
+    Args:
+        agent_configs: Agent-level tool configs (may be None or contain nested dicts)
+        runtime_configs: Runtime overrides from metadata (may be None)
+
+    Returns:
+        Merged dict with sanitized tool names as keys and config dicts as values.
+        Only includes entries that are dicts (non-dict values are agent-wide defaults).
+    """
+    merged: dict[str, dict[str, Any]] = {}
+
+    # Layer 1: Agent-level per-tool configs (direct keys)
+    if agent_configs:
+        _merge_config_layer(merged, agent_configs, skip_tool_configs_key=True)
+
+    # Layer 2: Agent-level per-tool configs (nested tool_configs key)
+    if agent_configs:
+        nested_agent = agent_configs.get(TOOL_CONFIGS_KEY)
+        if isinstance(nested_agent, dict):
+            _merge_config_layer(merged, nested_agent, skip_tool_configs_key=False)
+
+    # Layer 3: Runtime per-tool configs (direct keys, override agent defaults)
+    if runtime_configs:
+        _merge_config_layer(merged, runtime_configs, skip_tool_configs_key=True)
+
+    # Layer 4: Runtime per-tool configs (nested tool_configs key, highest precedence)
+    if runtime_configs:
+        nested_runtime = runtime_configs.get(TOOL_CONFIGS_KEY)
+        if isinstance(nested_runtime, dict):
+            _merge_config_layer(merged, nested_runtime, skip_tool_configs_key=False)
+
+    return merged
+
+
+class PTCCodeTool(BaseTool):
+    """Tool for executing Python code with MCP tool access in a sandbox.
+
+    This tool uses BaseTool to properly access runtime config via run_manager.metadata.
+    The config parameter is NOT exposed to the LLM schema - it's extracted from
+    the callback manager during execution.
+    """
+
+    name: str = "execute_ptc_code"
+    description: str = (
+        "Execute Python code that can call MCP tools programmatically. "
+        "Import tools from the generated `tools` package (e.g., `from tools.yfinance import get_stock`) "
+        "and run normal Python code. Use print() to output results. "
+        "Returns JSON with ok, stdout, stderr, and exit_code keys. "
+        "This tool is useful for chaining multiple MCP tool calls with local data processing."
+    )
+
+    # Internal attributes (not exposed to LLM)
+    _ptc_executor: "PTCSandboxExecutor" = None  # type: ignore[assignment]
+    _ptc_runtime: "E2BSandboxRuntime" = None  # type: ignore[assignment]
+    _agent_tool_configs: dict[str, Any] | None = None
+
+    def __init__(
+        self,
+        executor: "PTCSandboxExecutor",
+        runtime: "E2BSandboxRuntime",
+        agent_tool_configs: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize the PTC code tool.
+
+        Args:
+            executor: The PTC sandbox executor.
+            runtime: The E2B sandbox runtime.
+            agent_tool_configs: Optional agent-level tool configs.
+            **kwargs: Additional keyword arguments passed to BaseTool.
+        """
+        super().__init__(**kwargs)
+        # Store as private attributes to avoid Pydantic field issues
+        object.__setattr__(self, "_ptc_executor", executor)
+        object.__setattr__(self, "_ptc_runtime", runtime)
+        object.__setattr__(self, "_agent_tool_configs", agent_tool_configs)
+
+    @property
+    def args(self) -> dict[str, Any]:
+        """Return the argument schema for the tool."""
+        return {
+            "code": {
+                "type": "string",
+                "description": (
+                    "Python code to execute. Import MCP tools from the generated `tools` package, "
+                    "for example: `from tools.yfinance import get_stock_history`. "
+                    "The code runs in a sandboxed environment with access to all configured MCP tools. "
+                    "Use print() to output results. The tool returns JSON with keys: "
+                    "ok, stdout, stderr, exit_code."
+                ),
+            }
+        }
+
+    def _run(
+        self,
+        code: str,
+        run_manager: CallbackManagerForToolRun | None = None,
+    ) -> str:
+        """Execute code synchronously (wraps async version)."""
+        # Extract runtime metadata from run_manager
+        runtime_metadata = None
+        if run_manager and hasattr(run_manager, "metadata"):
+            runtime_metadata = run_manager.metadata
+
+        # Run async version in sync context
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.run(self._execute(code, runtime_metadata))
+
+        # Already in async context - run in thread
+        def run_in_new_loop() -> str:
+            new_loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(new_loop)
+            try:
+                return new_loop.run_until_complete(self._execute(code, runtime_metadata))
+            finally:
+                new_loop.close()
+
+        with concurrent.futures.ThreadPoolExecutor() as executor_service:
+            future = executor_service.submit(run_in_new_loop)
+            return future.result()
+
+    async def _arun(
+        self,
+        code: str,
+        run_manager: AsyncCallbackManagerForToolRun | None = None,
+    ) -> str:
+        """Execute code asynchronously."""
+        # Extract runtime metadata from run_manager
+        runtime_metadata = None
+        if run_manager and hasattr(run_manager, "metadata"):
+            runtime_metadata = run_manager.metadata
+
+        return await self._execute(code, runtime_metadata)
+
+    async def _execute(
+        self,
+        code: str,
+        runtime_metadata: dict[str, Any] | None,
+    ) -> str:
+        """Internal execution logic."""
+        try:
+            logger.info("Executing PTC code in sandbox")
+            result = await self._ptc_executor.execute_code(code)
+
+            if result.exit_code == 0:
+                logger.info("PTC code execution completed successfully")
+                payload = {
+                    "ok": True,
+                    "stdout": result.stdout,
+                    "stderr": "",
+                    "exit_code": 0,
+                }
+                return json.dumps(payload)
+
+            logger.warning(f"PTC code execution failed with exit code {result.exit_code}")
+            payload = {
+                "ok": False,
+                "stdout": result.stdout,
+                "stderr": result.stderr,
+                "exit_code": result.exit_code,
+            }
+            return json.dumps(payload)
+
+        except Exception as e:
+            logger.error(f"PTC code execution failed: {e}")
+            payload = {
+                "ok": False,
+                "stdout": "",
+                "stderr": f"Execution failed: {type(e).__name__}: {e}",
+                "exit_code": 1,
+            }
+            return json.dumps(payload)
+
+    async def cleanup(self) -> None:
+        """Clean up the sandbox runtime."""
+        await self._ptc_runtime.cleanup()
+
+
+def create_execute_ptc_code_tool(
+    mcp_client: "BaseMCPClient | None",
+    config: "PTCSandboxConfig | None" = None,  # noqa: F821
+    agent_tool_configs: dict[str, Any] | None = None,
+) -> PTCCodeTool:
+    r"""Create a tool that executes Python code with MCP tool access.
+
+    The code runs inside an E2B sandbox with access to generated MCP tool modules.
+    This tool is designed for LLM-generated code that needs to call multiple tools
+    programmatically in a single execution.
+
+    Args:
+        mcp_client: The MCP client with configured servers.
+        config: Optional sandbox executor configuration.
+        agent_tool_configs: Optional agent-level tool configs (from agent.tool_configs).
+            These are merged with runtime overrides from RunnableConfig.metadata.
+
+    Returns:
+        PTCCodeTool configured for PTC code execution.
+
+    Example:
+        ```python
+        from aip_agents.mcp.client import LangchainMCPClient
+        from aip_agents.tools.execute_ptc_code import create_execute_ptc_code_tool
+
+        mcp_client = LangchainMCPClient()
+        await mcp_client.add_server("yfinance", {...})
+
+        tool = create_execute_ptc_code_tool(mcp_client)
+        result = await tool.ainvoke({"code": "from tools.yfinance import get_stock\\nprint(get_stock('AAPL'))"})
+        ```
+    """
+    # Import here to avoid circular dependencies and allow lazy loading
+    from aip_agents.ptc.executor import PTCSandboxConfig, PTCSandboxExecutor
+    from aip_agents.sandbox.e2b_runtime import E2BSandboxRuntime
+
+    # Use provided config or create default
+    sandbox_config = config or PTCSandboxConfig()
+
+    # Create runtime and executor
+    runtime = E2BSandboxRuntime(
+        template=sandbox_config.sandbox_template,
+        ptc_packages=sandbox_config.ptc_packages,
+    )
+    executor = PTCSandboxExecutor(mcp_client, runtime, sandbox_config)
+
+    return PTCCodeTool(
+        executor=executor,
+        runtime=runtime,
+        agent_tool_configs=agent_tool_configs,
+    )