aip-agents-binary 0.5.25__py3-none-macosx_13_0_arm64.whl → 0.6.8__py3-none-macosx_13_0_arm64.whl

aip_agents/examples/hello_world_ptc_custom_tools.py

@@ -0,0 +1,83 @@
+"""Minimal PTC hello world example with custom tools.
+
+Author: Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+
+Required environment variables:
+- OPENAI_API_KEY
+- E2B_API_KEY
+"""
+
+import asyncio
+import json
+from pathlib import Path
+
+from langchain_openai import ChatOpenAI
+
+from aip_agents.agent import LangGraphReactAgent
+from aip_agents.examples.tools.multiply_tool import MultiplyTool
+from aip_agents.ptc import PromptConfig, PTCCustomToolConfig, PTCSandboxConfig, file_tool, package_tool
+from aip_agents.tools.time_tool import TimeTool
+
+
+async def main() -> None:
+    """Run a hello-world PTC flow with custom tools."""
+    repo_root = Path.cwd()
+    multiply_tool_path = repo_root / "aip_agents/examples/tools/multiply_tool.py"
+
+    instruction = (
+        "You are a helpful assistant with access to execute_ptc_code. "
+        "Use execute_ptc_code to run Python and print output. "
+        "Custom tools are available under tools.custom (import with "
+        "'from tools.custom import <tool_name>')."
+    )
+
+    agent = LangGraphReactAgent(
+        name="ptc_custom_tools_hello_world",
+        instruction=instruction,
+        model=ChatOpenAI(model="gpt-5.2"),
+        tools=[TimeTool(), MultiplyTool()],
+        tool_configs={"multiply": {"offset": 20}},
+        ptc_config=PTCSandboxConfig(
+            enabled=True,
+            sandbox_timeout=180.0,
+            prompt=PromptConfig(mode="auto"),
+            custom_tools=PTCCustomToolConfig(
+                enabled=True,
+                bundle_roots=[str(repo_root)],
+                requirements=[],
+                tools=[
+                    package_tool(
+                        "time_tool",
+                        import_path="aip_agents.tools.time_tool",
+                        class_name="TimeTool",
+                    ),
+                    file_tool(
+                        "multiply",
+                        file_path=str(multiply_tool_path),
+                        class_name="MultiplyTool",
+                    ),
+                ],
+            ),
+        ),
+    )
+
+    try:
+        # Pass tool config at runtime via metadata
+        # The multiply tool will use offset=10, so multiply(a=6, b=7) returns 6*7+10=52
+        print("execute_ptc_code output: ", end="")
+        last_chunk = None
+        async for chunk in agent.arun_sse_stream(
+            query=("Use execute_ptc_code to import from tools.custom. Print time_tool() and multiply(a=6, b=7)."),
+            metadata={"tool_configs": {"multiply": {"offset": 10}}},
+        ):
+            last_chunk = chunk
+            print(json.dumps(chunk))
+            print("-" * 20)
+    finally:
+        await agent.cleanup()
+
+    print("execute_ptc_code output: ", last_chunk["content"])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

aip_agents/examples/hello_world_ptc_custom_tools.pyi

@@ -0,0 +1,7 @@
+from aip_agents.agent import LangGraphReactAgent as LangGraphReactAgent
+from aip_agents.examples.tools.multiply_tool import MultiplyTool as MultiplyTool
+from aip_agents.ptc import PTCCustomToolConfig as PTCCustomToolConfig, PTCSandboxConfig as PTCSandboxConfig, PromptConfig as PromptConfig, file_tool as file_tool, package_tool as package_tool
+from aip_agents.tools.time_tool import TimeTool as TimeTool
+
+async def main() -> None:
+    """Run a hello-world PTC flow with custom tools."""

aip_agents/examples/hello_world_tool_output_client.py

@@ -39,6 +39,15 @@ async def main():
             print(chunk["content"], end="", flush=True)
         if chunk.get("metadata"):
             print(f"\nMetadata: {chunk['metadata']}", end="\n\n", flush=True)
