add-redis-iris

添加 Redis Iris

检查、安装、接入。不重写 Agent。

1. 找到 Agent

定位：

• 调用轮次：模型的调用位置（invoke、Runner.run、generate_content、agent.run、kickoff、chat.completions.create、messages.create）。
• 工具注册：工具的定义位置，以及将工具传递给模型的位置。
• 用户和会话 ID：请求中的用户 ID 和线程或会话 ID 所在的位置。
• 多个循环（手写循环和框架，或两个框架）？在不导入框架的模块中只创建一次产品对象，在每个循环各自的接入点进行配置，并逐个转换循环。不要替用户选择循环。

2. 检测框架

搜索导入：

导入	框架
langgraph、langchain、langchain_core	LangGraph / LangChain
agents（openai-agents 包）	OpenAI Agents SDK
google.adk	Google ADK
pydantic_ai	Pydantic AI
crewai	CrewAI
仅有 openai、anthropic 或其他模型客户端	普通循环

从锁文件中确认版本。产品技能会通过 MCP 查询该版本对应的 API。

3. 找出缺少什么

代码中的症状	产品	技能
没有长期记忆，只有 InMemoryStore、检查点，记忆存放在字典或本地数据库中	Agent Memory	add-agent-memory
已通过自己的 REST 或 MCP 客户端使用 Redis Agent Memory、自写适配器，或面向模型的记忆工具	Agent Memory	add-agent-memory、"Already on Redis Agent Memory"
将策略或流程硬编码在提示词中、在提示词中提供工具使用指导，或在策略文档上构建向量存储	Agent Playbooks	add-agent-playbooks
语义响应缓存：模型回答会被存储并提供给后续用户，且由人工整理	Agent Playbooks	add-agent-playbooks、"Replacing a response cache"
在 Agent 中逐个配置多个 MCP 服务，每个服务各有自己的密钥，或提示词中包含过多工具架构	Context Gateway	add-context-gateway
基于关键字的 if/else 路由，或仅为选择路由而调用大模型	Intent Router	add-intent-router
没有逐轮追踪：无法查看某个回答使用了哪些大模型调用、工具和检索，也无法了解成本	Lens	add-lens

如果用户指定了产品，就使用该产品。如果不明确，只询问一次，并列出你发现的情况。

Lens 可与任何产品搭配使用，也可以单独使用：它会追踪整个调用轮次，每个 Iris 产品也会在其中追踪自身。添加其他产品时，同时推荐 Lens。

4. 安装

• 存在 uv.lock 或 [tool.uv]：uv add redis-iris。
• 使用 Poetry：poetry add redis-iris。
• 否则，将 redis-iris 添加到项目的 requirements 文件中。

如果预发行版导致解析失败，请重试：uv add --prerelease=allow redis-iris。确认安装成功：uv run python -c "import redis_iris; print(redis_iris.__version__)"。

5. 路由

遵循每个选定产品的技能。使用多个产品时，每个技能都会添加自己的调用。也可以通过 Iris.from_env() 从一个配置中构建（iris.agent_memory()、iris.agent_playbooks()、iris.context_gateway()、iris.intent_router()）。

只询问一次服务运行在 Redis Cloud 还是自托管套件上，然后编写项目的 iris.toml 配置文件。只有 iris CLI 会读取 iris.toml；应用读取环境变量。该文件只包含 URL：如果 TOML 中有令牌，CLI 将以状态码 2 退出。使用 IRIS_CONFIG=./iris.toml 和 IRIS_PROFILE=cloud 或 IRIS_PROFILE=suite 选择配置。

Redis Cloud。用户从控制台填写 .env：每个产品对应 IRIS_<PRODUCT>_URL、其 ID 和 _API_KEY。

[profiles.cloud]
kind = "cloud"
console_url = "https://cloud.redis.io"

[profiles.cloud.agent_memory]
url = "https://gcp-us-east4.memory.redis.io"  # the data-plane URL from the console

自托管套件。运维人员的令牌放在 .env.admin 中，绝不能放在应用的 .env 中；service create --write-env .env 会写入应用的 .env。

[profiles.suite]
kind = "self-managed"

[profiles.suite.agent_memory]
service_url = "https://memory-admin.example.com"  # control plane: the CLI calls it for service create and check
url = "https://memory.example.com"  # data plane: what the agent calls
identity_url = "https://memory-identity.example.com"  # Identity Service that mints the agent's keys

为应用使用的每个产品添加一个表：agent_memory、agent_playbooks、context_gateway、intent_router。[profiles.suite.context_gateway] 不含 url：service create --write-env 会写入 Gateway 的端点。若套件使用一个共享的 Identity Service，则只需设置一次 [profiles.suite.identity] 的 url，而不是分别设置每个 identity_url。IRIS_<PRODUCT>_SERVICE_URL、IRIS_<PRODUCT>_URL 和 IRIS_<PRODUCT>_IDENTITY_URL 会覆盖配置文件中的值。

规则

• 保留用户的框架、图和提示词。尽可能缩小差异。
• 绝不要凭记忆猜测框架 API。通过 MCP 查找（参见各产品技能）。
• 只使用 redis_iris 中的 API。redis_iris.integrations.langgraph.attach（额外安装 redis-iris[langgraph]）和 redis_iris.integrations.adk.attach（无需额外安装）均可用；不存在 IrisTool、iris.tools() 或 iris.turn()。
• 缺少设置或服务中断时，SDK 会引发异常。询问产品故障是否可以导致本轮失败；大多数生产环境中的 Agent 会捕获异常并继续，使用空内容块。
• 绝不要提交密钥。