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

aip_agents/agent/langgraph_react_agent.py

@@ -18,14 +18,14 @@ from collections.abc import Awaitable, Callable, Sequence
 from dataclasses import asdict, dataclass
 from functools import reduce
 from textwrap import dedent
-from typing import TYPE_CHECKING, Annotated, Any
+from typing import TYPE_CHECKING, Annotated, Any, cast
 
-from deprecated import deprecated
+from deprecated import deprecated  # type: ignore[import-untyped]
 
 if TYPE_CHECKING:
     from aip_agents.guardrails.manager import GuardrailManager
-from gllm_core.event import EventEmitter
-from gllm_core.schema import Chunk
+from gllm_core.event import EventEmitter  # type: ignore[import-untyped]
+from gllm_core.schema import Chunk  # type: ignore[import-untyped]
 from langchain_core.language_models import BaseChatModel
 from langchain_core.messages import (
     AIMessage,
@@ -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
@@ -212,6 +221,12 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
             **kwargs,
         )
 
+        if self.model is None and self.lm_invoker is None:
+            logger.warning(
+                "Agent '%s': Model and LM invoker are both unset. Calls that require a model will fail.",
+                self.name,
+            )
+
         # Handle tool output management
         self.tool_output_manager = tool_output_manager
         self._pii_handlers_by_thread: dict[str, ToolPIIHandler] = {}
@@ -233,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,
@@ -256,7 +283,7 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
 
         # Auto-configure TodoListMiddleware if planning enabled
         if planning:
-            middleware_list.append(TodoListMiddleware())
+            middleware_list.append(cast(AgentMiddleware, TodoListMiddleware()))
 
         # Auto-configure GuardrailMiddleware if guardrail provided
         if guardrail:
@@ -419,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
@@ -431,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]]]:
@@ -732,7 +763,7 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
         pending_artifacts: list[dict[str, Any]] = state.get("artifacts") or []
         reference_updates: list[Chunk] = []
         tool_map = {tool.name: tool for tool in self.resolved_tools}
-        pii_mapping = {}
+        pii_mapping: dict[str, str] = {}
 
         aggregated_metadata_delta: dict[str, Any] = {}
         total_tools_token_usage: list[UsageMetadata] = []
@@ -756,7 +787,8 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
                 ),
             )
 
-        tasks = [asyncio.create_task(run_tool(tc)) for tc in last_message.tool_calls]
+        normalized_tool_calls = [self._normalize_tool_call(tc) for tc in last_message.tool_calls]
+        tasks = [asyncio.create_task(run_tool(tc)) for tc in normalized_tool_calls]
 
         for coro in asyncio.as_completed(tasks):
             tool_result = await coro
@@ -779,6 +811,31 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
             pii_mapping,
         )
 
+    def _normalize_tool_call(self, tool_call: Any) -> dict[str, Any]:
+        """Normalize tool call inputs into a dict with required keys."""
+        if isinstance(tool_call, dict):
+            normalized = dict(tool_call)
+        elif hasattr(tool_call, "model_dump"):
+            normalized = tool_call.model_dump()
+        elif hasattr(tool_call, "dict"):
+            normalized = tool_call.dict()
+        elif hasattr(tool_call, "name") and hasattr(tool_call, "args"):
+            normalized = {
+                "id": getattr(tool_call, "id", None),
+                "name": getattr(tool_call, "name", None),
+                "args": getattr(tool_call, "args", None),
+            }
+        else:
+            raise TypeError("Tool call must be a dict-like object or ToolCall instance.")
+
+        if not isinstance(normalized, dict):
+            raise TypeError("Tool call normalization did not produce a dict.")
+
+        if "name" not in normalized or "args" not in normalized:
+            raise TypeError("Tool call must include 'name' and 'args' fields.")
+
+        return normalized
+
     def _accumulate_tool_result(  # noqa: PLR0913
         self,
         tool_result: Any,
@@ -787,7 +844,7 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
         aggregated_metadata_delta: dict[str, Any],
         reference_updates: list[Chunk],
         total_tools_token_usage: list[UsageMetadata],
-        pii_mapping: dict[str, str] | None,
+        pii_mapping: dict[str, str],
     ) -> None:  # noqa: PLR0913
         """Accumulate results from a single tool call.
 
@@ -1233,13 +1290,16 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
 
             # Create enhanced tool configuration with output management
             tool_config = self._create_enhanced_tool_config(config, state, tool_call["name"], tool_call_id)
+            if not isinstance(tool_config, dict):
+                raise TypeError("Tool configuration must be a dictionary.")
+            tool_config_runnable = tool_config
 
             arun_streaming_method = getattr(tool, TOOL_RUN_STREAMING_METHOD, None)
 
             if arun_streaming_method and callable(arun_streaming_method):
                 tool_output = await self._execute_tool_with_streaming(tool, tool_call, tool_config)
             else:
-                tool_output = await tool.ainvoke(resolved_args, tool_config)
+                tool_output = await tool.ainvoke(resolved_args, tool_config_runnable)
 
             references = extract_references_from_tool(tool, tool_output)
 
@@ -1513,7 +1573,7 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
         tool_call: dict[str, Any],
         execution_time: float,
         pending_artifacts: list[dict[str, Any]],
-    ) -> tuple[list[BaseMessage], list[dict[str, Any]], dict[str, Any]]:
+    ) -> tuple[list[ToolMessage], list[dict[str, Any]], dict[str, Any]]:
         """Process tool output into messages, artifacts, and metadata.
 
         Args:
