Skip to main content
Incomplete provenance

3 of 9 release files were uploaded without provenance metadata. View details.

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

1. Installation from PyPI

The package and its dependencies are available from the public Python Package Index.

Using pip

pip install aip-agents

Using uv

uv add aip-agents

2. Development Installation (Git)

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

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

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

pip install "glaip-sdk[local]"

Optional Extras

pip install "aip-agents[a2ui]"
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.

PII masking

Set enable_pii=True on LangGraphReactAgent to mask supported PII in the current query and in the content of supplied HumanMessage and AIMessage history before the model receives them. Fields outside message content are left unchanged. When remote NER is configured, supported query and history text is sent to that service for analysis. Values already in metadata["pii_mapping"] are replaced with tags first; unmatched text may be sent unchanged. Mapping-only masking works without remote NER. Binary and non-text content is left unchanged. This covers only HumanMessage and AIMessage content; other history roles, non-message entries, tool-call arguments, and additional_kwargs are not masked by this feature.

Vision Authentication

Enable vision=True to add read_image. The vision tool inherits the agent's model credentials, including a Google Vertex service-account path or structured credentials configured through AgentConfig.lm_credentials:

import os

from aip_agents.agent.langgraph_react_agent import LangGraphReactAgent
from aip_agents.schema.agent import AgentConfig

agent = LangGraphReactAgent(
    name="vision-agent",
    instruction="Analyze attached images when needed.",
    model="google/gemini-3.5-flash",
    config=AgentConfig(
        lm_credentials=os.environ["GOOGLE_VERTEX_AI_CREDENTIAL_PATH"],
        project_id=os.getenv("GOOGLE_CLOUD_PROJECT"),
        location=os.getenv("GOOGLE_CLOUD_LOCATION", "us-central1"),
    ),
    vision=True,
)

API-key configuration continues to use the Gemini API. Explicit vision configuration can override the model or use lm_credentials directly; the legacy vision.api_key field remains supported.

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

Skill Loader and Runtime Selection

Both skill_loader and skill_runtime default to "aip". New integrations can use GL Skill loading while the parent AIP agent keeps reasoning, authorization, resource access, and tool execution:

from aip_agents.middleware.skills import SkillConfig

config = SkillConfig(skills=[skill], skill_loader="gl_skill", skill_runtime="aip")
agent = LangGraphReactAgent(name="parent", instruction="...", model=model, skills=config)

GL loading requires gl-skill-binary>=0.1.1,<0.2.0. PyPI publishes 0.1.1 wheels for CPython 3.11–3.13 on Linux x86_64, Windows x86_64, and macOS arm64. The loader uses GL's LocalSkillProvider to parse and normalize each local Skill, including GL's compatibility recovery, then adapts the document into GL's result contract. AIP separately stages its acquired payloads and keeps its skill_load / skill_resource tools. Selecting this loader never constructs a GL executor. Missing or incompatible binaries fail when GL loading is selected; omitted selectors preserve existing behavior.

GL loading retains fail-fast validation: one rejected Skill aborts synchronous staging; asynchronous staging returns an empty Skill inventory and records skill_source_errors. Errors identify the failing Skill, with its local path and provider reason where available. Unlike AIP's skip-invalid behavior, GL can reject BOM-prefixed or unrecoverable frontmatter, non-regular resource files, unlistable parent directories, and bundles exceeding its document/resource or parent-directory scan limits. Tested corpus parity does not imply identical acceptance or failure isolation for every possible input.

The existing GL execution option remains available for current callers:

By default the middleware is prompt-driven: the parent model loads skills with skill_load / skill_resource and follows the instructions itself. Setting skill_runtime="gl_skill" swaps the Skill tools for a single bounded skill_run(name, query) tool backed by the standalone GL Skill runtime (provided by gl-skill-binary, included in the skills extra). The parent model invokes the skill by name, receives one structured result, and keeps its normal loop and capabilities.

from aip_agents.middleware.skills import SkillConfig

config = SkillConfig(skills=[skill], skill_runtime="gl_skill")
agent = LangGraphReactAgent(name="parent", instruction="...", model=model, skills=config)

