aip-agents-binary 0.6.4__py3-none-any.whl

aip_agents/examples/hello_world_langchain_mcp_http_interactive.py

@@ -0,0 +1,130 @@
+"""Interactive example showing LangChain agent with MCP tools integration using Streamable HTTP transport.
+
+This script provides an interactive CLI interface with chat history functionality,
+similar to hello_world_model_switch_cli.py, but with MCP tools via HTTP transport.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+import asyncio
+import os
+
+from langchain_core.messages import AIMessage, HumanMessage, SystemMessage
+
+from aip_agents.agent import LangChainAgent
+from aip_agents.utils.env_loader import load_local_env
+
+load_local_env()
+
+
+def print_help():
+    """Prints available commands and their descriptions."""
+    help_text = (
+        "\nAvailable commands:\n"
+        "  /help    Show this help message\n"
+        "  /exit    Quit the chat\n"
+        "Type anything else to chat with the assistant.\n"
+    )
+    print(help_text)
+
+
+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.
+    """
+    url = "https://huggingface.co/mcp"
+    token = os.getenv("TEST_HF_TOKEN")
+
+    missing = [
+        name
+        for name, value in {
+            "TEST_HF_TOKEN": token,
+        }.items()
+        if not value
+    ]
+
+    if missing:
+        missing_vars = ", ".join(missing)
+        raise RuntimeError(
+            "Missing required environment variables for MCP configuration: "
+            f"{missing_vars}. Please set them before running the example."
+        )
+
+    return {
+        "mcp_server": {
+            "url": url,
+            "transport": "http",
+            "headers": {
+                "Authorization": f"Bearer {token}",
+            },
+        }
+    }
+
+
+async def main():
+    """Runs the interactive LangChainAgent with MCP tools via Streamable HTTP transport."""
+    print("Welcome to the Interactive LangChain MCP HTTP Example!")
+    print("🎯 Demonstrating MCP tools integration with HTTP transport:")
+    print("  • Web browsing capabilities via Playwright tools")
+    print()
+    print("Type your message, or type /help to show available commands, or /exit to quit.")
+
+    # Initialize the agent with MCP tools
+    langchain_agent = LangChainAgent(
+        name="interactive_langchain_mcp_example",
+        instruction=("You are a helpful assistant."),
+        # Using a basic model for the example - you can adjust this as needed
+        model="openai/gpt-4.1",  # Changed to a string identifier for consistency
+    )
+    mcp_config = build_mcp_config_from_env()
+    langchain_agent.add_mcp_server(mcp_config)
+
+    # Conversation history as LangChain message objects
+    messages = [SystemMessage(content="You are a helpful assistant.")]
+
+    while True:
+        user_input = input("You: ").strip()
+        if user_input.lower() == "/help":
+            print_help()
+            continue
+        if user_input.lower() == "/exit":
+            print("Goodbye!")
+            break
+        elif user_input == "":
+            continue
+
+        # Add user message to history
+        messages.append(HumanMessage(content=user_input))
+
+        # Run the agent with history
+        try:
+            # Pass the conversation history to the agent
+            response = await langchain_agent.arun(query=user_input, messages=messages[:-1])
+
+            # Extract AI message (should be last in response state)
+            output = response.get("output")
+            ai_message = None
+
+            # Try to find the returned messages in the response (standard pattern)
+            if "messages" in response and response["messages"]:
+                # Use the last message as the AI reply
+                ai_message = response["messages"][-1]
+            elif output:
+                ai_message = AIMessage(content=output)
+            else:
+                ai_message = AIMessage(content=str(response))
+
+            messages.append(ai_message)
+            print(f"Agent: {ai_message.content}")
+        except Exception as e:
+            print(f"Error: {e}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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_http_stream.py

@@ -0,0 +1,42 @@
+"""Example showing LangChain agent with MCP tools integration.
+
+Transport: Streamable HTTP
+Streaming: Yes
+
+This example demonstrates how to create a LangChain agent that can use tools
+from MCP servers via Streamable HTTP transport while streaming the response
+in real-time.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+import asyncio
+
+from langchain_openai import ChatOpenAI
+
+from aip_agents.agent import LangChainAgent
+from aip_agents.examples.mcp_configs.configs import mcp_config_http
+
+
+async def main():
+    """Demonstrates the LangChainAgent with MCP tools via Streamable HTTP transport and streaming capabilities."""
+    langchain_agent = LangChainAgent(
+        name="langchain_mcp_stream_example",
+        instruction="""You are a helpful assistant that can browse the web.""",
+        model=ChatOpenAI(model="gpt-4.1", temperature=0),
+    )
+    langchain_agent.add_mcp_server(mcp_config_http)
+
+    async for chunk in langchain_agent.arun_stream(query="What's the latest news about FC Barcelona?"):
+        if isinstance(chunk, str):
+            print(chunk, end="", flush=True)
+
+    # run again to make sure it use persistent session
+    async for chunk in langchain_agent.arun_stream(query="What's the latest news about UEFA Champions League?"):
+        if isinstance(chunk, str):
+            print(chunk, end="", flush=True)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

aip_agents/examples/hello_world_langchain_mcp_http_stream.pyi

@@ -0,0 +1,5 @@
+from aip_agents.agent import LangChainAgent as LangChainAgent
+from aip_agents.examples.mcp_configs.configs import mcp_config_http as mcp_config_http
+
+async def main() -> None:
+    """Demonstrates the LangChainAgent with MCP tools via Streamable HTTP transport and streaming capabilities."""

aip_agents/examples/hello_world_langchain_mcp_multi_server.py

@@ -0,0 +1,155 @@
+"""Demo: LangChain agent with allowed_tools whitelist filtering.
+
+Shows how allowed_tools restricts tool access across 3 MCP servers:
+- STDIO: only get_current_time allowed (not generate_uuid or get_weather_forecast)
+- SSE: only get_random_quote allowed (not word_count or get_weather_forecast)
+- HTTP: only get_random_fact allowed (not convert_to_base64 or get_weather_forecast)
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+import asyncio
+import logging
+from typing import Any
+
+from langchain_openai import ChatOpenAI
+
+from aip_agents.agent import LangChainAgent
+from aip_agents.examples.mcp_configs.configs import mcp_tool_whitelisting_demo
+from aip_agents.schema.a2a import A2AStreamEventType
+from aip_agents.utils.logger import logger_manager
+
+
+def _normalize_event_type(raw_value: Any) -> A2AStreamEventType | None:
+    """Convert raw event_type payloads (enum or string) into A2AStreamEventType.
+
+    Args:
+        raw_value: Event type payload emitted by the agent stream (enum or string).
+
+    Returns:
+        Parsed A2AStreamEventType value, or None when the payload is unrecognized.
+    """
+    if isinstance(raw_value, A2AStreamEventType):
+        return raw_value
+    if isinstance(raw_value, str):
+        try:
+            return A2AStreamEventType(raw_value.lower())
+        except ValueError:
+            return None
+    return None
+
+
+def _log_tool_call(event: dict[str, Any], is_allowed: bool) -> bool:
+    """Log tool call events and return True if at least one call existed.
+
+    Args:
+        event: A2A event payload containing tool_call metadata.
+        is_allowed: Whether the current query is expected to hit an allowed tool.
+
+    Returns:
+        True when at least one tool call entry is present; False otherwise.
+    """
+    tool_info = event.get("tool_info") or {}
+    tool_calls = tool_info.get("tool_calls") or []
+    if not tool_calls:
+        print("⚠️ Tool call event received without tool_calls payload")
+        return False
+
+    first_call = tool_calls[0]
+    tool_name = first_call.get("name", "unknown")
+    icon = "⚠️" if not is_allowed else "✅"
+    print(f"{icon} Tool called: {tool_name}")
+    return True
+
+
+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.
+    """
+    print(f"\nQuery: {query}")
+    tool_called = False
+    final_response = None
+    try:
+        async for event in agent.arun_a2a_stream(query=query):
+            event_type = _normalize_event_type(event.get("event_type"))
+            if event_type is None:
+                print(f"⚠️ Unknown event type payload: {event.get('event_type')!r}")
+                continue
+
+            if event_type is A2AStreamEventType.TOOL_CALL:
+                tool_called = _log_tool_call(event, is_allowed) or tool_called
+                continue
+
+            if event_type is A2AStreamEventType.FINAL_RESPONSE:
+                final_response = event.get("content")
+                break
+    except Exception as e:
+        print(f"❌ Error processing query: {e}")
+        return False
+    if final_response:
+        print(f"🧠 LLM response: {final_response}")
+    if not tool_called:
+        print("✅ No tool called (blocked or LLM answered directly)")
+    return tool_called
+
+
+async def main():
+    """Demo allowed_tools filtering with 3 MCP servers (STDIO, SSE, HTTP)."""
+    logger_manager.set_level(logging.WARNING)
+
+    agent = LangChainAgent(
+        name="allowed_tools_demo",
+        instruction=(
+            "You are a helpful assistant with access to tools from 3 MCP servers.\n"
+            "Use the available tools to answer questions.\n"
+            "Note: Each server has specific tools whitelisted via allowed_tools."
+        ),
+        model=ChatOpenAI(model="gpt-4.1-mini"),
+    )
+    agent.add_mcp_server(mcp_tool_whitelisting_demo)
+
+    all_allowed_queries_called_tools = True
+    any_disallowed_query_called_tools = False
+
+    print("\n=== ALLOWED TOOLS (should work) ===")
+    allowed_queries = [
+        "Get the current time for me",
+        "Tell me an inspirational quote",
+        "Share a fun fact with me",
+    ]
+    for query in allowed_queries:
+        called = await process_query(agent, query, is_allowed=True)
+        all_allowed_queries_called_tools = all_allowed_queries_called_tools and called
+
+    print("\n\n=== DISALLOWED TOOLS (should fail or skip) ===")
+    disallowed_queries = [
+        "Generate a UUID for me",  # Not allowed from STDIO
+        "Get the weather forecast for Jakarta",  # Not allowed from any server
+        "Count words in 'hello world'",  # Not allowed from SSE
+    ]
+    for query in disallowed_queries:
+        called = await process_query(agent, query, is_allowed=False)
+        any_disallowed_query_called_tools = any_disallowed_query_called_tools or called
+
+    print("\n=== SUMMARY: allowed_tools vs disabled_tools behavior ===")
+    if all_allowed_queries_called_tools:
+        print("✅ allowed_tools: All allowed queries called tools as expected.")
+    else:
+        print("❌ allowed_tools: Some allowed queries did not call any tools.")
+
+    if any_disallowed_query_called_tools:
+        print("❌ disabled_tools: Some disallowed queries still called tools.")
+    else:
+        print("✅ disabled_tools: No tools were called for any disallowed queries.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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_langchain_mcp_sse.py

@@ -0,0 +1,34 @@
+"""Example showing LangChain agent with MCP tools integration using SSE transport.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+import asyncio
+
+from langchain_openai import ChatOpenAI
+
+from aip_agents.agent import LangChainAgent
+from aip_agents.examples.mcp_configs.configs import mcp_config_sse
+
+
+async def main():
+    """Demonstrates the LangChainAgent with MCP tools via SSE transport."""
+    langchain_agent = LangChainAgent(
+        name="langchain_mcp_example",
+        instruction=(
+            "You are a helpful assistant that can browse the web. If you are blocked by captcha, try another website."
+        ),
+        model=ChatOpenAI(model="gpt-4.1", temperature=0),
+    )
+    langchain_agent.add_mcp_server(mcp_config_sse)
+
+    response = await langchain_agent.arun(query="What's the rating of the movie 'The Matrix'? browse it")
+    print(response["output"])
+    print("-" * 50)
+    response = await langchain_agent.arun(query="When is the next solar eclipse?, browse it")
+    print(response["output"])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

aip_agents/examples/hello_world_langchain_mcp_sse.pyi

@@ -0,0 +1,5 @@
+from aip_agents.agent import LangChainAgent as LangChainAgent
+from aip_agents.examples.mcp_configs.configs import mcp_config_sse as mcp_config_sse
+
+async def main() -> None:
+    """Demonstrates the LangChainAgent with MCP tools via SSE transport."""

aip_agents/examples/hello_world_langchain_mcp_sse_stream.py

@@ -0,0 +1,40 @@
+"""Example showing LangChain agent with MCP tools integration and streaming capabilities using SSE transport.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+import asyncio
+
+from langchain_openai import ChatOpenAI
+
+from aip_agents.agent import LangChainAgent
+from aip_agents.examples.mcp_configs.configs import mcp_config_sse
+
+
+async def main():
+    """Demonstrates the LangChainAgent with MCP tools via SSE transport and streaming capabilities."""
+    langchain_agent = LangChainAgent(
+        name="langchain_mcp_stream_example",
+        instruction="""You are a helpful assistant that can browse the web using playwright tools.""",
+        model=ChatOpenAI(model="gpt-4.1", temperature=0),
+    )
+    langchain_agent.add_mcp_server(mcp_config_sse)
+
+    full_response = ""
+    async for chunk in langchain_agent.arun_stream(
+        query="What are the result of Copa Del Rey Final in 2024/2025 season, browse it.",
+    ):
+        if isinstance(chunk, str):
+            print(chunk, end="", flush=True)
+            full_response += chunk
+        elif isinstance(chunk, dict) and "messages" in chunk:
+            print("\n(Stream finished with final state object)")
+        elif isinstance(chunk, dict):
+            pass
+
+    print(full_response)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

aip_agents/examples/hello_world_langchain_mcp_sse_stream.pyi

@@ -0,0 +1,5 @@
+from aip_agents.agent import LangChainAgent as LangChainAgent
+from aip_agents.examples.mcp_configs.configs import mcp_config_sse as mcp_config_sse
+
+async def main() -> None:
+    """Demonstrates the LangChainAgent with MCP tools via SSE transport and streaming capabilities."""

aip_agents/examples/hello_world_langchain_mcp_stdio.py

@@ -0,0 +1,30 @@
+"""Example showing LangChain agent with MCP tools integration using stdio transport.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+import asyncio
+
+from langchain_openai import ChatOpenAI
+
+from aip_agents.agent import LangChainAgent
+from aip_agents.examples.mcp_configs.configs import mcp_config_stdio
+
+
+async def main():
+    """Demonstrates the LangChainAgent with MCP tools via stdio transport."""
+    langchain_agent = LangChainAgent(
+        name="langchain_mcp_example",
+        instruction="""You are a helpful assistant that can provide weather forecasts.
+        For weather, specify the day in lowercase (e.g., 'monday').""",
+        model=ChatOpenAI(model="gpt-4.1", temperature=0),
+    )
+    langchain_agent.add_mcp_server(mcp_config_stdio)
+
+    response = await langchain_agent.arun(query="What's the weather forecast for monday?")
+    print(response["output"])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

aip_agents/examples/hello_world_langchain_mcp_stdio.pyi

@@ -0,0 +1,5 @@
+from aip_agents.agent import LangChainAgent as LangChainAgent
+from aip_agents.examples.mcp_configs.configs import mcp_config_stdio as mcp_config_stdio
+
+async def main() -> None:
+    """Demonstrates the LangChainAgent with MCP tools via stdio transport."""

aip_agents/examples/hello_world_langchain_mcp_stdio_stream.py

@@ -0,0 +1,41 @@
+"""Example showing LangChain agent with MCP tools integration and streaming capabilities using stdio transport.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+import asyncio
+
+from langchain_openai import ChatOpenAI
+
+from aip_agents.agent import LangChainAgent
+from aip_agents.examples.mcp_configs.configs import mcp_config_stdio
+
+
+async def main():
+    """Demonstrates the LangChainAgent with MCP tools via stdio transport and streaming capabilities."""
+    langchain_agent = LangChainAgent(
+        name="langchain_mcp_stream_example",
+        instruction="""You are a helpful assistant that can provide weather forecasts.
+        For weather, specify the day in lowercase (e.g., 'monday').""",
+        model=ChatOpenAI(model="gpt-4.1", temperature=0),
+    )
+    langchain_agent.add_mcp_server(mcp_config_stdio)
+
+    full_response = ""
+    async for chunk in langchain_agent.arun_stream(
+        query="What's the weather forecast for monday?",
+    ):
+        if isinstance(chunk, str):
+            print(chunk, end="", flush=True)
+            full_response += chunk
+        elif isinstance(chunk, dict) and "messages" in chunk:
+            print("\n(Stream finished with final state object)")
+        elif isinstance(chunk, dict):
+            pass
+
+    print(full_response)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

aip_agents/examples/hello_world_langchain_mcp_stdio_stream.pyi

@@ -0,0 +1,5 @@
+from aip_agents.agent import LangChainAgent as LangChainAgent
+from aip_agents.examples.mcp_configs.configs import mcp_config_stdio as mcp_config_stdio
+
+async def main() -> None:
+    """Demonstrates the LangChainAgent with MCP tools via stdio transport and streaming capabilities."""

aip_agents/examples/hello_world_langchain_stream.py

@@ -0,0 +1,36 @@
+"""Minimal LangChain agent example demonstrating streaming capabilities.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+
+"""
+
+import asyncio
+
+from langchain_openai import ChatOpenAI
+
+from aip_agents.agent import LangChainAgent
+from aip_agents.examples.tools.langchain_arithmetic_tools import add_numbers
+
+
+async def langchain_stream_example():
+    """Demonstrates the LangChainAgent's arun_stream method with async execution."""
+    agent = LangChainAgent(
+        name="LangChainStreamingCalculator",
+        instruction="You are a helpful calculator assistant that can add numbers. "
+        "When asked to add numbers, use the add_numbers tool. "
+        "Explain your steps clearly for streaming demonstration.",
+        model=ChatOpenAI(model="gpt-4.1", temperature=0),
+        tools=[add_numbers],
+    )
+
+    # Stream the response chunks
+    async for chunk in agent.arun_stream(
+        query="What is the sum of 23 and 47? And then add 10 to that, then add 5 more."
+    ):
+        if isinstance(chunk, str):
+            print(chunk, end="", flush=True)
+
+
+if __name__ == "__main__":
+    asyncio.run(langchain_stream_example())

aip_agents/examples/hello_world_langchain_stream.pyi

@@ -0,0 +1,5 @@
+from aip_agents.agent import LangChainAgent as LangChainAgent
+from aip_agents.examples.tools.langchain_arithmetic_tools import add_numbers as add_numbers
+
+async def langchain_stream_example() -> None:
+    """Demonstrates the LangChainAgent's arun_stream method with async execution."""

aip_agents/examples/hello_world_langchain_stream_lm_invoker.py

@@ -0,0 +1,39 @@
+"""Minimal LangChain agent example demonstrating streaming capabilities.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+import asyncio
+
+import dotenv
+
+from aip_agents.agent import LangChainAgent
+from aip_agents.examples.tools.langchain_arithmetic_tools import add_numbers
+
+dotenv.load_dotenv(override=True)
+
+
+async def langchain_stream_example():
+    """Demonstrates the LangChainAgent's arun_stream method with async execution."""
+    agent = LangChainAgent(
+        name="LangChainStreamingCalculator",
+        instruction="You are a helpful calculator assistant that can add numbers. "
+        "When asked to add numbers, use the add_numbers tool. "
+        "Explain your steps clearly for streaming demonstration.",
+        model="openai/gpt-4o",
+        tools=[add_numbers],
+    )
+
+    # Stream the response chunks
+    async for chunk in agent.arun_stream(
+        query="What is the sum of 23 and 47? And then add 10 to that, then add 5 more."
+    ):
+        if isinstance(chunk, str):
+            print(chunk, end="", flush=True)  # Print text chunks as they come in
+        elif isinstance(chunk, dict):
+            print(f"Dict chunk: {chunk}")
+
+
+if __name__ == "__main__":
+    asyncio.run(langchain_stream_example())

aip_agents/examples/hello_world_langchain_stream_lm_invoker.pyi

@@ -0,0 +1,5 @@
+from aip_agents.agent import LangChainAgent as LangChainAgent
+from aip_agents.examples.tools.langchain_arithmetic_tools import add_numbers as add_numbers
+
+async def langchain_stream_example() -> None:
+    """Demonstrates the LangChainAgent's arun_stream method with async execution."""