aip-agents-binary 0.0.0b4__cp312-cp312-win_amd64.whl → 0.5.4__cp312-cp312-win_amd64.whl

aip_agents/examples/hello_world_a2a_langchain_server_lm_invoker.pyi

@@ -1,10 +1,15 @@
 from _typeshed import Incomplete
 from aip_agents.agent import LangChainAgent as LangChainAgent
 from aip_agents.examples.tools.langchain_weather_tool import weather_tool as weather_tool
-from aip_agents.utils.logger_manager import LoggerManager as LoggerManager
+from aip_agents.utils.logger import get_logger as get_logger
 
 logger: Incomplete
 SERVER_AGENT_NAME: str
 
 def main(host: str, port: int):
-    """Runs the LangChain Weather A2A server."""
+    """Runs the LangChain Weather A2A server.
+
+    Args:
+        host (str): Host to bind the server to.
+        port (int): Port to bind the server to.
+    """

aip_agents/examples/hello_world_a2a_langflow_client.pyi

@@ -0,0 +1,9 @@
+from _typeshed import Incomplete
+from aip_agents.agent.langflow_agent import LangflowAgent as LangflowAgent
+from aip_agents.schema.agent import A2AClientConfig as A2AClientConfig
+from aip_agents.utils.logger import get_logger as get_logger
+
+logger: Incomplete
+
+async def main() -> None:
+    """Main function demonstrating the Langflow client with streaming A2A capabilities."""

aip_agents/examples/hello_world_a2a_langflow_server.pyi

@@ -0,0 +1,14 @@
+from _typeshed import Incomplete
+from aip_agents.agent.langflow_agent import LangflowAgent as LangflowAgent
+from aip_agents.utils.logger import get_logger as get_logger
+
+logger: Incomplete
+SERVER_AGENT_NAME: str
+
+def main(host: str, port: int):
+    """Runs the Langflow A2A server.
+
+    Args:
+        host (str): Host to bind the server to.
+        port (int): Port to bind the server to.
+    """

aip_agents/examples/hello_world_a2a_langgraph_artifact_client.pyi

@@ -1,5 +1,5 @@
 from aip_agents.agent import LangGraphAgent as LangGraphAgent
-from aip_agents.agent.types import A2AClientConfig as A2AClientConfig
+from aip_agents.schema.agent import A2AClientConfig as A2AClientConfig
 
 async def main() -> None:
     """Main function demonstrating the General Assistant agent with A2A capabilities."""

aip_agents/examples/hello_world_a2a_langgraph_artifact_client_streaming.pyi

@@ -1,5 +1,5 @@
 from aip_agents.agent import LangGraphAgent as LangGraphAgent
-from aip_agents.agent.types import A2AClientConfig as A2AClientConfig
+from aip_agents.schema.agent import A2AClientConfig as A2AClientConfig
 
 async def main() -> None:
     """Main function demonstrating the General Assistant agent with streaming A2A capabilities."""

aip_agents/examples/hello_world_a2a_langgraph_artifact_server.pyi

@@ -2,10 +2,15 @@ from _typeshed import Incomplete
 from aip_agents.agent import LangGraphAgent as LangGraphAgent
 from aip_agents.examples.tools.image_artifact_tool import ImageArtifactTool as ImageArtifactTool
 from aip_agents.examples.tools.table_generator_tool import TableGeneratorTool as TableGeneratorTool
-from aip_agents.utils.logger_manager import LoggerManager as LoggerManager
+from aip_agents.utils.logger import get_logger as get_logger
 
 logger: Incomplete
 SERVER_AGENT_NAME: str
 
 def main(host: str, port: int):
-    """Runs the LangGraph Weather A2A server."""
+    """Runs the LangGraph Artifact Generation A2A server.
+
+    Args:
+        host (str): Host to bind the server to.
+        port (int): Port to bind the server to.
+    """

aip_agents/examples/hello_world_a2a_langgraph_client.pyi

@@ -1,7 +1,7 @@
 from _typeshed import Incomplete
 from aip_agents.agent import LangGraphAgent as LangGraphAgent
