aip-agents-binary 0.6.5__py3-none-macosx_13_0_arm64.whl → 0.6.6__py3-none-macosx_13_0_arm64.whl

aip_agents/agent/langgraph_react_agent.py

@@ -2723,12 +2723,35 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
         # Attempt to sync PTC tool if MCP client is available
         self._sync_ptc_tool()
 
+    def _enrich_custom_tool_metadata(self) -> None:
+        """Enrich custom tool definitions with metadata from agent's tools.
+
+        This method matches custom tool definitions in ptc_config with actual tool
+        objects from self.tools and enriches them with description and input_schema.
+        Called at PTC sync time to ensure tool definitions have accurate metadata.
+
+        The matching is done by comparing tool names (both original and sanitized).
+
+        Note: This method modifies self._ptc_config.custom_tools.tools in-place.
+        """
+        if not self._ptc_config:
+            return
+
+        # Lazy import to avoid circular dependencies
+        from aip_agents.ptc import enrich_custom_tools_from_agent
+
+        enrich_custom_tools_from_agent(
+            self._ptc_config.custom_tools,
+            self.tools,
+            agent_name=self.name,
+        )
+
     def _sync_ptc_tool(self) -> None:
-        """Build and register the execute_ptc_code tool when MCP servers are available.
+        """Build and register the execute_ptc_code tool when MCP or custom tools are available.
 
         This method is called after enable_ptc() and after MCP servers are added.
         It creates the execute_ptc_code tool using the current MCP client
-        configuration and adds it to the agent's resolved tools.
+        configuration and/or custom tools config and adds it to the agent's resolved tools.
 
         The tool is only created once. Subsequent calls are no-ops if the tool
         has already been synced.
@@ -2739,27 +2762,40 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
         if self._ptc_tool_synced:
             return
 
-        # Check if we have MCP servers configured
-        if not self.mcp_config:
-            logger.debug(f"Agent '{self.name}': PTC tool sync deferred - no MCP servers configured")
-            return
+        # Check if we have custom tools enabled
+        has_custom_tools = self._ptc_config.custom_tools.enabled and self._ptc_config.custom_tools.tools
+        has_mcp_servers = bool(self.mcp_config)
 
-        if not self.mcp_client:
-            logger.debug(f"Agent '{self.name}': PTC tool sync deferred - no MCP client yet")
-            return
+        if has_mcp_servers:
+            if not self.mcp_client:
+                logger.debug(f"Agent '{self.name}': PTC tool sync deferred - no MCP client yet")
+                return
 
-        if not self.mcp_client.is_initialized:
-            logger.debug(f"Agent '{self.name}': PTC tool sync deferred - MCP client not initialized")
+            if not self.mcp_client.is_initialized:
+                logger.debug(f"Agent '{self.name}': PTC tool sync deferred - MCP client not initialized")
+                return
+
+            mcp_client_to_use = self.mcp_client
+        elif has_custom_tools:
+            mcp_client_to_use = None
+        else:
             return
 
+        # Enrich custom tool definitions with metadata from actual tool objects
+        if has_custom_tools:
+            self._enrich_custom_tool_metadata()
+
         # Lazy import to avoid circular dependencies
         from aip_agents.tools.execute_ptc_code import create_execute_ptc_code_tool
 
-        logger.info(f"Agent '{self.name}': Syncing PTC tool with MCP client")
+        if has_custom_tools and not mcp_client_to_use:
+            logger.info(f"Agent '{self.name}': Syncing PTC tool with custom tools only (no MCP)")
+        else:
+            logger.info(f"Agent '{self.name}': Syncing PTC tool with MCP client")
 
         # Create the execute_ptc_code tool with agent's tool configs
         self._ptc_tool = create_execute_ptc_code_tool(
-            self.mcp_client, self._ptc_config, agent_tool_configs=self.tool_configs
+            mcp_client_to_use, self._ptc_config, agent_tool_configs=self.tool_configs
         )
 
         # Rebuild graph to include PTC tool
@@ -2776,28 +2812,39 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
 
         This method builds and injects a PTC usage block into the agent's
         instruction when PTC is enabled. The prompt is refreshed when MCP
-        configuration changes (detected via hash).
+        or custom tools configuration changes (detected via hash).
         """
         if not self._ptc_config or not self._ptc_config.enabled:
             return
 
-        if not self.mcp_client:
+        # Check if we have custom tools enabled
+        has_custom_tools = self._ptc_config.custom_tools.enabled and self._ptc_config.custom_tools.tools
+
+        # For custom-only configs, allow None mcp_client
+        # For MCP-only or MCP+custom, require mcp_client
+        if not has_custom_tools and not self.mcp_client:
             return
 
         # Lazy import to avoid circular dependencies
         from aip_agents.ptc.prompt_builder import build_ptc_prompt, compute_ptc_prompt_hash
 
-        # Get prompt config from PTC sandbox config
+        # Get prompt config and custom tools config from PTC sandbox config
         prompt_config = self._ptc_config.prompt if self._ptc_config else None
+        custom_tools_config = self._ptc_config.custom_tools if self._ptc_config else None
 
-        # Check if MCP config has changed
-        current_hash = compute_ptc_prompt_hash(self.mcp_client, config=prompt_config)
+        # Use mcp_client if available, None for custom-only
+        mcp_client_to_use = self.mcp_client if self.mcp_client else None
+
+        # Check if MCP or custom tools config has changed
+        current_hash = compute_ptc_prompt_hash(
+            mcp_client_to_use, config=prompt_config, custom_tools_config=custom_tools_config
+        )
         if current_hash == self._ptc_prompt_hash:
             logger.debug(f"Agent '{self.name}': PTC prompt unchanged, skipping refresh")
             return
 
         # Build and inject the prompt
-        ptc_prompt = build_ptc_prompt(self.mcp_client, config=prompt_config)
+        ptc_prompt = build_ptc_prompt(mcp_client_to_use, config=prompt_config, custom_tools_config=custom_tools_config)
 
         # Rebuild instruction from original + PTC guidance
         self.instruction = f"{self._original_instruction}\n\n{ptc_prompt}"

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/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/ptc/__init__.py

@@ -1,22 +1,61 @@
-"""PTC (Programmatic Tool Calling) core module (MCP-only).
+"""PTC (Programmatic Tool Calling) core module.
 
-This module provides the core PTC functionality for MCP tools, including
-executor, prompt builder, and sandbox bridge.
+This module provides core PTC functionality, including executor, prompt builder,
+sandbox bridge, and custom tool configuration validation.
 
 Authors:
     Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
 """
 
