aip-agents-binary 0.6.0__py3-none-macosx_13_0_arm64.whl → 0.6.1__py3-none-macosx_13_0_arm64.whl

aip_agents/agent/langgraph_react_agent.py

@@ -87,6 +87,9 @@ from aip_agents.utils.token_usage_helper import (
     extract_token_usage_from_tool_output,
 )
 
+if TYPE_CHECKING:
+    from aip_agents.ptc import PTCSandboxConfig
+
 logger = get_logger(__name__)
 
 # Default instruction for ReAct agents
@@ -165,6 +168,7 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
         middlewares: Sequence[AgentMiddleware] | None = None,
         guardrail: GuardrailManager | None = None,
         step_limit_config: StepLimitConfig | None = None,
+        ptc_config: PTCSandboxConfig | None = None,
         **kwargs: Any,
     ):
         """Initialize the LangGraph ReAct Agent.
@@ -193,6 +197,11 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
                      input/output filtering during agent execution.
             enable_pii: Optional toggle to enable PII handling for tool inputs and outputs.
             step_limit_config: Optional configuration for step limits and delegation depth.
+            ptc_config: Optional configuration for PTC sandbox execution. See PTCSandboxConfig
+                for available options including enabled flag, sandbox timeout, and template settings.
+                PTC is enabled when ptc_config is not None and ptc_config.enabled is True.
+                When enabled, prompt guidance is automatically injected into the agent's instruction.
+                PTC runs in a sandbox only; there is no in-process trusted PTC path.
             **kwargs: Additional keyword arguments passed to BaseLangGraphAgent.
         """
         # Use LangGraph's standard AgentState for ReAct
@@ -239,6 +248,18 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
 
         self.step_limit_config = step_limit_config
 
+        # Initialize PTC state (Programmatic Tool Calling)
+        self._ptc_config: PTCSandboxConfig | None = None
+        self._ptc_tool_synced = False
+        self._ptc_tool: BaseTool | None = None
+        self._ptc_prompt_hash: str = ""
+        # Capture instruction after middleware setup so middleware prompts are preserved
+        self._original_instruction: str = self.instruction
+
+        # Enable PTC if requested via constructor
+        if ptc_config is not None and ptc_config.enabled:
+            self.enable_ptc(ptc_config)
+
     def _setup_middleware(
         self,
         planning: bool,
@@ -425,9 +446,9 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
             )
 
     def _rebuild_resolved_tools(self) -> None:
-        """Rebuild resolved tools including middleware tools.
+        """Rebuild resolved tools including middleware and PTC tools.
 