Notes:

  • Omitting the selector (or skill_runtime="aip") preserves the current behavior exactly.
  • Base aip-agents imports never require gl-skill-binary. GL loading imports its loading APIs when selected; GL execution imports its runtime when skill_run starts. Missing dependencies produce actionable errors.
  • skill_run accepts only name and query; names resolve against the middleware's attached, materialized skills, never a model-supplied path.
  • With an explicitly configured eligible local parent filesystem, the host-admitted inner GL run receives the resolved skill, query, model runtime, bounded time budget, and workspace.list@1, workspace.read@1, workspace.write@1, and workspace.edit@1 capabilities. Writes and exact edits are UTF-8 text only, use the parent backend's existing operations, and cannot target the skills staging or backend metadata paths. When the host also enables the backend's explicit allow_execute=True flag, the run may receive workspace.execute_command@1 with exact argv, relative cwd, bounded output, and parent-controlled timeout/cancellation. The parent backend is never exposed directly; model-controlled environment/network options, MCPs, memory, guardrails, and HITL are never lent to it.
  • Without a parent filesystem, without host mutation admission, or without backend execution opt-in, gl_skill remains instruction-only or read-only as before. InMemoryBackend remains read/write/edit-only; LocalDiskBackend and eligible E2B SandboxBackend instances use their existing list/read/write/edit/execute operations, with LocalDisk execution reserved for trusted explicit allow_execute=True use. Command-shell/interpreter eval forms are denied at the GL boundary, and local command output redacts the physical workspace root. Sandbox runtimes that cannot enforce the requested output bound fail closed before dispatch. Unsupported Sandbox providers and unknown backend implementations are not admitted. Shared-workspace operations do not apply WorkspacePolicy staging quotas; backend containment, deadlines, command output limits, and GL run limits remain authoritative.

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",
        }
    },
)

Upgrading to 0.6.191 (a2ui-agent-sdk 0.9): A2UIMiddleware.schema_manager is removed, because SDK 0.9 no longer has A2uiSchemaManager. The aip_agents.a2ui.public_url module is also removed; the same names are exported by aip_agents.utils.public_url.

Before After
middleware.schema_manager.supported_catalog_ids [catalog.catalog_id for catalog in middleware.catalogs]
middleware.schema_manager.get_selected_catalog() middleware.catalogs[0]
middleware.schema_manager.generate_system_prompt(...) middleware.modify_model_request(request, state)
selected_catalog.validator.validate(messages) a2ui.utils.validate_payload([middleware.catalogs[0]], messages)
from aip_agents.a2ui.public_url import ... from aip_agents.utils.public_url import ...

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.
  • Each <a2ui-json> block is validated on its own, then the whole response is checked again so references between blocks are caught. For v0.8 that second pass is the middleware's root/child-reference check; for v0.9 it is a2ui.utils.validate_payload.
  • Validation accepts any configured catalog that a surface names; the prompt describes only the first one.

Managing Dependencies

  1. Go to the aip-agents module root, e.g. cd python/aip-agents.
  2. Run uv sync --locked --extra dev to create .venv and install the committed uv.lock dependencies.
  3. Run uv lock after changing dependency declarations in pyproject.toml, then run uv sync --locked --extra dev to update the environment.

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 uv sync --locked --all-extras to create the full development environment used by the unit test suite.
  3. Set the Visual Studio Code interpreter to .venv/bin/python (Ctrl+Shift+P or Cmd+Shift+P).
  4. Run a unit test to verify the environment:
make test-unit

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:
uv run --extra dev python aip_agents/examples/mcp_servers/mcp_server_stdio.py
  • For SSE:
uv run --extra dev python aip_agents/examples/mcp_servers/mcp_server_sse.py
  • For HTTP:
uv run --extra dev 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 uv run --extra dev python aip_agents/examples/<file>.py. Examples support OpenAI for LangGraph/LangChain and Google ADK where specified.

LangChain Examples

STDIO Transport
  • Non-Streaming:
uv run --extra dev python aip_agents/examples/hello_world_langchain_mcp_stdio.py
  • Streaming:
uv run --extra dev python aip_agents/examples/hello_world_langchain_mcp_stdio_stream.py
SSE Transport
  • Non-Streaming:
uv run --extra dev python aip_agents/examples/hello_world_langchain_mcp_sse.py
  • Streaming:
uv run --extra dev python aip_agents/examples/hello_world_langchain_mcp_sse_stream.py
HTTP Transport
  • Non-Streaming:
uv run --extra dev python aip_agents/examples/hello_world_langchain_mcp_http.py
  • Streaming:
uv run --extra dev python aip_agents/examples/hello_world_langchain_mcp_http_stream.py

Google ADK Examples

STDIO Transport
  • Non-Streaming:
