aip-agents-binary 0.5.25b1__py3-none-macosx_13_0_arm64.whl

aip_agents/examples/pii_demo_multi_agent_server.py

@@ -0,0 +1,247 @@
+"""Multi-Agent PII Demo Server - Demonstrates PII handling across agent hierarchy.
+
+This server hosts a hierarchical agent system demonstrating PII propagation:
+1. Level 1 (Coordinator): Main orchestrator that routes requests
+2. Level 2 (Specialists): Domain-specific agents with PII-returning tools
+   - CustomerServiceAgent: Handles customer inquiries
+   - HRAgent: Handles employee data requests
+   - UserSupportAgent: Handles user profile requests
+
+Architecture:
+PIICoordinator (A2A Server)
+├── CustomerServiceAgent (with get_customer_info tool)
+├── HRAgent (with get_employee_data tool)
+└── UserSupportAgent (with get_user_profile tool)
+
+Features demonstrated:
+- PII anonymization in tool outputs
+- PII propagation from child agents to parent
+- Multi-agent delegation with PII mapping merge
+- Collision handling when multiple agents discover PII
+
+To run this server:
+    export NER_API_URL=http://localhost:8080
+    export NER_API_KEY=your-api-key
+    python aip_agents/examples/pii_demo_multi_agent_server.py
+
+It will listen on http://localhost:8003 by default.
+
+Authors:
+    Fachriza Adhiatma (fachriza.d.adhiatma@gdplabs.id)
+"""
+
+import click
+import uvicorn
+from a2a.types import AgentCapabilities, AgentCard, AgentSkill
+from dotenv import load_dotenv
+from langchain_openai import ChatOpenAI
+
+from aip_agents.agent import LangGraphAgent
+from aip_agents.examples.tools.pii_demo_tools import (
+    get_customer_info,
+    get_employee_data,
+    get_user_profile,
+)
+from aip_agents.utils.logger import LoggerManager
+
+load_dotenv()
+
+logger = LoggerManager().get_logger(__name__)
+
+SERVER_AGENT_NAME = "PIICoordinator"
+
+
+def create_specialist_agents(llm: ChatOpenAI) -> tuple[LangGraphAgent, LangGraphAgent, LangGraphAgent]:
+    """Create Level 2 specialist agents with PII-returning tools.
+
+    Args:
+        llm: The language model to use for the specialist agents.
+
+    Returns:
+        Tuple of (customer_service_agent, hr_agent, user_support_agent).
+    """
+    # Customer Service Agent - handles customer inquiries
+    customer_service_agent = LangGraphAgent(
+        name="CustomerServiceAgent",
+        instruction="""You are a customer service specialist. You help retrieve customer information.
+
+You have access to the get_customer_info tool to retrieve customer details.
+When asked about customers, use this tool to get their information.
+
+You will receive output from tools in masked version with PII tags like <PERSON_xxx>, <EMAIL_ADDRESS_xxx>.
+Present the information as-is without trying to reveal or change the masked values.
+
+Always be helpful and professional in your responses.""",
+        model=llm,
+        tools=[get_customer_info],
+    )
+
+    # HR Agent - handles employee data requests
+    hr_agent = LangGraphAgent(
+        name="HRAgent",
+        instruction="""You are an HR specialist. You help retrieve employee information.
+
+You have access to the get_employee_data tool to retrieve employee details.
+When asked about employees, use this tool to get their information.
+
+You will receive output from tools in masked version with PII tags like <PERSON_xxx>, <EMAIL_ADDRESS_xxx>.
+Present the information as-is without trying to reveal or change the masked values.
+
+Always maintain confidentiality and professionalism.""",
+        model=llm,
+        tools=[get_employee_data],
+    )
+
+    # User Support Agent - handles user profile requests
+    user_support_agent = LangGraphAgent(
+        name="UserSupportAgent",
+        instruction="""You are a user support specialist. You help retrieve user profile information.
+
+You have access to the get_user_profile tool to retrieve user details.
+When asked about users, use this tool to get their profile information.
+
+You will receive output from tools in masked version with PII tags like <PERSON_xxx>, <EMAIL_ADDRESS_xxx>.
+Present the information as-is without trying to reveal or change the masked values.
+
+Always be helpful and respect user privacy.""",
+        model=llm,
+        tools=[get_user_profile],
+    )
+
+    return customer_service_agent, hr_agent, user_support_agent
+
+
+def create_coordinator_agent(
+    llm: ChatOpenAI,
+    specialist_agents: tuple[LangGraphAgent, LangGraphAgent, LangGraphAgent],
+) -> LangGraphAgent:
+    """Create Level 1 coordinator agent that orchestrates specialist agents.
+
+    Args:
+        llm: The language model to use for the coordinator agent.
+        specialist_agents: Tuple of specialist agents.
+
+    Returns:
+        The configured coordinator agent.
+    """
+    customer_service_agent, hr_agent, user_support_agent = specialist_agents
+
+    coordinator = LangGraphAgent(
+        name=SERVER_AGENT_NAME,
+        instruction="""You are a coordinator that manages requests across different departments.
+
+You oversee three specialist teams:
+- CustomerServiceAgent: Handles customer information requests (customer IDs like C001, C002, C003)
+- HRAgent: Handles employee data requests (employee IDs like E001, E002, E003)
+- UserSupportAgent: Handles user profile requests (user IDs like U001, U002, U003)
+
+For each request, analyze what type of information is needed and delegate appropriately:
+- Customer-related requests -> CustomerServiceAgent
+- Employee/HR-related requests -> HRAgent
+- User profile requests -> UserSupportAgent
+- Complex requests may require multiple specialists
+
+You will receive responses with PII tags like <PERSON_xxx>, <EMAIL_ADDRESS_xxx>.
+Present the information as-is without trying to reveal or change the masked values.
+
+Always provide a clear summary of the information gathered from your specialists.""",
+        model=llm,
+        agents=[customer_service_agent, hr_agent, user_support_agent],
+    )
+
+    return coordinator
+
+
+@click.command()
+@click.option("--host", "host", default="localhost", help="Host to bind the server to.")
+@click.option("--port", "port", default=8003, help="Port to bind the server to.")
+def main(host: str, port: int):
+    """Runs the Multi-Agent PII Demo A2A server.
+
+    This server demonstrates PII handling across a multi-agent hierarchy:
+    - PII anonymization in tool outputs
+    - PII propagation from child agents to parent
+    - Multi-agent delegation with PII mapping merge
+
+    Args:
+        host: Host to bind the server to.
+        port: Port to bind the server to.
+    """
+    logger.info(f"Starting {SERVER_AGENT_NAME} on http://{host}:{port}")
+    logger.info("Multi-agent PII handling demo with 3 specialist agents")
+
+    agent_card = AgentCard(
+        name=SERVER_AGENT_NAME,
+        description=(
+            "A coordinator agent managing 3 specialist agents for customer, employee, "
+            "and user information with automatic PII handling across the hierarchy."
+        ),
+        url=f"http://{host}:{port}",
+        version="1.0.0",
+        defaultInputModes=["text"],
+        defaultOutputModes=["text"],
+        capabilities=AgentCapabilities(streaming=True),
+        skills=[
+            AgentSkill(
+                id="multi_agent_coordination",
+                name="Multi-Agent PII Coordination",
+                description="Coordinates requests across multiple specialist agents with PII handling.",
+                examples=[
+                    "Get information for customer C001 and employee E001",
+                    "Compare customer C002 with user U002",
+                    "Get all available information about John",
+                ],
+                tags=["coordination", "multi-agent", "pii"],
+            ),
+            AgentSkill(
+                id="customer_service",
+                name="Customer Service",
+                description="Retrieves customer information via CustomerServiceAgent.",
+                examples=[
+                    "Get customer info for C001",
+                    "What is the email for customer C002?",
+                ],
+                tags=["customer", "pii"],
+            ),
+            AgentSkill(
+                id="hr_services",
+                name="HR Services",
+                description="Retrieves employee data via HRAgent.",
+                examples=[
+                    "Get employee data for E001",
+                    "What department is employee E002 in?",
+                ],
+                tags=["employee", "hr", "pii"],
+            ),
+            AgentSkill(
+                id="user_support",
+                name="User Support",
+                description="Retrieves user profile information via UserSupportAgent.",
+                examples=[
+                    "Get user profile for U001",
+                    "What city does user U002 live in?",
+                ],
+                tags=["user", "profile", "pii"],
+            ),
+        ],
+        tags=["pii", "demo", "multi-agent", "hierarchy"],
+    )
+
+    llm = ChatOpenAI(model="gpt-4.1", temperature=0, streaming=True)
+
+    # Build the 2-level hierarchy
+    logger.info("Creating Level 2 specialist agents...")
+    specialist_agents = create_specialist_agents(llm)
+
+    logger.info("Creating Level 1 coordinator agent...")
+    coordinator_agent = create_coordinator_agent(llm, specialist_agents)
+
+    app = coordinator_agent.to_a2a(agent_card=agent_card)
+
+    logger.info("A2A application configured. Starting Uvicorn server...")
+    logger.info("Hierarchy: 1 Coordinator -> 3 Specialists (each with PII tools)")
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    main()