-        Overrides base class to ensure middleware tools are preserved
+        Overrides base class to ensure middleware tools and the PTC tool are preserved
         when tools are rebuilt (e.g., after update_regular_tools).
         """
         # Call base class to rebuild with regular, a2a, delegation, and mcp tools
@@ -437,6 +458,10 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
         if hasattr(self, "_middleware_tools") and self._middleware_tools:
             self.resolved_tools.extend(self._middleware_tools)
 
+        # Add PTC tool if synced
+        if hasattr(self, "_ptc_tool") and self._ptc_tool is not None:
+            self.resolved_tools.append(self._ptc_tool)
+
     def _handle_tool_artifacts(
         self, tool_output: Any, pending_artifacts: list[dict[str, Any]]
     ) -> tuple[str, list[dict[str, Any]]]:
@@ -2620,6 +2645,173 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
         if current_thread_id:
             self._pii_handlers_by_thread.pop(current_thread_id, None)
 
+    # ==========================================================================
+    # Programmatic Tool Calling (PTC) Methods
+    # ==========================================================================
+
+    def add_mcp_server(self, mcp_config: dict[str, dict[str, Any]]) -> None:
+        """Add MCP servers and refresh PTC tool state if needed."""
+        super().add_mcp_server(mcp_config)
+
+        if not self._ptc_config or not self._ptc_config.enabled:
+            return
+
+        if self._ptc_tool is not None:
+            self._ptc_tool = None
+
+        self._ptc_tool_synced = False
+        logger.debug(f"Agent '{self.name}': PTC tool will resync after MCP changes")
+
+    def enable_ptc(self, config: PTCSandboxConfig | None = None) -> None:
+        """Enable Programmatic Tool Calling (PTC) for this agent.
+
+        PTC allows the LLM to execute Python code that calls MCP tools
+        programmatically inside a sandboxed environment. This is useful for
+        chaining multiple tool calls with local data processing.
+
+        The execute_ptc_code tool is automatically added to the agent's tools
+        after MCP servers are configured. If no MCP servers are configured,
+        the tool sync is deferred until servers are added.
+
+        Args:
+            config: Optional configuration for PTC sandbox execution.
+                See PTCSandboxConfig for options like enabled flag and sandbox_timeout.
+                If None is passed, a default config with enabled=True will be created.
+
+        Example:
+            agent.enable_ptc(PTCSandboxConfig(enabled=True))
+            agent.add_mcp_server({"yfinance": {...}})
+            # execute_ptc_code tool is now available
+
+        Note:
+            PTC can also be enabled via the constructor by passing
+            ptc_config=PTCSandboxConfig(enabled=True, ...).
+        """
+        # Lazy import to avoid circular dependencies
+        from aip_agents.ptc.executor import PTCSandboxConfig
+
+        self._ptc_config = config or PTCSandboxConfig()
+        self._ptc_config.enabled = True
+        self._ptc_tool_synced = False
+
+        logger.info(f"Agent '{self.name}': PTC enabled")
+
+        # Attempt to sync PTC tool if MCP client is available
+        self._sync_ptc_tool()
+
+    def _sync_ptc_tool(self) -> None:
+        """Build and register the execute_ptc_code tool when MCP servers 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.
+
+        The tool is only created once. Subsequent calls are no-ops if the tool
+        has already been synced.
+        """
+        if not self._ptc_config or not self._ptc_config.enabled:
+            return
+
+        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
+
+        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")
+            return
+
+        # 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")
+
+        # 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
+        )
+
+        # Rebuild graph to include PTC tool
+        self._rebuild_graph()
+
+        self._ptc_tool_synced = True
+        logger.info(f"Agent '{self.name}': PTC tool synced successfully")
+
+        # Sync PTC prompt guidance
+        self._sync_ptc_prompt()
+
+    def _sync_ptc_prompt(self) -> None:
+        """Sync PTC usage guidance into the agent instruction.
+
+        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).
+        """
+        if not self._ptc_config or not self._ptc_config.enabled:
+            return
+
+        if 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
+        prompt_config = self._ptc_config.prompt if self._ptc_config else None
+
+        # Check if MCP config has changed
+        current_hash = compute_ptc_prompt_hash(self.mcp_client, config=prompt_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)
+
+        # Rebuild instruction from original + PTC guidance
+        self.instruction = f"{self._original_instruction}\n\n{ptc_prompt}"
+        self._ptc_prompt_hash = current_hash
+
+        logger.info(f"Agent '{self.name}': PTC prompt guidance injected")
+
+    async def _register_mcp_tools(self) -> None:
+        """Override to sync PTC tool after MCP tools are registered.
+
+        This extends the base implementation to ensure the execute_ptc_code
+        tool is added after MCP servers are initialized.
+        """
+        await super()._register_mcp_tools()
+
+        # Sync PTC tool after MCP tools are registered
+        if self._ptc_config and self._ptc_config.enabled and not self._ptc_tool_synced:
+            self._sync_ptc_tool()
+
+    async def cleanup(self) -> None:
+        """Cleanup agent resources including PTC sandbox.
+
+        Extends base cleanup to also cleanup the PTC sandbox runtime if
+        execute_ptc_code tool was created.
+        """
+        # Cleanup PTC tool's sandbox runtime if present
+        if self._ptc_tool is not None:
+            try:
+                cleanup_method = getattr(self._ptc_tool, "cleanup", None)
+                if cleanup_method and callable(cleanup_method):
+                    await cleanup_method()
+                    logger.debug(f"Agent '{self.name}': PTC sandbox cleanup completed")
+            except Exception as e:
+                logger.warning(f"Agent '{self.name}': Error during PTC sandbox cleanup: {e}")
+
+        # Call parent cleanup for MCP client
+        await super().cleanup()
+
     def _format_graph_output(self, final_state_result: dict[str, Any]) -> Any:
         """Convert final graph state to user-friendly output.
 

