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

aip_agents/examples/hello_world_sentry.py

@@ -0,0 +1,133 @@
+"""This is a simple FastAPI app to test Sentry with Open Telemetry from GL Connectors SDK.
+
+To run this example, make sure to set the following environment variables:
+    SENTRY_DSN
+    SENTRY_ENVIRONMENT
+    SENTRY_PROJECT
+    VERSION_NUMBER
+    BUILD_NUMBER
+    USE_OPENTELEMETRY
+
+Authors:
+    Saul Sayers (saul.sayers@gdplabs.id)
+"""
+
+import io
+import os
+import subprocess
+import sys
+import threading
+import time
+
+import uvicorn
+from fastapi import FastAPI
+from fastapi.responses import JSONResponse
+from fastapi.staticfiles import StaticFiles
+
+from aip_agents.examples.hello_world_langgraph import langgraph_example
+from aip_agents.sentry import setup_telemetry
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+BASE_URL = "http://localhost:8585"
+SENTRY_ENVIRONMENT = os.getenv("SENTRY_ENVIRONMENT", "development")
+USE_OPENTELEMETRY = os.getenv("USE_OPENTELEMETRY", "true").lower() == "true"
+
+
+def fetch_endpoints():
+    """Fetch all endpoints from the server."""
+    BASE_URL = "http://127.0.0.1:8585"
+    endpoints = [
+        "/",
+        "/langgraph-hello-world",
+        "/test-telemetry",
+        "/raise-error",
+    ]
+    for ep in endpoints:
+        url = BASE_URL + ep
+        try:
+            # Because using request.get() will trigger sentry, but the ep name is not saved.
+            # Instead of GET /langgraph-hello-world, sentry will save it as GET
+            url = f"http://127.0.0.1:8585{ep}"
+            result = subprocess.run(["curl", "-i", url], capture_output=True, text=True, check=False)
+            logger.info(result.stdout)
+        except Exception as e:
+            logger.error(f"Error fetching {ep}: {e}")
+
+
+def create_app() -> FastAPI:
+    """Create and configure the FastAPI application.
+
+    Returns:
+        FastAPI: The configured FastAPI application.
+    """
+    app = FastAPI(
+        title="GL Connectors SDK - Sentry with Open Telemetry",
+        description="This is a simple FastAPI app to test Sentry with Open Telemetry.",
+        version="0.0.1",
+        docs_url=None,
+        redoc_url="/docs",
+    )
+
+    if os.path.isdir("static"):
+        app.mount("/static", StaticFiles(directory="static"), name="static")
+    setup_telemetry(app)
+
+    @app.get("/", tags=["Root"])
+    async def index():
+        if USE_OPENTELEMETRY:
+            return {
+                "message": "Application running with Sentry + OpenTelemetry.",
+                "telemetry_mode": "Sentry with OpenTelemetry",
+                "environment": SENTRY_ENVIRONMENT,
+            }
+        else:
+            return {
+                "message": "Application running with Sentry only (no OpenTelemetry).",
+                "telemetry_mode": "Sentry only",
+                "environment": SENTRY_ENVIRONMENT,
+            }
+
+    @app.get("/langgraph-hello-world", tags=["LangGraph"])
+    async def langgraph_hello_world():
+        old_stdout = sys.stdout
+        sys.stdout = mystdout = io.StringIO()
+        try:
+            await langgraph_example()
+            output = mystdout.getvalue()
+        finally:
+            sys.stdout = old_stdout
+        return JSONResponse(content={"output": output})
+
+    @app.get("/test-telemetry", tags=["Root"])
+    async def test_telemetry():
+        return {
+            "message": "Telemetry test endpoint called.",
+            "using_opentelemetry": USE_OPENTELEMETRY,
+            "check": "Check your Sentry dashboard for traces.",
+        }
+
+    @app.get("/raise-error", tags=["Root"])
+    async def raise_error():
+        raise RuntimeError("This is a test error for Sentry!")
+
+    return app
+
+
+def run_server():
+    """Run the FastAPI server."""
+    uvicorn.run(
+        "aip_agents.examples.hello_world_sentry:create_app",
+        host="127.0.0.1",
+        port=8585,
+        factory=True,
+        log_level="info",
+    )
+
+
+if __name__ == "__main__":
+    server_thread = threading.Thread(target=run_server, daemon=True)
+    server_thread.start()
+    time.sleep(2)
+    fetch_endpoints()