-from aip_agents.agent.types import A2AClientConfig as A2AClientConfig
-from aip_agents.utils.logger_manager import LoggerManager as LoggerManager
+from aip_agents.schema.agent import A2AClientConfig as A2AClientConfig
+from aip_agents.utils.logger import get_logger as get_logger
 
 logger: Incomplete
 

aip_agents/examples/hello_world_a2a_langgraph_client_agent.pyi

@@ -1,7 +1,7 @@
 from _typeshed import Incomplete
 from aip_agents.agent import LangGraphAgent as LangGraphAgent
-from aip_agents.agent.types import A2AClientConfig as A2AClientConfig
-from aip_agents.utils.logger_manager import LoggerManager as LoggerManager
+from aip_agents.schema.agent import A2AClientConfig as A2AClientConfig
+from aip_agents.utils.logger import get_logger as get_logger
 
 logger: Incomplete
 

aip_agents/examples/hello_world_a2a_langgraph_client_agent_lm_invoker.pyi

@@ -1,2 +1,2 @@
 from aip_agents.agent import LangChainAgent as LangChainAgent
-from aip_agents.agent.types import A2AClientConfig as A2AClientConfig
+from aip_agents.schema.agent import A2AClientConfig as A2AClientConfig

aip_agents/examples/hello_world_a2a_langgraph_client_streaming.pyi

@@ -1,9 +1,9 @@
 from _typeshed import Incomplete
 from aip_agents.agent import LangGraphAgent as LangGraphAgent
-from aip_agents.agent.types import A2AClientConfig as A2AClientConfig
-from aip_agents.utils.logger_manager import LoggerManager as LoggerManager
+from aip_agents.schema.agent import A2AClientConfig as A2AClientConfig
+from aip_agents.utils.logger import get_logger as get_logger
 
 logger: Incomplete
 
-async def main():
+async def main() -> None:
     """Main function demonstrating the General Assistant agent with streaming A2A capabilities."""

aip_agents/examples/hello_world_a2a_langgraph_client_streaming_lm_invoker.pyi

@@ -1,5 +1,5 @@
 from aip_agents.agent import LangChainAgent as LangChainAgent
-from aip_agents.agent.types import A2AClientConfig as A2AClientConfig
+from aip_agents.schema.agent import A2AClientConfig as A2AClientConfig
 
 async def main() -> None:
     """Main function demonstrating the General Assistant agent with streaming A2A capabilities."""

aip_agents/examples/hello_world_a2a_langgraph_client_streaming_tool_streaming.pyi

@@ -1,5 +1,5 @@
 from aip_agents.agent import LangChainAgent as LangChainAgent
-from aip_agents.agent.types import A2AClientConfig as A2AClientConfig
+from aip_agents.schema.agent import A2AClientConfig as A2AClientConfig
 
 async def main() -> None:
     """Main function demonstrating the General Assistant agent with streaming A2A time/weather capabilities."""

aip_agents/examples/hello_world_a2a_langgraph_server.pyi

@@ -1,9 +1,14 @@
 from _typeshed import Incomplete
 from aip_agents.agent import LangGraphAgent as LangGraphAgent
-from aip_agents.utils.logger_manager import LoggerManager as LoggerManager
+from aip_agents.utils.logger import get_logger as get_logger
 
 logger: Incomplete
 SERVER_AGENT_NAME: str
 
 def main(host: str, port: int):
-    """Runs the LangGraph Weather A2A server."""
+    """Runs the LangGraph Weather A2A server.
+
+    Args:
+        host (str): Host to bind the server to.
+        port (int): Port to bind the server to.
+    """

aip_agents/examples/hello_world_a2a_langgraph_server_lm_invoker.pyi

@@ -1,10 +1,15 @@
 from _typeshed import Incomplete
 from aip_agents.agent import LangChainAgent as LangChainAgent
 from aip_agents.examples.tools.langchain_weather_tool import weather_tool as weather_tool
-from aip_agents.utils.logger_manager import LoggerManager as LoggerManager
+from aip_agents.utils.logger import get_logger as get_logger
 
 logger: Incomplete
 SERVER_AGENT_NAME: str
 
 def main(host: str, port: int):