aip_agents/examples/pii_demo_multi_agent_server.pyi

@@ -0,0 +1,40 @@
+from _typeshed import Incomplete
+from aip_agents.agent import LangGraphAgent as LangGraphAgent
+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
+from langchain_openai import ChatOpenAI
+
+logger: Incomplete
+SERVER_AGENT_NAME: str
+
+def create_specialist_agents(llm: ChatOpenAI) -> tuple[LangGraphAgent, LangGraphAgent, LangGraphAgent]:
+    """Create Level 2 specialist agents with PII-returning tools.
+
+    Args:
+        llm: The language model to use for the specialist agents.
+
+    Returns:
+        Tuple of (customer_service_agent, hr_agent, user_support_agent).
+    """
+def create_coordinator_agent(llm: ChatOpenAI, specialist_agents: tuple[LangGraphAgent, LangGraphAgent, LangGraphAgent]) -> LangGraphAgent:
+    """Create Level 1 coordinator agent that orchestrates specialist agents.
+
+    Args:
+        llm: The language model to use for the coordinator agent.
+        specialist_agents: Tuple of specialist agents.
+
+    Returns:
+        The configured coordinator agent.
+    """
+def main(host: str, port: int):
+    """Runs the Multi-Agent PII Demo A2A server.
+
+    This server demonstrates PII handling across a multi-agent hierarchy:
+    - PII anonymization in tool outputs
+    - PII propagation from child agents to parent
+    - Multi-agent delegation with PII mapping merge
+
+    Args:
+        host: Host to bind the server to.
+        port: Port to bind the server to.
+    """

