AIP Agents

Python 3.13 support starts with aip-agents 0.6.141. Due to an issue with Python >=3.13.12, support for that version range starts with aip-agents 0.6.152. Python 3.12 remains the preferred version.

Description

The core agent library for local execution in GL AIP (GDP Labs AI Agents Package). aip-agents is part of the GL AIP ecosystem:

• aip-agents (this library) — The underlying agent library for local execution
• ai-agent-platform — The platform that provides remote server/run capabilities (uses aip-agents internally)
• glaip-sdk — The SDK that end users use to run agents either locally (directly via aip-agents) or on the remote server (via ai-agent-platform)

You can use aip-agents directly for local execution, or let glaip-sdk manage local vs remote mode for you. See the GL AIP overview for the full architecture.

Installation

Prerequisites

• Python 3.11 - 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 repository

1. Installation from the GDP Labs registry

This package is published to the internal GDP Labs registry. Ensure your pip/Poetry config includes the registry: https://glsdk.gdplabs.id/gen-ai-internal/simple/.

Using pip

pip install aip-agents

Using Poetry

poetry add aip-agents

2. Development Installation (Git)

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

poetry add "git+ssh://git@github.com/GDP-ADMIN/glaip-sdk.git#subdirectory=python/aip-agents"

3. Recommended: install via glaip-sdk for local mode

If you want local + remote compatibility, install the SDK's local extra instead:

pip install "glaip-sdk[local]"

Optional Extras

pip install "aip-agents[google]"
pip install "aip-agents[google-adk]"
pip install "aip-agents[memory]"
pip install "aip-agents[privacy]"

• google: Enable GoogleADKAgent plus A2UI support for the umbrella Google install.
• google-adk: Enable GoogleADKAgent and Google ADK MCP client integration.

Skills (PR-001 Foundation)

The Skills installer relies on GL Connectors SkillFactory. To install skills from GitHub, install the skills extra so gl-connectors-tools>=0.0.6 is available.

pip install "aip-agents[skills]"

from aip_agents.skills import Skill

skill = await Skill.from_github(
    source="https://github.com/anthropics/skills/tree/main/skills/brand-guidelines",
    destination_root=".agents/skills",
)

assert skill.name == "brand-guidelines"

If you only need to load an already-installed skill, use Skill.from_path(...).

Skill staging copies all resource files — both UTF-8 text and binary assets (images, PDFs, archives) — into the configured backend via write / write_bytes. A resource manifest is written at /skills/<skill>/.aip-skill-index.json with each resource's relative path, type classification (instruction/reference/example/script/asset), binary flag, and content summary. Noise directories such as .git, .venv, and node_modules are excluded.

When SkillsMiddleware receives multiple GitHub sources (for example, skills=["...", "..."]), it now attempts every install before failing. If one or more sources fail, middleware raises a single SkillInstallError that summarizes failed source URLs and underlying errors. This compatibility handling targets the upstream SkillFactory.create_multiple breaking-change line described in GDP-ADMIN/gl-connectors-sdk PR #699 (BatchResult + non-fail-fast behavior).

Integration Facade

Cross-package consumers such as glaip-sdk should import local-runtime boundary contracts from aip_agents.integration rather than reaching into deep internal modules.

Current contract modules:

• aip_agents.integration.agent
• aip_agents.integration.guardrails
• aip_agents.integration.hitl
• aip_agents.integration.ptc
• aip_agents.integration.skills
• aip_agents.integration.storage

The initial public contract version is v1 via aip_agents.integration.integration_contract_version.

The following deep paths are non-contract surfaces and may change without notice even when the facade currently re-exports related behavior:

• aip_agents.agent.hitl.*
• aip_agents.guardrails.engines.*
• aip_agents.guardrails.manager
• aip_agents.guardrails.schemas
• aip_agents.ptc.custom_tools
• aip_agents.ptc.naming
• aip_agents.ptc.tool_def_helpers
• aip_agents.storage.clients.*
• aip_agents.storage.providers.*
• aip_agents.utils.langgraph.tool_output_management