aip_agents/agent/langgraph_react_agent.pyi

@@ -6,6 +6,7 @@ from aip_agents.guardrails.manager import GuardrailManager as GuardrailManager
 from aip_agents.middleware.base import AgentMiddleware as AgentMiddleware, ModelRequest as ModelRequest
 from aip_agents.middleware.manager import MiddlewareManager as MiddlewareManager
 from aip_agents.middleware.todolist import TodoList as TodoList, TodoListMiddleware as TodoListMiddleware
+from aip_agents.ptc import PTCSandboxConfig as PTCSandboxConfig
 from aip_agents.schema.a2a import A2AStreamEventType as A2AStreamEventType
 from aip_agents.schema.hitl import ApprovalDecision as ApprovalDecision, HitlMetadata as HitlMetadata
 from aip_agents.schema.langgraph import ToolCallResult as ToolCallResult, ToolStorageParams as ToolStorageParams
@@ -86,7 +87,7 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
     """
     tool_output_manager: Incomplete
     step_limit_config: Incomplete
-    def __init__(self, name: str, instruction: str = ..., model: BaseChatModel | str | Any | None = None, tools: Sequence[BaseTool] | None = None, agents: Sequence[Any] | None = None, description: str | None = None, thread_id_key: str = 'thread_id', event_emitter: EventEmitter | None = None, tool_output_manager: ToolOutputManager | None = None, planning: bool = False, middlewares: Sequence[AgentMiddleware] | None = None, guardrail: GuardrailManager | None = None, step_limit_config: StepLimitConfig | None = None, **kwargs: Any) -> None:
+    def __init__(self, name: str, instruction: str = ..., model: BaseChatModel | str | Any | None = None, tools: Sequence[BaseTool] | None = None, agents: Sequence[Any] | None = None, description: str | None = None, thread_id_key: str = 'thread_id', event_emitter: EventEmitter | None = None, tool_output_manager: ToolOutputManager | None = None, planning: bool = False, middlewares: Sequence[AgentMiddleware] | None = None, guardrail: GuardrailManager | None = None, step_limit_config: StepLimitConfig | None = None, ptc_config: PTCSandboxConfig | None = None, **kwargs: Any) -> None:
         """Initialize the LangGraph ReAct Agent.
 
         Args:
@@ -113,6 +114,11 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
                      input/output filtering during agent execution.
             enable_pii: Optional toggle to enable PII handling for tool inputs and outputs.
             step_limit_config: Optional configuration for step limits and delegation depth.
+            ptc_config: Optional configuration for PTC sandbox execution. See PTCSandboxConfig
+                for available options including enabled flag, sandbox timeout, and template settings.
+                PTC is enabled when ptc_config is not None and ptc_config.enabled is True.
+                When enabled, prompt guidance is automatically injected into the agent's instruction.
+                PTC runs in a sandbox only; there is no in-process trusted PTC path.
             **kwargs: Additional keyword arguments passed to BaseLangGraphAgent.
         """
     def define_graph(self, graph_builder: StateGraph) -> CompiledStateGraph:
@@ -124,6 +130,39 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
         Returns:
             Compiled LangGraph ready for execution.
         """