aip_agents/examples/todolist_planning_a2a_langchain_client.py

@@ -0,0 +1,70 @@
+"""A2A client for the planning LangGraphReactAgent.
+
+Run the planning server first:
+    uv 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
+
+You should see streaming output, including when write_todos_tool is called.
+"""
+
+import asyncio
+import json
+
+from dotenv import load_dotenv
+from langchain_openai import ChatOpenAI
+
+from aip_agents.agent import LangChainAgent
+from aip_agents.schema.agent import A2AClientConfig
+
+load_dotenv()
+
+
+async def main() -> None:
+    """Connect to the planning A2A server and stream a planning query."""
+    assistant_agent = LangChainAgent(
+        name="PlanningClientAgent",
+        instruction=(
+            "You are a user-facing assistant that asks a planning agent "
+            "to break work into a todo list before executing it."
+        ),
+        model=ChatOpenAI(model="gpt-4.1", temperature=0),
+    )
+
+    client_a2a_config = A2AClientConfig(
+        discovery_urls=["http://localhost:8002"],
+    )
+
+    agent_cards = assistant_agent.discover_agents(client_a2a_config)
+    if not agent_cards:
+        print("No agents discovered at http://localhost:8002")
+        return
+
+    agent_card = agent_cards[0]
+    print(f"Discovered agent: {agent_card.name} @ {agent_card.url}")
+
+    query = "Research the latest advances in AI-driven drug discovery for oncology and synthesize findings into a comprehensive report—drawing on recent web-sourced literature and relevant company/market context—highlighting key breakthroughs, potential future directions, and a dedicated section on ethical considerations."
+
+    print("\nSending query to planning agent (streaming)...\n")
+
+    async for chunk in assistant_agent.astream_to_agent(agent_card, message=query):
+        content = chunk.get("content")
+        metadata = chunk.get("metadata", {})
+        status = metadata.get("status") or metadata.get("state")
+
+        if status and status.lower() in ("running", "processing"):
+            print("Query:", query)
+            if "tool_info" in metadata:
+                print("Tool Info:", json.dumps(metadata["tool_info"], indent=2))
+
+        if status and status.lower() in ("finished", "completed"):
+            print("\n=== Completed — final output ===\n")
+            if content:
+                print(content)
+            elif metadata.get("output"):
+                print(metadata.get("output"))
+
+
+if __name__ == "__main__":  # pragma: no cover - manual smoke script
+    asyncio.run(main())