uv run --extra dev --extra google-adk python aip_agents/examples/hello_world_google_adk_mcp_stdio.py
  • Streaming:
uv run --extra dev --extra google-adk python aip_agents/examples/hello_world_google_adk_mcp_stdio_stream.py
SSE Transport
  • Non-Streaming:
uv run --extra dev --extra google-adk python aip_agents/examples/hello_world_google_adk_mcp_sse.py
  • Streaming:
uv run --extra dev --extra google-adk python aip_agents/examples/hello_world_google_adk_mcp_sse_stream.py
HTTP Transport
  • Non-Streaming:
uv run --extra dev --extra google-adk python aip_agents/examples/hello_world_google_adk_mcp_http.py
  • Streaming:
uv run --extra dev --extra google-adk python aip_agents/examples/hello_world_google_adk_mcp_http_stream.py

LangGraph Examples (OpenAI)

STDIO Transport
  • Non-Streaming:
uv run --extra dev python aip_agents/examples/hello_world_langgraph_mcp_stdio.py
  • Streaming:
uv run --extra dev python aip_agents/examples/hello_world_langgraph_mcp_stdio_stream.py
SSE Transport
  • Non-Streaming:
uv run --extra dev python aip_agents/examples/hello_world_langgraph_mcp_sse.py
  • Streaming:
uv run --extra dev python aip_agents/examples/hello_world_langgraph_mcp_sse_stream.py
HTTP Transport
  • Non-Streaming:
uv run --extra dev python aip_agents/examples/hello_world_langgraph_mcp_http.py
  • Streaming:
uv run --extra dev 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
  1. In another terminal, start the Name Generator SSE server:
uv run --extra dev python aip_agents/examples/mcp_servers/mcp_name.py
  1. Run the multi-server client example:
uv run --extra dev 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:

Missing, null, or ordinary empty tool settings ({}) do not request approval. An explicit {"hitl": {}} requires approval with the default 300-second timeout; legacy timeout-only and typed ToolApprovalConfig policies also require approval. Install a package containing this fix in the execution runtime/sandbox, not only in the caller's client environment.

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

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 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 && uv run --extra dev --extra memory 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.agent.langgraph_react_agent import LangGraphReactAgent
from aip_agents.middleware.base import AgentMiddleware, ModelRequest, ToolCallDecision


class CustomMiddleware(AgentMiddleware):
    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 {}

    def before_tool_call(self, tool_call: dict, state: dict) -> ToolCallDecision | None:
        # Block one tool and abstain on all other calls.
        if tool_call.get("name") == "delete_record":
            return ToolCallDecision(
                allowed=False,
                message="Deleting records is disabled.",
                reason_code="DELETE_BLOCKED",
            )
        return None

# 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)

before_tool_call can return None to abstain or a ToolCallDecision to allow or deny a call. An allow continues through later middleware; the first denial stops the middleware chain. A denial is returned to the model as a tool error and skips HITL approval and tool execution. abefore_tool_call is the asynchronous form for policies that need async I/O; implement it instead of the synchronous hook when needed.

When one model response contains multiple tool calls, AIP Agents checks them sequentially in the order returned by the model and passes the same state dictionary to each check. Later checks see state changes made by earlier checks. AIP Agents finishes all middleware checks before starting HITL or tool execution; calls allowed by middleware still execute concurrently.

The normalized tool_call dictionary is mutable and shared by the middleware chain. Changes made by one middleware are visible to later middleware and, for allowed calls, are used by HITL checks and tool lookup/execution. Hooks run in registration order, so put argument-transforming middleware before policies that need to inspect the transformed arguments. If a mutating middleware denies a call, the denial result still uses the original tool-call ID and name.

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.

Concurrent sandbox execution

See Concurrent sandbox invocations for run context resolution, isolated custom/native tool execution, artifact collection, cancellation and shared-workspace coordination.

Metadata

Release files for aip-agents-binary 0.6.192

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Incomplete provenance

3 of 9 files were uploaded without provenance metadata.

We recommend further investigation before installing these files. View details.

Built distributions (wheels)

