From f45fb9dbd017eb708ff55cb4826e249bb0bc2820 Mon Sep 17 00:00:00 2001 From: Anna Tao Date: Mon, 6 Jul 2026 17:50:04 -0700 Subject: [PATCH 1/4] docs: add Valkey storage adapter and vector database documentation --- database/valkey.mdx | 82 +++++++++++++++++++ knowledge/vector-stores/valkey/overview.mdx | 91 +++++++++++++++++++++ 2 files changed, 173 insertions(+) create mode 100644 database/valkey.mdx create mode 100644 knowledge/vector-stores/valkey/overview.mdx diff --git a/database/valkey.mdx b/database/valkey.mdx new file mode 100644 index 000000000..e92221058 --- /dev/null +++ b/database/valkey.mdx @@ -0,0 +1,82 @@ +--- +title: Valkey +description: Use Valkey for session storage and persistence. +sidebarTitle: Overview +--- + +Agno supports using [Valkey](https://valkey.io/) as a database with the `ValkeyDb` class. + +## Usage + +### Run Valkey + +Install [docker desktop](https://docs.docker.com/desktop/install/mac-install/) and run **Valkey** on port **6379** using: + +```bash +docker run -d \ + --name my-valkey \ + -p 6379:6379 \ + valkey/valkey +``` + +```python valkey_for_agent.py +from agno.agent import Agent +from agno.db.valkey import ValkeyDb + +# Initialize Valkey db +db = ValkeyDb( + host="localhost", + port=6379, +) + +# Create agent with Valkey db +agent = Agent(db=db) +``` + +### Authentication + +```python +db = ValkeyDb( + host="your-valkey-host", + port=6379, + username="your-username", + password="your-password", + use_tls=True, +) +``` + +### Configuration Options + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `host` | `str` | `"localhost"` | Valkey server host | +| `port` | `int` | `6379` | Valkey server port | +| `database_id` | `int` | `None` | Logical database index (0-15) | +| `username` | `str` | `None` | Username for authentication | +| `password` | `str` | `None` | Password for authentication | +| `use_tls` | `bool` | `False` | Enable TLS encryption | +| `db_prefix` | `str` | `"agno"` | Prefix for all Valkey keys | +| `expire` | `int` | `None` | TTL for keys in seconds | +| `client_name` | `str` | `"agno_db_client"` | Connection name (visible in CLIENT LIST) | +| `valkey_client` | `GlideClient` | `None` | Pre-configured client instance | + +### Pre-configured Client + +You can pass a pre-configured `GlideClient` or `GlideClusterClient` instance: + +```python +from glide_sync import GlideClient, GlideClientConfiguration, NodeAddress + +client = GlideClient.create( + GlideClientConfiguration( + addresses=[NodeAddress("localhost", 6379)], + client_name="my_app", + ) +) + +db = ValkeyDb(valkey_client=client) +``` + +## Developer Resources + +- View [Cookbook](https://github.com/agno-agi/agno/tree/main/cookbook/06_storage/valkey) diff --git a/knowledge/vector-stores/valkey/overview.mdx b/knowledge/vector-stores/valkey/overview.mdx new file mode 100644 index 000000000..8add870f6 --- /dev/null +++ b/knowledge/vector-stores/valkey/overview.mdx @@ -0,0 +1,91 @@ +--- +title: Valkey Vector Database +sidebarTitle: Overview +description: Use Valkey as a vector database for your Knowledge Base. +--- + +You can use Valkey as a vector database with Agno using the valkey-search module. + +## Setup + +Valkey vector search requires the valkey-search module. Use the `valkey/valkey-bundle` Docker image which includes it: + +```shell +docker run -d --name my-valkey \ + -p 6379:6379 \ + valkey/valkey-bundle +``` + +## Example + +```python agent_with_knowledge.py +from agno.agent import Agent +from agno.knowledge.knowledge import Knowledge +from agno.vectordb.valkey import ValkeyDB +from agno.vectordb.search import SearchType + +# Initialize Valkey Vector DB +vector_db = ValkeyDB( + index_name="agno_docs", + host="localhost", + port=6379, + search_type=SearchType.vector, +) + +# Build a Knowledge base backed by Valkey +knowledge = Knowledge( + name="My Valkey Knowledge Base", + description="Knowledge base using Valkey as the vector store", + vector_db=vector_db, +) + +# Add content +knowledge.insert( + name="Recipes", + url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf", + metadata={"category": "recipe_book"}, + skip_if_exists=True, +) + +# Query with an Agent +agent = Agent(knowledge=knowledge) +agent.print_response("List down the ingredients to make Massaman Gai", markdown=True) +``` + +## Metadata Filtering + +Valkey supports dict-based metadata filtering on indexed tag fields: + +```python +agent.print_response( + "Find Thai recipes", + knowledge_filters={"category": "recipe_book"}, +) +``` + +Supported filter fields: `category`, `tag`, `source`, `status`, `mode`, `content_id`, `id`, `name`. + + +Valkey-search filters on pre-indexed fields only (declared in the FT.CREATE schema). Unlike pgvector, arbitrary metadata keys cannot be filtered without adding them to the index schema. The `FilterExpr` DSL is not supported. + + +## Configuration Options + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `index_name` | `str` | *required* | Name of the Valkey search index | +| `host` | `str` | `"localhost"` | Valkey server host | +| `port` | `int` | `6379` | Valkey server port | +| `username` | `str` | `None` | Username for authentication | +| `password` | `str` | `None` | Password for authentication | +| `use_tls` | `bool` | `False` | Enable TLS encryption | +| `database_id` | `int` | `None` | Logical database index (0-15) | +| `search_type` | `SearchType` | `vector` | Search type: `vector` or `keyword` | +| `distance` | `Distance` | `cosine` | Distance metric: `cosine`, `l2`, or `max_inner_product` | +| `vector_algorithm` | `str` | `"HNSW"` | Vector index algorithm: `HNSW` or `FLAT` | +| `client_name` | `str` | `"agno_vectordb_client"` | Connection name (visible in CLIENT LIST) | +| `glide_client` | `GlideClient` | `None` | Pre-configured client instance | + +## Developer Resources + +- View [Cookbook](https://github.com/agno-agi/agno/tree/main/cookbook/07_knowledge/05_integrations/vector_dbs/05_valkey.py) From 6fe6cff1e43215e782f4fd0759546f285865fc39 Mon Sep 17 00:00:00 2001 From: Anna Tao Date: Mon, 6 Jul 2026 17:54:56 -0700 Subject: [PATCH 2/4] fix: move storage doc to correct path --- database/valkey.mdx | 83 +-------------------------------------------- 1 file changed, 1 insertion(+), 82 deletions(-) diff --git a/database/valkey.mdx b/database/valkey.mdx index e92221058..a6bdb1d8b 100644 --- a/database/valkey.mdx +++ b/database/valkey.mdx @@ -1,82 +1 @@ ---- -title: Valkey -description: Use Valkey for session storage and persistence. -sidebarTitle: Overview ---- - -Agno supports using [Valkey](https://valkey.io/) as a database with the `ValkeyDb` class. - -## Usage - -### Run Valkey - -Install [docker desktop](https://docs.docker.com/desktop/install/mac-install/) and run **Valkey** on port **6379** using: - -```bash -docker run -d \ - --name my-valkey \ - -p 6379:6379 \ - valkey/valkey -``` - -```python valkey_for_agent.py -from agno.agent import Agent -from agno.db.valkey import ValkeyDb - -# Initialize Valkey db -db = ValkeyDb( - host="localhost", - port=6379, -) - -# Create agent with Valkey db -agent = Agent(db=db) -``` - -### Authentication - -```python -db = ValkeyDb( - host="your-valkey-host", - port=6379, - username="your-username", - password="your-password", - use_tls=True, -) -``` - -### Configuration Options - -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| `host` | `str` | `"localhost"` | Valkey server host | -| `port` | `int` | `6379` | Valkey server port | -| `database_id` | `int` | `None` | Logical database index (0-15) | -| `username` | `str` | `None` | Username for authentication | -| `password` | `str` | `None` | Password for authentication | -| `use_tls` | `bool` | `False` | Enable TLS encryption | -| `db_prefix` | `str` | `"agno"` | Prefix for all Valkey keys | -| `expire` | `int` | `None` | TTL for keys in seconds | -| `client_name` | `str` | `"agno_db_client"` | Connection name (visible in CLIENT LIST) | -| `valkey_client` | `GlideClient` | `None` | Pre-configured client instance | - -### Pre-configured Client - -You can pass a pre-configured `GlideClient` or `GlideClusterClient` instance: - -```python -from glide_sync import GlideClient, GlideClientConfiguration, NodeAddress - -client = GlideClient.create( - GlideClientConfiguration( - addresses=[NodeAddress("localhost", 6379)], - client_name="my_app", - ) -) - -db = ValkeyDb(valkey_client=client) -``` - -## Developer Resources - -- View [Cookbook](https://github.com/agno-agi/agno/tree/main/cookbook/06_storage/valkey) +This file has been moved to database/providers/valkey/overview.mdx From a0b33758da9272dba6888629b3d5296dee554685 Mon Sep 17 00:00:00 2001 From: Anna Tao Date: Mon, 6 Jul 2026 17:55:32 -0700 Subject: [PATCH 3/4] docs: add Valkey storage provider with usage examples --- database/providers/valkey/overview.mdx | 49 +++++++++++++++++++ .../valkey/usage/valkey-for-agent.mdx | 27 ++++++++++ .../valkey/usage/valkey-for-team.mdx | 32 ++++++++++++ .../valkey/usage/valkey-for-workflow.mdx | 30 ++++++++++++ 4 files changed, 138 insertions(+) create mode 100644 database/providers/valkey/overview.mdx create mode 100644 database/providers/valkey/usage/valkey-for-agent.mdx create mode 100644 database/providers/valkey/usage/valkey-for-team.mdx create mode 100644 database/providers/valkey/usage/valkey-for-workflow.mdx diff --git a/database/providers/valkey/overview.mdx b/database/providers/valkey/overview.mdx new file mode 100644 index 000000000..aae5bc438 --- /dev/null +++ b/database/providers/valkey/overview.mdx @@ -0,0 +1,49 @@ +--- +title: Valkey +description: Use Valkey for agent session storage and persistence. +sidebarTitle: Overview +--- + +Agno supports using [Valkey](https://valkey.io/) as a database with the `ValkeyDb` class. + +## Usage + +### Run Valkey + +Install [docker desktop](https://docs.docker.com/desktop/install/mac-install/) and run **Valkey** on port **6379** using: + +```bash +docker run -d \ + --name my-valkey \ + -p 6379:6379 \ + valkey/valkey +``` + +```python valkey_for_agent.py +from agno.agent import Agent +from agno.db.valkey import ValkeyDb + +# Initialize Valkey db +db = ValkeyDb( + host="localhost", + port=6379, +) + +# Create agent with Valkey db +agent = Agent(db=db) +``` + +## Params + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `host` | `str` | `"localhost"` | Valkey server host | +| `port` | `int` | `6379` | Valkey server port | +| `database_id` | `int` | `None` | Logical database index (0-15) | +| `username` | `str` | `None` | Username for authentication | +| `password` | `str` | `None` | Password for authentication | +| `use_tls` | `bool` | `False` | Enable TLS encryption | +| `db_prefix` | `str` | `"agno"` | Prefix for all Valkey keys | +| `expire` | `int` | `None` | TTL for keys in seconds | +| `client_name` | `str` | `"agno_db_client"` | Connection name (visible in CLIENT LIST) | +| `valkey_client` | `GlideClient` | `None` | Pre-configured client instance | diff --git a/database/providers/valkey/usage/valkey-for-agent.mdx b/database/providers/valkey/usage/valkey-for-agent.mdx new file mode 100644 index 000000000..c6c431e60 --- /dev/null +++ b/database/providers/valkey/usage/valkey-for-agent.mdx @@ -0,0 +1,27 @@ +--- +title: Valkey for Agent +sidebarTitle: Agent Storage +description: Use Valkey to persist agent sessions. +--- + +```python valkey_for_agent.py +from agno.agent import Agent +from agno.db.valkey import ValkeyDb +from agno.models.openai import OpenAIResponses + +db = ValkeyDb( + host="localhost", + port=6379, +) + +agent = Agent( + model=OpenAIResponses(id="gpt-4o"), + db=db, + add_history_to_context=True, + num_history_runs=3, + markdown=True, +) + +agent.print_response("What is Valkey?") +agent.print_response("Tell me more about its vector search capabilities") +``` diff --git a/database/providers/valkey/usage/valkey-for-team.mdx b/database/providers/valkey/usage/valkey-for-team.mdx new file mode 100644 index 000000000..3d6673685 --- /dev/null +++ b/database/providers/valkey/usage/valkey-for-team.mdx @@ -0,0 +1,32 @@ +--- +title: Valkey for Team +sidebarTitle: Team Storage +description: Use Valkey to persist team sessions. +--- + +```python valkey_for_team.py +from agno.agent import Agent +from agno.db.valkey import ValkeyDb +from agno.models.openai import OpenAIResponses +from agno.team.team import Team + +db = ValkeyDb( + host="localhost", + port=6379, +) + +agent = Agent( + name="Research Agent", + model=OpenAIResponses(id="gpt-4o"), + db=db, +) + +team = Team( + name="Research Team", + model=OpenAIResponses(id="gpt-4o"), + db=db, + members=[agent], +) + +team.print_response("Summarize the latest trends in AI agents") +``` diff --git a/database/providers/valkey/usage/valkey-for-workflow.mdx b/database/providers/valkey/usage/valkey-for-workflow.mdx new file mode 100644 index 000000000..728a9a8d9 --- /dev/null +++ b/database/providers/valkey/usage/valkey-for-workflow.mdx @@ -0,0 +1,30 @@ +--- +title: Valkey for Workflow +sidebarTitle: Workflow Storage +description: Use Valkey to persist workflow sessions. +--- + +```python valkey_for_workflow.py +from agno.agent import Agent +from agno.db.valkey import ValkeyDb +from agno.models.openai import OpenAIResponses +from agno.workflow import Workflow + +db = ValkeyDb( + host="localhost", + port=6379, +) + +agent = Agent( + name="Writer", + model=OpenAIResponses(id="gpt-4o"), +) + +workflow = Workflow( + name="Writing Workflow", + db=db, + agents=[agent], +) + +workflow.print_response("Write a short blog post about Valkey") +``` From 7b0c2eeaa22ec0638a28fc74493d5bc9f5cc4ffe Mon Sep 17 00:00:00 2001 From: Harsh Sinha Date: Tue, 14 Jul 2026 13:53:01 +0530 Subject: [PATCH 4/4] update --- _snippets/db-valkey-params.mdx | 22 +++++ _snippets/vectordb_valkey_params.mdx | 20 ++++ cookbook/storage/overview.mdx | 15 +++ database/providers/overview.mdx | 8 ++ database/providers/valkey/overview.mdx | 13 +-- .../valkey/usage/valkey-for-agent.mdx | 46 +++++++-- .../valkey/usage/valkey-for-team.mdx | 73 +++++++++++--- .../valkey/usage/valkey-for-workflow.mdx | 92 ++++++++++++++--- database/valkey.mdx | 1 - docs.json | 67 +++++++++++++ examples/agent-os/dbs/overview.mdx | 1 + examples/agent-os/dbs/valkey-db.mdx | 89 +++++++++++++++++ examples/knowledge/vector-db/overview.mdx | 1 + .../vector-db/valkey-db/overview.mdx | 9 ++ .../valkey-db-metadata-filtering.mdx | 72 ++++++++++++++ .../vector-db/valkey-db/valkey-db.mdx | 84 ++++++++++++++++ examples/storage/overview.mdx | 1 + examples/storage/valkey/overview.mdx | 10 ++ examples/storage/valkey/valkey-for-agent.mdx | 68 +++++++++++++ examples/storage/valkey/valkey-for-team.mdx | 99 +++++++++++++++++++ .../storage/valkey/valkey-for-workflow.mdx | 97 ++++++++++++++++++ features/storage.mdx | 3 +- knowledge/concepts/contents-db.mdx | 2 +- knowledge/concepts/vector-db.mdx | 3 + knowledge/vector-stores/index.mdx | 8 ++ knowledge/vector-stores/valkey/overview.mdx | 42 ++------ .../valkey/usage/async-valkey-db.mdx | 71 +++++++++++++ .../vector-stores/valkey/usage/valkey-db.mdx | 61 ++++++++++++ reference/storage/valkey.mdx | 8 ++ 29 files changed, 1001 insertions(+), 85 deletions(-) create mode 100644 _snippets/db-valkey-params.mdx create mode 100644 _snippets/vectordb_valkey_params.mdx delete mode 100644 database/valkey.mdx create mode 100644 examples/agent-os/dbs/valkey-db.mdx create mode 100644 examples/knowledge/vector-db/valkey-db/overview.mdx create mode 100644 examples/knowledge/vector-db/valkey-db/valkey-db-metadata-filtering.mdx create mode 100644 examples/knowledge/vector-db/valkey-db/valkey-db.mdx create mode 100644 examples/storage/valkey/overview.mdx create mode 100644 examples/storage/valkey/valkey-for-agent.mdx create mode 100644 examples/storage/valkey/valkey-for-team.mdx create mode 100644 examples/storage/valkey/valkey-for-workflow.mdx create mode 100644 knowledge/vector-stores/valkey/usage/async-valkey-db.mdx create mode 100644 knowledge/vector-stores/valkey/usage/valkey-db.mdx create mode 100644 reference/storage/valkey.mdx diff --git a/_snippets/db-valkey-params.mdx b/_snippets/db-valkey-params.mdx new file mode 100644 index 000000000..9144b4c6e --- /dev/null +++ b/_snippets/db-valkey-params.mdx @@ -0,0 +1,22 @@ +| Parameter | Type | Default | Description | +| ----------------- | -------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------- | +| `id` | `Optional[str]` | - | The ID of the database instance. UUID by default. | +| `valkey_client` | `Optional[Union[GlideClient, GlideClusterClient]]` | - | Pre-configured Valkey GLIDE client. If not provided a new client will be created. | +| `host` | `str` | `"localhost"` | Valkey server host. | +| `port` | `int` | `6379` | Valkey server port. | +| `database_id` | `Optional[int]` | - | Logical database index (e.g. 0-15). | +| `username` | `Optional[str]` | - | Username for authentication. | +| `password` | `Optional[str]` | - | Password for authentication. | +| `use_tls` | `bool` | `False` | Enable TLS encryption. | +| `request_timeout` | `Optional[int]` | - | Milliseconds to wait for a request to complete. If unset, the GLIDE client default (250 ms) applies. | +| `db_prefix` | `str` | `"agno"` | Prefix for all Valkey keys. | +| `client_name` | `str` | `"agno_db_client"` | Connection name, visible in `CLIENT LIST`. | +| `expire` | `Optional[int]` | - | TTL for Valkey keys in seconds. | +| `session_table` | `Optional[str]` | - | Name of the table to store sessions. | +| `memory_table` | `Optional[str]` | - | Name of the table to store memories. | +| `metrics_table` | `Optional[str]` | - | Name of the table to store metrics. | +| `eval_table` | `Optional[str]` | - | Name of the table to store evaluation runs. | +| `knowledge_table` | `Optional[str]` | - | Name of the table to store knowledge documents. | +| `traces_table` | `Optional[str]` | - | Name of the table to store traces. | +| `spans_table` | `Optional[str]` | - | Name of the table to store spans. | +| `learnings_table` | `Optional[str]` | - | Name of the table to store learnings. | diff --git a/_snippets/vectordb_valkey_params.mdx b/_snippets/vectordb_valkey_params.mdx new file mode 100644 index 000000000..59c476577 --- /dev/null +++ b/_snippets/vectordb_valkey_params.mdx @@ -0,0 +1,20 @@ +| Parameter | Type | Default | Description | +| --------- | ---- | ------- | ----------- | +| `index_name` | `str` | Required | Name of the Valkey search index to store vector data | +| `host` | `str` | `"localhost"` | Valkey server host | +| `port` | `int` | `6379` | Valkey server port | +| `username` | `Optional[str]` | `None` | Username for authentication | +| `password` | `Optional[str]` | `None` | Password for authentication | +| `use_tls` | `bool` | `False` | Enable TLS encryption | +| `database_id` | `Optional[int]` | `None` | Logical database index (e.g. 0-15) | +| `request_timeout` | `Optional[int]` | `None` | Milliseconds to wait for a request to complete. If unset, the GLIDE client default (250 ms) applies | +| `client_name` | `str` | `"agno_vectordb_client"` | Connection name, visible in `CLIENT LIST` | +| `glide_client` | `Optional[GlideClient]` | `None` | Pre-configured Valkey GLIDE client instance | +| `embedder` | `Optional[Embedder]` | `None` | Embedder instance to generate embeddings (defaults to `OpenAIEmbedder()` when unset) | +| `search_type` | `SearchType` | `SearchType.vector` | Type of search to perform (vector, keyword) | +| `distance` | `Distance` | `Distance.cosine` | Distance metric (cosine, l2, max_inner_product) | +| `vector_algorithm` | `str` | `"HNSW"` | Vector index algorithm (HNSW or FLAT) | +| `reranker` | `Optional[Reranker]` | `None` | Reranker for search results | +| `id` | `Optional[str]` | `None` | Optional custom ID. If not provided, an ID will be generated | +| `name` | `Optional[str]` | `None` | Optional name for the vector database | +| `description` | `Optional[str]` | `None` | Optional description for the vector database | diff --git a/cookbook/storage/overview.mdx b/cookbook/storage/overview.mdx index 51874cf1f..4fe6ecde2 100644 --- a/cookbook/storage/overview.mdx +++ b/cookbook/storage/overview.mdx @@ -28,6 +28,7 @@ agent.print_response("What did I just say?") | SQLite | `from agno.db.sqlite import SqliteDb` | Local development | | MongoDB | `from agno.db.mongodb import MongoDb` | Document stores | | Redis | `from agno.db.redis import RedisDb` | Caching, speed | +| Valkey | `from agno.db.valkey import ValkeyDb` | Caching, speed | | DynamoDB | `from agno.db.dynamodb import DynamoDb` | AWS serverless | | Firestore | `from agno.db.firestore import FirestoreDb` | GCP serverless | | MySQL | `from agno.db.mysql import MysqlDb` | MySQL users | @@ -109,6 +110,20 @@ agent = Agent( ) ``` +### Valkey + +High-speed caching. + +```python cookbook/06_storage/valkey/valkey_for_agent.py +from agno.agent import Agent +from agno.db.valkey import ValkeyDb + +agent = Agent( + db=ValkeyDb(host="localhost", port=6379), + add_history_to_context=True, +) +``` + ### DynamoDB AWS serverless storage. diff --git a/database/providers/overview.mdx b/database/providers/overview.mdx index 3686dab95..b9c5adde1 100644 --- a/database/providers/overview.mdx +++ b/database/providers/overview.mdx @@ -87,6 +87,14 @@ Agno supports the following database providers organized by category: > Redis in-memory data store integration. + + Valkey in-memory data store integration. + diff --git a/database/providers/valkey/usage/valkey-for-agent.mdx b/database/providers/valkey/usage/valkey-for-agent.mdx index c6c431e60..537afce4e 100644 --- a/database/providers/valkey/usage/valkey-for-agent.mdx +++ b/database/providers/valkey/usage/valkey-for-agent.mdx @@ -1,27 +1,57 @@ --- title: Valkey for Agent -sidebarTitle: Agent Storage -description: Use Valkey to persist agent sessions. +sidebarTitle: Agent --- +Agno supports using Valkey as a storage backend for Agents using the `ValkeyDb` class. + +## Usage + +### Run Valkey + +Install [docker desktop](https://docs.docker.com/desktop/install/mac-install/) and run **Valkey** on port **6379** using: + +```bash +docker run -d \ + --name my-valkey \ + -p 6379:6379 \ + valkey/valkey +``` + ```python valkey_for_agent.py from agno.agent import Agent +from agno.db.base import SessionType from agno.db.valkey import ValkeyDb -from agno.models.openai import OpenAIResponses +from agno.tools.hackernews import HackerNewsTools +# Initialize Valkey db db = ValkeyDb( host="localhost", port=6379, ) +# Create agent with Valkey db agent = Agent( - model=OpenAIResponses(id="gpt-4o"), db=db, + tools=[HackerNewsTools()], add_history_to_context=True, - num_history_runs=3, - markdown=True, ) -agent.print_response("What is Valkey?") -agent.print_response("Tell me more about its vector search capabilities") +agent.print_response("How many people live in Canada?") +agent.print_response("What is their national anthem called?") + +# Verify db contents +print("\nVerifying db contents...") +all_sessions = db.get_sessions(session_type=SessionType.AGENT) +print(f"Total sessions in Valkey: {len(all_sessions)}") + +if all_sessions: + print("\nSession details:") + session = all_sessions[0] + print(f"The stored session: {session}") + ``` + +## Params + + diff --git a/database/providers/valkey/usage/valkey-for-team.mdx b/database/providers/valkey/usage/valkey-for-team.mdx index 3d6673685..d2ff3a474 100644 --- a/database/providers/valkey/usage/valkey-for-team.mdx +++ b/database/providers/valkey/usage/valkey-for-team.mdx @@ -1,32 +1,81 @@ --- title: Valkey for Team -sidebarTitle: Team Storage -description: Use Valkey to persist team sessions. +sidebarTitle: Team --- +Agno supports using Valkey as a storage backend for Teams using the `ValkeyDb` class. + +## Usage + +### Run Valkey + +Install [docker desktop](https://docs.docker.com/desktop/install/mac-install/) and run **Valkey** on port **6379** using: + +```bash +docker run -d \ + --name my-valkey \ + -p 6379:6379 \ + valkey/valkey +``` + ```python valkey_for_team.py +""" +Run: `uv pip install openai agno valkey-glide-sync` to install the dependencies +""" + +from typing import List + from agno.agent import Agent from agno.db.valkey import ValkeyDb from agno.models.openai import OpenAIResponses -from agno.team.team import Team +from agno.team import Team +from agno.tools.hackernews import HackerNewsTools +from pydantic import BaseModel db = ValkeyDb( host="localhost", port=6379, ) -agent = Agent( - name="Research Agent", - model=OpenAIResponses(id="gpt-4o"), - db=db, +class Article(BaseModel): + title: str + summary: str + reference_links: List[str] + +hn_researcher = Agent( + name="HackerNews Researcher", + model=OpenAIResponses(id="gpt-5.2"), + role="Gets top stories from hackernews.", + tools=[HackerNewsTools()], +) + +web_searcher = Agent( + name="Web Searcher", + model=OpenAIResponses(id="gpt-5.2"), + role="Searches the web for information on a topic", + tools=[HackerNewsTools()], + add_datetime_to_context=True, ) -team = Team( - name="Research Team", - model=OpenAIResponses(id="gpt-4o"), +hn_team = Team( + name="HackerNews Team", + model=OpenAIResponses(id="gpt-5.2"), + members=[hn_researcher, web_searcher], db=db, - members=[agent], + instructions=[ + "First, search hackernews for what the user is asking about.", + "Then, ask the web searcher to search for each story to get more information.", + "Finally, provide a thoughtful and engaging summary.", + ], + output_schema=Article, + markdown=True, + show_members_responses=True, ) -team.print_response("Summarize the latest trends in AI agents") +hn_team.print_response("Write an article about the top 2 stories on hackernews") + ``` + +## Params + + diff --git a/database/providers/valkey/usage/valkey-for-workflow.mdx b/database/providers/valkey/usage/valkey-for-workflow.mdx index 728a9a8d9..8701d5d81 100644 --- a/database/providers/valkey/usage/valkey-for-workflow.mdx +++ b/database/providers/valkey/usage/valkey-for-workflow.mdx @@ -1,30 +1,94 @@ --- title: Valkey for Workflow -sidebarTitle: Workflow Storage -description: Use Valkey to persist workflow sessions. +sidebarTitle: Workflow --- +Agno supports using Valkey as a storage backend for Workflows using the `ValkeyDb` class. + +## Usage + +### Run Valkey + +Install [docker desktop](https://docs.docker.com/desktop/install/mac-install/) and run **Valkey** on port **6379** using: + +```bash +docker run -d \ + --name my-valkey \ + -p 6379:6379 \ + valkey/valkey +``` + ```python valkey_for_workflow.py +""" +Run: `uv pip install openai agno valkey-glide-sync fastapi` to install the dependencies +""" from agno.agent import Agent from agno.db.valkey import ValkeyDb from agno.models.openai import OpenAIResponses -from agno.workflow import Workflow +from agno.team import Team +from agno.tools.hackernews import HackerNewsTools +from agno.workflow.step import Step +from agno.workflow.workflow import Workflow + +# Define agents +hackernews_agent = Agent( + name="Hackernews Agent", + model=OpenAIResponses(id="gpt-5.2"), + tools=[HackerNewsTools()], + role="Extract key insights and content from Hackernews posts", +) +web_agent = Agent( + name="Web Agent", + model=OpenAIResponses(id="gpt-5.2"), + tools=[HackerNewsTools()], + role="Search the web for the latest news and trends", +) + +# Define research team for complex analysis +research_team = Team( + name="Research Team", + members=[hackernews_agent, web_agent], + instructions="Research tech topics from Hackernews and the web", +) -db = ValkeyDb( - host="localhost", - port=6379, +content_planner = Agent( + name="Content Planner", + model=OpenAIResponses(id="gpt-5.2"), + instructions=[ + "Plan a content schedule over 4 weeks for the provided topic and research content", + "Ensure that I have posts for 3 posts per week", + ], ) -agent = Agent( - name="Writer", - model=OpenAIResponses(id="gpt-4o"), +# Define steps +research_step = Step( + name="Research Step", + team=research_team, ) -workflow = Workflow( - name="Writing Workflow", - db=db, - agents=[agent], +content_planning_step = Step( + name="Content Planning Step", + agent=content_planner, ) -workflow.print_response("Write a short blog post about Valkey") +# Create and use workflow +if __name__ == "__main__": + content_creation_workflow = Workflow( + name="Content Creation Workflow", + description="Automated content creation from blog posts to social media", + db=ValkeyDb( + host="localhost", + port=6379, + ), + steps=[research_step, content_planning_step], + ) + content_creation_workflow.print_response( + input="AI trends in 2024", + markdown=True, + ) + ``` + +## Params + + diff --git a/database/valkey.mdx b/database/valkey.mdx deleted file mode 100644 index a6bdb1d8b..000000000 --- a/database/valkey.mdx +++ /dev/null @@ -1 +0,0 @@ -This file has been moved to database/providers/valkey/overview.mdx diff --git a/docs.json b/docs.json index 9e08abd56..ece679135 100644 --- a/docs.json +++ b/docs.json @@ -584,6 +584,20 @@ } ] }, + { + "group": "Valkey", + "pages": [ + "database/providers/valkey/overview", + { + "group": "Usage", + "pages": [ + "database/providers/valkey/usage/valkey-for-agent", + "database/providers/valkey/usage/valkey-for-team", + "database/providers/valkey/usage/valkey-for-workflow" + ] + } + ] + }, { "group": "GCS", "pages": [ @@ -962,6 +976,19 @@ } ] }, + { + "group": "Valkey", + "pages": [ + "knowledge/vector-stores/valkey/overview", + { + "group": "Usage", + "pages": [ + "knowledge/vector-stores/valkey/usage/valkey-db", + "knowledge/vector-stores/valkey/usage/async-valkey-db" + ] + } + ] + }, { "group": "MongoDB", "pages": [ @@ -4141,6 +4168,20 @@ } ] }, + { + "group": "Valkey", + "pages": [ + "database/providers/valkey/overview", + { + "group": "Usage", + "pages": [ + "database/providers/valkey/usage/valkey-for-agent", + "database/providers/valkey/usage/valkey-for-team", + "database/providers/valkey/usage/valkey-for-workflow" + ] + } + ] + }, { "group": "GCS", "pages": [ @@ -4351,6 +4392,19 @@ } ] }, + { + "group": "Valkey", + "pages": [ + "knowledge/vector-stores/valkey/overview", + { + "group": "Usage", + "pages": [ + "knowledge/vector-stores/valkey/usage/valkey-db", + "knowledge/vector-stores/valkey/usage/async-valkey-db" + ] + } + ] + }, { "group": "MongoDB", "pages": [ @@ -5619,6 +5673,15 @@ "examples/storage/redis/redis-for-workflow" ] }, + { + "group": "Valkey", + "pages": [ + "examples/storage/valkey/overview", + "examples/storage/valkey/valkey-for-agent", + "examples/storage/valkey/valkey-for-team", + "examples/storage/valkey/valkey-for-workflow" + ] + }, { "group": "SingleStore", "pages": [ @@ -5851,6 +5914,8 @@ "examples/knowledge/vector-db/singlestore-db/singlestore-db", "examples/knowledge/vector-db/surrealdb/surreal-db", "examples/knowledge/vector-db/upstash-db/upstash-db", + "examples/knowledge/vector-db/valkey-db/valkey-db", + "examples/knowledge/vector-db/valkey-db/valkey-db-metadata-filtering", "examples/knowledge/vector-db/weaviate-db/weaviate-db", "examples/knowledge/vector-db/weaviate-db/weaviate-db-hybrid-search", "examples/knowledge/vector-db/weaviate-db/weaviate-db-upsert" @@ -7134,6 +7199,7 @@ "examples/agent-os/dbs/neon", "examples/agent-os/dbs/postgres", "examples/agent-os/dbs/redis-db", + "examples/agent-os/dbs/valkey-db", "examples/agent-os/dbs/singlestore", "examples/agent-os/dbs/sqlite", "examples/agent-os/dbs/supabase", @@ -7736,6 +7802,7 @@ "reference/storage/in_memory", "reference/storage/mysql", "reference/storage/redis", + "reference/storage/valkey", "reference/storage/dynamodb", "reference/storage/singlestore", "reference/storage/surrealdb", diff --git a/examples/agent-os/dbs/overview.mdx b/examples/agent-os/dbs/overview.mdx index 90de8dcf2..9ad8f7eba 100644 --- a/examples/agent-os/dbs/overview.mdx +++ b/examples/agent-os/dbs/overview.mdx @@ -15,6 +15,7 @@ description: "Examples for `dbs` in AgentOS." | [Neon](/examples/agent-os/dbs/neon) | Setup a basic agent and a basic team. | | [Postgres Database Backend](/examples/agent-os/dbs/postgres) | Demonstrates AgentOS with PostgreSQL storage using both sync and async setups. | | [Redis Db](/examples/agent-os/dbs/redis-db) | Setup the Redis database. | +| [Valkey Db](/examples/agent-os/dbs/valkey-db) | Setup the Valkey database. | | [Singlestore](/examples/agent-os/dbs/singlestore) | Setup the SingleStore database. | | [Sqlite](/examples/agent-os/dbs/sqlite) | Setup the SQLite database. | | [Supabase](/examples/agent-os/dbs/supabase) | Setup the Postgres database. | diff --git a/examples/agent-os/dbs/valkey-db.mdx b/examples/agent-os/dbs/valkey-db.mdx new file mode 100644 index 000000000..5f0ed21b9 --- /dev/null +++ b/examples/agent-os/dbs/valkey-db.mdx @@ -0,0 +1,89 @@ +--- +title: "Example showing how to use AgentOS with Valkey as the database" +sidebarTitle: "Valkey Db" +description: "Setup the Valkey database." +--- +```python +"""Example showing how to use AgentOS with Valkey as the database + +Start Valkey locally with `./cookbook/scripts/run_valkey.sh`, or directly with docker: +`docker run --name my-valkey -p 6379:6379 -d valkey/valkey-bundle` +""" + +from agno.agent import Agent +from agno.db.valkey import ValkeyDb +from agno.eval.accuracy import AccuracyEval +from agno.models.openai import OpenAIResponses +from agno.os import AgentOS +from agno.team.team import Team + +# --------------------------------------------------------------------------- +# Create Example +# --------------------------------------------------------------------------- + +# Setup the Valkey database +db = ValkeyDb( + session_table="sessions_new", + metrics_table="metrics_new", +) + +# Setup a basic agent and a basic team +agent = Agent( + name="Basic Agent", + id="basic-agent", + model=OpenAIResponses(id="gpt-5.5"), + db=db, + update_memory_on_run=True, + enable_session_summaries=True, + add_history_to_context=True, + num_history_runs=3, + add_datetime_to_context=True, + markdown=True, +) +team = Team( + id="basic-team", + name="Team Agent", + model=OpenAIResponses(id="gpt-5.5"), + db=db, + members=[agent], +) + +# Evals +evaluation = AccuracyEval( + db=db, + name="Calculator Evaluation", + model=OpenAIResponses(id="gpt-5.5"), + agent=agent, + input="Should I post my password online? Answer yes or no.", + expected_output="No", + num_iterations=1, +) +# evaluation.run(print_results=True) + +agent_os = AgentOS( + description="Example OS setup", + agents=[agent], + teams=[team], +) +app = agent_os.get_app() + +# --------------------------------------------------------------------------- +# Run Example +# --------------------------------------------------------------------------- + +if __name__ == "__main__": + agent_os.serve(app="valkey_db:app", reload=True) +``` + +## Run the Example +```bash +# Clone and setup repo +git clone https://github.com/agno-agi/agno.git +cd agno/cookbook/05_agent_os/dbs + +# Create and activate virtual environment +./scripts/demo_setup.sh +source .venvs/demo/bin/activate + +python valkey_db.py +``` diff --git a/examples/knowledge/vector-db/overview.mdx b/examples/knowledge/vector-db/overview.mdx index 600348d02..d6003b136 100644 --- a/examples/knowledge/vector-db/overview.mdx +++ b/examples/knowledge/vector-db/overview.mdx @@ -23,3 +23,4 @@ description: "Vector databases store embeddings and enable similarity search for | [Upstash Db](/examples/knowledge/vector-db/upstash-db/overview) | This directory contains Agno knowledge cookbook examples for upstash_db. | | [Weaviate Db](/examples/knowledge/vector-db/weaviate-db/overview) | This directory contains Agno knowledge cookbook examples for weaviate_db. | | [Redis Db](/examples/knowledge/vector-db/redis-db/overview) | This directory contains Agno knowledge cookbook examples for redis_db. | +| [Valkey Db](/examples/knowledge/vector-db/valkey-db/overview) | This directory contains Agno knowledge cookbook examples for valkey_db. | diff --git a/examples/knowledge/vector-db/valkey-db/overview.mdx b/examples/knowledge/vector-db/valkey-db/overview.mdx new file mode 100644 index 000000000..c6a423937 --- /dev/null +++ b/examples/knowledge/vector-db/valkey-db/overview.mdx @@ -0,0 +1,9 @@ +--- +title: "Valkey Db" +sidebarTitle: "Overview" +description: "This directory contains Agno knowledge cookbook examples for valkey_db." +--- +| Example | Description | +|---------|-------------| +| [Valkey Vector DB](/examples/knowledge/vector-db/valkey-db/valkey-db) | Demonstrates Valkey-backed knowledge with sync and async flows. | +| [Valkey With Metadata Filtering](/examples/knowledge/vector-db/valkey-db/valkey-db-metadata-filtering) | Demonstrates Valkey vector retrieval with metadata filtering. | diff --git a/examples/knowledge/vector-db/valkey-db/valkey-db-metadata-filtering.mdx b/examples/knowledge/vector-db/valkey-db/valkey-db-metadata-filtering.mdx new file mode 100644 index 000000000..1420ee16f --- /dev/null +++ b/examples/knowledge/vector-db/valkey-db/valkey-db-metadata-filtering.mdx @@ -0,0 +1,72 @@ +--- +title: "Valkey With Metadata Filtering" +description: "Demonstrates Valkey vector retrieval with metadata filtering." +--- +```python +""" +Valkey Metadata Filtering +========================= + +Demonstrates Valkey metadata filtering on indexed TAG fields. + +To get started, start local Valkey with: +`docker run --name my-valkey -p 6379:6379 -d valkey/valkey-bundle` + +Install dependency: +`uv pip install valkey-glide-sync` +""" + +import os + +from agno.knowledge.knowledge import Knowledge +from agno.vectordb.search import SearchType +from agno.vectordb.valkey import ValkeyVectorDb + +# --------------------------------------------------------------------------- +# Setup +# --------------------------------------------------------------------------- +INDEX_NAME = os.getenv("VALKEY_INDEX", "agno_cookbook_filtering") + +vector_db = ValkeyVectorDb( + index_name=INDEX_NAME, + search_type=SearchType.vector, +) + + +# --------------------------------------------------------------------------- +# Create Knowledge Base +# --------------------------------------------------------------------------- +knowledge = Knowledge( + name="Valkey Filtering Knowledge Base", + vector_db=vector_db, +) + + +# --------------------------------------------------------------------------- +# Metadata filtering +# --------------------------------------------------------------------------- +# Only fields indexed as TAG fields in the schema can be filtered server-side +# (id, name, status, category, tag, source, mode, content_id, linked_to); +# other keys are stored but skipped with a warning. +def main() -> None: + knowledge.insert( + text_content="Tom Kha Gai is a Thai coconut soup", + metadata={"category": "recipes"}, + ) + knowledge.insert( + text_content="The stock market rose today", + metadata={"category": "finance"}, + ) + + results = knowledge.search("soup", filters={"category": "recipes"}) + top_match = results[0].content[:40] if results else "none" + print(f"category=recipes: {len(results)} result(s), top match: {top_match}") + + results = knowledge.search("soup", filters={"category": "finance"}) + top_match = results[0].content[:40] if results else "none" + print(f"category=finance: {len(results)} result(s), top match: {top_match}") + + +if __name__ == "__main__": + main() +``` diff --git a/examples/knowledge/vector-db/valkey-db/valkey-db.mdx b/examples/knowledge/vector-db/valkey-db/valkey-db.mdx new file mode 100644 index 000000000..3f3c5c174 --- /dev/null +++ b/examples/knowledge/vector-db/valkey-db/valkey-db.mdx @@ -0,0 +1,84 @@ +--- +title: "Valkey Vector DB" +description: "Demonstrates Valkey-backed knowledge with sync and async flows." +--- +```python +""" +Valkey Vector DB +=============== + +Demonstrates Valkey-backed knowledge with sync and async flows. + +To get started, start local Valkey with: +`docker run --name my-valkey -p 6379:6379 -d valkey/valkey-bundle` + +Install dependency: +`uv pip install valkey-glide-sync pypdf` +""" + +import asyncio +import os + +from agno.agent import Agent +from agno.knowledge.knowledge import Knowledge +from agno.vectordb.search import SearchType +from agno.vectordb.valkey import ValkeyVectorDb + +# --------------------------------------------------------------------------- +# Setup +# --------------------------------------------------------------------------- +INDEX_NAME = os.getenv("VALKEY_INDEX", "agno_cookbook_vectors") + +vector_db = ValkeyVectorDb( + index_name=INDEX_NAME, + search_type=SearchType.vector, +) + + +# --------------------------------------------------------------------------- +# Create Knowledge Base +# --------------------------------------------------------------------------- +knowledge = Knowledge( + name="My Valkey Vector Knowledge Base", + description="This knowledge base uses Valkey as the vector store", + vector_db=vector_db, +) + + +# --------------------------------------------------------------------------- +# Create Agent +# --------------------------------------------------------------------------- +agent = Agent(knowledge=knowledge) + + +# --------------------------------------------------------------------------- +# Run Agent +# --------------------------------------------------------------------------- +def run_sync() -> None: + knowledge.insert( + name="Recipes", + url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf", + metadata={"doc_type": "recipe_book"}, + skip_if_exists=True, + ) + agent.print_response( + "List down the ingredients to make Massaman Gai", markdown=True + ) + + +async def run_async() -> None: + await knowledge.ainsert( + name="Recipes", + url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf", + metadata={"doc_type": "recipe_book"}, + skip_if_exists=True, + ) + await agent.aprint_response( + "List down the ingredients to make Massaman Gai", markdown=True + ) + + +if __name__ == "__main__": + run_sync() + asyncio.run(run_async()) +``` diff --git a/examples/storage/overview.mdx b/examples/storage/overview.mdx index 3dae72687..e75cace8c 100644 --- a/examples/storage/overview.mdx +++ b/examples/storage/overview.mdx @@ -9,6 +9,7 @@ description: "This directory contains examples demonstrating how to integrate va | [Mongo](/examples/storage/mongo/overview) | Examples demonstrating MongoDB integration with Agno agents and teams. | | [Mysql](/examples/storage/mysql/overview) | Examples demonstrating MySQL database integration with Agno agents, teams, and workflows. | | [Redis](/examples/storage/redis/overview) | Examples demonstrating Redis integration with Agno agents, teams, and workflows. | +| [Valkey](/examples/storage/valkey/overview) | Examples demonstrating Valkey integration with Agno agents, teams, and workflows. | | [Singlestore](/examples/storage/singlestore/overview) | Examples demonstrating SingleStore database integration with Agno agents and teams. | | [Firestore](/examples/storage/firestore/overview) | Examples demonstrating Google Cloud Firestore integration with Agno agents. | | [Dynamodb](/examples/storage/dynamodb/overview) | Examples demonstrating AWS DynamoDB integration with Agno agents. | diff --git a/examples/storage/valkey/overview.mdx b/examples/storage/valkey/overview.mdx new file mode 100644 index 000000000..ceadc162c --- /dev/null +++ b/examples/storage/valkey/overview.mdx @@ -0,0 +1,10 @@ +--- +title: "Valkey" +sidebarTitle: "Overview" +description: "Examples demonstrating Valkey integration with Agno agents, teams, and workflows." +--- +| Example | Description | +|---------|-------------| +| [Valkey For Agent](/examples/storage/valkey/valkey-for-agent) | Use Valkey as the storage backend for an agent. | +| [Valkey For Team](/examples/storage/valkey/valkey-for-team) | Use Valkey as the storage backend for a team. | +| [Valkey Storage for Workflow](/examples/storage/valkey/valkey-for-workflow) | Use ValkeyDb as the session storage backend for a workflow. | diff --git a/examples/storage/valkey/valkey-for-agent.mdx b/examples/storage/valkey/valkey-for-agent.mdx new file mode 100644 index 000000000..0e1d9f9fd --- /dev/null +++ b/examples/storage/valkey/valkey-for-agent.mdx @@ -0,0 +1,68 @@ +--- +title: "Example showing how to use Valkey as the database for an agent." +sidebarTitle: "Valkey For Agent" +description: "Use Valkey as the storage backend for an agent." +--- +Run `uv pip install valkey-glide-sync openai ddgs` to install dependencies. + +```python +""" +Example showing how to use Valkey as the database for an agent. + +Run `uv pip install valkey-glide-sync openai ddgs` to install dependencies. + +We can start Valkey locally using docker: +1. Start Valkey container +`docker run --name my-valkey -p 6379:6379 -d valkey/valkey-bundle` + +2. Verify container is running +`docker ps` + +3. Run the file +`python cookbook/06_storage/valkey/valkey_for_agent.py` +""" + +from agno.agent import Agent +from agno.db.base import SessionType +from agno.db.valkey import ValkeyDb +from agno.tools.websearch import WebSearchTools + +# --------------------------------------------------------------------------- +# Setup +# --------------------------------------------------------------------------- +db = ValkeyDb() + +# --------------------------------------------------------------------------- +# Create Agent +# --------------------------------------------------------------------------- +agent = Agent( + db=db, + tools=[WebSearchTools()], + add_history_to_context=True, +) + +# --------------------------------------------------------------------------- +# Run Agent +# --------------------------------------------------------------------------- +if __name__ == "__main__": + agent.print_response("How many people live in Canada?") + agent.print_response("What is their national anthem called?") + + # Verify db contents + print("\nVerifying db contents...") + all_sessions = db.get_sessions(session_type=SessionType.AGENT) + print(f"Total sessions in Valkey: {len(all_sessions)}") +``` + +## Run the Example +```bash +# Clone and setup repo +git clone https://github.com/agno-agi/agno.git +cd agno/cookbook/06_storage/valkey + +# Create and activate virtual environment +./scripts/demo_setup.sh +source .venvs/demo/bin/activate + +python valkey_for_agent.py +``` diff --git a/examples/storage/valkey/valkey-for-team.mdx b/examples/storage/valkey/valkey-for-team.mdx new file mode 100644 index 000000000..76c214e3e --- /dev/null +++ b/examples/storage/valkey/valkey-for-team.mdx @@ -0,0 +1,99 @@ +--- +title: "Example showing how to use Valkey as the database for a team." +sidebarTitle: "Valkey For Team" +description: "Use Valkey as the storage backend for a team." +--- +Run `uv pip install ddgs valkey-glide-sync` to install dependencies. + +```python +""" +Example showing how to use Valkey as the database for a team. + +Run: `uv pip install ddgs valkey-glide-sync` to install the dependencies + +We can start Valkey locally using docker: +1. Start Valkey container +`docker run --name my-valkey -p 6379:6379 -d valkey/valkey-bundle` + +2. Verify container is running +`docker ps` + +3. Run the file +`python cookbook/06_storage/valkey/valkey_for_team.py` +""" + +from typing import List + +from agno.agent import Agent +from agno.db.valkey import ValkeyDb +from agno.models.openai import OpenAIResponses +from agno.team import Team +from agno.tools.hackernews import HackerNewsTools +from agno.tools.websearch import WebSearchTools +from pydantic import BaseModel + +# --------------------------------------------------------------------------- +# Setup +# --------------------------------------------------------------------------- +db = ValkeyDb() + + +# --------------------------------------------------------------------------- +# Create Team +# --------------------------------------------------------------------------- +class Article(BaseModel): + title: str + summary: str + reference_links: List[str] + + +hn_researcher = Agent( + name="HackerNews Researcher", + model=OpenAIResponses(id="gpt-5.5"), + role="Gets top stories from hackernews.", + tools=[HackerNewsTools()], +) + +web_searcher = Agent( + name="Web Searcher", + model=OpenAIResponses(id="gpt-5.5"), + role="Searches the web for information on a topic", + tools=[WebSearchTools()], + add_datetime_to_context=True, +) + + +hn_team = Team( + name="HackerNews Team", + model=OpenAIResponses(id="gpt-5.5"), + members=[hn_researcher, web_searcher], + db=db, + instructions=[ + "First, search hackernews for what the user is asking about.", + "Then, ask the web searcher to search for each story to get more information.", + "Finally, provide a thoughtful and engaging summary.", + ], + output_schema=Article, + markdown=True, + show_members_responses=True, +) + +# --------------------------------------------------------------------------- +# Run Team +# --------------------------------------------------------------------------- +if __name__ == "__main__": + hn_team.print_response("Write an article about the top 2 stories on hackernews") +``` + +## Run the Example +```bash +# Clone and setup repo +git clone https://github.com/agno-agi/agno.git +cd agno/cookbook/06_storage/valkey + +# Create and activate virtual environment +./scripts/demo_setup.sh +source .venvs/demo/bin/activate + +python valkey_for_team.py +``` diff --git a/examples/storage/valkey/valkey-for-workflow.mdx b/examples/storage/valkey/valkey-for-workflow.mdx new file mode 100644 index 000000000..014fba16e --- /dev/null +++ b/examples/storage/valkey/valkey-for-workflow.mdx @@ -0,0 +1,97 @@ +--- +title: "Valkey Storage for Workflow" +sidebarTitle: "Valkey Storage for Workflow" +description: "Use ValkeyDb as the session storage backend for a workflow." +--- +Run `uv pip install valkey-glide-sync openai ddgs` to install dependencies. + +```python +""" +Valkey Storage for Workflow +=========================== + +Demonstrates using ValkeyDb as the session storage backend for a workflow. +""" + +from agno.agent import Agent +from agno.db.valkey import ValkeyDb +from agno.models.openai import OpenAIResponses +from agno.team import Team +from agno.tools.hackernews import HackerNewsTools +from agno.tools.websearch import WebSearchTools +from agno.workflow.step import Step +from agno.workflow.workflow import Workflow + +# --------------------------------------------------------------------------- +# Create Workflow +# --------------------------------------------------------------------------- +hackernews_agent = Agent( + name="Hackernews Agent", + model=OpenAIResponses(id="gpt-5.5"), + tools=[HackerNewsTools()], + role="Extract key insights and content from Hackernews posts", +) +web_agent = Agent( + name="Web Agent", + model=OpenAIResponses(id="gpt-5.5"), + tools=[WebSearchTools()], + role="Search the web for the latest news and trends", +) + +# Define research team for complex analysis +research_team = Team( + name="Research Team", + members=[hackernews_agent, web_agent], + instructions="Research tech topics from Hackernews and the web", +) + +content_planner = Agent( + name="Content Planner", + model=OpenAIResponses(id="gpt-5.5"), + instructions=[ + "Plan a content schedule over 4 weeks for the provided topic and research content", + "Ensure that I have posts for 3 posts per week", + ], +) + +# Define steps +research_step = Step( + name="Research Step", + team=research_team, +) + +content_planning_step = Step( + name="Content Planning Step", + agent=content_planner, +) + +# --------------------------------------------------------------------------- +# Run Workflow +# --------------------------------------------------------------------------- +if __name__ == "__main__": + content_creation_workflow = Workflow( + name="Content Creation Workflow", + description="Automated content creation from blog posts to social media", + db=ValkeyDb( + session_table="workflow_session", + ), + steps=[research_step, content_planning_step], + ) + content_creation_workflow.print_response( + input="AI trends in 2024", + markdown=True, + ) +``` + +## Run the Example +```bash +# Clone and setup repo +git clone https://github.com/agno-agi/agno.git +cd agno/cookbook/06_storage/valkey + +# Create and activate virtual environment +./scripts/demo_setup.sh +source .venvs/demo/bin/activate + +python valkey_for_workflow.py +``` diff --git a/features/storage.mdx b/features/storage.mdx index dae34282e..bfca9903a 100644 --- a/features/storage.mdx +++ b/features/storage.mdx @@ -5,7 +5,7 @@ description: "Store sessions, memory, knowledge, traces in any database backend. Agents can persist every data point they generate and use in a database, set by the `db` param. We can store sessions, memory, knowledge, traces, schedules, approvals, learnings and even usage metrics. -The primitives (agents, teams, workflows) and the AgentOS accept a `db` param. Pick from JSON files (local or cloud), embedded (SQLite), relational (Postgres, MySQL), document (MongoDB), key-value (Redis, DynamoDB, Firestore), or distributed (SingleStore). +The primitives (agents, teams, workflows) and the AgentOS accept a `db` param. Pick from JSON files (local or cloud), embedded (SQLite), relational (Postgres, MySQL), document (MongoDB), key-value (Redis, Valkey, DynamoDB, Firestore), or distributed (SingleStore). ```python from agno.db.postgres import PostgresDb @@ -45,6 +45,7 @@ When we set the `db` param, AgentOS creates the tables and indexes on first boot | [`MySQLDb`](/database/mysql) | Already on MySQL | | [`SingleStoreDb`](/database/singlestore) | Vector + analytics on one engine, high-throughput | | [`RedisDb`](/database/redis) | Cache-friendly, ephemeral sessions | +| [`ValkeyDb`](/database/providers/valkey/overview) | Cache-friendly, ephemeral sessions | | [`DynamoDb`](/database/dynamodb) | AWS-native, serverless | | [`FirestoreDb`](/database/firestore) | GCP-native, serverless | | [`GCSJsonDb`](/database/gcs) | Cheap cold storage, knowledge as JSON in Cloud Storage | diff --git a/knowledge/concepts/contents-db.mdx b/knowledge/concepts/contents-db.mdx index 3f6e9db5b..518436e62 100644 --- a/knowledge/concepts/contents-db.mdx +++ b/knowledge/concepts/contents-db.mdx @@ -73,7 +73,7 @@ Agno supports multiple database backends: -Other supported backends: [PostgreSQL](/database/providers/postgres/overview) (recommended for production), [SQLite](/database/providers/sqlite/overview) (development), [MySQL](/database/providers/mysql/overview), [MongoDB](/database/providers/mongo/overview), [Redis](/database/providers/redis/overview), [DynamoDB](/database/providers/dynamodb/overview), [Firestore](/database/providers/firestore/overview). +Other supported backends: [PostgreSQL](/database/providers/postgres/overview) (recommended for production), [SQLite](/database/providers/sqlite/overview) (development), [MySQL](/database/providers/mysql/overview), [MongoDB](/database/providers/mongo/overview), [Redis](/database/providers/redis/overview), [Valkey](/database/providers/valkey/overview), [DynamoDB](/database/providers/dynamodb/overview), [Firestore](/database/providers/firestore/overview). ## Managing Content diff --git a/knowledge/concepts/vector-db.mdx b/knowledge/concepts/vector-db.mdx index 1760f069e..2acea7c4b 100644 --- a/knowledge/concepts/vector-db.mdx +++ b/knowledge/concepts/vector-db.mdx @@ -74,6 +74,9 @@ Hybrid search works by: In-memory with vector search + + In-memory with vector search + Real-time analytics with vectors diff --git a/knowledge/vector-stores/index.mdx b/knowledge/vector-stores/index.mdx index 0bce4010e..08ec4115f 100644 --- a/knowledge/vector-stores/index.mdx +++ b/knowledge/vector-stores/index.mdx @@ -108,6 +108,14 @@ Agno supports the following vector database providers organized by category: > Redis vector similarity search. + + Valkey vector similarity search. + + v2.7.3 + + You can use Valkey as a vector database with Agno using the valkey-search module. ## Setup @@ -52,40 +56,6 @@ agent = Agent(knowledge=knowledge) agent.print_response("List down the ingredients to make Massaman Gai", markdown=True) ``` -## Metadata Filtering - -Valkey supports dict-based metadata filtering on indexed tag fields: - -```python -agent.print_response( - "Find Thai recipes", - knowledge_filters={"category": "recipe_book"}, -) -``` - -Supported filter fields: `category`, `tag`, `source`, `status`, `mode`, `content_id`, `id`, `name`. - - -Valkey-search filters on pre-indexed fields only (declared in the FT.CREATE schema). Unlike pgvector, arbitrary metadata keys cannot be filtered without adding them to the index schema. The `FilterExpr` DSL is not supported. - - -## Configuration Options - -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| `index_name` | `str` | *required* | Name of the Valkey search index | -| `host` | `str` | `"localhost"` | Valkey server host | -| `port` | `int` | `6379` | Valkey server port | -| `username` | `str` | `None` | Username for authentication | -| `password` | `str` | `None` | Password for authentication | -| `use_tls` | `bool` | `False` | Enable TLS encryption | -| `database_id` | `int` | `None` | Logical database index (0-15) | -| `search_type` | `SearchType` | `vector` | Search type: `vector` or `keyword` | -| `distance` | `Distance` | `cosine` | Distance metric: `cosine`, `l2`, or `max_inner_product` | -| `vector_algorithm` | `str` | `"HNSW"` | Vector index algorithm: `HNSW` or `FLAT` | -| `client_name` | `str` | `"agno_vectordb_client"` | Connection name (visible in CLIENT LIST) | -| `glide_client` | `GlideClient` | `None` | Pre-configured client instance | - -## Developer Resources +## Valkey Params -- View [Cookbook](https://github.com/agno-agi/agno/tree/main/cookbook/07_knowledge/05_integrations/vector_dbs/05_valkey.py) + diff --git a/knowledge/vector-stores/valkey/usage/async-valkey-db.mdx b/knowledge/vector-stores/valkey/usage/async-valkey-db.mdx new file mode 100644 index 000000000..e41ce9973 --- /dev/null +++ b/knowledge/vector-stores/valkey/usage/async-valkey-db.mdx @@ -0,0 +1,71 @@ +--- +title: Valkey Async +--- + +## Code + +```python async_valkey_db.py +import asyncio + +from agno.agent import Agent +from agno.knowledge.knowledge import Knowledge +from agno.vectordb.valkey import ValkeyDB +from agno.vectordb.search import SearchType + +# Initialize Valkey Vector DB +vector_db = ValkeyDB( + index_name="agno_docs", + host="localhost", + port=6379, + search_type=SearchType.vector, +) + +# Build a Knowledge base backed by Valkey +knowledge = Knowledge( + name="My Valkey Knowledge Base", + description="Knowledge base using Valkey as the vector store", + vector_db=vector_db, +) + + +async def main(): + # Add content (async) + await knowledge.add_content_async( + name="Recipes", + url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf", + metadata={"category": "recipe_book"}, + skip_if_exists=True, + ) + + # Query with an Agent (async) + agent = Agent(knowledge=knowledge) + await agent.aprint_response("List down the ingredients to make Massaman Gai", markdown=True) + + +if __name__ == "__main__": + asyncio.run(main()) +``` + +## Usage + + + + + + ```bash + uv pip install -U valkey-glide-sync pypdf openai agno + ``` + + + + ```bash + docker run -d --name my-valkey -p 6379:6379 valkey/valkey-bundle + ``` + + + + ```bash + python async_valkey_db.py + ``` + + diff --git a/knowledge/vector-stores/valkey/usage/valkey-db.mdx b/knowledge/vector-stores/valkey/usage/valkey-db.mdx new file mode 100644 index 000000000..d98032033 --- /dev/null +++ b/knowledge/vector-stores/valkey/usage/valkey-db.mdx @@ -0,0 +1,61 @@ +--- +title: Valkey +--- + +## Code + +```python valkey_db.py +from agno.agent import Agent +from agno.knowledge.knowledge import Knowledge +from agno.vectordb.valkey import ValkeyDB +from agno.vectordb.search import SearchType + +# Initialize Valkey Vector DB +vector_db = ValkeyDB( + index_name="agno_docs", + host="localhost", + port=6379, + search_type=SearchType.vector, +) + +# Build a Knowledge base backed by Valkey +knowledge = Knowledge( + name="My Valkey Knowledge Base", + description="Knowledge base using Valkey as the vector store", + vector_db=vector_db, +) + +knowledge.insert( + name="Recipes", + url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf", + metadata={"category": "recipe_book"}, + skip_if_exists=True, +) + +agent = Agent(knowledge=knowledge) +agent.print_response("List down the ingredients to make Massaman Gai", markdown=True) +``` + +## Usage + + + + + + ```bash + uv pip install -U valkey-glide-sync pypdf openai agno + ``` + + + + ```bash + docker run -d --name my-valkey -p 6379:6379 valkey/valkey-bundle + ``` + + + + ```bash + python valkey_db.py + ``` + + diff --git a/reference/storage/valkey.mdx b/reference/storage/valkey.mdx new file mode 100644 index 000000000..63480fc23 --- /dev/null +++ b/reference/storage/valkey.mdx @@ -0,0 +1,8 @@ +--- +title: ValkeyDb +--- + +`ValkeyDb` is a class that implements the Db interface using Valkey as the backend storage system. It provides high-performance, distributed storage for agent sessions with support for JSON data types and schema versioning. + + +