During the additive migration window, existing deep imports may still work, but new cross-package integrations should target the facade namespace only.

The legacy aip_agents.agent runtime import inventory and compatibility risks are captured in docs/public-agent-api-compatibility.md.

A2UI Support (v0.8 and v0.9 standard catalogs)

aip-agents can emit and preserve A2UI payloads in the final SSE metadata as metadata.a2ui_content when configured with a2ui at agent creation.

Enablement example:

from aip_agents.agent.langgraph_react_agent import LangGraphReactAgent

agent = LangGraphReactAgent(
    name="restaurant-finder",
    instruction="Help customer choose a restaurant.",
    config={
        "a2ui": {
            "enabled": True,
            "schema_version": "0.9",
        }
    },
)

Behavior in this release:

• Outbound A2UI payload in the final response is validated and normalized to A2UIContentMetadata.
• On validation fallback, metadata includes validation.status = "fallback" and a machine-readable validation.fallback_reason.
• A userAction can be passed to the agent as ordinary input; dedicated renderer-action normalization and routing are outside this package.
• schema_version controls catalog selection and defaults to "0.9" (STANDARD_SCHEMA_VERSION) when omitted; pass schema_version="0.8" explicitly to keep the legacy wire shape.
• Both "0.8" and "0.9" ship bundled default list/form/confirmation examples (aip_agents/a2ui/examples/<version>/) used to enrich the system prompt.
• Deep semantic renderability checks (root/child-reference validation beyond jsonschema) remain v0.8-only; v0.9 payloads are jsonschema-validated but not yet checked for renderability parity.

Managing Dependencies

1. Go to the aip-agents module root, e.g. cd python/aip-agents.
2. Run poetry shell to create a virtual environment.
3. Run poetry install to install the aip-agents requirements (Poetry will generate a local lock file for you if needed; the repository ignores it).
4. Run poetry update if you change any dependency versions in 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. From python/aip-agents, install hooks with pre-commit install (this enables the module deep-import-scanner hook to run on every commit)
2. Run poetry shell to create a virtual environment.
3. Run poetry install to install the aip-agents requirements (this will also create a local lock file that stays local).
4. Run which python to get the path to be referenced at Visual Studio Code interpreter path (Ctrl+Shift+P or Cmd+Shift+P)
5. Try running the unit test to see if it's working:

poetry run pytest -s tests/unit_tests/

Hello World Examples

Prerequisites

• Python 3.11 - 3.13
• Install the package:

pip install aip-agents

• Install Google ADK support only if you use Google ADK examples:

pip install "aip-agents[google-adk]"

• 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 aip_agents/examples in the source repo. 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., python/aip-agents if you cloned the repository).

LangGraph (OpenAI):

python aip_agents/examples/hello_world_langgraph.py

LangGraph with GL Connectors (OpenAI):

python aip_agents/examples/hello_world_langgraph_gl_connector_twitter.py

LangGraph Streaming (OpenAI):

python aip_agents/examples/hello_world_langgraph_stream.py

LangGraph Multi-Agent Coordinator (OpenAI):

python aip_agents/examples/hello_world_a2a_multi_agent_coordinator_server.py

Google ADK:

python aip_agents/examples/hello_world_google_adk.py

Google ADK Streaming:

python aip_agents/examples/hello_world_google_adk_stream.py

LangChain (OpenAI):

python aip_agents/examples/hello_world_langchain.py

LangChain Streaming (OpenAI):

python aip_agents/examples/hello_world_langchain_stream.py

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

python aip_agents/examples/hitl_demo.py

2. Running MCP Examples

Prerequisites

Ensure you have set the environment variables for API keys required by the examples you run:

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

GOOGLE_API_KEY is only required for Google ADK examples.

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 (python/aip-agents) and run:

• For STDIO:

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

• For SSE:

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

• For HTTP:

poetry run python aip_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 aip_agents/examples/<file>.py. Examples support OpenAI for LangGraph/LangChain and Google ADK where specified.