aip_agents/examples/todolist_planning_a2a_langchain_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:
+    """Connect to the planning A2A server and stream a planning query."""

aip_agents/examples/todolist_planning_a2a_langgraph_server.py

@@ -0,0 +1,88 @@
+"""A2A server exposing a LangGraphReactAgent with planning (TodoListMiddleware).
+
+Run:
+    uv 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.
+"""
+
+import click
+import langchain
+import uvicorn
+from a2a.types import AgentCapabilities, AgentCard, AgentSkill
+from dotenv import load_dotenv
+from langchain_openai import ChatOpenAI
+
+from aip_agents.agent import LangGraphReactAgent
+from aip_agents.examples.tools.serper_tool import MockGoogleSerperTool
+from aip_agents.examples.tools.stock_tools import get_stock_price
+from aip_agents.utils.logger import get_logger
+
+langchain.debug = True
+
+load_dotenv()
+
+logger = get_logger(__name__)
+
+SERVER_AGENT_NAME = "PlanningTodoAgent"
+
+
+@click.command()
+@click.option("--host", "host", default="localhost", help="Host to bind the server to.")
+@click.option("--port", "port", default=8002, help="Port to bind the server to.")
+def main(host: str, port: int) -> None:
+    """Run an A2A server with a planning-enabled LangGraphReactAgent.
+
+    The agent has TodoListMiddleware attached via planning=True and will
+    expose the write_todos_tool over A2A with token streaming enabled.
+
+    Args:
+        host: The host to bind the server to.
+        port: The port to bind the server to.
+    """
+    logger.info(f"Starting {SERVER_AGENT_NAME} on http://{host}:{port}")
+
+    agent_card = AgentCard(
+        name=SERVER_AGENT_NAME,
+        description="Planning agent that breaks tasks into todos using write_todos.",
+        url=f"http://{host}:{port}",
+        version="1.0.0",
+        defaultInputModes=["text"],
+        defaultOutputModes=["text"],
+        capabilities=AgentCapabilities(streaming=True),
+        skills=[
+            AgentSkill(
+                id="planning",
+                name="Planning and Todo Management",
+                description="Breaks high-level tasks into a todo list and tracks progress.",
+                examples=[
+                    "Plan a 3-step migration task and show the todo list.",
+                    "Create a todo list for building a small feature.",
+                ],
+                tags=["planning", "todos"],
+            )
+        ],
+        tags=["planning", "todos"],
+    )
+
+    llm = ChatOpenAI(model="gpt-4.1", temperature=0, streaming=True)
+
+    # No custom tools; planning=True will attach TodoListMiddleware and
+    # provide write_todos_tool automatically.
+    agent = LangGraphReactAgent(
+        name=SERVER_AGENT_NAME,
+        instruction=("You are an Assistant Agent, your job is to answer based on a query."),
+        model=llm,
+        tools=[MockGoogleSerperTool(), get_stock_price],
+        planning=True,
+    )
+
+    app = agent.to_a2a(agent_card=agent_card)
+
+    logger.info("Planning A2A application configured. Starting Uvicorn server...")
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":  # pragma: no cover - manual smoke script
+    main()