@@ -1541,7 +1601,7 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
 
     def _handle_command_output(
         self, tool_output: Command, tool_call: dict[str, Any], execution_time: float, metadata_delta: dict[str, Any]
-    ) -> tuple[list[BaseMessage], list[dict[str, Any]], dict[str, Any]]:
+    ) -> tuple[list[ToolMessage], list[dict[str, Any]], dict[str, Any]]:
         """Handle Command type tool outputs.
 
         Args:
@@ -1570,7 +1630,7 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
 
     def _handle_string_output(
         self, tool_output: str, tool_call: dict[str, Any], execution_time: float
-    ) -> tuple[list[BaseMessage], list[dict[str, Any]], dict[str, Any]]:
+    ) -> tuple[list[ToolMessage], list[dict[str, Any]], dict[str, Any]]:
         """Handle string type tool outputs.
 
         Args:
@@ -1596,7 +1656,7 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
         execution_time: float,
         pending_artifacts: list[dict[str, Any]],
         metadata_delta: dict[str, Any],
-    ) -> tuple[list[BaseMessage], list[dict[str, Any]], dict[str, Any]]:
+    ) -> tuple[list[ToolMessage], list[dict[str, Any]], dict[str, Any]]:
         """Handle legacy dict and other tool outputs.
 
         Args:
@@ -1694,8 +1754,11 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
             self._emit_default_tool_call_event(writer, tool_name, tool_call_id, tool_args)
 
             streaming_kwargs = self._build_streaming_kwargs(tool_args, tool_config)
+            arun_streaming_method = getattr(tool, TOOL_RUN_STREAMING_METHOD, None)
+            if not callable(arun_streaming_method):
+                raise RuntimeError(f"Tool '{tool_name}' does not implement streaming.")
 
-            async for chunk in tool.arun_streaming(**streaming_kwargs):
+            async for chunk in arun_streaming_method(**streaming_kwargs):
                 final_output, saw_tool_result = self._handle_streaming_chunk(
                     chunk=chunk,
                     writer=writer,
@@ -2125,6 +2188,9 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
 
         effective_event_emitter = state.get("event_emitter") or self.event_emitter
 
+        if self.lm_invoker is None:
+            raise RuntimeError("LM invoker is required for this execution path.")
+
         if self.resolved_tools:
             self.lm_invoker.set_tools(self.resolved_tools)
 
@@ -2183,6 +2249,9 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
         ):
             langchain_prompt = [SystemMessage(content=enhanced_instruction)] + list(current_messages)
 
+        if self.model is None:
+            raise RuntimeError("Model is required for this execution path.")
+
         model_with_tools = self.model.bind_tools(self.resolved_tools) if self.resolved_tools else self.model
 
         ai_message = await model_with_tools.ainvoke(langchain_prompt, config)
@@ -2576,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/compare_streaming_client.py

@@ -8,10 +8,10 @@ This script demonstrates:
 
 Prerequisites:
     Start the server first:
-        uv run python -m aip_agents.examples.compare_streaming_server
+        poetry run python -m aip_agents.examples.compare_streaming_server
 
 Then run this client:
-    uv run python -m aip_agents.examples.compare_streaming_client
+    poetry run python -m aip_agents.examples.compare_streaming_client
 
 Authors:
     AI Agent Platform Team

aip_agents/examples/compare_streaming_server.py

@@ -6,7 +6,7 @@ This server provides an agent with:
 
 To run this server:
     cd libs/aip_agents
-    uv run python -m aip_agents.examples.compare_streaming_server
+    poetry run python -m aip_agents.examples.compare_streaming_server
 
 It will listen on http://localhost:18999 by default.
 

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/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/todolist_planning_a2a_langchain_client.py

@@ -1,10 +1,10 @@
 """A2A client for the planning LangGraphReactAgent.
 
 Run the planning server first:
-    uv run python -m aip_agents.examples.todolist_planning_a2a_langgraph_server
+    poetry run python -m aip_agents.examples.todolist_planning_a2a_langgraph_server
 
 Then run this client:
-    uv run python -m aip_agents.examples.todolist_planning_a2a_langchain_client
+    poetry run python -m aip_agents.examples.todolist_planning_a2a_langchain_client
 
 You should see streaming output, including when write_todos_tool is called.
 """

aip_agents/examples/todolist_planning_a2a_langgraph_server.py

@@ -1,7 +1,7 @@
 """A2A server exposing a LangGraphReactAgent with planning (TodoListMiddleware).
 
 Run:
-    uv run python -m aip_agents.examples.todolist_planning_a2a_langgraph_server \
+    poetry run python -m aip_agents.examples.todolist_planning_a2a_langgraph_server \
         --host localhost --port 8002
 
 Then connect with the matching A2A client to observe write_todos_tool calls.

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