+    def add_mcp_server(self, mcp_config: dict[str, dict[str, Any]]) -> None:
+        """Add MCP servers and refresh PTC tool state if needed."""
+    def enable_ptc(self, config: PTCSandboxConfig | None = None) -> None:
+        '''Enable Programmatic Tool Calling (PTC) for this agent.
+
+        PTC allows the LLM to execute Python code that calls MCP tools
+        programmatically inside a sandboxed environment. This is useful for
+        chaining multiple tool calls with local data processing.
+
+        The execute_ptc_code tool is automatically added to the agent\'s tools
+        after MCP servers are configured. If no MCP servers are configured,
+        the tool sync is deferred until servers are added.
+
+        Args:
+            config: Optional configuration for PTC sandbox execution.
+                See PTCSandboxConfig for options like enabled flag and sandbox_timeout.
+                If None is passed, a default config with enabled=True will be created.
+
+        Example:
+            agent.enable_ptc(PTCSandboxConfig(enabled=True))
+            agent.add_mcp_server({"yfinance": {...}})
+            # execute_ptc_code tool is now available
+
+        Note:
+            PTC can also be enabled via the constructor by passing
+            ptc_config=PTCSandboxConfig(enabled=True, ...).
+        '''
+    async def cleanup(self) -> None:
+        """Cleanup agent resources including PTC sandbox.
+
+        Extends base cleanup to also cleanup the PTC sandbox runtime if
+        execute_ptc_code tool was created.
+        """
 
 class LangGraphAgent(LangGraphReactAgent):
     """Alias for LangGraphReactAgent."""

aip_agents/examples/hello_world_ptc.py

@@ -0,0 +1,51 @@
+"""Minimal PTC hello world example.
+
+Required environment variables:
+- OPENAI_API_KEY
+- E2B_API_KEY
+"""
+
+import asyncio
+
+from langchain_openai import ChatOpenAI
+
+from aip_agents.agent import LangGraphReactAgent
+from aip_agents.ptc import PromptConfig, PTCSandboxConfig
+
+
+async def main() -> None:
+    """Run a hello-world PTC flow."""
+    instruction = (
+        "You are a helpful assistant with access to execute_ptc_code. "
+        "Use execute_ptc_code to run Python and print output. "
+        "The tool returns JSON with ok/stdout/stderr/exit_code."
+    )
+
+    agent = LangGraphReactAgent(
+        name="ptc_hello_world",
+        instruction=instruction,
+        model=ChatOpenAI(model="gpt-5.2"),
+        ptc_config=PTCSandboxConfig(enabled=True, sandbox_timeout=180.0, prompt=PromptConfig(mode="index")),
+    )
+    agent.add_mcp_server(
+        {
+            "deepwiki": {
+                "transport": "streamable-http",
+                "url": "https://mcp.deepwiki.com/mcp",
+                "headers": {},
+                "timeout": 60.0,
+            }
+        }
+    )
+
+    try:
+        response = await agent.arun(
+            query="Use execute_ptc_code to print 'Hello, world!' and count the number of words in the output of deepwiki.read_wiki_structure('anthropics/claude-code')."
+        )
+        print("execute_ptc_code output:", response["output"])
+    finally:
+        await agent.cleanup()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

aip_agents/examples/hello_world_ptc.pyi

@@ -0,0 +1,5 @@
+from aip_agents.agent import LangGraphReactAgent as LangGraphReactAgent
+from aip_agents.ptc import PTCSandboxConfig as PTCSandboxConfig, PromptConfig as PromptConfig
+
+async def main() -> None:
+    """Run a hello-world PTC flow."""

aip_agents/ptc/__init__.py