+from aip_agents.ptc.custom_tools import (
+    PTCCustomToolConfig,
+    PTCCustomToolValidationError,
+    PTCFileToolDef,
+    PTCPackageToolDef,
+    PTCToolDef,
+    enrich_tool_def_with_metadata,
+    extract_tool_metadata,
+    validate_custom_tool_config,
+)
+from aip_agents.ptc.custom_tools_payload import (
+    CustomToolPayloadResult,
+    build_custom_tools_payload,
+)
 from aip_agents.ptc.exceptions import PTCError, PTCToolError
 from aip_agents.ptc.prompt_builder import PromptConfig, build_ptc_prompt, compute_ptc_prompt_hash
+from aip_agents.ptc.tool_def_helpers import file_tool, package_tool
+from aip_agents.ptc.tool_enrichment import (
+    build_tool_lookup,
+    enrich_custom_tools_from_agent,
+    match_tool_by_name,
+)
 
 __all__ = [
     # Exceptions
     "PTCError",
     "PTCToolError",
+    "PTCCustomToolValidationError",
     # Executor
     "PTCSandboxConfig",
     "PTCSandboxExecutor",
+    # Custom tools
+    "PTCCustomToolConfig",
+    "PTCToolDef",
+    "PTCPackageToolDef",
+    "PTCFileToolDef",
+    "validate_custom_tool_config",
+    "extract_tool_metadata",
+    "enrich_tool_def_with_metadata",
+    # Tool enrichment
+    "build_tool_lookup",
+    "match_tool_by_name",
+    "enrich_custom_tools_from_agent",
+    # Tool definition helpers
+    "package_tool",
+    "file_tool",
+    # Custom tools payload
+    "CustomToolPayloadResult",
+    "build_custom_tools_payload",
     # Prompt builder
     "PromptConfig",
     "build_ptc_prompt",

aip_agents/ptc/__init__.pyi

@@ -1,7 +1,11 @@
+from aip_agents.ptc.custom_tools import PTCCustomToolConfig as PTCCustomToolConfig, PTCCustomToolValidationError as PTCCustomToolValidationError, PTCFileToolDef as PTCFileToolDef, PTCPackageToolDef as PTCPackageToolDef, PTCToolDef as PTCToolDef, enrich_tool_def_with_metadata as enrich_tool_def_with_metadata, extract_tool_metadata as extract_tool_metadata, validate_custom_tool_config as validate_custom_tool_config
+from aip_agents.ptc.custom_tools_payload import CustomToolPayloadResult as CustomToolPayloadResult, build_custom_tools_payload as build_custom_tools_payload
 from aip_agents.ptc.exceptions import PTCError as PTCError, PTCToolError as PTCToolError
 from aip_agents.ptc.prompt_builder import PromptConfig as PromptConfig, build_ptc_prompt as build_ptc_prompt, compute_ptc_prompt_hash as compute_ptc_prompt_hash
+from aip_agents.ptc.tool_def_helpers import file_tool as file_tool, package_tool as package_tool
+from aip_agents.ptc.tool_enrichment import build_tool_lookup as build_tool_lookup, enrich_custom_tools_from_agent as enrich_custom_tools_from_agent, match_tool_by_name as match_tool_by_name
 
-__all__ = ['PTCError', 'PTCToolError', 'PTCSandboxConfig', 'PTCSandboxExecutor', 'PromptConfig', 'build_ptc_prompt', 'compute_ptc_prompt_hash', 'build_sandbox_payload', 'wrap_ptc_code']
+__all__ = ['PTCError', 'PTCToolError', 'PTCCustomToolValidationError', 'PTCSandboxConfig', 'PTCSandboxExecutor', 'PTCCustomToolConfig', 'PTCToolDef', 'PTCPackageToolDef', 'PTCFileToolDef', 'validate_custom_tool_config', 'extract_tool_metadata', 'enrich_tool_def_with_metadata', 'build_tool_lookup', 'match_tool_by_name', 'enrich_custom_tools_from_agent', 'package_tool', 'file_tool', 'CustomToolPayloadResult', 'build_custom_tools_payload', 'PromptConfig', 'build_ptc_prompt', 'compute_ptc_prompt_hash', 'build_sandbox_payload', 'wrap_ptc_code']
 
 # Names in __all__ with no definition:
 #   PTCSandboxConfig