LangChain Examples

STDIO Transport

• Non-Streaming:

poetry run python aip_agents/examples/hello_world_langchain_mcp_stdio.py

• Streaming:

poetry run python aip_agents/examples/hello_world_langchain_mcp_stdio_stream.py

SSE Transport

• Non-Streaming:

poetry run python aip_agents/examples/hello_world_langchain_mcp_sse.py

• Streaming:

poetry run python aip_agents/examples/hello_world_langchain_mcp_sse_stream.py

HTTP Transport

• Non-Streaming:

poetry run python aip_agents/examples/hello_world_langchain_mcp_http.py

• Streaming:

poetry run python aip_agents/examples/hello_world_langchain_mcp_http_stream.py

Google ADK Examples

STDIO Transport

• Non-Streaming:

poetry run python aip_agents/examples/hello_world_google_adk_mcp_stdio.py

• Streaming:

poetry run python aip_agents/examples/hello_world_google_adk_mcp_stdio_stream.py

SSE Transport

• Non-Streaming:

poetry run python aip_agents/examples/hello_world_google_adk_mcp_sse.py

• Streaming:

poetry run python aip_agents/examples/hello_world_google_adk_mcp_sse_stream.py

HTTP Transport

• Non-Streaming:

poetry run python aip_agents/examples/hello_world_google_adk_mcp_http.py

• Streaming:

poetry run python aip_agents/examples/hello_world_google_adk_mcp_http_stream.py

LangGraph Examples (OpenAI)

STDIO Transport

• Non-Streaming:

poetry run python aip_agents/examples/hello_world_langgraph_mcp_stdio.py

• Streaming:

poetry run python aip_agents/examples/hello_world_langgraph_mcp_stdio_stream.py

SSE Transport

• Non-Streaming:

poetry run python aip_agents/examples/hello_world_langgraph_mcp_sse.py

• Streaming:

poetry run python aip_agents/examples/hello_world_langgraph_mcp_sse_stream.py

HTTP Transport

• Non-Streaming:

poetry run python aip_agents/examples/hello_world_langgraph_mcp_http.py

• Streaming:

poetry run python aip_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 aip_agents/examples/mcp_servers/mcp_name.py

3. Run the multi-server client example:

poetry run python aip_agents/examples/hello_world_langchain_mcp_multi_server.py

3. Running Individual A2A Examples:

• Navigate to the library's root directory (e.g., libs/aip-agents if you cloned the repository).
• Open a new terminal and navigate to the aip_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 aip_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

AIP 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 aip_agents.agent import LangGraphReactAgent
from aip_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

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 aip_agents/examples/hitl_demo.py

Delegation Timeout Policy

When using coordinator agents with delegated sub-agents (delegate_to_<agent> tools), timeout behavior follows a dedicated policy:

• Source of truth: delegated timeout comes from the delegated agent configuration (agent.timeout or agent.config.timeout_seconds). Delegation checks timeout_seconds first and falls back to legacy execution_timeout only for delegation-specific compatibility.
• Regular tool-resilience timeout metadata (resilience.timeout_seconds, top-level timeout_seconds, and tool_timeout_seconds) does not control delegated-agent timeout behavior.
• Legacy delegation timeout override keys are ignored for effective timeout resolution.
• Ignored override attempts emit a deterministic warning signal in tool metadata:
  • metadata.delegation_timeout_warning.code = \"delegation_timeout_override_ignored\"
  • metadata.delegation_timeout_warning.ignored_keys lists ignored keys
  • metadata.delegation_timeout_warning.effective_timeout_seconds records delegated effective timeout when available

If delegated timeout configuration is missing, invalid, or non-positive, delegation fails before execution with invalid_timeout_config.

Root Agent Timeout

Set AgentConfig(timeout_seconds=N) to enforce one absolute deadline across the agent's complete execution. The deadline covers setup, middleware, model calls, tools, delegation, HITL waits, formatting, and all stream waits. Delegated agents inherit the parent's remaining budget; their own shorter timeout still takes precedence.