@@ -0,0 +1,48 @@
+"""PTC (Programmatic Tool Calling) core module (MCP-only).
+
+This module provides the core PTC functionality for MCP tools, including
+executor, prompt builder, and sandbox bridge.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from aip_agents.ptc.exceptions import PTCError, PTCToolError
+from aip_agents.ptc.prompt_builder import PromptConfig, build_ptc_prompt, compute_ptc_prompt_hash
+
+__all__ = [
+    # Exceptions
+    "PTCError",
+    "PTCToolError",
+    # Executor
+    "PTCSandboxConfig",
+    "PTCSandboxExecutor",
+    # Prompt builder
+    "PromptConfig",
+    "build_ptc_prompt",
+    "compute_ptc_prompt_hash",
+    # Sandbox bridge
+    "build_sandbox_payload",
+    "wrap_ptc_code",
+]
+
+
+def __getattr__(name: str):
+    """Lazy import to avoid circular dependencies."""
+    if name == "PTCSandboxConfig":
+        from aip_agents.ptc.executor import PTCSandboxConfig
+
+        return PTCSandboxConfig
+    elif name == "PTCSandboxExecutor":
+        from aip_agents.ptc.executor import PTCSandboxExecutor
+
+        return PTCSandboxExecutor
+    elif name == "build_sandbox_payload":
+        from aip_agents.ptc.sandbox_bridge import build_sandbox_payload
+
+        return build_sandbox_payload
+    elif name == "wrap_ptc_code":
+        from aip_agents.ptc.sandbox_bridge import wrap_ptc_code
+
+        return wrap_ptc_code
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

aip_agents/ptc/__init__.pyi

@@ -0,0 +1,10 @@
+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
+
+__all__ = ['PTCError', 'PTCToolError', 'PTCSandboxConfig', 'PTCSandboxExecutor', 'PromptConfig', 'build_ptc_prompt', 'compute_ptc_prompt_hash', 'build_sandbox_payload', 'wrap_ptc_code']
+
+# Names in __all__ with no definition:
+#   PTCSandboxConfig
+#   PTCSandboxExecutor
+#   build_sandbox_payload
+#   wrap_ptc_code

aip_agents/ptc/doc_gen.py

@@ -0,0 +1,122 @@
+"""Documentation generation utilities for PTC.
+
+Shared constants and helpers for generating tool documentation in sandbox payloads.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from typing import Any
+
+from aip_agents.ptc.naming import sanitize_function_name
+
+# Documentation limits (fixed constants per plan)
+DOC_DESC_LIMIT = 120  # Tool description trim limit
+DOC_PARAM_DESC_LIMIT = 80  # Parameter description trim limit
+
+
+def json_type_to_display(json_type: Any) -> str:
+    """Convert JSON type to display string.
+
+    Args:
+        json_type: JSON schema type.
+
+    Returns:
+        Human-readable type string.
+    """
+    if isinstance(json_type, list):
+        return "any"
+    type_map = {
+        "string": "str",
+        "integer": "int",
+        "number": "float",
+        "boolean": "bool",
+        "array": "list",
+        "object": "dict",
+        "null": "None",
+    }
+    return type_map.get(str(json_type), "any")
+
+
+def trim_text(text: str | None, limit: int) -> str:
+    """Trim text to limit with ellipsis if needed.
+
+    Args:
+        text: Text to trim.
+        limit: Maximum length before trimming.
+
+    Returns:
+        Trimmed text.
+    """
+    if not text:
+        return ""
+    if len(text) > limit:
+        return text[:limit] + "..."
+    return text
+
+
+def render_tool_doc(
+    func_name: str,
+    signature: str,
+    description: str,
+    schema: dict[str, Any],
+    is_stub: bool = False,
+    example_code: str | None = None,
+    example_heading: str = "## Example",
+) -> str:
+    """Render markdown documentation for a tool.
+
+    Args:
+        func_name: Sanitized function name.
+        signature: Full function signature.
+        description: Tool description.
+        schema: Input schema for parameters.
+        is_stub: Whether this is a stub documentation.
+        example_code: Optional example code block content (without ```python).
+        example_heading: Heading for the example section.
+
+    Returns:
+        Markdown documentation string.
+    """
+    if is_stub:
+        desc = "Details unavailable because tool definitions are not loaded yet."
+    else:
+        desc = trim_text(description, DOC_DESC_LIMIT) or "No description available."
+
+    lines = [
+        f"# {func_name}",
+        "",
+        f"**Description:** {desc}",
+        "",
+        f"**Signature:** `{signature}`",
+        "",
+    ]
+
+    # Add parameters section
+    properties = schema.get("properties", {})
+    required = set(schema.get("required", []))
+
+    if properties:
+        lines.append("## Parameters")
+        lines.append("")
+        for prop_name, prop_schema in sorted(properties.items()):
+            safe_param = sanitize_function_name(prop_name)
+            prop_type = json_type_to_display(prop_schema.get("type", "any"))
+            is_required = "required" if prop_name in required else "optional"
+
+            # Trim param description
+            raw_param_desc = prop_schema.get("description", "")
+            param_desc = trim_text(raw_param_desc, DOC_PARAM_DESC_LIMIT)
+
+            lines.append(f"- **{safe_param}** ({prop_type}, {is_required}): {param_desc}")
+        lines.append("")
+
+    # Add example section
+    if example_code:
+        lines.append(example_heading)
+        lines.append("")
+        lines.append("```python")
+        lines.append(example_code)
+        lines.append("```")
+
+    return "\n".join(lines)