aip_agents/examples/hello_world_sentry.pyi

@@ -0,0 +1,21 @@
+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 import get_logger as get_logger
+from fastapi import FastAPI
+
+logger: Incomplete
+BASE_URL: str
+SENTRY_ENVIRONMENT: Incomplete
+USE_OPENTELEMETRY: Incomplete
+
+def fetch_endpoints() -> None:
+    """Fetch all endpoints from the server."""
+def create_app() -> FastAPI:
+    """Create and configure the FastAPI application.
+
+    Returns:
+        FastAPI: The configured FastAPI application.
+    """
+def run_server() -> None:
+    """Run the FastAPI server."""

aip_agents/examples/hello_world_step_limits.py

@@ -0,0 +1,273 @@
+"""Example demonstrating configurable step limits and delegation depth tracking.
+
+This example shows how to:
+1. Configure maximum steps for an agent
+2. Configure maximum delegation depth
+3. Handle step limit exceeded errors gracefully
+4. Track delegation chains across multi-agent hierarchies
+
+Authors:
+    Saul Sayers (saul.sayers@gdplabs.id)
+"""
+
+import asyncio
+import os
+
+from langchain_openai import ChatOpenAI
+
+from aip_agents.agent import LangGraphReactAgent
+from aip_agents.examples.tools.langchain_arithmetic_tools import add_numbers
+from aip_agents.schema.step_limit import MaxStepsExceededError, StepLimitConfig
+from aip_agents.utils.step_limit_manager import StepLimitManager
+
+
+def print_config_validation(config: StepLimitConfig | None, context: str):
+    """Print step limit configuration validation."""
+    print(f"\n{'=' * 60}")
+    print(f"Configuration Validation - {context}")
+    print(f"{'=' * 60}")
+    if config is None:
+        print("✓ Config: None (will use platform defaults)")
+        print("  Expected: max_steps=25, max_delegation_depth=5")
+    else:
+        print(f"✓ max_steps: {config.max_steps}")
+        print(f"✓ max_delegation_depth: {config.max_delegation_depth}")
+
+        # Validate ranges
+        if 1 <= config.max_steps <= 1000:
+            print("  ✓ max_steps is valid (1-1000)")
+        else:
+            print("  ✗ max_steps is INVALID (should be 1-1000)")
+
+        if 0 <= config.max_delegation_depth <= 10:
+            print("  ✓ max_delegation_depth is valid (0-10)")
+        else:
+            print("  ✗ max_delegation_depth is INVALID (should be 0-10)")
+    print(f"{'=' * 60}\n")
+
+
+async def test_case_1_success_no_limits():
+    """Test Case 1: Success - High limits, no warnings."""
+    print("\n" + "=" * 60)
+    print("TEST CASE 1: Success - High Limits (No Warnings)")
+    print("=" * 60)
+
+    model = ChatOpenAI(model="gpt-4o-mini", temperature=0)
+    tools = [add_numbers]
+
+    # Very high limits - should complete successfully
+    step_limit_config = StepLimitConfig(
+        max_steps=100,  # High limit
+        max_delegation_depth=5,  # High depth
+    )
+
+    print_config_validation(step_limit_config, "High Limits")
+
+    agent = LangGraphReactAgent(
+        name="SuccessAgent",
+        instruction="You are a helpful math assistant.",
+        model=model,
+        tools=tools,
+    )
+
+    query = "What is 5 + 3?"
+    print(f"Query: {query}")
+    print("Expected: Should complete successfully without warnings\n")
+
+    try:
+        response = await agent.arun(
+            query=query,
+            step_limit_config=step_limit_config,
+            configurable={"thread_id": "test_case_1"},
+        )
+        print(f"✅ SUCCESS: {response['output']}")
+        print("✅ Test passed: Agent completed without hitting limits\n")
+    except Exception as e:
+        print(f"❌ FAILED: {e}\n")
+
+
+async def test_case_2_parallel_tool_batch_accounting():
+    """Test Case 2: Demonstrate that parallel tool batches consume multiple steps."""
+    manager = StepLimitManager(StepLimitConfig(max_steps=6))
+    print("\n" + "=" * 60)
+    print("TEST CASE 2: Parallel Tool Batch Accounting")
+    print("=" * 60)
+    print("Simulating one agent reasoning step plus 5 parallel tool calls.\n")
+
+    print(f"Initial steps: {manager.context.current_step}, remaining budget: {manager.context.remaining_step_budget}")
+    manager.increment_step()  # Agent LLM call
+    print(
+        f"After agent turn -> steps: {manager.context.current_step}, remaining: {manager.context.remaining_step_budget}"
+    )
+
+    # Simulate a batch of 5 tool calls executed in parallel
+    manager.increment_step(count=5)
+    print("After 5 parallel tool calls (count=5):")
+    print(f"Steps used: {manager.context.current_step}, remaining: {manager.context.remaining_step_budget}")
+
+    # Ensure limit is enforced now
+    try:
+        manager.check_step_limit()
+    except MaxStepsExceededError as exc:
+        print(f"✅ Limit enforcement triggered immediately: {exc}")
+        return
+
+    print("❌ Expected the limit to be hit after consuming 6 steps, but it was not.")
+
+
+async def test_case_3_step_limit_exceeded():
+    """Test Case 3: Step Limit Exceeded - Only 2 steps allowed."""
+    print("\n" + "=" * 60)
+    print("TEST CASE 3: Step Limit Exceeded (max_steps=2)")
+    print("=" * 60)
+
+    model = ChatOpenAI(model="gpt-4o-mini", temperature=0)
+    tools = [add_numbers]
+
+    # Very low step limit - will hit limit
+    step_limit_config = StepLimitConfig(
+        max_steps=2,  # Only 2 steps: 1 for thinking, 1 for tool call
+        max_delegation_depth=0,
+    )
+
+    print_config_validation(step_limit_config, "Very Low Step Limit")
+
+    agent = LangGraphReactAgent(
+        name="LimitedAgent",
+        instruction="You are a helpful math assistant. Always use the add_numbers tool.",
+        model=model,
+        tools=tools,
+    )
+
+    query = "Use the add_numbers tool to calculate 7 + 8, then add 10 to the result"
+    print(f"Query: {query}")
+    print("Expected: Should hit step limit after 2 steps\n")
+    print("Step 0: Initial LLM call")
+    print("Step 1: Tool call (add_numbers)")
+    print("Step 2: Would be final response, but LIMIT HIT!\n")
+
+    try:
+        response = await agent.arun(
+            query=query,
+            step_limit_config=step_limit_config,
+            configurable={"thread_id": "test_case_3"},
+        )
+        output = response["output"]
+        print(f"Response: {output}\n")
+
+        # Check if the response indicates limit was hit
+        if "exceeded" in output.lower() or "limit" in output.lower():
+            print("✅ SUCCESS: Step limit was enforced!")
+            print("✅ Test passed: Agent terminated at limit\n")
+        else:
+            print("⚠️  Agent completed without hitting limit")
+            print("   (This might happen if task was very simple)\n")
+    except Exception as e:
+        print(f"Exception raised: {type(e).__name__}: {e}")
+        print("✅ Test passed: Step limit enforced via exception\n")
+
+
+async def test_case_4_delegation_depth_exceeded():
+    """Test Case 4: Delegation Depth Exceeded - Zero depth."""
+    print("\n" + "=" * 60)
+    print("TEST CASE 4: Delegation Depth Exceeded (depth=0)")
+    print("=" * 60)
+
+    model = ChatOpenAI(model="gpt-4o-mini", temperature=0)
+
+    # Create sub-agent
+    math_agent = LangGraphReactAgent(
+        name="MathAgent",
+        instruction="You are a math specialist. Use add_numbers tool for calculations.",
+        model=model,
+        tools=[add_numbers],
+    )
+
+    # Create coordinator
+    coordinator = LangGraphReactAgent(
+        name="Coordinator",
+        instruction="You coordinate tasks. You MUST delegate all math to MathAgent using the delegate_to_agent tool.",
+        model=model,
+        tools=[],
+    )
+    coordinator.register_delegation_agents([math_agent])
+
+    # Zero delegation depth - should block delegation
+    step_limit_config = StepLimitConfig(
+        max_steps=50,  # High steps
+        max_delegation_depth=0,  # NO delegation allowed!
+    )
+
+    print_config_validation(step_limit_config, "Zero Delegation Depth")
+
+    query = "Delegate to MathAgent to calculate 20 + 30"
+    print(f"Query: {query}")
+    print("Expected: Delegation should be BLOCKED (depth=0)\n")
+    print("The coordinator will try to delegate but should get an error\n")
+
+    try:
+        response = await coordinator.arun(
+            query=query,
+            step_limit_config=step_limit_config,
+            configurable={"thread_id": "test_case_4"},
+        )
+        output = response["output"]
+        print(f"Response: {output}\n")
+
+        # Check if delegation was blocked
+        if (
+            "cannot" in output.lower()
+            or "depth" in output.lower()
+            or "exceeded" in output.lower()
+            or "error" in output.lower()
+        ):
+            print("✅ SUCCESS: Delegation depth limit enforced!")
+            print("✅ Test passed: Delegation was blocked\n")
+        else:
+            print("⚠️  Agent responded without delegating")
+            print("   (Coordinator may have answered directly instead)\n")
+    except Exception as e:
+        print(f"Exception raised: {type(e).__name__}: {e}")
+        if "delegation" in str(e).lower() or "depth" in str(e).lower():
+            print("✅ Test passed: Delegation depth enforced via exception\n")
+        else:
+            print("⚠️  Different error occurred\n")
+
+
+async def main():
+    """Run all test cases."""
+    print("=" * 60)
+    print("Step Limit Configuration - Test Suite")
+    print("=" * 60)
+    print("\nRunning 4 test cases:")
+    print("1. Success with high limits")
+    print("2. Parallel tool batch accounting demo")
+    print("3. Step limit exceeded")
+    print("4. Delegation depth exceeded")
+    print("\nNOTE: Some limits are enforced silently via the agent's")
+    print("      internal logic. Check for error messages in responses.")
+
+    await test_case_1_success_no_limits()
+    await test_case_2_parallel_tool_batch_accounting()
+    await test_case_3_step_limit_exceeded()
+    await test_case_4_delegation_depth_exceeded()
+
+    print("\n" + "=" * 60)
+    print("All test cases completed!")
+    print("=" * 60)
+    print("\n📝 Summary:")
+    print("- Test 1: Should show successful completion")
+    print("- Test 2: Shows that parallel tool batches consume multiple steps at once")
+    print("- Test 3: Should show step limit enforcement")
+    print("- Test 4: Should show delegation blocking")
+
+
+if __name__ == "__main__":
+    # Check for API key
+    if not os.getenv("OPENAI_API_KEY"):
+        print("ERROR: OPENAI_API_KEY environment variable not set!")
+        print("Please set it before running:")
+        print('export OPENAI_API_KEY="your-key-here"')
+        exit(1)
+
+    asyncio.run(main())

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

