SuperAPI AI 工具集

add-context-gateway

智能体与模型

查看项目

更新于 11-04 01:30

技能介绍

用途

该技能把智能体当前配置的多个 MCP 服务器统一放到一个 Redis Iris Context Gateway 之后,让智能体改为连接单个 MCP 端点并使用单个 agent key。智能体原有的工具保留不变,改变的只是工具访问路径。整体流程为:先询问、再配置、最后重新指向。

主要能力

  • 托管每个上游服务器的密钥。
  • 为工具名添加命名空间,避免不同上游之间的名称冲突。
  • 当工具目录较大时,以 search_tools 和 run_tool 替代暴露全部 schema。
  • 对经确认的只读工具进行缓存。
  • 对过大的结果以句柄形式返回。
  • 支持以 JSON 输出、无交互方式运行 CLI。

使用方式

  1. 发现阶段:阅读项目,找出智能体配置的所有 MCP 服务器(如 .mcp.json、.cursor/mcp.json、McpToolset、MCPServerStreamableHttp、MultiServerMCPClient、stdio_client 或手写 MCP 客户端),记录各端点及其密钥来源;找出工具交给模型的位置和回合执行位置;通过导入判断框架及其是否自带 MCP 客户端;注记仅支持 stdio 的服务器,因为上游必须是 HTTP MCP 端点(streamable-http),stdio 服务器需先以 HTTP 提供或留在 Gateway 之外。

  2. 确认 Gateway 运行位置:Redis Cloud(在控制台创建 Gateway 和上游,CLI 只连接 Gateway 的 MCP 端点;云环境关闭缓存与压缩)或自管理(本地 Compose 栈或本地部署,由 CLI 完成全部配置)。

  3. 向开发者询问五个问题(不确定时采用默认值):

    • 智能体使用哪些 MCP 服务器、密钥存放在哪里:每个 HTTP 端点建立一个上游,使用 upstream add --name NAME --endpoint URL 并配合 --bearer-secret env:VAR 或 --header NAME --header-secret env:VAR;若为智能体应查询的 Redis 数据库,则使用 Context Surface 上游并先编写数据模型。
    • 智能体总共看到多少工具:数十个用 --tool-exposure-mode full;数百个或 schema 占用提示词过多时用 --tool-exposure-mode search。
    • 哪些只读工具对相同参数返回相同结果:对相关工具设置 --cache-ttl 策略,需要 Gateway 启用缓存和数据库。
    • 哪些工具返回结果过大:启用压缩和不淘汰(noeviction)数据库,配置句柄默认值或 --compression-ttl,对必须始终返回完整结果的工具使用 --compression-capture never。
    • 框架是否自行连接 MCP 服务器:是(如 Claude Code、Cursor、ADK、OpenAI Agents SDK、LangChain MCP 适配器)则将其 MCP 客户端指向 Gateway URL 和 key;否则使用 SDK 的 gateway.model_tools() 或 gateway.hooks()。
  4. 在写代码前从 MCP 获取当前事实:查询框架文档 MCP 了解所安装版本的 MCP 客户端如何接收 streamable HTTP URL 和 Authorization 头;如已连接 Redis 文档 MCP,可查询 Context Gateway 概念(上游、暴露模式、缓存、句柄)。无 MCP 可用时阅读虚拟环境中已安装包的源码,并在报告中说明。

  5. 安装 CLI:pip install redis-iris,需要 Python 3.11 或更高版本;在 LangGraph 上安装 redis-iris[langgraph]。

  6. 配置:

    • Redis Cloud:目前无 Gateway 配置 API,控制平面仅接受控制台会话,云配置会以 cloud_unsupported 拒绝 service、upstream 和 policy 命令。开发者需在控制台创建 Gateway、添加上游或创建 Context Surface,然后在连接步骤复制 MCP 端点并创建 agent key,放入智能体环境或 .env 的 IRIS_CONTEXT_GATEWAY_URL 和 IRIS_CONTEXT_GATEWAY_API_KEY。密钥由开发者设置,绝不在对话中索取,也不要 echo、cat 或 grep 环境文件。将两个变量名以空值加入 .env.example,且不要提交 .env。云环境不启用缓存和压缩。
    • 自管理:由人员导出 IRIS_CONTEXT_GATEWAY_SERVICE_URL、IRIS_CONTEXT_GATEWAY_SERVICE_TOKEN、IRIS_IDENTITY_URL 和 IRIS_IDENTITY_TOKEN。本地 Compose 栈可在命令后加 --local 提供 service URL 和 token,但 Identity URL 仍需 IRIS_IDENTITY_URL。Identity token 的取值顺序为 --identity-token、IRIS_CONTEXT_GATEWAY_IDENTITY_TOKEN、IRIS_IDENTITY_TOKEN,最后是产品服务 token(仅当两者为同一密钥时有效)。可使用 iris --json --no-input context-gateway service list、service create --name support --tool-exposure-mode full --write-env .env、service check <gatewayId>。Gateway CLI 只从环境读取 IRIS_CONTEXT_GATEWAY_API_KEY,不读 .env。
  7. Gateway 开关与数据库:每个 Gateway 有缓存和压缩两个开关(ENABLED 或 DISABLED),可用 service show 查看。缓存禁用时 --cache-ttl 策略会返回 400;压缩关闭时压缩策略会被存储但不生效。两者还依赖运维方的部署开关。带数据库创建时两个开关均为 ENABLED;不带数据库时均为 DISABLED;数据库不支持压缩且未指定压缩时,缓存启用、压缩存储为禁用。缓存只对可缓存工具(未标记 readOnlyHint: false 或 destructiveHint: true)且设置了策略时生效。压缩需要 Gateway 数据库使用 noeviction 策略并安装 JSON 模块。缓存和句柄共用数据库,各自有 maxmemory 份额(默认 0.5 和 0.4,合计最多 0.95)。可用 service diagnose --metrics-url 查看计数。自管理时数据库来自部署配置,不从 CLI 指定。

  8. 以智能体方式运行 CLI:始终在产品名之前加 --json --no-input。先读后写,先运行 service list。始终用 --write-env PATH 传递密钥。遇到 configuration_error、unauthenticated 或 forbidden 时停止并告知人员需设置哪个变量。上游密钥仅以引用方式传入:env:NAME、file:PATH 或 -。遇到 resource_exists 时询问是否用 --reuse details.gatewayId 或换名,绝不删除重试。每个错误为 stderr 上的单个 JSON 值,带 error.code,按错误码分派处理。--write-env .env 会写入 IRIS_CONTEXT_GATEWAY_URL、IRIS_CONTEXT_GATEWAY_ID 和 IRIS_CONTEXT_GATEWAY_API_KEY,同样三个名称以空值加入 .env.example。

  9. 添加上游:iris --json --no-input context-gateway --gateway-id <gw_...> upstream add --name CRM --endpoint https://crm.example.com/mcp --bearer-secret env:CRM_TOKEN,或使用 --header X-Api-Key --header-secret env:TICKETS_KEY,随后可用 upstream tools crm 查看。upstream add 即使打印 initialCatalogFailure 也已完成创建:422 表示凭据被拒(用 upstream update 修复后再 upstream refresh),424 表示发现失败(检查控制平面能否访问端点),408 表示超时。Context Surface 上游的 422 表示 Surface 数据库拒绝了控制平面登录,424 表示工具生成失败(如 Redis NOPERM),均需在部署配置中修复后再 upstream refresh。

  10. 编写数据模型:Context Surface 上游需要数据模型 JSON,说明智能体可读取哪些记录以及如何索引;Gateway 据此生成工具,因此需在 upstream add --kind context-surface 之前编写。模型层级包括 Model(title、description、entities[])、Entity(name、description、redis_key_template、relationships[]、fields[]、可选 document_type)、Field(name、type、description、is_key_component、redis_indices[]、标签可选 allowed_values)、Relationship(name、target、description、source_field)。规则:键模板中每个 {placeholder} 必须是 is_key_component: true 的字段,键字段不带索引;第一个占位符之前的文本必须……(资料在此处截断)。

适用场景

已有智能体通过多个 MCP 服务器接入工具,希望统一端点、集中管理密钥、避免工具名冲突、精简提示词中的工具 schema、缓存只读查询,或处理超大返回结果时。

限制

  • 需要 Python 3.11 及以上的 redis-iris。
  • Redis Cloud 暂无 Gateway 配置 API,需在控制台手工完成。
  • 上游必须是 HTTP MCP 端点(streamable-http),stdio 服务器需先转为 HTTP 或留在 Gateway 之外。
  • 缓存和压缩需要对应的 Gateway 开关和运维部署开关,压缩还要求 noeviction 数据库与 JSON 模块。
  • 云环境不启用缓存和压缩。
  • 数据模型规则部分资料不完整,相关细节暂未提供。