-    """Runs the LangChain Weather A2A server."""
+    """Runs the LangChain Weather A2A server.
+
+    Args:
+        host (str): Host to bind the server to.
+        port (int): Port to bind the server to.
+    """

aip_agents/examples/hello_world_a2a_langgraph_server_tool_streaming.pyi

@@ -1,10 +1,15 @@
 from _typeshed import Incomplete
 from aip_agents.agent import LangChainAgent as LangChainAgent
 from aip_agents.examples.tools.langgraph_streaming_tool import LangGraphStreamingTool as LangGraphStreamingTool
-from aip_agents.utils.logger_manager import LoggerManager as LoggerManager
+from aip_agents.utils.logger import get_logger as get_logger
 
 logger: Incomplete
 SERVER_AGENT_NAME: str
 
 def main(host: str, port: int):
-    """Runs the LangGraph Agent Wrapper A2A server."""
+    """Runs the LangGraph Agent Wrapper A2A server.
+
+    Args:
+        host (str): Host to bind the server to.
+        port (int): Port to bind the server to.
+    """

aip_agents/examples/hello_world_a2a_mcp_langgraph.pyi

@@ -1,5 +1,5 @@
 from aip_agents.agent import LangGraphAgent as LangGraphAgent
-from aip_agents.agent.types import A2AClientConfig as A2AClientConfig
+from aip_agents.schema.agent import A2AClientConfig as A2AClientConfig
 
 A2A_SERVER_PORT: int
 A2A_AGENT_NAME: str

aip_agents/examples/hello_world_a2a_three_level_agent_hierarchy_client.pyi

@@ -1,18 +1,43 @@
 from aip_agents.agent import LangGraphAgent as LangGraphAgent
-from aip_agents.agent.types import A2AClientConfig as A2AClientConfig
+from aip_agents.schema.agent import A2AClientConfig as A2AClientConfig
 
 async def main() -> None:
     """Main function demonstrating the Three-Level Agent Hierarchy client."""
 async def test_research_task(client_agent, coordinator_card) -> None:
-    """Test a research-only task that flows through research specialists and workers."""
+    """Test a research-only task that flows through research specialists and workers.
+
+    Args:
+        client_agent: The client agent to send the query with.
+        coordinator_card: The agent card of the hierarchical coordinator.
+    """
 async def test_content_task(client_agent, coordinator_card) -> None:
-    """Test a content-only task that flows through content specialists and workers."""
+    """Test a content-only task that flows through content specialists and workers.
+
+    Args:
+        client_agent: The client agent to send the query with.
+        coordinator_card: The agent card of the hierarchical coordinator.
+    """
 async def test_complex_task(client_agent, coordinator_card) -> None:
-    """Test a complex task requiring both research and content specialists."""
+    """Test a complex task requiring both research and content specialists.
+
+    Args:
+        client_agent: The client agent to send the query with.
+        coordinator_card: The agent card of the hierarchical coordinator.
+    """
 async def test_artifact_generation(client_agent, coordinator_card) -> None:
-    """Test artifact generation across the hierarchy."""
+    """Test artifact generation across the hierarchy.
+
+    Args:
+        client_agent: The client agent to send the query with.
+        coordinator_card: The agent card of the hierarchical coordinator.
+    """
 def handle_artifacts(result, test_name) -> None:
-    """Handle and display information about artifacts from the result."""
+    """Handle and display information about artifacts from the result.
+
+    Args:
+        result: The result from the agent containing artifacts.
+        test_name: The name of the test for display purposes.
+    """
 def print_artifact_info(artifact: dict) -> None:
     """Print information about an artifact.
 

aip_agents/examples/hello_world_a2a_three_level_agent_hierarchy_server.pyi

@@ -2,16 +2,44 @@ from _typeshed import Incomplete
 from aip_agents.agent import LangGraphAgent as LangGraphAgent
 from aip_agents.examples.tools.image_artifact_tool import ImageArtifactTool as ImageArtifactTool
 from aip_agents.examples.tools.table_generator_tool import TableGeneratorTool as TableGeneratorTool
-from aip_agents.utils.logger_manager import LoggerManager as LoggerManager
+from aip_agents.utils.logger import get_logger as get_logger
 
 logger: Incomplete
 SERVER_AGENT_NAME: str
 
 def create_worker_agents(llm) -> tuple[LangGraphAgent, LangGraphAgent, LangGraphAgent, LangGraphAgent]:
-    """Create Level 3 worker agents that perform atomic operations."""
+    """Create Level 3 worker agents that perform atomic operations.
+
+    Args:
+        llm: The language model to use for the worker agents.
+
+    Returns:
+        tuple[LangGraphAgent, LangGraphAgent, LangGraphAgent, LangGraphAgent]: Tuple of (web_search_worker, data_analysis_worker, writing_worker, formatting_worker).
+    """
 def create_specialist_agents(llm, worker_agents) -> tuple[LangGraphAgent, LangGraphAgent]:
-    """Create Level 2 specialist agents that coordinate worker agents."""
+    """Create Level 2 specialist agents that coordinate worker agents.
+
+    Args:
+        llm: The language model to use for the specialist agents.
+        worker_agents: Tuple of worker agents from create_worker_agents function.
+
+    Returns:
+        tuple[LangGraphAgent, LangGraphAgent]: Tuple of (research_specialist, content_specialist).
+    """
 def create_coordinator_agent(llm, specialist_agents) -> LangGraphAgent:
-    """Create Level 1 coordinator agent that orchestrates everything."""
+    """Create Level 1 coordinator agent that orchestrates everything.
+
+    Args:
+        llm: The language model to use for the coordinator agent.
+        specialist_agents: Tuple of specialist agents from create_specialist_agents function.
+
+    Returns:
+        LangGraphAgent: The configured coordinator agent.
+    """
 def main(host: str, port: int):
-    """Runs the Three-Level Agent Hierarchy A2A server."""
+    """Runs the Three-Level Agent Hierarchy A2A server.
+
+    Args:
+        host (str): Host to bind the server to.
+        port (int): Port to bind the server to.
+    """

aip_agents/examples/hello_world_a2a_with_metadata_langchain_client.pyi

@@ -1,5 +1,5 @@
 from aip_agents.agent import LangGraphReactAgent as LangGraphReactAgent
-from aip_agents.agent.types import A2AClientConfig as A2AClientConfig
+from aip_agents.schema.agent import A2AClientConfig as A2AClientConfig
 
 async def main() -> None:
     """Demonstrate RunnableConfig with agent defaults and runtime overrides."""

aip_agents/examples/hello_world_a2a_with_metadata_langchain_server_lm_invoker.pyi

@@ -2,9 +2,14 @@ from _typeshed import Incomplete
 from aip_agents.agent import LangGraphReactAgent as LangGraphReactAgent
 from aip_agents.examples.hello_world_a2a_langchain_server import SERVER_AGENT_NAME as SERVER_AGENT_NAME
 from aip_agents.examples.tools.langchain_currency_exchange_tool import CurrencyExchangeTool as CurrencyExchangeTool
-from aip_agents.utils.logger_manager import LoggerManager as LoggerManager
+from aip_agents.utils.logger import get_logger as get_logger
 
 logger: Incomplete
 
 def main(host: str, port: int):
-    """Runs the LangChain Weather A2A server."""
+    """Runs the LangChain Currency Exchange A2A server.
+
+    Args:
+        host (str): Host to bind the server to.
+        port (int): Port to bind the server to.
+    """

aip_agents/examples/hello_world_langchain_mcp_http_interactive.pyi

@@ -0,0 +1,16 @@
+from aip_agents.agent import LangChainAgent as LangChainAgent
+from aip_agents.utils.env_loader import load_local_env as load_local_env
+
+def print_help() -> None:
+    """Prints available commands and their descriptions."""
+def build_mcp_config_from_env() -> dict:
+    """Construct MCP configuration from environment variables.
+
+    Returns:
+        dict: MCP configuration dictionary.
+
+    Raises:
+        RuntimeError: If required environment variables are missing.
+    """
+async def main() -> None:
+    """Runs the interactive LangChainAgent with MCP tools via Streamable HTTP transport."""

aip_agents/examples/hello_world_langchain_mcp_multi_server.pyi

@@ -0,0 +1,18 @@
+from aip_agents.agent import LangChainAgent as LangChainAgent
+from aip_agents.examples.mcp_configs.configs import mcp_tool_whitelisting_demo as mcp_tool_whitelisting_demo
+from aip_agents.schema.a2a import A2AStreamEventType as A2AStreamEventType
+from aip_agents.utils.logger import logger_manager as logger_manager
+
+async def process_query(agent, query: str, is_allowed: bool = True) -> bool:
+    """Process a single query and report if tools were called.
+
+    Args:
+        agent: The LangChain agent to run.
+        query: The query to process.
+        is_allowed: Whether this query should use allowed tools.
+
+    Returns:
+        True if at least one tool was called while processing the query, False otherwise.
+    """
+async def main() -> None:
+    """Demo allowed_tools filtering with 3 MCP servers (STDIO, SSE, HTTP)."""

aip_agents/examples/hello_world_langflow_agent.pyi

@@ -0,0 +1,35 @@
+from aip_agents.agent.langflow_agent import LangflowAgent as LangflowAgent
+from aip_agents.clients.langflow import LangflowApiClient as LangflowApiClient
+
+async def fetch_flow_id() -> tuple[str, str]:
+    """Fetch available flows and return the first flow ID and name."""
+async def create_agent(flow_id: str, flow_name: str) -> LangflowAgent:
+    """Create and configure the Langflow agent.
+
+    Args:
+        flow_id (str): The flow ID to use for the agent.
+        flow_name (str): The name of the flow.
+
+    Returns:
+        LangflowAgent: The configured Langflow agent.
+    """
+async def demonstrate_regular_execution(agent: LangflowAgent) -> None:
+    """Demonstrate regular execution.
+
+    Args:
+        agent (LangflowAgent): The Langflow agent to demonstrate with.
+    """
+async def demonstrate_streaming(agent: LangflowAgent) -> None:
+    """Demonstrate streaming execution.
+
+    Args:
+        agent (LangflowAgent): The Langflow agent to demonstrate with.
+    """
+async def demonstrate_session_management(agent: LangflowAgent) -> None:
+    """Demonstrate session management.
+
+    Args:
+        agent (LangflowAgent): The Langflow agent to demonstrate with.
+    """
+async def main() -> None:
+    """Demonstrate basic Langflow agent usage."""

aip_agents/examples/hello_world_model_switch_cli.pyi

@@ -1,15 +1,30 @@
 from _typeshed import Incomplete
 from aip_agents.agent import LangChainAgent as LangChainAgent
-from aip_agents.agent.types import AgentConfig as AgentConfig
+from aip_agents.schema.agent import AgentConfig as AgentConfig
 
+DEEPINFRA_URL: str
 MODEL_IDS: Incomplete
 MODEL_CONFIGS: Incomplete
 
 def make_agent(model_id):
-    """Makes an agent with the given model id."""
+    """Makes an agent with the given model id.
+
+    Args:
+        model_id: The model identifier to use for the agent.
+
+    Returns:
+        LangChainAgent: The configured agent instance.
+    """
 def print_help() -> None:
     """Prints available commands and their descriptions."""
 def handle_switch_model(current_model):
-    """Handles model switching. Returns (new_model, new_agent)."""
+    """Handles model switching. Returns (new_model, new_agent).
+
+    Args:
+        current_model: The currently active model identifier.
+
+    Returns:
+        tuple: (new_model, new_agent) where new_model is the selected model ID and new_agent is the configured agent instance.
+    """
 def main() -> None:
     """Runs the Hello World Model Switch CLI."""

aip_agents/examples/hello_world_pii_logger.pyi

@@ -1,5 +1,5 @@
 from _typeshed import Incomplete
-from aip_agents.utils.logger_manager import LoggerManager as LoggerManager
+from aip_agents.utils.logger import get_logger as get_logger
 
 logger: Incomplete
 sensitive_info: str

aip_agents/examples/hello_world_sentry.pyi

@@ -1,7 +1,7 @@
 from _typeshed import Incomplete
 from aip_agents.examples.hello_world_langgraph import langgraph_example as langgraph_example
 from aip_agents.sentry import setup_telemetry as setup_telemetry
-from aip_agents.utils.logger_manager import LoggerManager as LoggerManager
+from aip_agents.utils.logger import get_logger as get_logger
 from fastapi import FastAPI
 
 logger: Incomplete

aip_agents/examples/hello_world_step_limits.pyi

@@ -0,0 +1,17 @@
+from aip_agents.agent import LangGraphReactAgent as LangGraphReactAgent
+from aip_agents.examples.tools.langchain_arithmetic_tools import add_numbers as add_numbers
+from aip_agents.schema.step_limit import MaxStepsExceededError as MaxStepsExceededError, StepLimitConfig as StepLimitConfig
+from aip_agents.utils.step_limit_manager import StepLimitManager as StepLimitManager
+
+def print_config_validation(config: StepLimitConfig | None, context: str):
+    """Print step limit configuration validation."""
+async def test_case_1_success_no_limits() -> None:
+    """Test Case 1: Success - High limits, no warnings."""
+async def test_case_2_parallel_tool_batch_accounting() -> None:
+    """Test Case 2: Demonstrate that parallel tool batches consume multiple steps."""
+async def test_case_3_step_limit_exceeded() -> None:
+    """Test Case 3: Step Limit Exceeded - Only 2 steps allowed."""
+async def test_case_4_delegation_depth_exceeded() -> None:
+    """Test Case 4: Delegation Depth Exceeded - Zero depth."""
+async def main() -> None:
+    """Run all test cases."""

aip_agents/examples/hello_world_stock_a2a_server.pyi

@@ -1,7 +1,7 @@
 from _typeshed import Incomplete
 from aip_agents.agent import LangGraphAgent as LangGraphAgent
 from aip_agents.examples.tools.stock_tools import StockNewsInput as StockNewsInput, StockPriceInput as StockPriceInput, get_stock_news as get_stock_news, get_stock_price as get_stock_price
-from aip_agents.utils.logger_manager import LoggerManager as LoggerManager
+from aip_agents.utils.logger import get_logger as get_logger
 from langchain_core.tools import BaseTool as BaseTool
 
 logger: Incomplete
@@ -9,4 +9,9 @@ SERVER_AGENT_NAME: str
 stock_tools: list[BaseTool]
 
 def main(host: str, port: int):
-    """Runs the StockAgent A2A server."""
+    """Runs the StockAgent A2A server.
+
+    Args:
+        host (str): Host to bind the server to.
+        port (int): Port to bind the server to.
+    """

aip_agents/examples/hello_world_tool_output_client.pyi

@@ -1,5 +1,5 @@
 from aip_agents.agent import LangGraphReactAgent as LangGraphReactAgent
-from aip_agents.agent.types import A2AClientConfig as A2AClientConfig
+from aip_agents.schema.agent import A2AClientConfig as A2AClientConfig
 
 async def main() -> None:
     """Demonstrate tool output management with data visualization."""

aip_agents/examples/hello_world_tool_output_server.pyi

@@ -5,10 +5,15 @@ from aip_agents.examples.tools.data_visualization_tool import DataVisualizerTool
 from aip_agents.storage.clients.minio_client import MinioConfig as MinioConfig, MinioObjectStorage as MinioObjectStorage
 from aip_agents.storage.providers.object_storage import ObjectStorageProvider as ObjectStorageProvider
 from aip_agents.utils.langgraph.tool_output_management import ToolOutputConfig as ToolOutputConfig, ToolOutputManager as ToolOutputManager
-from aip_agents.utils.logger_manager import LoggerManager as LoggerManager
+from aip_agents.utils.logger import get_logger as get_logger
 
 logger: Incomplete
 SERVER_AGENT_NAME: str
 
 def main(host: str, port: int):
-    """Run the Data Visualization A2A server."""
+    """Run the Data Visualization A2A server.
+
+    Args:
+        host (str): Host to bind the server to.
+        port (int): Port to bind the server to.
+    """

aip_agents/examples/hitl_demo.pyi

@@ -0,0 +1,67 @@
+import asyncio
+import httpx
+from _typeshed import Incomplete
+from aip_agents.agent import LangGraphReactAgent as LangGraphReactAgent
+from aip_agents.schema.hitl import ApprovalRequest as ApprovalRequest
+from aip_agents.utils.env_loader import load_local_env as load_local_env
+from aip_agents.utils.logger import get_logger as get_logger
+from dataclasses import dataclass
+from langchain_core.tools import tool
+from starlette.applications import Starlette
+
+logger: Incomplete
+
+@tool
+def check_candidate_inbox(candidate_email: str) -> str:
+    """Retrieve the latest email from a candidate (safe tool).
+
+    Args:
+        candidate_email (str): The email address of the candidate.
+
+    Returns:
+        str: The latest email content from the candidate.
+    """
+@tool
+def validate_candidate(candidate_name: str, role: str, score: int) -> str:
+    """Record the candidate decision in the applicant tracking system.
+
+    Args:
+        candidate_name (str): The name of the candidate.
+        role (str): The role the candidate is being evaluated for.
+        score (int): The evaluation score for the candidate.
+
+    Returns:
+        str: The validation result with recommendation and notes.
+    """
+@tool
+def send_candidate_email(candidate_email: str, subject: str, body: str) -> str:
+    """Send an email update to the candidate.
+
+    Args:
+        candidate_email (str): The email address of the candidate.
+        subject (str): The subject line of the email.
+        body (str): The body content of the email.
+
+    Returns:
+        str: Confirmation message that the email was sent.
+    """
+
+CANDIDATE_PROFILES: dict[str, dict[str, str | int | bool]]
+CANDIDATE_SEQUENCE: list[dict[str, str | int | bool]]
+NAME_INDEX: Incomplete
+
+class _ServerContext:
+    def __init__(self, app: Starlette, host: str, port: int) -> None: ...
+    async def __aenter__(self) -> _ServerContext: ...
+    async def __aexit__(self, exc_type, exc, _tb) -> None: ...
+
+@dataclass
+class RunContext:
+    """Context object containing runtime dependencies for the HITL demo server."""
+    http_client: httpx.AsyncClient
+    host: str
+    port: int
+    pending_queue: asyncio.Queue[ApprovalRequest]
+
+async def main() -> None:
+    """Interactive HITL approval demo."""

aip_agents/examples/pii_demo_langgraph_client.pyi

@@ -0,0 +1,5 @@
+from aip_agents.agent import LangChainAgent as LangChainAgent
+from aip_agents.schema.agent import A2AClientConfig as A2AClientConfig
+
+async def main() -> None:
+    """Stream queries and inspect chunks with PII handling."""

aip_agents/examples/pii_demo_langgraph_server.pyi

@@ -0,0 +1,20 @@
+from _typeshed import Incomplete
+from aip_agents.agent import LangChainAgent as LangChainAgent
+from aip_agents.examples.tools.pii_demo_tools import get_customer_info as get_customer_info, get_employee_data as get_employee_data, get_user_profile as get_user_profile
+from aip_agents.utils.logger import LoggerManager as LoggerManager
+
+logger: Incomplete
+SERVER_AGENT_NAME: str
+
+def main(host: str, port: int):
+    """Runs the PII Demo LangGraph A2A server.
+
+    This server demonstrates PII handling capabilities including:
+    - Automatic anonymization of sensitive data in tool outputs
+    - Deanonymization of PII for tool inputs
+    - Collision detection and resolution in parallel tool execution
+
+    Args:
+        host (str): Host to bind the server to.
+        port (int): Port to bind the server to.
+    """

aip_agents/examples/pii_demo_multi_agent_client.pyi

@@ -0,0 +1,5 @@
+from aip_agents.agent import LangGraphAgent as LangGraphAgent
+from aip_agents.schema.agent import A2AClientConfig as A2AClientConfig
+
+async def main() -> None:
+    """Main function demonstrating the Multi-Agent PII Demo client."""