aip_agents/ptc/doc_gen.pyi

@@ -0,0 +1,40 @@
+from aip_agents.ptc.naming import sanitize_function_name as sanitize_function_name
+from typing import Any
+
+DOC_DESC_LIMIT: int
+DOC_PARAM_DESC_LIMIT: int
+
+def json_type_to_display(json_type: Any) -> str:
+    """Convert JSON type to display string.
+
+    Args:
+        json_type: JSON schema type.
+
+    Returns:
+        Human-readable type string.
+    """
+def trim_text(text: str | None, limit: int) -> str:
+    """Trim text to limit with ellipsis if needed.
+
+    Args:
+        text: Text to trim.
+        limit: Maximum length before trimming.
+
+    Returns:
+        Trimmed text.
+    """
+def render_tool_doc(func_name: str, signature: str, description: str, schema: dict[str, Any], is_stub: bool = False, example_code: str | None = None, example_heading: str = '## Example') -> str:
+    """Render markdown documentation for a tool.
+
+    Args:
+        func_name: Sanitized function name.
+        signature: Full function signature.
+        description: Tool description.
+        schema: Input schema for parameters.
+        is_stub: Whether this is a stub documentation.
+        example_code: Optional example code block content (without ```python).
+        example_heading: Heading for the example section.
+
+    Returns:
+        Markdown documentation string.
+    """

aip_agents/ptc/exceptions.py

@@ -0,0 +1,39 @@
+"""PTC-specific exceptions.
+
+This module defines exceptions for Programmatic Tool Calling operations.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+
+class PTCError(Exception):
+    """Base exception for PTC errors."""
+
+    pass
+
+
+class PTCToolError(PTCError):
+    """Error during tool execution.
+
+    Attributes:
+        server_name: The MCP server where the error occurred.
+        tool_name: The tool that failed.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        server_name: str | None = None,
+        tool_name: str | None = None,
+    ) -> None:
+        """Initialize PTCToolError.
+
+        Args:
+            message: Error message.
+            server_name: The MCP server name (optional).
+            tool_name: The tool name (optional).
+        """
+        super().__init__(message)
+        self.server_name = server_name
+        self.tool_name = tool_name

aip_agents/ptc/exceptions.pyi

@@ -0,0 +1,22 @@
+from _typeshed import Incomplete
+
+class PTCError(Exception):
+    """Base exception for PTC errors."""
+
+class PTCToolError(PTCError):
+    """Error during tool execution.
+
+    Attributes:
+        server_name: The MCP server where the error occurred.
+        tool_name: The tool that failed.
+    """
+    server_name: Incomplete
+    tool_name: Incomplete
+    def __init__(self, message: str, server_name: str | None = None, tool_name: str | None = None) -> None:
+        """Initialize PTCToolError.
+
+        Args:
+            message: Error message.
+            server_name: The MCP server name (optional).
+            tool_name: The tool name (optional).
+        """