Table of built distributions (wheels) for aip-agents-binary 0.6.192
File Actions
aip_agents_binary-0.6.192-cp313-cp313-win_amd64.whl CPython 3.13 CPython 3.13 Windows x86-64 Details for aip_agents_binary-0.6.192-cp313-cp313-win_amd64.whl
aip_agents_binary-0.6.192-cp313-cp313-manylinux_2_28_x86_64.whl CPython 3.13 CPython 3.13 Linux glibc 2.28+ x86-64 Details for aip_agents_binary-0.6.192-cp313-cp313-manylinux_2_28_x86_64.whl
aip_agents_binary-0.6.192-cp313-cp313-macosx_13_0_arm64.whl CPython 3.13 CPython 3.13 macOS 13.0+ ARM64 Details for aip_agents_binary-0.6.192-cp313-cp313-macosx_13_0_arm64.whl
aip_agents_binary-0.6.192-cp312-cp312-win_amd64.whl CPython 3.12 CPython 3.12 Windows x86-64 Details for aip_agents_binary-0.6.192-cp312-cp312-win_amd64.whl
aip_agents_binary-0.6.192-cp312-cp312-manylinux_2_28_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.28+ x86-64 Details for aip_agents_binary-0.6.192-cp312-cp312-manylinux_2_28_x86_64.whl
aip_agents_binary-0.6.192-cp312-cp312-macosx_13_0_arm64.whl CPython 3.12 CPython 3.12 macOS 13.0+ ARM64 Details for aip_agents_binary-0.6.192-cp312-cp312-macosx_13_0_arm64.whl
aip_agents_binary-0.6.192-cp311-cp311-win_amd64.whl CPython 3.11 CPython 3.11 Windows x86-64 Details for aip_agents_binary-0.6.192-cp311-cp311-win_amd64.whl
aip_agents_binary-0.6.192-cp311-cp311-manylinux_2_28_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.28+ x86-64 Details for aip_agents_binary-0.6.192-cp311-cp311-manylinux_2_28_x86_64.whl
aip_agents_binary-0.6.192-cp311-cp311-macosx_13_0_arm64.whl CPython 3.11 CPython 3.11 macOS 13.0+ ARM64 Details for aip_agents_binary-0.6.192-cp311-cp311-macosx_13_0_arm64.whl

Total release size: 86.1 MB

Release files / aip_agents_binary-0.6.192-cp313-cp313-win_amd64.whl

Incomplete provenance

This file belongs to a release with incomplete provenance: while this file has provenance metadata, other files in this release do not.

We recommend further investigation before installing this file. View details.

Download URL aip_agents_binary-0.6.192-cp313-cp313-win_amd64.whl
Size 7.8 MB
Tags CPython 3.13 Windows x86-64
SHA-256 checksum
How to use checksums
3183b8fe40c176313954c99a3800d1c254a53269205bc313bb36e593b5be908e
BLAKE2b-256 checksum
How to use checksums
ad5b6fc2de6da9d02314505a7fefc585e51309a0e2c0340d7a2d46a74fffa6f2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / aip_agents_binary-0.6.192-cp313-cp313-manylinux_2_28_x86_64.whl

Incomplete provenance

This file belongs to a release with incomplete provenance: while other files in this release have provenance metadata, this file does not.

We recommend further investigation before installing this file. View details.

Download URL aip_agents_binary-0.6.192-cp313-cp313-manylinux_2_28_x86_64.whl
Size 12.0 MB
Tags CPython 3.13 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
34fdeb155f1c02e08ac1cccf1039f639e0ec693c5c5cb683af99ee8ae782048c
BLAKE2b-256 checksum
How to use checksums
76b09c1339c6e0acec06b239111417023daa5d68cda6206022ba88c130631343
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"AlmaLinux","version":"8.10","id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / aip_agents_binary-0.6.192-cp313-cp313-macosx_13_0_arm64.whl

Incomplete provenance

This file belongs to a release with incomplete provenance: while this file has provenance metadata, other files in this release do not.

We recommend further investigation before installing this file. View details.

Download URL aip_agents_binary-0.6.192-cp313-cp313-macosx_13_0_arm64.whl
Size 9.4 MB
Tags CPython 3.13 macOS 13.0+ ARM64
SHA-256 checksum
How to use checksums
971ddc4b29f48b3e915ae82ea3dfd7c5c23baff06c2748d5f95939fcff70ce32
BLAKE2b-256 checksum
How to use checksums
38bfb73fdc491f2c8af4e17bd8cb6bfbe63263d5e4139505289a34a491ad6685
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / aip_agents_binary-0.6.192-cp312-cp312-win_amd64.whl

Incomplete provenance

This file belongs to a release with incomplete provenance: while this file has provenance metadata, other files in this release do not.

We recommend further investigation before installing this file. View details.

