diff --git a/content/integrate/google-adk/_index.md b/content/integrate/google-adk/_index.md index fe5bd1e57b..7a9917f8c9 100644 --- a/content/integrate/google-adk/_index.md +++ b/content/integrate/google-adk/_index.md @@ -23,40 +23,36 @@ weight: 30 ## Architecture -adk-redis connects three backend systems to the ADK framework: +adk-redis connects several backend systems to the ADK framework: -- **[Redis Agent Memory Server](https://github.com/redis/agent-memory-server)** handles working memory (sessions), long-term memory (extracted facts), auto-summarization, and memory search. +- **[Redis Agent Memory]({{< relref "/develop/ai/context-engine/agent-memory" >}})** handles working memory (sessions), long-term memory (extracted facts), auto-summarization, and memory search. Use the default `redis-agent-memory` for new work. It runs either on [Redis Cloud]({{< relref "/operate/rc/context-engine/agent-memory" >}}) or [self-managed]({{< relref "/develop/ai/context-engine/agent-memory/self-managed" >}}) on your own Kubernetes cluster; both share one Data Plane API, so you pick a deployment by pointing `api_base_url` at the right endpoint. - **[RedisVL]({{< relref "/develop/ai/redisvl" >}})** (Redis Vector Library) powers the search tools and local semantic cache provider. - **[LangCache](https://redis.io/langcache/)** provides managed semantic caching with server-side embeddings. +{{< note >}} +[Agent Memory Server](https://github.com/redis/agent-memory-server) +(`opensource-agent-memory`) is now deprecated. If you have an existing +deployment, see +[Agent Memory Server (deprecated)]({{< relref "/integrate/google-adk/agent-memory-server" >}}), +which also covers migrating to Redis Agent Memory. +{{< /note >}} + ## Prerequisites -- **Redis 8.4+** with vector search support -- **Agent Memory Server** for memory and session services +- **Redis 8.4+** with vector search support, for the search tools and the local semantic cache +- **A [Redis Agent Memory]({{< relref "/develop/ai/context-engine/agent-memory" >}}) store**, for the session and memory services, which gives you a Data Plane endpoint, an API key, and a store ID -```bash -# Start Redis -docker run -d --name redis -p 6379:6379 redis:8.4-alpine - -# Start Agent Memory Server -docker run -d --name agent-memory-server -p 8088:8088 \ - -e REDIS_URL=redis://host.docker.internal:6379 \ - -e GEMINI_API_KEY=your-key \ - -e GENERATION_MODEL=gemini/gemini-2.5-flash \ - -e EMBEDDING_MODEL=gemini/text-embedding-004 \ - redislabs/agent-memory-server:latest \ - agent-memory api --host 0.0.0.0 --port 8088 --task-backend=asyncio -``` +Provision a store, then pass its Data Plane endpoint, API key, and store ID to the services. -On Linux, `host.docker.internal` does not resolve by default. Use -`--network=host` plus `REDIS_URL=redis://127.0.0.1:6379`, or point -`REDIS_URL` at the Docker bridge gateway (typically -`redis://172.17.0.1:6379`). +- On **Redis Cloud**, there is nothing to run. See [Create an Agent Memory service]({{< relref "/operate/rc/context-engine/agent-memory/create-service" >}}). +- To run it **yourself**, see [Self-managed Agent Memory]({{< relref "/develop/ai/context-engine/agent-memory/self-managed" >}}) for deployment, configuration, and operations on your own Kubernetes cluster. + +Both use `backend="redis-agent-memory"`. Only `api_base_url` differs. ## Installation ```bash -# Memory and session services (requires Agent Memory Server) +# Memory and session services (both backends) pip install adk-redis[memory] # Search tools via RedisVL @@ -75,6 +71,8 @@ pip install adk-redis[all] pip install 'redisvl[mcp]>=0.18.2' ``` +The `memory` extra requires `redis-agent-memory>=0.2.0`. + ## Quick start Wire up Redis Agent Memory in a few lines: @@ -84,23 +82,29 @@ from google.adk import Agent from google.adk.agents.callback_context import CallbackContext from google.adk.runners import Runner from adk_redis.sessions import ( - RedisWorkingMemorySessionService, - RedisWorkingMemorySessionServiceConfig, + RedisSessionMemoryService, + RedisSessionMemoryServiceConfig, ) from adk_redis.memory import ( RedisLongTermMemoryService, RedisLongTermMemoryServiceConfig, ) -session_service = RedisWorkingMemorySessionService( - config=RedisWorkingMemorySessionServiceConfig( - api_base_url="http://localhost:8088", +session_service = RedisSessionMemoryService( + config=RedisSessionMemoryServiceConfig( + backend="redis-agent-memory", + api_base_url="https://your-endpoint.redis.io", + api_key="your-api-key", + store_id="your-store-id", default_namespace="my_app", ) ) memory_service = RedisLongTermMemoryService( config=RedisLongTermMemoryServiceConfig( - api_base_url="http://localhost:8088", + backend="redis-agent-memory", + api_base_url="https://your-endpoint.redis.io", + api_key="your-api-key", + store_id="your-store-id", default_namespace="my_app", ) ) @@ -127,17 +131,17 @@ runner = Runner( | Capability | Description | Page | |------------|-------------|------| -| **Redis Agent Memory** | Working and long-term memory via framework services, REST tools, or MCP | [Redis Agent Memory]({{< relref "/integrate/google-adk/redis-agent-memory" >}}) | +| **Redis Agent Memory** | Session and long-term memory on Redis Cloud or self-managed, via framework services or REST tools | [Redis Agent Memory]({{< relref "/integrate/google-adk/redis-agent-memory" >}}) | | **Integration patterns** | Framework-managed, LLM-controlled REST, and MCP tools | [Integration patterns]({{< relref "/integrate/google-adk/integration-patterns" >}}) | | **Search tools** | Vector, hybrid, text, range, and SQL search via RedisVL, plus the `rvl mcp` server over `McpToolset` | [Search tools]({{< relref "/integrate/google-adk/search-tools" >}}) | -| **Semantic caching** | LLM response and tool result caching | [Semantic caching]({{< relref "/integrate/google-adk/semantic-caching" >}}) | -| **Examples** | Nine complete examples covering all capabilities | [Examples]({{< relref "/integrate/google-adk/examples" >}}) | +| **Semantic caching** | LLM response and tool result caching, with stable entry IDs and targeted invalidation | [Semantic caching]({{< relref "/integrate/google-adk/semantic-caching" >}}) | +| **Examples** | Complete examples covering all capabilities | [Examples]({{< relref "/integrate/google-adk/examples" >}}) | +| **Agent Memory Server** (deprecated) | Reference for the deprecated `opensource-agent-memory` backend, and how to migrate off it | [Agent Memory Server (deprecated)]({{< relref "/integrate/google-adk/agent-memory-server" >}}) | ## More info - [adk-redis on GitHub](https://github.com/redis-developer/adk-redis) - [adk-redis on PyPI](https://pypi.org/project/adk-redis/) - [Car dealership tutorial](https://redis.io/tutorials/build-a-car-dealership-agent-with-google-adk-and-redis-agent-memory/) -- [Redis Agent Memory Server](https://github.com/redis/agent-memory-server) - [RedisVL documentation]({{< relref "/develop/ai/redisvl" >}}) - [Google ADK documentation](https://google.github.io/adk-docs/) diff --git a/content/integrate/google-adk/agent-memory-server.md b/content/integrate/google-adk/agent-memory-server.md new file mode 100644 index 0000000000..cd6b88d7c9 --- /dev/null +++ b/content/integrate/google-adk/agent-memory-server.md @@ -0,0 +1,124 @@ +--- +LinkTitle: Agent Memory Server (deprecated) +Title: Agent Memory Server (deprecated) +alwaysopen: false +categories: +- docs +- integrate +- oss +- rs +- rc +description: Deprecated. The opensource-agent-memory backend is no longer maintained. + Migrate existing deployments to Redis Agent Memory. +group: ai +stack: true +summary: Deprecated backend. How to migrate an existing Agent Memory Server deployment + to Redis Agent Memory. +type: integration +weight: 6 +--- + +{{< warning >}} +**Deprecated. Do not use for new work.** + +The `opensource-agent-memory` backend and the +[Agent Memory Server](https://github.com/redis/agent-memory-server) it targets +are deprecated and are not maintained going forward. Its capabilities are not +being carried forward, and support for it will be removed from adk-redis. + +New agents should use +[Redis Agent Memory]({{< relref "/integrate/google-adk/redis-agent-memory" >}}) +with `backend="redis-agent-memory"`, on +[Redis Cloud]({{< relref "/operate/rc/context-engine/agent-memory" >}}) or +[self-managed]({{< relref "/develop/ai/context-engine/agent-memory/self-managed" >}}) +on your own Kubernetes cluster. + +This page exists only to help existing deployments migrate. +{{< /warning >}} + +## What it was + +Agent Memory Server is a separate open source memory server, documented in +[its own repository](https://github.com/redis/agent-memory-server). It is not +Redis Agent Memory and does not speak the +[Agent Memory Data Plane API]({{< relref "/develop/ai/context-engine/agent-memory/api-reference" >}}). +adk-redis reached it with `backend="opensource-agent-memory"`, an +`api_base_url` pointing at the server, and the `agent-memory-client>=0.14.0` +dependency. + +A handful of capabilities existed only on this backend: auto-summarization, +extraction strategies, recency-boosted search, and an MCP endpoint. They are +configured through `model_name`, `context_window_max`, `extraction_strategy`, +`extraction_strategy_config`, and `recency_boost`, none of which have any effect +with `redis-agent-memory`. See the +[Agent Memory Server repository](https://github.com/redis/agent-memory-server) +for the server's own setup and reference material. + +{{< note >}} +Running Agent Memory yourself never required this backend. Self-managed Agent +Memory is supported and maintained, and uses `backend="redis-agent-memory"` just +like Redis Cloud. You choose a deployment with `api_base_url`, not with +`backend`. +{{< /note >}} + +## Migrate to Redis Agent Memory + +1. Provision a Redis Agent Memory store, on + [Redis Cloud]({{< relref "/operate/rc/context-engine/agent-memory/create-service" >}}) + or [self-managed]({{< relref "/develop/ai/context-engine/agent-memory/self-managed" >}}). + Either gives you a Data Plane endpoint, an API key, and a store ID. +2. Change `backend` from `opensource-agent-memory` to `redis-agent-memory` on + every service and tool config, or drop the field, since it is the default. +3. Point `api_base_url` at the Data Plane endpoint, and add `api_key` and + `store_id`. +4. Remove the backend-only settings listed above. They are silently inert on + `redis-agent-memory`. +5. Replace any MCP memory wiring with the + [REST memory tools]({{< relref "/integrate/google-adk/redis-agent-memory#rest-tools" >}}), + which work the same way on both backends. +6. Drop `agent-memory-client` from your dependencies. The `memory` extra + requires `redis-agent-memory>=0.2.0`. + +```python +# Before: deprecated backend +config = RedisSessionMemoryServiceConfig( + backend="opensource-agent-memory", + api_base_url="http://localhost:8088", + default_namespace="my_app", + model_name="gemini-2.5-flash", + context_window_max=8000, +) + +# After: Redis Agent Memory, on Redis Cloud or self-managed +config = RedisSessionMemoryServiceConfig( + backend="redis-agent-memory", + api_base_url="https://your-endpoint.redis.io", + api_key="your-api-key", + store_id="your-store-id", + default_namespace="my_app", +) +``` + +Changing configuration does not copy existing memories. Plan for a +re-extraction window, or run both backends while long-term memory repopulates. + +## Examples still on this backend + +Three examples in the adk-redis repository have not yet moved: +[simple_redis_memory](https://github.com/redis-developer/adk-redis/tree/main/examples/simple_redis_memory), +[travel_agent_memory_hybrid](https://github.com/redis-developer/adk-redis/tree/main/examples/travel_agent_memory_hybrid), +and +[fitness_coach_mcp](https://github.com/redis-developer/adk-redis/tree/main/examples/fitness_coach_mcp) +(which uses the MCP endpoint this backend alone provides). + +For a supported starting point, use +[managed_memory_quickstart]({{< relref "/integrate/google-adk/examples#managed_memory_quickstart" >}}). +[travel_agent_memory_tools](https://github.com/redis-developer/adk-redis/tree/main/examples/travel_agent_memory_tools) +switches backends with `REDIS_MEMORY_BACKEND`, so it already runs on +`redis-agent-memory`. + +## More info + +- [Redis Agent Memory]({{< relref "/integrate/google-adk/redis-agent-memory" >}}): the supported backend +- [Self-managed Agent Memory]({{< relref "/develop/ai/context-engine/agent-memory/self-managed" >}}): run Agent Memory on your own Kubernetes cluster +- [Agent Memory Server on GitHub](https://github.com/redis/agent-memory-server): the deprecated server's own documentation diff --git a/content/integrate/google-adk/examples.md b/content/integrate/google-adk/examples.md index 64b40239aa..8a6a016d62 100644 --- a/content/integrate/google-adk/examples.md +++ b/content/integrate/google-adk/examples.md @@ -11,13 +11,13 @@ categories: description: Complete examples for every adk-redis capability. group: ai stack: true -summary: Nine runnable examples covering Redis Agent Memory, search tools, semantic +summary: Runnable examples covering Redis Agent Memory, search tools, semantic caching, and MCP integration. type: integration weight: 5 --- -The [adk-redis repository](https://github.com/redis-developer/adk-redis/tree/main/examples) includes nine complete examples. Each focuses on a specific capability. +The [adk-redis repository](https://github.com/redis-developer/adk-redis/tree/main/examples) includes ten complete examples, each focused on a specific capability. The seven below run on supported backends; the remaining three are listed under [Deprecated backend examples](#deprecated-backend-examples). ## Prerequisites @@ -25,52 +25,36 @@ All examples require: - **Python 3.10+** - **Redis 8.4+**: `docker run -d --name redis -p 6379:6379 redis:8.4-alpine` -- **Agent Memory Server** (for memory examples): See [setup instructions](https://github.com/redis/agent-memory-server) +- **A memory backend** (for memory examples): a [Redis Agent Memory]({{< relref "/integrate/google-adk/redis-agent-memory" >}}) store on Redis Cloud or self-managed. - **API keys**: Most examples need a `GOOGLE_API_KEY` for Gemini -## `simple_redis_memory` +## `managed_memory_quickstart` -**Capability:** Redis Agent Memory (framework-managed) +**Backend:** `redis-agent-memory` · **Run:** `python main.py` -Minimal starting point. Wires up `RedisWorkingMemorySessionService` and `RedisLongTermMemoryService` with a basic conversational agent. No search tools, no caching: just memory. +The smallest memory example, and the counterpart to `simple_redis_memory`. Uses `redis-agent-memory`, so there is no Agent Memory Server and no Docker to set up. Wires `RedisSessionMemoryService` and `RedisLongTermMemoryService` to an agent with ADK's built-in `preload_memory` and `load_memory` tools. -[View on GitHub](https://github.com/redis-developer/adk-redis/tree/main/examples/simple_redis_memory) - -## `travel_agent_memory_hybrid` - -**Capability:** Redis Agent Memory + REST tools + web search + planning - -The most complete example. Combines framework-managed memory services with LLM-controlled memory tools, web search, itinerary planning, and calendar export. Demonstrates the [hybrid integration pattern]({{< relref "/integrate/google-adk/integration-patterns#hybrid-approach" >}}). - -[View on GitHub](https://github.com/redis-developer/adk-redis/tree/main/examples/travel_agent_memory_hybrid) +[View on GitHub](https://github.com/redis-developer/adk-redis/tree/main/examples/managed_memory_quickstart) ## `travel_agent_memory_tools` -**Capability:** REST memory tools (LLM-controlled) +**Backend:** `redis-agent-memory`, switchable · **Run:** `adk web .` -Uses REST-based memory tools exclusively, without framework-managed services. The LLM has full control over when to search, create, update, and delete memories. +Uses REST-based memory tools exclusively, without framework-managed services. The LLM has full control over when to search, create, update, and delete memories. Set `REDIS_MEMORY_BACKEND` to switch backends. [View on GitHub](https://github.com/redis-developer/adk-redis/tree/main/examples/travel_agent_memory_tools) -## `fitness_coach_mcp` - -**Capability:** MCP memory tools - -Demonstrates MCP-based memory integration. The agent connects to the Agent Memory Server via SSE and manages semantic and episodic memories for workout tracking. - -[View on GitHub](https://github.com/redis-developer/adk-redis/tree/main/examples/fitness_coach_mcp) - ## `redis_search_tools` -**Capability:** Vector, hybrid, text, and range search +**Capability:** Vector, text, and range search · **Run:** `adk web .` -Four in-process RedisVL [search tools]({{< relref "/integrate/google-adk/search-tools" >}}) plugged into a single agent with a product catalog dataset. +Three in-process RedisVL [search tools]({{< relref "/integrate/google-adk/search-tools" >}}) plugged into a single agent with a product catalog dataset. [View on GitHub](https://github.com/redis-developer/adk-redis/tree/main/examples/redis_search_tools) ## `redis_sql_search` -**Capability:** SQL `SELECT` search +**Capability:** SQL `SELECT` search · **Run:** `adk web .` A 10-product catalog with the `RedisSQLSearchTool`. The agent emits parameterized SQL (`WHERE category = 'electronics' AND price < :max_price`) to answer structured catalog questions. Requires `pip install 'adk-redis[sql]'`. @@ -78,7 +62,7 @@ A 10-product catalog with the `RedisSQLSearchTool`. The agent emits parameterize ## `redisvl_mcp_search` -**Capability:** RedisVL MCP server via ADK's `McpToolset` +**Capability:** RedisVL MCP server via ADK's `McpToolset` · **Run:** `adk web .` The MCP counterpart of `redis_search_tools`. A `rvl mcp` server hosts a knowledge-base index in hybrid (vector + BM25) mode and the agent connects via ADK's native `McpToolset`. No adk-redis wrapper involved; the standard `McpToolset` + `StdioConnectionParams` pattern is used. @@ -86,7 +70,7 @@ The MCP counterpart of `redis_search_tools`. A `rvl mcp` server hosts a knowledg ## `semantic_cache` -**Capability:** Local semantic caching (RedisVL) +**Capability:** Local semantic caching (RedisVL) · **Run:** `python main.py` Demonstrates LLM response caching and tool result caching using the `RedisVLCacheProvider` with local embeddings and ADK callbacks. @@ -94,7 +78,7 @@ Demonstrates LLM response caching and tool result caching using the `RedisVLCach ## `langcache_cache` -**Capability:** Managed semantic caching (LangCache) +**Capability:** Managed semantic caching (LangCache) · **Run:** `python main.py` Uses the managed [LangCache]({{< relref "/integrate/google-adk/semantic-caching" >}}) service for semantic caching with server-side embeddings. No local vectorizer required. @@ -102,13 +86,24 @@ Uses the managed [LangCache]({{< relref "/integrate/google-adk/semantic-caching" ## Running an example +Examples marked `python main.py` run as scripts. Examples marked `adk web .` +run in the ADK developer UI from inside the example directory. + ```bash pip install adk-redis[all] -cd examples/simple_redis_memory +cd examples/managed_memory_quickstart export GOOGLE_API_KEY=your-key python main.py ``` +## Deprecated backend examples + +Three examples are written against the deprecated `opensource-agent-memory` +backend: `simple_redis_memory`, `travel_agent_memory_hybrid`, and +`fitness_coach_mcp`. They are listed under +[Agent Memory Server (deprecated)]({{< relref "/integrate/google-adk/agent-memory-server#examples-still-on-this-backend" >}}). +For a `redis-agent-memory` starting point, use `managed_memory_quickstart` above. + ## More info - [Car dealership tutorial](https://redis.io/tutorials/build-a-car-dealership-agent-with-google-adk-and-redis-agent-memory/): Full walkthrough building an agent from scratch diff --git a/content/integrate/google-adk/integration-patterns.md b/content/integrate/google-adk/integration-patterns.md index bb2aa53b3b..70210ddb0f 100644 --- a/content/integrate/google-adk/integration-patterns.md +++ b/content/integrate/google-adk/integration-patterns.md @@ -8,16 +8,16 @@ categories: - oss - rs - rc -description: Three approaches for connecting Google ADK agents to Redis memory. +description: Approaches for connecting Google ADK agents to Redis memory. group: ai stack: true -summary: Choose between framework-managed services, LLM-controlled REST tools, and - MCP protocol tools for memory integration. +summary: Choose between framework-managed services and LLM-controlled REST tools for + memory integration. type: integration weight: 2 --- -adk-redis offers three distinct approaches for connecting agents to memory. Each has different tradeoffs around control, complexity, and standardization. +adk-redis offers two approaches for connecting agents to memory. Each has different tradeoffs around control and complexity. ## Comparison @@ -25,17 +25,27 @@ adk-redis offers three distinct approaches for connecting agents to memory. Each |----------|---------|-----------|----------|----------| | **ADK services** | Framework | Low | HTTP | Invisible infrastructure | | **REST tools** | LLM | Medium | HTTP | Explicit memory management | -| **MCP tools** | LLM | Medium | SSE | Standardized, portable | + +Both use `backend="redis-agent-memory"`, the default, on Redis Cloud or +self-managed. See +[Redis Agent Memory]({{< relref "/integrate/google-adk/redis-agent-memory#choose-a-deployment" >}}) +for the deployment options. + +{{< note >}} +A third approach, MCP memory tools, is only available on the deprecated +[Agent Memory Server]({{< relref "/integrate/google-adk/agent-memory-server" >}}) +backend. +{{< /note >}} ## 1. ADK services (framework-managed) -Configure `RedisWorkingMemorySessionService` and `RedisLongTermMemoryService`, pass them to the `Runner`, and the framework handles everything automatically. Memory extraction happens in the background. Search happens before each agent turn. The agent code never directly interacts with memory. +Configure `RedisSessionMemoryService` and `RedisLongTermMemoryService`, pass them to the `Runner`, and the framework handles everything automatically. Memory extraction happens in the background. Search happens before each agent turn. The agent code never directly interacts with memory. ```python from google.adk.runners import Runner from adk_redis.sessions import ( - RedisWorkingMemorySessionService, - RedisWorkingMemorySessionServiceConfig, + RedisSessionMemoryService, + RedisSessionMemoryServiceConfig, ) from adk_redis.memory import ( RedisLongTermMemoryService, @@ -45,15 +55,21 @@ from adk_redis.memory import ( runner = Runner( agent=agent, app_name="my_app", - session_service=RedisWorkingMemorySessionService( - config=RedisWorkingMemorySessionServiceConfig( - api_base_url="http://localhost:8088", + session_service=RedisSessionMemoryService( + config=RedisSessionMemoryServiceConfig( + backend="redis-agent-memory", + api_base_url="https://your-endpoint.redis.io", + api_key="your-api-key", + store_id="your-store-id", default_namespace="my_app", ) ), memory_service=RedisLongTermMemoryService( config=RedisLongTermMemoryServiceConfig( - api_base_url="http://localhost:8088", + backend="redis-agent-memory", + api_base_url="https://your-endpoint.redis.io", + api_key="your-api-key", + store_id="your-store-id", default_namespace="my_app", ) ), @@ -76,9 +92,11 @@ from adk_redis.tools.memory import ( ) config = MemoryToolConfig( - api_base_url="http://localhost:8088", + backend="redis-agent-memory", + api_base_url="https://your-endpoint.redis.io", + api_key="your-api-key", + store_id="your-store-id", default_namespace="my_app", - recency_boost=True, ) agent = Agent( @@ -95,29 +113,6 @@ agent = Agent( **Tradeoffs:** Requires prompt engineering to teach the LLM memory management strategy, but gives the agent genuine autonomy over its own memory. -## 3. MCP tools (Model Context Protocol) - -Point ADK's `McpToolset` at the Agent Memory Server's SSE endpoint. Tool discovery happens automatically. - -```python -from adk_redis.tools.mcp_memory import create_memory_mcp_toolset - -memory_tools = create_memory_mcp_toolset( - server_url="http://localhost:9000", - tool_filter=["search_long_term_memory", "create_long_term_memories"], -) - -agent = Agent( - model="gemini-2.5-flash", - name="mcp_agent", - tools=[memory_tools], -) -``` - -Available MCP tools: `search_long_term_memory`, `create_long_term_memories`, `get_long_term_memory`, `edit_long_term_memory`, `delete_long_term_memories`, `memory_prompt`, `set_working_memory`. - -**Tradeoffs:** Most standardized and portable approach. Swap memory backends without changing agent code. Requires Agent Memory Server with MCP support on a separate port. - ## Hybrid approach The most powerful configuration combines framework services with REST tools. Framework services handle session persistence and automatic background extraction. REST tools give the LLM explicit CRUD control on top. @@ -144,11 +139,15 @@ runner = Runner( ) ``` -The [travel_agent_memory_hybrid](https://github.com/redis-developer/adk-redis/tree/main/examples/travel_agent_memory_hybrid) example demonstrates this pattern. +The pattern works on `redis-agent-memory`. The +example that demonstrates it, +[travel_agent_memory_hybrid](https://github.com/redis-developer/adk-redis/tree/main/examples/travel_agent_memory_hybrid), +is currently written against the deprecated backend; see +[Agent Memory Server (deprecated)]({{< relref "/integrate/google-adk/agent-memory-server#examples-still-on-this-backend" >}}). ## More info -- [simple_redis_memory](https://github.com/redis-developer/adk-redis/tree/main/examples/simple_redis_memory): Framework-managed services +- [managed_memory_quickstart](https://github.com/redis-developer/adk-redis/tree/main/examples/managed_memory_quickstart): Framework services on Redis Agent Memory - [travel_agent_memory_tools](https://github.com/redis-developer/adk-redis/tree/main/examples/travel_agent_memory_tools): REST tools only -- [fitness_coach_mcp](https://github.com/redis-developer/adk-redis/tree/main/examples/fitness_coach_mcp): MCP tools +- [Agent Memory Server (deprecated)]({{< relref "/integrate/google-adk/agent-memory-server" >}}): MCP tools and other deprecated-backend patterns - [Car dealership tutorial](https://redis.io/tutorials/build-a-car-dealership-agent-with-google-adk-and-redis-agent-memory/) diff --git a/content/integrate/google-adk/redis-agent-memory.md b/content/integrate/google-adk/redis-agent-memory.md index c55ac939ad..1391c3d820 100644 --- a/content/integrate/google-adk/redis-agent-memory.md +++ b/content/integrate/google-adk/redis-agent-memory.md @@ -8,61 +8,93 @@ categories: - oss - rs - rc -description: Working and long-term memory for Google ADK agents using the Redis Agent Memory Server. +description: Session and long-term memory for Google ADK agents using Redis Agent Memory. group: ai stack: true -summary: Add persistent working and long-term memory to ADK agents via framework services, REST tools, or MCP. +summary: Add persistent session and long-term memory to ADK agents via framework services or REST tools. type: integration weight: 1 --- -Redis Agent Memory gives ADK agents two tiers of persistent memory, backed by the [Redis Agent Memory Server](https://github.com/redis/agent-memory-server): +Redis Agent Memory gives ADK agents two tiers of persistent memory: -- **Working memory** — session-scoped storage for the current conversation, with automatic summarization when context grows long. -- **Long-term memory** — facts extracted from past conversations, stored as vectors in Redis and searchable by semantic similarity with optional recency boosting. +- **Session memory**: session-scoped storage for the current conversation. +- **Long-term memory**: facts extracted from past conversations, stored as vectors in Redis and searchable by semantic similarity with recency boosting. -You can wire these tiers into an ADK agent three ways: +## Choose a deployment + +Set `backend="redis-agent-memory"`, the default, on every service and tool +config. Redis Cloud and self-managed Agent Memory share one +[Data Plane API]({{< relref "/develop/ai/context-engine/agent-memory/api-reference" >}}), +so you select a deployment by pointing `api_base_url` at the right Data Plane, +not by changing `backend`: + +| Deployment | `api_base_url` | Setup | +|------------|----------------|-------| +| Redis Cloud | Your Redis Cloud Agent Memory endpoint | [Create an Agent Memory service]({{< relref "/operate/rc/context-engine/agent-memory/create-service" >}}) | +| Self-managed | Your own Data Plane URL | [Self-managed Agent Memory]({{< relref "/develop/ai/context-engine/agent-memory/self-managed" >}}) | + +{{< note >}} +Running Agent Memory yourself does not mean using the deprecated +`opensource-agent-memory` backend. Self-managed Agent Memory is supported and +maintained, and uses `backend="redis-agent-memory"` like Redis Cloud. The +deprecated backend targets a different system, the open source Agent Memory +Server, which does not speak the Data Plane API. See +[Agent Memory Server (deprecated)]({{< relref "/integrate/google-adk/agent-memory-server" >}}) +if you have an existing deployment to migrate. +{{< /note >}} + +Wire memory into an ADK agent one of two ways: | Approach | Control | Best for | |----------|---------|----------| | **Framework services** | ADK Runner (automatic) | Invisible infrastructure | | **REST tools** | LLM (explicit) | Agent autonomy over memory | -| **MCP tools** | LLM via MCP protocol | Portable, standardized | See [Integration patterns]({{< relref "/integrate/google-adk/integration-patterns" >}}) for detailed tradeoff comparison. -## Working memory +## Session memory -`RedisWorkingMemorySessionService` implements ADK's `BaseSessionService`. It stores the current conversation in the Redis Agent Memory Server and automatically summarizes older messages when the context window limit is approached. +`RedisSessionMemoryService` implements ADK's `BaseSessionService`. It stores the current conversation in the configured memory backend. ```python from adk_redis.sessions import ( - RedisWorkingMemorySessionService, - RedisWorkingMemorySessionServiceConfig, + RedisSessionMemoryService, + RedisSessionMemoryServiceConfig, ) -session_service = RedisWorkingMemorySessionService( - config=RedisWorkingMemorySessionServiceConfig( - api_base_url="http://localhost:8088", +session_service = RedisSessionMemoryService( + config=RedisSessionMemoryServiceConfig( + backend="redis-agent-memory", + api_base_url="https://your-endpoint.redis.io", + api_key="your-api-key", + store_id="your-store-id", default_namespace="my_app", - model_name="gemini-2.5-flash", - context_window_max=8000, ) ) ``` +{{< note >}} +`RedisWorkingMemorySessionService` and `RedisWorkingMemorySessionServiceConfig` +were renamed to `RedisSessionMemoryService` and +`RedisSessionMemoryServiceConfig` in adk-redis 0.0.8. The old names remain as +deprecated aliases that emit a `DeprecationWarning` and will be removed in +0.1.0. The module `adk_redis.sessions.working_memory` also moved to +`adk_redis.sessions.session_memory`. +{{< /note >}} + ### Configuration | Parameter | Description | Default | |-----------|-------------|---------| -| `api_base_url` | Agent Memory Server URL | Required | -| `default_namespace` | Isolates data between applications | Required | -| `model_name` | LLM used for summarization | `None` | -| `context_window_max` | Token limit that triggers summarization | `None` | - -### Auto-summarization - -When the token count of stored messages crosses `context_window_max`, the Agent Memory Server uses the model specified in `model_name` to summarize older turns. Recent messages are preserved in full. This avoids the hard tradeoff between truncating context (losing information) and sending the full conversation (hitting token limits and costs). +| `backend` | Memory backend | `redis-agent-memory` | +| `api_base_url` | Data Plane endpoint | `http://localhost:8000` | +| `api_key` | API key | `None` | +| `store_id` | Store ID | `None` | +| `default_namespace` | Isolates data between applications | `None` | +| `timeout` | Request timeout in seconds | `30.0` | +| `timeout_ms` | Request timeout in milliseconds. Overrides `timeout`. | `None` | +| `session_ttl_seconds` | Expiry for stored sessions | `None` | ### Incremental appends @@ -79,7 +111,7 @@ The service implements all of ADK's session methods: ## Long-term memory -`RedisLongTermMemoryService` implements ADK's `BaseMemoryService`. After each conversation, the Agent Memory Server extracts structured information (facts, preferences, episodic events), embeds them as vectors, and stores them in Redis for semantic search across all past sessions. +`RedisLongTermMemoryService` implements ADK's `BaseMemoryService`. After each conversation, the memory backend extracts structured information (facts, preferences, episodic events), embeds them as vectors, and stores them in Redis for semantic search across all past sessions. ```python from adk_redis.memory import ( @@ -89,12 +121,11 @@ from adk_redis.memory import ( memory_service = RedisLongTermMemoryService( config=RedisLongTermMemoryServiceConfig( - api_base_url="http://localhost:8088", + backend="redis-agent-memory", + api_base_url="https://your-endpoint.redis.io", + api_key="your-api-key", + store_id="your-store-id", default_namespace="my_app", - extraction_strategy="discrete", - recency_boost=True, - semantic_weight=0.7, - recency_weight=0.3, ) ) ``` @@ -103,28 +134,22 @@ memory_service = RedisLongTermMemoryService( | Parameter | Description | Default | |-----------|-------------|---------| -| `api_base_url` | Agent Memory Server URL | Required | -| `default_namespace` | Namespace for data isolation | Required | -| `extraction_strategy` | How conversations are broken into memories: `discrete`, `summary`, or `preferences` | `None` | -| `recency_boost` | Enable recency-weighted search | `False` | -| `semantic_weight` | Weight for vector similarity (0-1) | `0.7` | -| `recency_weight` | Weight for recency signal (0-1) | `0.3` | - -### Extraction strategies - -- **`discrete`**: Extracts individual facts as separate memories, making them independently searchable. -- **`summary`**: Creates a narrative summary of the conversation. -- **`preferences`**: Focuses on user preferences and settings. - -### Recency boosting - -Raw semantic similarity often isn't enough. A user might have said "I love Italian food" three years ago and "I've been getting into Japanese cuisine" last week. Both are semantically relevant, but the recent one matters more. - -Recency boosting combines semantic similarity with time-based signals so that recent preferences outweigh stale ones. +| `backend` | Memory backend | `redis-agent-memory` | +| `api_base_url` | Data Plane endpoint | `http://localhost:8000` | +| `api_key` | API key | `None` | +| `store_id` | Store ID | `None` | +| `default_namespace` | Namespace for data isolation | `None` | +| `timeout` | Request timeout in seconds | `30.0` | +| `search_top_k` | Maximum memories returned per search | `10` | +| `similarity_threshold` | Minimum similarity for a match (0-1) | `None` | +| `distance_threshold` | Maximum vector distance for a match (0-1) | `None` | +| `store_events_as_messages` | Store session events as chat messages | `True` | +| `default_memory_type` | Memory type applied to new memories | `semantic` | +| `default_topics` | Topics applied to new memories | `[]` | ## Framework services -Pass both services to an ADK `Runner`. The framework handles memory automatically: sessions are persisted via working memory, long-term memory is searched before each agent turn, and an `after_agent_callback` triggers extraction in the background. +Pass both services to an ADK `Runner`. The framework handles memory automatically: sessions are persisted via session memory, long-term memory is searched before each agent turn, and an `after_agent_callback` triggers extraction in the background. ```python from google.adk import Agent @@ -151,30 +176,44 @@ runner = Runner( ### Runtime flow -1. ADK creates or retrieves a session via `RedisWorkingMemorySessionService`. +1. ADK creates or retrieves a session via `RedisSessionMemoryService`. 2. Long-term memory is searched for context relevant to the current conversation. -3. User messages are appended to working memory incrementally. +3. User messages are appended to session memory incrementally. 4. The LLM generates a response using session context plus retrieved memories. 5. `after_agent_callback` triggers `add_session_to_memory()` for background extraction. -6. If the conversation grows long, working memory auto-summarizes older turns. ## REST tools -Give the agent explicit memory tools that the LLM calls like any other function. The LLM decides when to search memory, what to store, and what to update. No framework services required. +Give the agent explicit memory tools that the LLM calls like any other function. The LLM decides when to search memory, what to store, and what to update. No framework services required. The tools share a single `MemoryToolConfig`. + +adk-redis ships six memory tools: + +| Tool | Description | +|------|-------------| +| `SearchMemoryTool` | Search long-term memories by query | +| `CreateMemoryTool` | Store new long-term memories | +| `GetMemoryTool` | Fetch a single memory by ID | +| `UpdateMemoryTool` | Update an existing memory by ID | +| `DeleteMemoryTool` | Delete memories by ID | +| `MemoryPromptTool` | Enrich the agent prompt with relevant memories | ```python from adk_redis.tools.memory import ( SearchMemoryTool, CreateMemoryTool, + GetMemoryTool, UpdateMemoryTool, DeleteMemoryTool, + MemoryPromptTool, MemoryToolConfig, ) config = MemoryToolConfig( - api_base_url="http://localhost:8088", + backend="redis-agent-memory", + api_base_url="https://your-endpoint.redis.io", + api_key="your-api-key", + store_id="your-store-id", default_namespace="my_app", - recency_boost=True, ) agent = Agent( @@ -183,43 +222,33 @@ agent = Agent( tools=[ SearchMemoryTool(config=config), CreateMemoryTool(config=config), + GetMemoryTool(config=config), UpdateMemoryTool(config=config), DeleteMemoryTool(config=config), + MemoryPromptTool(config=config), ], ) ``` Requires prompt engineering to teach the LLM memory management strategy, but gives the agent genuine autonomy over its own memory. -## MCP tools - -Point ADK's `McpToolset` at the Agent Memory Server's SSE endpoint. Tool discovery happens automatically — no manual tool wiring required. +### Invocation-scoped users -```python -from adk_redis.tools.mcp_memory import create_memory_mcp_toolset - -memory_tools = create_memory_mcp_toolset( - server_url="http://localhost:9000", - tool_filter=["search_long_term_memory", "create_long_term_memories"], -) +The memory tools resolve the acting user from the ADK `tool_context` before falling back to the user configured on `MemoryToolConfig`. A single shared `Runner` therefore stays scoped to the user of each invocation, with no per-user tool instances. -agent = Agent( - model="gemini-2.5-flash", - name="mcp_agent", - tools=[memory_tools], -) -``` +`CreateMemoryTool.run_async()` also accepts an application-supplied `id` for idempotent writes against Redis Agent Memory. IDs are derived with namespace and user scope to prevent cross-tenant collisions, and are never exposed to the LLM. -Available MCP tools: `search_long_term_memory`, `create_long_term_memories`, `get_long_term_memory`, `edit_long_term_memory`, `delete_long_term_memories`, `memory_prompt`, `set_working_memory`. +## MCP tools -The most portable approach — swap memory backends without changing agent code. Requires the Agent Memory Server running with MCP support on a separate port. +MCP memory tools are only available on the deprecated +[Agent Memory Server]({{< relref "/integrate/google-adk/agent-memory-server" >}}) +backend. The `redis-agent-memory` backend does not expose an MCP endpoint, on +Redis Cloud or self-managed; use the REST tools above. ## More info -- [Integration patterns]({{< relref "/integrate/google-adk/integration-patterns" >}}): Detailed tradeoff comparison of all three approaches -- [simple_redis_memory](https://github.com/redis-developer/adk-redis/tree/main/examples/simple_redis_memory): Minimal framework services setup +- [Integration patterns]({{< relref "/integrate/google-adk/integration-patterns" >}}): Detailed tradeoff comparison of the approaches +- [managed_memory_quickstart](https://github.com/redis-developer/adk-redis/tree/main/examples/managed_memory_quickstart): Framework services, no Docker - [travel_agent_memory_tools](https://github.com/redis-developer/adk-redis/tree/main/examples/travel_agent_memory_tools): REST tools only -- [fitness_coach_mcp](https://github.com/redis-developer/adk-redis/tree/main/examples/fitness_coach_mcp): MCP tools -- [travel_agent_memory_hybrid](https://github.com/redis-developer/adk-redis/tree/main/examples/travel_agent_memory_hybrid): Framework services + REST tools combined -- [Agent Memory Server documentation](https://github.com/redis/agent-memory-server) - +- [Self-managed Agent Memory]({{< relref "/develop/ai/context-engine/agent-memory/self-managed" >}}): run Agent Memory on your own Kubernetes cluster +- [Agent Memory Server (deprecated)]({{< relref "/integrate/google-adk/agent-memory-server" >}}): existing deployments and migration diff --git a/content/integrate/google-adk/semantic-caching.md b/content/integrate/google-adk/semantic-caching.md index b1e841898a..85864fadd2 100644 --- a/content/integrate/google-adk/semantic-caching.md +++ b/content/integrate/google-adk/semantic-caching.md @@ -54,17 +54,41 @@ provider = RedisVLCacheProvider( No local vectorizer needed. Embeddings are generated server-side. ```python +import os + from adk_redis.cache import LangCacheProvider, LangCacheProviderConfig provider = LangCacheProvider( config=LangCacheProviderConfig( - cache_id="your-cache-id", - api_key="your-api-key", + cache_id=os.environ["LANGCACHE_CACHE_ID"], + api_key=os.environ["LANGCACHE_API_KEY"], + server_url="https://aws-us-east-1.langcache.redis.io", ttl=3600, ) ) ``` +Set `server_url` to the endpoint for your LangCache region. + +## Cache entry IDs and targeted invalidation + +Both providers return a `CacheEntry` from `check()` and an entry ID from +`store()`. When the backend exposes a stable identifier, `CacheEntry.entry_id` +carries it, and you can retire exactly that entry with `delete_by_id()` instead +of clearing the whole cache. + +```python +entry = await provider.check(prompt="What is the return policy?") + +if entry is not None and entry.entry_id is not None: + # Retire one stale answer without touching unrelated entries + await provider.delete_by_id(entry.entry_id) +``` + +`CacheEntry` also carries the matched `prompt`, the cached `response`, the match +`distance`, and any `metadata` stored alongside the entry. `entry_id` is `None` +when the backend does not expose an identifier. + ## LLM response cache Intercepts model calls through ADK's `before_model_callback` and `after_model_callback`.