+        tool_info = chunk.get("metadata", {}).get("tool_info") if isinstance(chunk.get("metadata"), dict) else None
+        if isinstance(tool_info, dict):
+            for tool_call in tool_info.get("tool_calls", []):
+                if tool_call.get("name") == "data_visualizer":
+                    data_source = tool_call.get("args", {}).get("data_source")
+                    if not (isinstance(data_source, str) and data_source.startswith("$tool_output.")):
+                        raise RuntimeError(
+                            "Tool output sharing failed: expected data_source to reference $tool_output.<call_id>."
+                        )
     print("\n")
 
 

aip_agents/examples/tools/multiply_tool.py

@@ -0,0 +1,43 @@
+"""Tool to multiply two integers.
+
+Author: Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field
+
+
+class MultiplyToolInput(BaseModel):
+    """Input schema for the MultiplyTool."""
+
+    a: int = Field(..., description="First factor.")
+    b: int = Field(..., description="Second factor.")
+
+
+class MultiplyToolConfig(BaseModel):
+    """Configuration for MultiplyTool."""
+
+    offset: int = Field(default=0, description="Offset to add to the result.")
+
+
+class MultiplyTool(BaseTool):
+    """Tool to multiply two integers."""
+
+    name: str = "multiply"
+    description: str = "Multiply two integers."
+    args_schema: type[BaseModel] = MultiplyToolInput
+    tool_config_schema: type[BaseModel] = MultiplyToolConfig
+
+    def _run(self, a: int, b: int) -> int:
+        """Return the product of two integers."""
+        offset = 0
+        if hasattr(self, "get_tool_config"):
+            config = self.get_tool_config()
+            if config:
+                offset = getattr(config, "offset", 0)
+
+        return a * b + offset
+
+    async def _arun(self, a: int, b: int) -> int:
+        """Return the product of two integers asynchronously."""
+        return self._run(a=a, b=b)

aip_agents/examples/tools/multiply_tool.pyi

@@ -0,0 +1,18 @@
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel
+
+class MultiplyToolInput(BaseModel):
+    """Input schema for the MultiplyTool."""
+    a: int
+    b: int
+
+class MultiplyToolConfig(BaseModel):
+    """Configuration for MultiplyTool."""
+    offset: int
+
+class MultiplyTool(BaseTool):
+    """Tool to multiply two integers."""
+    name: str
+    description: str
+    args_schema: type[BaseModel]
+    tool_config_schema: type[BaseModel]

aip_agents/guardrails/engines/base.py

@@ -39,7 +39,7 @@ class GuardrailEngine(Protocol):
         Returns:
             GuardrailResult indicating if content is safe
         """
-        ...
+        ...  # pragma: no cover
 
     @abstractmethod
     async def check_output(self, content: str) -> GuardrailResult:
@@ -51,12 +51,12 @@ class GuardrailEngine(Protocol):
         Returns:
             GuardrailResult indicating if content is safe
         """
-        ...
+        ...  # pragma: no cover
 
     @abstractmethod
     def model_dump(self) -> dict:
         """Serialize engine configuration into a JSON-compatible dictionary."""
-        ...
+        ...  # pragma: no cover
 
 
 class BaseGuardrailEngine(ABC):
@@ -77,14 +77,14 @@ class BaseGuardrailEngine(ABC):
     @abstractmethod
     async def check_input(self, content: str) -> GuardrailResult:
         """Check user input content for safety violations."""
-        ...
+        ...  # pragma: no cover
 
     @abstractmethod
     async def check_output(self, content: str) -> GuardrailResult:
         """Check AI output content for safety violations."""
-        ...
+        ...  # pragma: no cover
 
     @abstractmethod
     def model_dump(self) -> dict:
         """Serialize engine configuration into a JSON-compatible dictionary."""
-        ...
+        ...  # pragma: no cover

aip_agents/mcp/client/__init__.py

@@ -7,8 +7,44 @@ Authors:
     Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
 """
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
 from aip_agents.mcp.client.base_mcp_client import BaseMCPClient
-from aip_agents.mcp.client.google_adk.client import GoogleADKMCPClient
-from aip_agents.mcp.client.langchain.client import LangchainMCPClient
+
+if TYPE_CHECKING:
+    from aip_agents.mcp.client.google_adk.client import GoogleADKMCPClient
+    from aip_agents.mcp.client.langchain.client import LangchainMCPClient
 
 __all__ = ["GoogleADKMCPClient", "LangchainMCPClient", "BaseMCPClient"]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy import of MCP client implementations.
