gllm-agents-binary 0.4.23

A library for managing agents in Gen AI applications.

GLLM Agents

Description

A library for managing agents in Generative AI applications.

Installation

Prerequisites

• Python 3.13+ - Install here
• Pip (if using Pip) - Install here
• Poetry 1.8.1+ (if using Poetry) - Install here
• Git (if using Git) - Install here
• For git installation:
  • Access to the GDP Labs SDK github repository

1. Installation from Artifact Registry

Choose one of the following methods to install the package:

Using pip

pip install gllm-agents-binary

Using Poetry

poetry add gllm-agents-binary

2. Development Installation (Git)

For development purposes, you can install directly from the Git repository:

poetry add "git+ssh://[e-mail]/GDP-ADMIN/gen-ai-internal.git#subdirectory=libs/gllm-agents"

Managing Dependencies

1. Go to root folder of gllm-agents module, e.g. cd libs/gllm-agents.
2. Run poetry shell to create a virtual environment.
3. Run poetry lock to create a lock file if you haven't done it yet.
4. Run poetry install to install the gllm-agents requirements for the first time.
5. Run poetry update if you update any dependency module version at pyproject.toml.

Contributing

Please refer to this Python Style Guide to get information about code style, documentation standard, and SCA that you need to use when contributing to this project

1. Activate pre-commit hooks using pre-commit install
2. Run poetry shell to create a virtual environment.
3. Run poetry lock to create a lock file if you haven't done it yet.
4. Run poetry install to install the gllm-agents requirements for the first time.
5. Run which python to get the path to be referenced at Visual Studio Code interpreter path (Ctrl+Shift+P or Cmd+Shift+P)
6. Try running the unit test to see if it's working:

poetry run pytest -s tests/unit_tests/

Hello World Examples

Prerequisites

• Python 3.13+
• Install the binary package:

pip install gllm-agents-binary

• For OpenAI: Set your API key in the environment:

export OPENAI_API_KEY=your-openai-key

• For Google ADK: Set your API key in the environment:

export GOOGLE_API_KEY=your-google-api-key

Run the Hello World Examples

The example scripts are located in the gllm_agents/examples directory within the library. You can run them individually or use the run_all_examples.py script.

1. Running Individual Examples:

Navigate to the library's root directory (e.g., libs/gllm-agents if you cloned the repository).

LangGraph (OpenAI):

python gllm_agents/examples/hello_world_langgraph.py

LangGraph with BOSA Connector (OpenAI):

python gllm_agents/examples/hello_world_langgraph_bosa_twitter.py

LangGraph Streaming (OpenAI):

python gllm_agents/examples/hello_world_langgraph_stream.py

LangGraph Multi-Agent Coordinator (OpenAI):

python gllm_agents/examples/hello_world_a2a_multi_agent_coordinator_server.py

Google ADK:

python gllm_agents/examples/hello_world_google_adk.py

Google ADK Streaming:

python gllm_agents/examples/hello_world_google_adk_stream.py

LangChain (OpenAI):

python gllm_agents/examples/hello_world_langchain.py

LangChain Streaming (OpenAI):

python gllm_agents/examples/hello_world_langchain_stream.py

HITL (Human-in-the-Loop) Approval Demo:

python gllm_agents/examples/hitl_demo.py

2. Running MCP Examples

Prerequisites

Ensure you have set the environment variables for API keys:

export OPENAI_API_KEY="your-openai-key"
export GOOGLE_API_KEY="your-google-api-key"

For examples that use stateful MCP tools like browser automation, start the Playwright MCP server in a separate terminal:

npx @playwright/mcp@latest --headless --port 8931

Note: Use the --headless flag to run the server without a visible browser window, which is recommended if the browser is not installed yet to avoid failures. For using an actual (non-headless) browser, refer to the Playwright MCP documentation.

Local MCP Servers

For STDIO, SSE, and HTTP transports using local servers, open a terminal in the library root (libs/gllm-agents) and run:

• For STDIO:

poetry run python gllm_agents/examples/mcp_servers/mcp_server_stdio.py

• For SSE:

poetry run python gllm_agents/examples/mcp_servers/mcp_server_sse.py

• For HTTP:

poetry run python gllm_agents/examples/mcp_servers/mcp_server_http.py

Note: Start the appropriate server before running the client examples for that transport.

Running Examples

All examples are run from the library root using poetry run python gllm_agents/examples/<file>.py. Examples support OpenAI for LangGraph/LangChain and Google ADK where specified.

LangChain Examples

STDIO Transport

• Non-Streaming:

poetry run python gllm_agents/examples/hello_world_langchain_mcp_stdio.py

• Streaming:

poetry run python gllm_agents/examples/hello_world_langchain_mcp_stdio_stream.py

SSE Transport

• Non-Streaming:

poetry run python gllm_agents/examples/hello_world_langchain_mcp_sse.py

• Streaming:

poetry run python gllm_agents/examples/hello_world_langchain_mcp_sse_stream.py

HTTP Transport

• Non-Streaming:

poetry run python gllm_agents/examples/hello_world_langchain_mcp_http.py

• Streaming:

poetry run python gllm_agents/examples/hello_world_langchain_mcp_http_stream.py

Google ADK Examples

STDIO Transport

• Non-Streaming:

poetry run python gllm_agents/examples/hello_world_google_adk_mcp_stdio.py

• Streaming:

poetry run python gllm_agents/examples/hello_world_google_adk_mcp_stdio_stream.py

SSE Transport

• Non-Streaming:

poetry run python gllm_agents/examples/hello_world_google_adk_mcp_sse.py

• Streaming:

poetry run python gllm_agents/examples/hello_world_google_adk_mcp_sse_stream.py

HTTP Transport

• Non-Streaming:

poetry run python gllm_agents/examples/hello_world_google_adk_mcp_http.py

• Streaming:

poetry run python gllm_agents/examples/hello_world_google_adk_mcp_http_stream.py

LangGraph Examples (OpenAI)

STDIO Transport

• Non-Streaming:

poetry run python gllm_agents/examples/hello_world_langgraph_mcp_stdio.py

• Streaming:

poetry run python gllm_agents/examples/hello_world_langgraph_mcp_stdio_stream.py

SSE Transport

• Non-Streaming:

poetry run python gllm_agents/examples/hello_world_langgraph_mcp_sse.py

• Streaming:

poetry run python gllm_agents/examples/hello_world_langgraph_mcp_sse_stream.py

HTTP Transport

• Non-Streaming:

poetry run python gllm_agents/examples/hello_world_langgraph_mcp_http.py

• Streaming:

poetry run python gllm_agents/examples/hello_world_langgraph_mcp_http_stream.py

Multi-Server Example

This LangChain example uses multiple MCP servers: Playwright (for browser actions) and a random name generator (SSE transport) with persistent sessions across multiple arun calls.

1. Start the Playwright server:

npx @playwright/mcp@latest --headless --port 8931

2. In another terminal, start the Name Generator SSE server:

poetry run python gllm_agents/examples/mcp_servers/mcp_name.py

3. Run the multi-server client example:

poetry run python gllm_agents/examples/hello_world_langchain_mcp_multi_server.py

3. Running Individual A2A Examples:

• Navigate to the library's root directory (e.g., libs/gllm-agents if you cloned the repository).
• Open a new terminal and navigate to the gllm_agents/examples directory to run the A2A server.

LangChain Server:

python hello_world_a2a_langchain_server.py

• Open a new terminal and navigate to the gllm_agents/examples directory to run the A2A client.

LangChain Client:

python hello_world_a2a_langchain_client.py

LangChain Client Integrated with Agent Workflow:

python hello_world_a2a_langchain_client_agent.py

LangChain Client Streaming:

python hello_world_a2a_langchain_client_stream.py

Human-in-the-Loop (HITL) Approval

GLLM Agents supports Human-in-the-Loop approval for tool execution, allowing human operators to review and approve high-risk tool calls before they execute.

Features

• Configurable Approval Policies: Set approval requirements per tool with customizable timeouts and behaviors
• Interactive CLI Prompts: Clear, structured prompts showing tool details and context
• Structured Logging: All approval decisions are logged with full metadata
• Timeout Handling: Configurable behavior when approval requests time out
• Non-blocking: Tools without HITL configuration execute normally

Quick Start

Configure HITL for specific tools in your agent:

from gllm_agents.agent import LangGraphReactAgent
from gllm_agents.agent.hitl.config import ToolApprovalConfig

# Create agent with tools
agent = LangGraphReactAgent(
    name="My Agent",
    tools=[send_email_tool, search_tool],
)

# Configure HITL via tool_configs
agent.tool_configs = {
    "tool_configs": {
        "send_email": {"hitl": {"timeout_seconds": 300}}
    }
}

When the agent attempts to use the send_email tool, it will:

1. Emit a pending approval event via DeferredPromptHandler
2. Wait for ApprovalManager.resolve_pending_request() to be called
3. Execute the tool only if approved
4. Log the decision for audit purposes

Configuration Options

Option	Type	Default	Description
timeout_seconds	int	300	Seconds to wait for operator input

Logging

All HITL decisions are logged with structured data:

{
  "event": "hitl_decision",
  "tool": "send_email",
  "decision": "approved",
  "operator_input": "A",
  "latency_ms": 2500,
  "timestamp": "2025-09-25T10:15:00Z"
}

Demo

Run the interactive demo to see HITL in action:

python gllm_agents/examples/hitl_demo.py

Architectural Notes

Memory Features

The library supports Mem0 as a memory backend for long-term conversation recall. Key features:

• Automatic persistence of user-agent interactions via memory_backend="mem0".
• Semantic search for relevant past conversations.
• New built_in_mem0_search tool for explicit recall by time period (e.g., "yesterday", "last week", "July 2025").
• Date range parsing for natural language time filters using dateparser.
• Conditional auto-augmentation (disabled by default to reduce noise; enable with memory_auto_augment=True).

Mem0 Date Recall Example

Use the coordinator example with memory enabled:

poetry run python gllm_agents/examples/hello_world_a2a_mem0_coordinator_server.py

In client:

agent = LangGraphAgent(
    name="client",
    instruction="...",
    model="gpt-4o-mini",
    memory_backend="mem0",
)

Test recall: After some interactions, query "What did we discuss yesterday?" – agent uses tool to filter by created_at.

Agent Interface (AgentInterface)

The gllm_agents.agent.interface.AgentInterface class defines a standardized contract for all agent implementations within the GLLM Agents ecosystem. It ensures that different agent types (e.g., LangGraph-based, Google ADK-based) expose a consistent set of methods for core operations.

Key methods defined by AgentInterface typically include:

• arun(): For asynchronous execution of the agent that returns a final consolidated response.
• arun_stream(): For asynchronous execution that streams back partial responses or events from the agent.

By adhering to this interface, users can interact with various agents in a uniform way, making it easier to switch between or combine different agent technologies.

Inversion of Control (IoC) / Dependency Injection (DI)

The agent implementations (e.g., LangGraphAgent, GoogleADKAgent) utilize Dependency Injection. For instance, LangGraphAgent accepts an agent_executor (like one created by LangGraph's create_react_agent) in its constructor. Similarly, GoogleADKAgent accepts a native adk_native_agent. This allows the core execution logic to be provided externally, promoting flexibility and decoupling the agent wrapper from the specific instantiation details of its underlying engine.