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.

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

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:

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

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.

Concurrent sandbox execution

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