@@ -0,0 +1,103 @@
+"""Stock Market A2A Server Example.
+
+This server provides stock market information and can be used as an A2A agent.
+
+To run:
+    python aip_agents/examples/hello_world_stock_a2a_server.py --port 8002
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+import os
+
+import click
+import uvicorn
+from a2a.types import AgentCapabilities, AgentCard, AgentSkill
+from langchain_core.tools import BaseTool
+from langchain_openai import ChatOpenAI
+
+from aip_agents.agent import LangGraphAgent
+from aip_agents.examples.tools.stock_tools import StockNewsInput, StockPriceInput, get_stock_news, get_stock_price
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+SERVER_AGENT_NAME = "StockAgent"
+
+
+stock_tools: list[BaseTool] = [get_stock_price, get_stock_news]
+
+
+@click.command()
+@click.option("--host", "host", default="0.0.0.0", 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):
+    """Runs the StockAgent A2A server.
+
+    Args:
+        host (str): Host to bind the server to.
+        port (int): 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="Provides stock market information including prices and news.",
+        url=f"http://{host}:{port}",
+        version="1.0.0",
+        defaultInputModes=["text"],
+        defaultOutputModes=["text"],
+        capabilities=AgentCapabilities(streaming=True, tools=True),
+        skills=[
+            AgentSkill(
+                id="get_stock_price",
+                name="Get Stock Price",
+                description="Retrieves the current stock price and performance data for a given symbol.",
+                examples=["What's the price of AAPL?", "Stock price for MSFT"],
+                tags=["finance", "stocks", "price"],
+                input_schema=StockPriceInput.model_json_schema(),
+            ),
+            AgentSkill(
+                id="get_stock_news",
+                name="Get Stock News",
+                description="Fetches recent news articles for a specified stock symbol.",
+                examples=[
+                    "Latest news for GOOGL",
+                    "Stock news for TSLA over last 3 days",
+                ],
+                tags=["finance", "stocks", "news"],
+                input_schema=StockNewsInput.model_json_schema(),
+            ),
+        ],
+        tags=["finance", "stocks"],
+    )
+
+    # For A2A, the LLM is used by the *client* agent to decide to call this agent.
+    # This agent itself just executes its tools based on the A2A request.
+    # However, LangGraphAgent requires an LLM, so we provide a basic one.
+    llm = ChatOpenAI(
+        model="gpt-4.1",
+        temperature=0,
+        streaming=True,
+        openai_api_key=os.getenv("OPENAI_API_KEY"),
+    )
+
+    langgraph_agent = LangGraphAgent(
+        name=SERVER_AGENT_NAME,
+        instruction="You are a Stock Agent. You can get stock prices and news. Use your tools to answer user queries.",
+        model=llm,
+        tools=stock_tools,
+        verbose=True,
+    )
+
+    app = langgraph_agent.to_a2a(
+        agent_card=agent_card,
+    )
+
+    logger.info("A2A application configured. Starting Uvicorn server...")
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    main()

