From 6336cc0062b6731ff3c446afc72f345c4d783d2d Mon Sep 17 00:00:00 2001 From: Vineet Vora Date: Tue, 30 Jun 2026 11:47:12 -0400 Subject: [PATCH] docs: document Redis as a required dependency MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Redis is required at runtime for any agent that streams or sends messages, but the docs presented it as optional. Locally this is masked by the Docker stack (which starts Redis automatically), and in deployment REDIS_URL was treated like an optional custom secret — so an agent could deploy successfully and then fail the first time it streams. Document it as required everywhere a developer encounters it: - README prerequisites + CLAUDE.md: Redis is required for local dev; the Docker stack starts it automatically; a local Redis conflicts on 6379 - concepts/streaming: streaming and messaging are backed by Redis - configuration (credentials mapping): REDIS_URL is a required credential - deployment/overview: REDIS_URL is a required deployment secret - deployment/cicd: REDIS_URL is a required baseline secret, and fix the misleading redis://localhost/ example value Docs only; no code or template changes. Co-Authored-By: Claude Opus 4.8 (1M context) --- CLAUDE.md | 2 +- README.md | 2 ++ agentex/docs/docs/concepts/streaming.md | 3 +++ agentex/docs/docs/configuration.md | 3 +++ agentex/docs/docs/deployment/cicd.md | 5 ++++- agentex/docs/docs/deployment/overview.md | 1 + 6 files changed, 14 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4986367e..99a62276 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -93,7 +93,7 @@ When running `make dev` in agentex/, the following services start: - **Port 5003**: FastAPI backend server - **Port 5432**: PostgreSQL (application database) - **Port 5433**: PostgreSQL (Temporal database) -- **Port 6379**: Redis (streams and caching) +- **Port 6379**: Redis (streams and caching) — required for streaming/messaging; the Docker stack starts it automatically, and a local Redis will conflict on this port (see [Redis Port Conflicts](#redis-port-conflicts)) - **Port 27017**: MongoDB (document storage) - **Port 7233**: Temporal server - **Port 8080**: Temporal Web UI diff --git a/README.md b/README.md index bc22fe3d..d104ff35 100644 --- a/README.md +++ b/README.md @@ -53,6 +53,8 @@ https://github.com/user-attachments/assets/9badad0d-f939-4243-ba39-68cafdae0078 - **Install Python 3.12+ (Required)**: https://www.python.org/downloads/ +> **Redis is required.** Agentex uses Redis for streaming and messaging. You do **not** need to install it yourself — the Docker stack (`./dev.sh` / `make dev`) starts it for you. If you already run Redis locally it will conflict on port `6379`, so stop it first (see [Troubleshooting](#redis-port-conflict)). + #### macOS/Linux ```bash diff --git a/agentex/docs/docs/concepts/streaming.md b/agentex/docs/docs/concepts/streaming.md index 80e0dba1..f088f896 100644 --- a/agentex/docs/docs/concepts/streaming.md +++ b/agentex/docs/docs/concepts/streaming.md @@ -8,6 +8,9 @@ Streaming enables real-time delivery of messages as they're being generated, pro Agentex decouples streaming from LLM provider streaming. You're not limited to streaming LLM responses - you can stream any content: progress updates, status messages, multi-step workflows, or custom notifications. +!!! note "Streaming requires Redis" + Streaming and messaging are delivered through Redis streams, so a reachable Redis is **required** for any agent that streams or sends messages. Locally, the Docker stack starts Redis for you. In deployment, the `REDIS_URL` environment variable must point at your Redis instance — see [Deploying Your Agent](../deployment/overview.md#prerequisites). + ## Streaming by Agent Type diff --git a/agentex/docs/docs/configuration.md b/agentex/docs/docs/configuration.md index 449ca79b..d9094bb5 100644 --- a/agentex/docs/docs/configuration.md +++ b/agentex/docs/docs/configuration.md @@ -125,6 +125,9 @@ agent: secret_key: "connection-string" ``` +!!! note "`REDIS_URL` is a required credential for streaming/messaging" + The examples above are your *own* secrets, but `REDIS_URL` is required by the platform for any agent that streams or sends messages — it is not optional. Map it here so it is synced to your deployment. See [Deploying Your Agent](deployment/overview.md#prerequisites). + ### Key Points: - **`name`**: Must be unique across your organization (used for task routing) diff --git a/agentex/docs/docs/deployment/cicd.md b/agentex/docs/docs/deployment/cicd.md index 993a2e32..0c7b186c 100644 --- a/agentex/docs/docs/deployment/cicd.md +++ b/agentex/docs/docs/deployment/cicd.md @@ -187,6 +187,9 @@ This will build and push your agent image to `your-registry-here/your-repository Agents require credentials (API keys, database URLs, etc.) that live in your secrets manager (AWS Secrets Manager, Azure Key Vault, etc.), not in code. The `agentex secrets sync` command bridges your secrets manager to Kubernetes by injecting credentials directly into the target namespace. +!!! note "`REDIS_URL` is a required baseline secret" + `agentex secrets sync` is not only for your own custom credentials. Any agent that streams or sends messages also needs `REDIS_URL` synced as a secret (shown as `REDIS_URL_SECRET` below) — it is **required**, not optional. Without it, the agent starts up fine but fails the first time it streams. See [Deploying Your Agent](overview.md#prerequisites). + **Authentication requirements**: Your CI/CD runner (e.g., GitHub Actions runner) needs access to both your secrets manager (to read secrets) and your Kubernetes cluster (to create Secret objects). **How it works**: The workflow fetches secrets from your secrets manager and constructs a YAML file containing the credentials and image pull secrets. This YAML is then passed to the sync command, which creates Kubernetes Secret objects in your namespace. @@ -199,7 +202,7 @@ credentials: api-key-jdoe: abc12345 api-key-jsmith: def6789 REDIS_URL_SECRET: - redis-url-secret: redis://localhost/ + redis-url-secret: # e.g. rediss://:6380 (TLS) or redis://:6379 imagePullSecrets: pull-secret-1: registry: registry-url diff --git a/agentex/docs/docs/deployment/overview.md b/agentex/docs/docs/deployment/overview.md index 359efa85..db5c239d 100644 --- a/agentex/docs/docs/deployment/overview.md +++ b/agentex/docs/docs/deployment/overview.md @@ -10,6 +10,7 @@ Before deploying, you need: - **Cluster access** - Contact your cluster administrators for access - **Namespace** - Get a namespace provisioned for your agent - **Permissions** - RBAC access to create deployments and secrets +- **Redis** - A reachable Redis instance. Agents require it for streaming and messaging, so its connection string must be provided as the `REDIS_URL` secret (synced in step 2 below). Unlike local development — where the Docker stack provides Redis automatically — a deployed agent has no Redis unless you configure one. Verify your setup: ```bash