Download URL aip_agents_binary-0.6.192-cp312-cp312-win_amd64.whl
Size 7.8 MB
Tags CPython 3.12 Windows x86-64
SHA-256 checksum
How to use checksums
dd13ff2db52ce63c91fd10b1228a8fc75ae99c31dd5e0dd2aea8d1ca560fc543
BLAKE2b-256 checksum
How to use checksums
bd4dca69ab35c086ecf65882c944c3f91792df5dc50bdbeb85325f7ed102a61c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / aip_agents_binary-0.6.192-cp312-cp312-manylinux_2_28_x86_64.whl

Incomplete provenance

This file belongs to a release with incomplete provenance: while other files in this release have provenance metadata, this file does not.

We recommend further investigation before installing this file. View details.

Download URL aip_agents_binary-0.6.192-cp312-cp312-manylinux_2_28_x86_64.whl
Size 11.9 MB
Tags CPython 3.12 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
fced2670b3ad817bb9e060036ace73135f85c08b6f5ae874251617c765e48f92
BLAKE2b-256 checksum
How to use checksums
3d2dadb3f8a590ec5db4a401da76c7a2367510c4a835276e5576cff39c25367e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"AlmaLinux","version":"8.10","id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / aip_agents_binary-0.6.192-cp312-cp312-macosx_13_0_arm64.whl

Incomplete provenance

This file belongs to a release with incomplete provenance: while this file has provenance metadata, other files in this release do not.

We recommend further investigation before installing this file. View details.

Download URL aip_agents_binary-0.6.192-cp312-cp312-macosx_13_0_arm64.whl
Size 9.4 MB
Tags CPython 3.12 macOS 13.0+ ARM64
SHA-256 checksum
How to use checksums
bef316979a97b8d434e36f62946279abbd9f0d071ca8dbc581e084da87eac2ff
BLAKE2b-256 checksum
How to use checksums
026de6da3c8308ba9b518acca2eedcf0e2155b3ff56488fbcd3ebe5dcfb0a5b2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / aip_agents_binary-0.6.192-cp311-cp311-win_amd64.whl

Incomplete provenance

This file belongs to a release with incomplete provenance: while this file has provenance metadata, other files in this release do not.

We recommend further investigation before installing this file. View details.

Download URL aip_agents_binary-0.6.192-cp311-cp311-win_amd64.whl
Size 8.0 MB
Tags CPython 3.11 Windows x86-64
SHA-256 checksum
How to use checksums
19f4b9d695e5b53952c9b7f1d52898d38f11005121dbfee25f58d8db7d19eca6
BLAKE2b-256 checksum
How to use checksums
857d5b74075f891f0ac6450e509bcad10c90fc6e8f3cc799daa23f7d6a8f0c60
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / aip_agents_binary-0.6.192-cp311-cp311-manylinux_2_28_x86_64.whl

Incomplete provenance

This file belongs to a release with incomplete provenance: while other files in this release have provenance metadata, this file does not.

We recommend further investigation before installing this file. View details.

Download URL aip_agents_binary-0.6.192-cp311-cp311-manylinux_2_28_x86_64.whl
Size 10.5 MB
Tags CPython 3.11 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
6a37c59463ca85010fa9cb44e9d26ab5099d644d85b60aaef6802590576d7550
BLAKE2b-256 checksum
How to use checksums
2f56f1041a7efad0935409193065abe9012a70aaca20655b1c2bff182fb26b67
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"AlmaLinux","version":"8.10","id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / aip_agents_binary-0.6.192-cp311-cp311-macosx_13_0_arm64.whl

Incomplete provenance

This file belongs to a release with incomplete provenance: while this file has provenance metadata, other files in this release do not.

We recommend further investigation before installing this file. View details.

Download URL aip_agents_binary-0.6.192-cp311-cp311-macosx_13_0_arm64.whl
Size 9.2 MB
Tags CPython 3.11 macOS 13.0+ ARM64
SHA-256 checksum
How to use checksums
a7c9d7e1c905f434bd2458ea9a016f46c3db7f2901200d1f903a59bd2e98d1e7
BLAKE2b-256 checksum
How to use checksums
0500b42c8e36c15dbe77a4fb5290dec58257775eb9954fb5e89d32cfb71b15b4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for aip-agents-binary 0.6.192

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Incomplete provenance

3 of 9 release files were uploaded without provenance metadata.

Files with provenance 6 / 9
Files without provenance 3 / 9
Select from 9 files

Attestation for aip_agents_binary-0.6.192-cp313-cp313-win_amd64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page