v0.2.8 Release Tutorial

This walkthrough shows how to try the user-facing features that shipped in v0.2.8:

• pinned source documents, skills, and support tickets
• first-turn retrieval in the knowledge agent
• citation tracing with thread get, thread trace, and thread sources
• the RedisCluster / RedisInstance split
• Redis Enterprise cluster creation from environment defaults
• cluster-scoped diagnostics in the CLI, API, and MCP server

The commands and sample files below were exercised on March 12, 2026. This guide is written as a normal user workflow, so it focuses on how to use the features rather than how they were verified.

Before You Start

Set up the project and create the Redis indexes once:

uv sync --dev
uv run redis-sre-agent index recreate --yes --json

If you want to try the API examples, start the API and worker first:

uv run redis-sre-agent worker start
uv run uvicorn redis_sre_agent.api.app:app --reload --port 8080

If you want to try the MCP example, start the MCP server in another shell:

uv run redis-sre-agent mcp serve

1) Add Three Source Documents With Front Matter

Create three temporary source documents under /tmp: one pinned runbook, one skill, and one support-ticket-style document.

mkdir -p /tmp/redis-sre-agent-v028-tutorial-source

cat > /tmp/redis-sre-agent-v028-tutorial-source/01-pinned-knowledge.md <<'EOF'
---
title: Sev-1 Escalation Policy
doc_type: runbook
category: shared
name: sev1-escalation-policy
priority: high
pinned: true
---

For sev-1 Redis incidents, post escalation code RDX-911 in the incident channel.
EOF

cat > /tmp/redis-sre-agent-v028-tutorial-source/02-skill.md <<'EOF'
---
title: Failover Investigation Skill
doc_type: skill
category: shared
name: failover-investigation
summary: Triage failover resets with host identifiers first.
priority: normal
pinned: false
---

1. Ask for host or cluster identifiers first.
2. Correlate reset timing with failover events.
3. Inspect connection churn and retry behavior.
EOF

cat > /tmp/redis-sre-agent-v028-tutorial-source/03-support-email.md <<'EOF'
---
title: Support Email RET-4421
doc_type: support_ticket
category: shared
name: ret-4421
summary: ECONNRESET during failover for cache-prod-1.
priority: normal
pinned: false
---

From: support@redis.example.com
Subject: RET-4421 failover resets on cache-prod-1.redis.company.net

Host: cache-prod-1.redis.company.net
Symptom: ECONNRESET during failover
Resolution: increase failover timeout and connection retry jitter.
EOF

Now prepare and ingest them:

uv run redis-sre-agent pipeline prepare-sources \
  --source-dir /tmp/redis-sre-agent-v028-tutorial-source \
  --batch-date 2099-01-04 \
  --artifacts-path /tmp/redis-sre-agent-v028-tutorial-artifacts

What this demonstrates:

• pinned: true puts the escalation policy into startup context
• doc_type: skill makes the document available through the skills flow
• doc_type: support_ticket sends the document into the support-ticket corpus
• name, summary, priority, and pinned are all carried through ingestion

If you want to inspect the prepared batch:

uv run redis-sre-agent pipeline show-batch 2099-01-04 \
  --artifacts-path /tmp/redis-sre-agent-v028-tutorial-artifacts

2) Ask The Agents Questions About Those Documents

The simplest way to feel the v0.2.8 source-document changes is to ask three short questions.

Pinned knowledge:

uv run redis-sre-agent query --agent knowledge \
  "For a sev-1 Redis incident, what escalation code should I post?"

You should get RDX-911. Because the runbook is pinned, the knowledge is available immediately at startup.

Skill discovery:

uv run redis-sre-agent query --agent knowledge \
  "Do we have a failover investigation skill, and what is it for?"

You should see the failover-investigation skill and its summary. This is the user-facing behavior behind the new skill document type.

Support-ticket retrieval:

uv run redis-sre-agent query --agent knowledge \
  "Find support history for ECONNRESET during failover on cache-prod-1.redis.company.net."

You should get a response grounded in the support-ticket document. In v0.2.8, the knowledge agent is also forced to retrieve on the first turn, so this kind of answer should come from the indexed content rather than a prompt-only guess.

3) Inspect Provenance With Thread Commands

After one of the queries above, use the thread tools to inspect where the answer came from.

First, list the messages in the thread:

uv run redis-sre-agent thread get <thread_id>

Then inspect the decision trace for the assistant message you care about:

uv run redis-sre-agent thread trace <assistant_message_id>

Use thread trace when you want to see which tools ran and what the answer was built from.

You can also inspect retrieved knowledge fragments for the whole thread:

uv run redis-sre-agent thread sources <thread_id>

Use thread sources when you want the fragment-level retrieval view. Together, these commands are the citation/provenance workflow documented in this release.

4) Create A Redis Enterprise Cluster And Link An Instance

v0.2.8 split Redis Enterprise cluster metadata from Redis database instances. The new flow is cluster first, then instance.

Create the cluster object:

uv run redis-sre-agent cluster create \
  --name "re-prod-cluster" \
  --cluster-type redis_enterprise \
  --environment production \
  --description "Redis Enterprise control plane for production" \
  --admin-url "https://re-cluster.example.com:9443" \
  --admin-username "admin@redis.com" \
  --admin-password "<admin-password>"

Then create a database instance linked to that cluster:

uv run redis-sre-agent instance create \
  --name "re-prod-db" \
  --connection-url "rediss://default:<db-password>@re-cluster.example.com:12000" \
  --environment production \
  --usage cache \
  --description "Redis Enterprise production database" \
  --instance-type redis_enterprise \
  --cluster-id "<cluster_id>"

That is the new model:

• RedisCluster stores cluster-level admin/API context
• RedisInstance stores the database connection details
• --cluster-id links the two

For broader connection examples, see connect-to-redis.md.

5) Use Environment Defaults For Redis Enterprise Admin Credentials

If you do not want to repeat admin credentials in every cluster create command, set these environment variables:

export REDIS_ENTERPRISE_ADMIN_URL="https://re-cluster.example.com:9443"
export REDIS_ENTERPRISE_ADMIN_USERNAME="admin@redis.com"
export REDIS_ENTERPRISE_ADMIN_PASSWORD="<admin-password>"

Now you can create another Redis Enterprise cluster object without passing those flags:

uv run redis-sre-agent cluster create \
  --name "re-cluster-from-env" \
  --cluster-type redis_enterprise \
  --environment production \
  --description "Uses REDIS_ENTERPRISE_ADMIN_* defaults"

This is useful when you manage multiple databases on the same Redis Enterprise control plane.

6) Run Cluster-Scoped Diagnostics

Once you have a cluster, you can target it directly instead of targeting a single instance.

CLI example:

uv run redis-sre-agent query -c <cluster_id> \
  "Check cluster health and summarize anything that needs attention."

Use -c / --redis-cluster-id when you want cluster-level context. Do not pass both --redis-cluster-id and --redis-instance-id in the same request.

API example:

curl -fsS -X POST http://localhost:8080/api/v1/tasks \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Check cluster health and summarize anything that needs attention.",
    "context": {
      "cluster_id": "<cluster_id>"
    }
  }'

MCP example:

redis_sre_deep_triage(
    query="Check cluster health and summarize anything that needs attention.",
    cluster_id="<cluster_id>",
)

This is the main non-source-document feature set in v0.2.8: the cluster object is first-class, and the CLI, API, and MCP server all accept cluster-scoped diagnostics.

Related Docs

• Source document features
• How to connect to Redis
• CLI usage