+
+    This avoids importing heavy dependencies (Google ADK, Vertex AI, etc.)
+    when they are not needed.
+
+    Args:
+        name: Attribute name to import.
+
+    Returns:
+        The requested class.
+
+    Raises:
+        AttributeError: If attribute is not found.
+    """
+    if name == "GoogleADKMCPClient":
+        from aip_agents.mcp.client.google_adk.client import (
+            GoogleADKMCPClient as _GoogleADKMCPClient,
+        )
+
+        return _GoogleADKMCPClient
+    elif name == "LangchainMCPClient":
+        from aip_agents.mcp.client.langchain.client import (
+            LangchainMCPClient as _LangchainMCPClient,
+        )
+
+        return _LangchainMCPClient
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

aip_agents/mcp/client/connection_manager.py

@@ -60,6 +60,9 @@ class MCPConnectionManager:
     async def start(self) -> tuple[Any, Any]:
         """Start connection in background task.
 
+        For HTTP/SSE transports, establishes connection directly to avoid anyio context issues.
+        For stdio transport, uses background task to manage subprocess lifecycle.
+
         Returns:
             tuple[Any, Any]: Tuple of (read_stream, write_stream) for ClientSession
 
@@ -67,6 +70,17 @@ class MCPConnectionManager:
             Exception: If connection establishment fails
         """
         logger.debug(f"Starting connection manager for {self.server_name}")
+
+        # Determine transport type first
+        self.transport_type = self._get_transport_type()
+
+        # For HTTP/SSE: connect directly (no background task needed)
+        # This avoids anyio.BrokenResourceError when streams cross task boundaries
+        if self.transport_type in (TransportType.HTTP, TransportType.SSE):
+            await self._establish_connection()
+            return self._connection
+
+        # For stdio: use background task to manage subprocess
         self._task = asyncio.create_task(self._connection_task())
         await self._ready_event.wait()
 
@@ -78,6 +92,20 @@ class MCPConnectionManager:
     async def stop(self) -> None:
         """Stop connection gracefully."""
         logger.debug(f"Stopping connection manager for {self.server_name}")
+
+        # For HTTP/SSE (no background task), just close transport
+        if self.transport_type in (TransportType.HTTP, TransportType.SSE):
+            if self._transport:
+                try:
+                    close_result = self._transport.close()
+                    if inspect.isawaitable(close_result):
+                        await close_result
+                except Exception as exc:
+                    logger.warning(f"Failed to close transport cleanly for {self.server_name}: {exc}")
+            self._connection = None
+            return
+
+        # For stdio (with background task), wait for task to finish
         if self._task and not self._task.done():
             self._stop_event.set()
             try:
@@ -94,6 +122,11 @@ class MCPConnectionManager:
         Returns:
             bool: True if connected, False otherwise
         """
+        # For HTTP/SSE (no background task), just check if connection exists
+        if self.transport_type in (TransportType.HTTP, TransportType.SSE):
+            return self._connection is not None
+
+        # For stdio (with background task), check task status too
         return (
             self._connection is not None
             and self._task is not None
@@ -144,7 +177,9 @@ class MCPConnectionManager:
         Raises:
             ConnectionError: If all connection attempts fail
         """
-        self.transport_type = self._get_transport_type()
+        # transport_type may already be set by start() for HTTP/SSE
+        if not self.transport_type:
+            self.transport_type = self._get_transport_type()
         details = f"URL: {self.config.get('url', 'N/A')}, Command: {self.config.get('command', 'N/A')}"
         logger.info(f"Establishing connection to {self.server_name} via {self.transport_type} ({details})")
 

aip_agents/mcp/client/connection_manager.pyi

@@ -31,6 +31,9 @@ class MCPConnectionManager:
     async def start(self) -> tuple[Any, Any]:
         """Start connection in background task.
 
+        For HTTP/SSE transports, establishes connection directly to avoid anyio context issues.
+        For stdio transport, uses background task to manage subprocess lifecycle.
+
         Returns:
             tuple[Any, Any]: Tuple of (read_stream, write_stream) for ClientSession