Expiration raises AgentRunTimeoutError for direct run, arun, and regular stream calls. A2A and SSE terminal error events include the same exception type, agent name, entry point, and configured timeout in metadata. Existing tool, HITL, MCP, sandbox, and PTC timeouts remain inner operation budgets.

Cancellation is cooperative. Synchronous work already running in an executor or daemon thread cannot be forcibly stopped, although the public run() call returns at the root deadline and late results are discarded. Successful cleanup is allowed to finish; cleanup after deadline cancellation is bounded.

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 Integration Tests

Use the Mem0 integration tests to validate memory persistence, recall, and deletion:

cd python/aip-agents && poetry run pytest tests/integration_tests/test_mem0_coordinator.py -q

Mem0 SDK Mode

Install the memory extra with SDK-mode dependencies and configure direct Elasticsearch access:

pip install "aip-agents[memory]"
export MEMORY_ELASTICSEARCH_URL="https://elasticsearch.example:9243"
export MEMORY_COLLECTION_NAME="mem0"
export MEMORY_EMBEDDING_MODEL="openai/text-embedding-3-small"
export MEMORY_EMBEDDING_DIMENSIONS="1536"
export OPENAI_API_KEY="your-api-key"

Elasticsearch credentials are provided through dedicated environment variables and never placed in agent_config: MEMORY_ELASTICSEARCH_USER and MEMORY_ELASTICSEARCH_PASSWORD for basic auth, or MEMORY_ELASTICSEARCH_API_KEY for API-key auth. Alternatively, embed the userinfo directly in MEMORY_ELASTICSEARCH_URL (http://user:pass@elasticsearch.example:9243); explicit environment variables take precedence over URL userinfo.

Pass the non-secret settings through agent_config and select SDK mode:

import os

agent_config = {
    "memory": "mem0",
    "memory_mode": "sdk",
    "memory_elasticsearch_url": os.environ["MEMORY_ELASTICSEARCH_URL"],
    "memory_collection_name": os.environ["MEMORY_COLLECTION_NAME"],
    "memory_embedding_model": os.environ["MEMORY_EMBEDDING_MODEL"],
    "memory_embedding_dimensions": int(os.environ["MEMORY_EMBEDDING_DIMENSIONS"]),
}

The runner builds the embedding invoker from the configured model and runtime credentials, then registers the agent's language-model invoker with MemoryLMComponent. Existing hosted mode remains the default and continues to use MEM0_HOST/MEM0_API_KEY or their GLLM_MEMORY_* aliases.

Deep Agents Middleware

The Deep Agents Middleware system provides composable components for enhancing agent capabilities with planning, context management, and custom lifecycle hooks.

Quick Start

Enable deep agent capabilities with a single parameter:

from aip_agents.agent.langgraph_react_agent import LangGraphReactAgent

# Enable planning + filesystem for complex multi-step tasks
agent = LangGraphReactAgent(
    name="research_agent",
    model="gpt-4",
    planning=True,  # Enables TodoListMiddleware for task decomposition
    tools=[search_tool, calculator_tool],
)

Understanding Planning vs Filesystem

Important: planning and filesystem are completely independent features:

• planning=True

  • Adds write_todos tool for task decomposition
  • Stores todos in in-memory dictionary (per thread_id)
  • Does NOT use or require filesystem
  • Perfect for breaking down complex tasks into steps
  • Example: "Research quantum computing" → agent creates 5 subtasks

• filesystem=True

  • Adds file operation tools: ls, read_file, write_file, edit_file, grep
  • Stores data in pluggable backend (default: InMemoryBackend)
  • Does NOT interact with planning/todos
  • Perfect for offloading large tool results to prevent context overflow
  • Example: Web search returns 50KB → agent writes to /research/results.txt

• Both together (planning=True, filesystem=True)

  • Agent can plan tasks AND manage large data
  • Todos stored separately in memory, files in backend
  • Most powerful combination for complex research/analysis tasks

Planning Only

For task decomposition without filesystem:

agent = LangGraphReactAgent(
    name="planner_agent",
    model="gpt-4",
    planning=True,
    tools=[...],
)

Filesystem Only

For context offloading without planning:

agent = LangGraphReactAgent(
    name="data_processor",
    model="gpt-4",
    filesystem=True,  # Enables FilesystemMiddleware
    tools=[...],
)

Custom Middleware

Create domain-specific middleware by implementing the AgentMiddleware protocol:

from aip_agents.middleware.base import AgentMiddleware, ModelRequest

class CustomMiddleware:
    def __init__(self):
        self.tools = []  # Add custom tools here
        self.system_prompt_additions = "Custom instructions..."

    def before_model(self, state: dict) -> dict:
        # Hook executed before model invocation
        return {}

    def modify_model_request(self, request: ModelRequest, state: dict) -> ModelRequest:
        # Modify the model request (add tools, adjust params, etc.)
        return request

    def after_model(self, state: dict) -> dict:
        # Hook executed after model invocation
        return {}

# COMPOSITION (not override): Custom middlewares EXTEND built-in middleware
agent = LangGraphReactAgent(
    name="custom_agent",
    model="gpt-4",
    planning=True,        # Adds TodoListMiddleware
    filesystem=True,      # Adds FilesystemMiddleware
    middlewares=[CustomMiddleware()],  # EXTENDS (doesn't replace) the above
    tools=[...],
)
# Result: Agent has ALL THREE middleware active:
#   1. TodoListMiddleware (from planning=True)
#   2. FilesystemMiddleware (from filesystem=True)
#   3. CustomMiddleware (from middlewares parameter)

Key Points:

• ✅ middlewares parameter extends (never replaces) auto-configured middleware
• ✅ planning and filesystem are independent - use either, both, or neither
• ✅ planning=True stores todos in memory (does NOT require filesystem)
• ✅ Execution order: built-in middleware (planning, filesystem) → custom middlewares
• ✅ All hooks from all middleware execute in sequence

Common Combinations:

# Planning only (no filesystem)
# → Todos stored in memory, no file operations available
agent = LangGraphReactAgent(planning=True)
# → [TodoListMiddleware]

# Filesystem only (no planning)
# → File operations available, no todo planning
agent = LangGraphReactAgent(filesystem=True)
# → [FilesystemMiddleware]

# Both planning and filesystem
# → Todos in memory + file operations (most powerful combination)
agent = LangGraphReactAgent(planning=True, filesystem=True)
# → [TodoListMiddleware, FilesystemMiddleware]

# Custom only (no auto-configuration)
agent = LangGraphReactAgent(middlewares=[CustomMiddleware()])
# → [CustomMiddleware]

# All together (composition)
agent = LangGraphReactAgent(
    planning=True,
    filesystem=True,
    middlewares=[CustomMiddleware()]
)
# → [TodoListMiddleware, FilesystemMiddleware, CustomMiddleware]

Advanced: Custom Storage Backend

Provide your own storage backend for filesystem operations:

from aip_agents.middleware.backends.protocol import BackendProtocol
from aip_agents.middleware.backends.memory import InMemoryBackend

# Use custom backend (e.g., PostgreSQL, S3, Redis)
custom_backend = MyCustomBackend()

agent = LangGraphReactAgent(
    name="agent",
    model="gpt-4",
    filesystem=custom_backend,  # Pass BackendProtocol instance
    tools=[...],
)

Benefits

• Context Window Management: Automatically offload large tool results to files
• Task Decomposition: Break down complex multi-step tasks into trackable todos
• Incremental Development: Add capabilities gradually (filesystem first, then planning)
• Zero Breaking Changes: Existing agents work unchanged (backward compatible)
• Extensible: Compose custom middleware with built-in components

For detailed documentation, see docs/deep_agents_guide.md (coming soon).

Agent Interface (AgentInterface)

The aip_agents.agent.interface.AgentInterface class defines a standardized contract for all agent implementations within the AIP 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.