aip_agents/examples/todolist_planning_a2a_langgraph_server.pyi

@@ -0,0 +1,19 @@
+from _typeshed import Incomplete
+from aip_agents.agent import LangGraphReactAgent as LangGraphReactAgent
+from aip_agents.examples.tools.serper_tool import MockGoogleSerperTool as MockGoogleSerperTool
+from aip_agents.examples.tools.stock_tools import get_stock_price as get_stock_price
+from aip_agents.utils.logger import get_logger as get_logger
+
+logger: Incomplete
+SERVER_AGENT_NAME: str
+
+def main(host: str, port: int) -> None:
+    """Run an A2A server with a planning-enabled LangGraphReactAgent.
+
+    The agent has TodoListMiddleware attached via planning=True and will
+    expose the write_todos_tool over A2A with token streaming enabled.
+
+    Args:
+        host: The host to bind the server to.
+        port: The port to bind the server to.
+    """

aip_agents/examples/tools/__init__.py

@@ -0,0 +1,27 @@
+"""Tools for the examples.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from aip_agents.examples.tools.adk_weather_tool import (
+    get_weather as weather_tool_adk,
+)
+from aip_agents.examples.tools.langchain_weather_tool import (
+    weather_tool as weather_tool_langchain,
+)
+from aip_agents.examples.tools.langgraph_streaming_tool import LangGraphStreamingTool as langgraph_streaming_tool
+from aip_agents.examples.tools.mock_retrieval_tool import MockRetrievalTool as mock_retrieval_tool
+from aip_agents.examples.tools.random_chart_tool import RandomChartTool as random_chart_tool
+from aip_agents.examples.tools.serper_tool import MockGoogleSerperTool as google_serper_tool
+from aip_agents.examples.tools.time_tool import TimeTool as time_tool
+
+__all__ = [
+    "weather_tool_langchain",
+    "weather_tool_adk",
+    "time_tool",
+    "google_serper_tool",
+    "langgraph_streaming_tool",
+    "mock_retrieval_tool",
+    "random_chart_tool",
+]

aip_agents/examples/tools/__init__.pyi

@@ -0,0 +1,9 @@
+from aip_agents.examples.tools.adk_weather_tool import get_weather as weather_tool_adk
+from aip_agents.examples.tools.langchain_weather_tool import weather_tool as weather_tool_langchain
+from aip_agents.examples.tools.langgraph_streaming_tool import LangGraphStreamingTool as langgraph_streaming_tool
+from aip_agents.examples.tools.mock_retrieval_tool import MockRetrievalTool as mock_retrieval_tool
+from aip_agents.examples.tools.random_chart_tool import RandomChartTool as random_chart_tool
+from aip_agents.examples.tools.serper_tool import MockGoogleSerperTool as google_serper_tool
+from aip_agents.examples.tools.time_tool import TimeTool as time_tool
+
+__all__ = ['weather_tool_langchain', 'weather_tool_adk', 'time_tool', 'google_serper_tool', 'langgraph_streaming_tool', 'mock_retrieval_tool', 'random_chart_tool']

aip_agents/examples/tools/adk_arithmetic_tools.py

@@ -0,0 +1,36 @@
+"""Common arithmetic tools for GLLM agent examples."""
+
+
+def add_numbers(a: int, b: int) -> str:
+    """Adds two integer numbers together and returns the result as a string.
+
+    For example, to add 5 and 3, you would call this with a=5 and b=3.
+
+    Args:
+        a: The first number.
+        b: The second number.
+
+    Returns:
+        The sum of the two numbers as a string, or an error message if addition fails.
+    """
+    try:
+        result = a + b
+        return str(result)
+    except Exception as e:
+        return f"Error: Could not add numbers. Reason: {str(e)}"
+
+
+def sum_numbers(a: int, b: int) -> int:
+    """Adds two integer numbers together and returns the integer result.
+
+    Used specifically in Google ADK examples where an integer return is expected.
+
+    Args:
+        a: The first number.
+        b: The second number.
+
+    Returns:
+        The sum of the two numbers as an integer.
+    """
+    print(f"Tool executed: sum_numbers({a}, {b})")
+    return a + b

aip_agents/examples/tools/adk_arithmetic_tools.pyi

@@ -0,0 +1,24 @@
+def add_numbers(a: int, b: int) -> str:
+    """Adds two integer numbers together and returns the result as a string.
+
+    For example, to add 5 and 3, you would call this with a=5 and b=3.
+
+    Args:
+        a: The first number.
+        b: The second number.
+
+    Returns:
+        The sum of the two numbers as a string, or an error message if addition fails.
+    """
+def sum_numbers(a: int, b: int) -> int:
+    """Adds two integer numbers together and returns the integer result.
+
+    Used specifically in Google ADK examples where an integer return is expected.
+
+    Args:
+        a: The first number.
+        b: The second number.
+
+    Returns:
+        The sum of the two numbers as an integer.
+    """

aip_agents/examples/tools/adk_weather_tool.py

@@ -0,0 +1,60 @@
+"""Defines a weather tool that can be used to get the weather for a specified city.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+# Combined weather data storage with detailed information
+WEATHER_DATA = {
+    "Jakarta": {"temperature": "32°C", "conditions": "Partly cloudy with high humidity", "humidity": "78%"},
+    "Singapore": {"temperature": "30°C", "conditions": "Scattered thunderstorms", "humidity": "85%"},
+    "Tokyo": {"temperature": "25°C", "conditions": "Clear skies", "humidity": "65%"},
+    "London": {"temperature": "18°C", "conditions": "Light rain", "humidity": "82%"},
+    "New York": {"temperature": "22°C", "conditions": "Sunny", "humidity": "60%"},
+    "Sydney": {"temperature": "24°C", "conditions": "Clear", "humidity": "70%"},
+}
+
+
+def get_weather(location: str) -> dict:
+    """Gets detailed weather information for a specified location.
+
+    Args:
+        location: The name of the city to get weather for.
+
+    Returns:
+        A dictionary containing:
+            - location: The requested location name
+            - weather: A dictionary with temperature, conditions, and humidity
+    """
+    try:
+        city_name = location.split(",")[0].strip().title()
+        weather = WEATHER_DATA.get(city_name)
+
+        if weather:
+            logger.info(f"Found weather for {city_name}: {weather}")
+            return {"location": city_name, "weather": weather}
+        else:
+            message = f"Weather data not available for {location}"
+            logger.warning(message)
+            return {
+                "location": city_name,
+                "weather": {"temperature": "Unknown", "conditions": "No data available", "humidity": "Unknown"},
+                "message": message,
+            }
+    except Exception as e:
+        error_msg = f"Error getting weather for {location}: {str(e)}"
+        logger.error(error_msg)
+        return {
+            "location": location,
+            "error": error_msg,
+            "weather": {"temperature": "Error", "conditions": "Error retrieving data", "humidity": "Error"},
+        }
+
+
+# Alias for backward compatibility
+weather_tool = get_weather

aip_agents/examples/tools/adk_weather_tool.pyi

@@ -0,0 +1,18 @@
+from _typeshed import Incomplete
+from aip_agents.utils.logger import get_logger as get_logger
+
+logger: Incomplete
+WEATHER_DATA: Incomplete
+
+def get_weather(location: str) -> dict:
+    """Gets detailed weather information for a specified location.
+
+    Args:
+        location: The name of the city to get weather for.
+
+    Returns:
+        A dictionary containing:
+            - location: The requested location name
+            - weather: A dictionary with temperature, conditions, and humidity
+    """
+weather_tool = get_weather