aip_agents/examples/hello_world_stock_a2a_server.pyi

@@ -0,0 +1,17 @@
+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 import get_logger as get_logger
+from langchain_core.tools import BaseTool as BaseTool
+
+logger: Incomplete
+SERVER_AGENT_NAME: str
+stock_tools: list[BaseTool]
+
+def main(host: str, port: int):
+    """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.py

@@ -0,0 +1,55 @@
+"""Simple A2A client demonstrating tool output management.
+
+This client connects to the data visualization server and demonstrates
+how tools can reference each other's outputs using the tool output
+management system.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+import asyncio
+
+from dotenv import load_dotenv
+
+from aip_agents.agent import LangGraphReactAgent
+from aip_agents.schema.agent import A2AClientConfig
+
+load_dotenv()
+
+
+async def main():
+    """Demonstrate tool output management with data visualization."""
+    # Create client agent
+    client = LangGraphReactAgent(
+        name="Client",
+        instruction="You request data visualization services.",
+        model="openai/gpt-4o-mini",
+    )
+
+    # Discover server agent
+    agents = client.discover_agents(A2AClientConfig(discovery_urls=["http://localhost:8885"]))
+    server_agent = agents[0]
+
+    async for chunk in client.astream_to_agent(
+        server_agent,
+        "Generate sales data for 1000 months and create a bar chart from it",
+    ):
+        if chunk.get("content"):
+            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")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

aip_agents/examples/hello_world_tool_output_client.pyi

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