diff --git a/content/develop/ai/context-engine/context-gateway/api-reference.md b/content/develop/ai/context-engine/context-gateway/api-reference.md index b893c7c55b..b278d17a76 100644 --- a/content/develop/ai/context-engine/context-gateway/api-reference.md +++ b/content/develop/ai/context-engine/context-gateway/api-reference.md @@ -67,7 +67,7 @@ The result is the tool's result. ### Result handle tools -Listed in both modes when the deployment turns on result handles. +Listed in both modes when result handles are on for the Gateway. | Tool | Arguments | Result | | --- | --- | --- | diff --git a/content/develop/ai/context-engine/context-gateway/concepts.md b/content/develop/ai/context-engine/context-gateway/concepts.md index 528ee32816..9bb3a3b31c 100644 --- a/content/develop/ai/context-engine/context-gateway/concepts.md +++ b/content/develop/ai/context-engine/context-gateway/concepts.md @@ -83,7 +83,9 @@ In `search` mode the agent calls `search_tools` and receives complete tool defin ## Tool policies -A **tool policy** sets optional behavior for one tool of one Upstream. Both behaviors need a Gateway database, selected with the Gateway's `databaseId`, and both are off until the deployment turns them on. +A **tool policy** sets optional behavior for one tool of one Upstream. Both behaviors need a Gateway database, selected with the Gateway's `databaseId`. + +Each Gateway also turns the result cache and result handles on or off for all of its tools with its `resultCache` and `resultHandles` settings, `enabled` or `disabled`. A Gateway created with a `databaseId` starts with both enabled, and a Gateway without one has both disabled. A feature serves a Gateway only when the Gateway's setting is `enabled` and the deployment turns the feature on. ### Result cache @@ -98,7 +100,7 @@ All callers with access to a Gateway share its cache entries. ### Result handles -A result handle holds a large tool result in the Gateway database. When the deployment turns on result handles, every eligible result over 32 kibibytes (KiB) becomes a handle, on every Gateway with a `databaseId`. The agent receives a small stub with the handle and reads the result in pages, queries, counts, or aggregates. +A result handle holds a large tool result in the Gateway database. When result handles are on for a Gateway, every eligible result over 32 kibibytes (KiB) becomes a handle. The agent receives a small stub with the handle and reads the result in pages, queries, counts, or aggregates. A tool opts out with a `resultHandle` policy of `capture: never`, or sets its own handle lifetime with `ttlSeconds`. An agent can also hold a result of any size with `run_tool_as_handle`. @@ -114,6 +116,7 @@ A handle is bound to the caller that created it, and it survives a rotation of t | Namespace | The prefix that makes an Upstream's tool names unique within a Gateway. | | Catalog | The stored list of an Upstream's tools. | | Tool policy | Per-tool settings for the result cache and result handles. | +| `resultCache`, `resultHandles` | Per-Gateway settings that turn the result cache and result handles on or off. | | Gateway database | The Redis database that holds cached results and result handles. | ## Next steps diff --git a/content/develop/ai/context-engine/context-gateway/developer-guide.md b/content/develop/ai/context-engine/context-gateway/developer-guide.md index 5491499769..eee198cac3 100644 --- a/content/develop/ai/context-engine/context-gateway/developer-guide.md +++ b/content/develop/ai/context-engine/context-gateway/developer-guide.md @@ -28,7 +28,7 @@ Platform teams create the Gateway and register its Upstreams through the Control |:-------|:------------|:------------------| | Python | Your application or agent uses Python. | Install [`redis-iris`](https://pypi.org/project/redis-iris/) and follow the [quickstart](/content/develop/ai/context-engine/context-gateway/quickstart.md). `ContextGateway` lists, searches, and calls tools, and its `service` property administers Gateways. | | CLI | You work from a shell, a script, or continuous integration. | The `iris context-gateway` commands ship in the same [`redis-iris`](https://pypi.org/project/redis-iris/) package. | -| TypeScript | Your application or agent uses JavaScript or TypeScript. | Install [`@redis-iris/context-gateway`](https://www.npmjs.com/package/@redis-iris/context-gateway). `ContextGatewayClient` opens MCP sessions, and `ContextGatewayService` calls the Control Plane. | +| TypeScript | Your application or agent uses JavaScript or TypeScript. | Install [`@redis-iris/context-gateway`](https://www.npmjs.com/package/@redis-iris/context-gateway) with the `alpha` tag. `ContextGateway` opens MCP sessions, and `ContextGatewayService` calls the Control Plane. | | HTTP | You need language-independent access or don't want a package dependency. | No package required. Send MCP requests to the Gateway endpoint as shown in [MCP](/content/develop/ai/context-engine/context-gateway/mcp.md). | The `redis-iris` package requires Python 3.11 or later. The TypeScript client requires Node.js 22 or later. @@ -50,7 +50,7 @@ In `full` mode, `tools/list` returns every tool under its qualified name. In `se ## Work with large results -When the deployment turns on result handles, a large result comes back as a stub with a handle. Read the parts you need with the handle tools, then release it. See [Read result handles](/content/develop/ai/context-engine/context-gateway/mcp.md#read-result-handles). +When result handles are on for the Gateway, a large result comes back as a stub with a handle. Read the parts you need with the handle tools, then release it. See [Read result handles](/content/develop/ai/context-engine/context-gateway/mcp.md#read-result-handles). ## References diff --git a/content/develop/ai/context-engine/context-gateway/manage-gateways.md b/content/develop/ai/context-engine/context-gateway/manage-gateways.md index d9a004820c..69a55f322c 100644 --- a/content/develop/ai/context-engine/context-gateway/manage-gateways.md +++ b/content/develop/ai/context-engine/context-gateway/manage-gateways.md @@ -32,7 +32,7 @@ Create a Gateway and save its `id` and `mcpEndpoint`. The Gateway serves Model C *Example set `iris_gateway_manage`, step `gateway-create`, in Python (Iris), cURL (Iris), and CLI (Iris).* -To use the result cache or result handles, select a Gateway database with `databaseId`. Your administrator names the available databases. +To use the result cache or result handles, select a Gateway database with `databaseId`. Your administrator names the available databases. A Gateway created with a `databaseId` has `resultCache` and `resultHandles` enabled unless you send them as `disabled`. Sending `enabled` without a `databaseId` returns `400`. ## List and inspect Gateways and Upstreams @@ -42,10 +42,26 @@ List the deployment's Gateways and a Gateway's Upstreams, and read one by ID. Ev ## Change a Gateway -Update a Gateway's `toolExposureMode` to `full` or `search`, its display name, or its `databaseId`. Agents see a new mode on their next request. See [Tool exposure modes](/content/develop/ai/context-engine/context-gateway/concepts.md#tool-exposure-modes). +Update a Gateway's `toolExposureMode` to `full` or `search`, its display name, its `databaseId`, or its `resultCache` and `resultHandles` settings. Agents see a new mode on their next request. See [Tool exposure modes](/content/develop/ai/context-engine/context-gateway/concepts.md#tool-exposure-modes). *Example step `gateway-update-mode`.* +### Turn the result cache and result handles on or off + +Set `resultCache` or `resultHandles` to `enabled` or `disabled` on a Gateway update. Every Gateway response returns both settings. A Gateway's setting takes effect only when the deployment also turns the feature on. See [Result cache and result handles](/content/operate/iris/context-gateway/self-managed/configuration.md#result-cache-and-result-handles). + +```json +{"revision": "", "resultCache": "enabled", "resultHandles": "disabled"} +``` + +| Change | What to send | +| --- | --- | +| Remove the Gateway database | `"databaseId": null` with `"resultCache": "disabled"` and `"resultHandles": "disabled"` in the same request. Without them, the update returns `400`. | +| Add a Gateway database to a Gateway that had none | `databaseId` with `"resultCache": "enabled"`, `"resultHandles": "enabled"`, or both. Adding a database alone keeps both settings as they were, which is `disabled` for a Gateway created without one. | +| Stop caching or handles for a Gateway | `"disabled"` for that setting. The Gateway stops reading and writing cache entries, or stops creating handles and removes the handle tools from `tools/list`. Stored entries and handles stay until their TTL. | + +*Example step `gateway-update-features`.* + ## Register an MCP server Register an MCP server as an Upstream with a namespace, its endpoint, and its credential. Any MCP server that serves Streamable HTTP works, including third-party and in-house servers. The Gateway discovers the server's tools during registration. @@ -77,7 +93,7 @@ Disable an Upstream to take its tools away from agents without deleting it. Its ## Set tool policies -Set a tool's policies with `toolPolicies` on an Upstream update. The result cache is opt-in for each tool. Result handles are on for every eligible result once the deployment turns them on, so a tool policy only opts a tool out or changes its handle lifetime. +Set a tool's policies with `toolPolicies` on an Upstream update. The result cache is opt-in for each tool. Result handles are on for every eligible result while they are on for the Gateway, so a tool policy only opts a tool out or changes its handle lifetime. | Policy | Member | Effect | | --- | --- | --- | @@ -89,6 +105,7 @@ Set a tool's policies with `toolPolicies` on an Upstream update. The result cach - Cache only tools whose data changes more slowly than the time to live (TTL). All callers with access to the Gateway share its cache entries. - A tool whose definition says `readOnlyHint: false` or `destructiveHint: true` is never cached. +- A new or changed `resultCache` policy returns `400` while the Gateway's `resultCache` is `disabled`, including on a Gateway without a `databaseId`. A stored policy sent back unchanged is kept. - When you move an Upstream to a new endpoint, the response lists any policies it removed in `droppedToolPolicies`. ## Rotate an Upstream credential diff --git a/content/develop/ai/context-engine/context-gateway/mcp.md b/content/develop/ai/context-engine/context-gateway/mcp.md index 9a5247ba99..1e617817f2 100644 --- a/content/develop/ai/context-engine/context-gateway/mcp.md +++ b/content/develop/ai/context-engine/context-gateway/mcp.md @@ -74,7 +74,7 @@ This client connects, lists tools, and calls one in either mode. ## Read result handles -When the deployment turns on result handles, the Gateway lists these tools in both modes: +When result handles are on for the Gateway, it lists these tools in both modes: | Tool | What it does | | --- | --- | diff --git a/content/develop/ai/context-engine/context-gateway/quickstart.md b/content/develop/ai/context-engine/context-gateway/quickstart.md index b5835b6903..861c5fb024 100644 --- a/content/develop/ai/context-engine/context-gateway/quickstart.md +++ b/content/develop/ai/context-engine/context-gateway/quickstart.md @@ -28,7 +28,7 @@ This walkthrough needs no agent framework or model-provider key. Follow one tab throughout the page. The Python package and command-line interface (CLI) are alpha prereleases pinned to the version used here. Both require Python 3.11 or later. The cURL and CLI examples use Bash and jq. - + **Python and CLI** @@ -39,7 +39,7 @@ python -m pip install redis-iris==0.1.0a4 ``` > [!NOTE] -> For TypeScript, use the generated client [@redis-iris/context-gateway](https://www.npmjs.com/package/@redis-iris/context-gateway). It opens Model Context Protocol (MCP) sessions with `ContextGatewayClient` and calls the Control Plane with `ContextGatewayService`. See the [developer guide](/content/develop/ai/context-engine/context-gateway/developer-guide.md). +> For TypeScript, use the generated client [@redis-iris/context-gateway](https://www.npmjs.com/package/@redis-iris/context-gateway). Install it with `npm install @redis-iris/context-gateway@alpha`. It opens Model Context Protocol (MCP) sessions with `ContextGateway` and calls the Control Plane with `ContextGatewayService`. See the [developer guide](/content/develop/ai/context-engine/context-gateway/developer-guide.md). **HTTP** diff --git a/content/operate/iris/context-gateway/self-managed/_index.md b/content/operate/iris/context-gateway/self-managed/_index.md index 14dbdf9887..bc280a96e8 100644 --- a/content/operate/iris/context-gateway/self-managed/_index.md +++ b/content/operate/iris/context-gateway/self-managed/_index.md @@ -55,7 +55,7 @@ Use separately managed Redis deployments for metadata, credentials, and customer | Gateway MCP | `/v1/gateways/{gatewayId}/mcp` | The Streamable HTTP MCP endpoint for one Gateway. | | Protected resource metadata | `/.well-known/oauth-protected-resource/v1/gateways/{gatewayId}/mcp` | Names the identity provider for MCP client sign-in. | | Control Plane | `/v1/gateways` | Administration of Gateways and Upstreams. | -| Health | `/v1/health/live`, `/v1/health/ready` | Liveness and readiness on both planes. | +| Health | `/health/liveness`, `/health/readiness` | Liveness and readiness on both planes. | | Identity Service | `/v1/api-keys` | Administration of agent keys. | ## Get started diff --git a/content/operate/iris/context-gateway/self-managed/api-examples.md b/content/operate/iris/context-gateway/self-managed/api-examples.md index d4c1191495..e9bf27f2ad 100644 --- a/content/operate/iris/context-gateway/self-managed/api-examples.md +++ b/content/operate/iris/context-gateway/self-managed/api-examples.md @@ -51,7 +51,7 @@ export OPERATIONS_ID="$(jq -er '.id' operations.json)" jq '{id, mcpEndpoint, toolExposureMode}' front-desk.json operations.json ``` -Result handles also need `result_handles.enabled` on the Data Plane. See [Result cache and result handles](/content/operate/iris/context-gateway/self-managed/configuration.md#result-cache-and-result-handles). +The `search` mode Gateway has a `databaseId`, so it starts with `resultCache` and `resultHandles` enabled. Result handles also need `result_handles.enabled` on the Data Plane. See [Result cache and result handles](/content/operate/iris/context-gateway/self-managed/configuration.md#result-cache-and-result-handles). diff --git a/content/operate/iris/context-gateway/self-managed/configuration.md b/content/operate/iris/context-gateway/self-managed/configuration.md index 2c1b188a54..bbbf14bd59 100644 --- a/content/operate/iris/context-gateway/self-managed/configuration.md +++ b/content/operate/iris/context-gateway/self-managed/configuration.md @@ -118,7 +118,9 @@ dataplane: | `result_handles.max_capture_bytes` | `8388608` | Results above this size come back whole. | | `result_handles.preview_items`, `preview_bytes` | `3`, `2048` | The size of a handle stub's preview. | -The result cache still needs a policy for each tool. Result handles apply to every eligible result on every Gateway with a `databaseId`, unless a tool's policy opts out. Both need the Gateway's `databaseId` to name a registered database. +These settings turn each feature on for the deployment. Each Gateway then has its own `resultCache` and `resultHandles` settings, and a feature serves a Gateway only when both the deployment and the Gateway turn it on. Both need the Gateway's `databaseId` to name a registered database. + +The result cache still needs a policy for each tool. Result handles apply to every eligible result on a Gateway that has them on, unless a tool's policy opts out. See [Turn the result cache and result handles on or off](/content/develop/ai/context-engine/context-gateway/manage-gateways.md#turn-the-result-cache-and-result-handles-on-or-off). ## Trust a private CA diff --git a/content/operate/iris/context-gateway/self-managed/deploy.md b/content/operate/iris/context-gateway/self-managed/deploy.md index 436637f797..fd66083121 100644 --- a/content/operate/iris/context-gateway/self-managed/deploy.md +++ b/content/operate/iris/context-gateway/self-managed/deploy.md @@ -90,7 +90,7 @@ Check each value in `gateway-values.yaml` before you install. If one is wrong, y | `publicBaseURL` is the Data Plane origin that MCP clients reach | `mcpEndpoint` in Gateway responses points to an address clients cannot reach, and identity provider sign-in fails | Set the public origin, including `https://`. | | `identityService.allowInsecureTransport` is `true` for an `http://` Identity Service URL | The Data Plane cannot check agent keys | Set it, or use an `https://` URL. | | The admin, internal, and runtime tokens come from three different Secrets or keys | Rendering fails, or the Identity Service cannot check keys | Create three distinct token files. | -| `license` points to a valid license | `/v1/health/ready` answers `503` | Mount the license file as issued. | +| `license` points to a valid license | `/health/readiness` answers `503` | Mount the license file as issued. | | Both component `image.repository` and `image.tag` are set | Pods `ImagePullBackOff` | Set both to the release images. | {{< /table-scrollable >}} @@ -134,8 +134,8 @@ kubectl -n port-forward svc/ids-iris-identity-service 9200:9200 Then check readiness on both planes: ```bash -curl -sS http://localhost:9100/v1/health/ready -curl -sS http://localhost:8083/v1/health/ready +curl -sS http://localhost:9100/health/readiness +curl -sS http://localhost:8083/health/readiness ``` ## 6. Create a Gateway diff --git a/content/operate/iris/context-gateway/self-managed/operations.md b/content/operate/iris/context-gateway/self-managed/operations.md index 82f97a67fe..0d53cc0a23 100644 --- a/content/operate/iris/context-gateway/self-managed/operations.md +++ b/content/operate/iris/context-gateway/self-managed/operations.md @@ -13,13 +13,13 @@ hideListLinks: true ## Check service health -Both planes serve `/v1/health/live` and `/v1/health/ready` without a credential. Readiness answers `503` while a token source cannot be read or is empty, or the license is not valid. The response does not name the failed check, so read the plane's logs. +Both planes serve `/health/liveness` and `/health/readiness` without a credential. Readiness answers `503` while a token source cannot be read or is empty, or the license is not valid. The response does not name the failed check, so read the plane's logs. With the ports forwarded as in [Deploy](/content/operate/iris/context-gateway/self-managed/deploy.md#5-verify-pods-and-health): ```bash -curl -sS http://localhost:9100/v1/health/ready -curl -sS http://localhost:8083/v1/health/ready +curl -sS http://localhost:9100/health/readiness +curl -sS http://localhost:8083/health/readiness ``` `iris context-gateway health` probes both planes, and `iris context-gateway service diagnose ` reports a Gateway's setup, including Upstreams with empty catalogs. @@ -51,6 +51,7 @@ A cache hit carries `resultCache` in the call's invocation metadata. Every other | Bypass `reason` | What to check | | --- | --- | | `not_opted_in` | The tool has no result cache policy. | +| `disabled` | The Gateway's `resultCache` is `disabled`. | | `no_database` | The Gateway has no `databaseId`. | | `unknown_database` | The Gateway's database is not registered on the Data Plane. Declare it on both planes. | | `vetoed_by_annotation` | The tool's definition says it is not read-only, or that it is destructive. | @@ -88,6 +89,8 @@ Upgrade both planes together and roll forward, not back. An older Data Plane can After an upgrade, refresh an Upstream's catalog when the release notes ask for it. +Gateways stored before the per-Gateway `resultCache` and `resultHandles` settings read as `enabled` when they have a `databaseId` and `disabled` otherwise, so their behavior does not change. Scripts that remove or add a Gateway's `databaseId`, or set `resultCache` tool policies, may need the changes in [Turn the result cache and result handles on or off](/content/develop/ai/context-engine/context-gateway/manage-gateways.md#turn-the-result-cache-and-result-handles-on-or-off). + ```bash helm upgrade gateway redis-ai/redis-context-gateway \ --version \ diff --git a/content/operate/iris/context-gateway/self-managed/reference.md b/content/operate/iris/context-gateway/self-managed/reference.md index 6d4fc4be17..697b69b455 100644 --- a/content/operate/iris/context-gateway/self-managed/reference.md +++ b/content/operate/iris/context-gateway/self-managed/reference.md @@ -30,7 +30,7 @@ Each file reference accepts a Kubernetes Secret or a Secrets Store Container Sto {{< table-scrollable >}} | Symptom | Likely cause | Fix | | --- | --- | --- | -| `/v1/health/ready` answers `503` | A token source cannot be read or is empty, or the license is not valid | Check the admin and internal token Secrets and the license. | +| `/health/readiness` answers `503` | A token source cannot be read or is empty, or the license is not valid | Check the admin and internal token Secrets and the license. | | Agent receives `401` | Key is missing, revoked, or expired, or sent in the wrong header | Send it as `Authorization: Bearer` or `X-Api-Key`, and check its status. | | Agent receives `403` | The key has no `context-gateway` grant for this Gateway | Update the key's grants with the Identity Service control token. | | Agent receives `404` | The Gateway does not exist, is being deleted, or belongs to another tenant | Check the Gateway ID and `tenantId`. | @@ -39,7 +39,9 @@ Each file reference accepts a Kubernetes Secret or a Secrets Store Container Sto | A tool call returns `upstream_rejected_credentials` | The Upstream refused the stored credential | Rotate the Upstream credential. | | Cached results keep coming back after a secret rotation | The secret was rotated in place under the same reference | Refresh the Upstream's catalog. | | Handles stop being created | The Gateway database is above 90 percent of `maxmemory`, refused a write, has another eviction policy than `noeviction`, or has no JSON support | Raise `maxmemory`, shorten the handle lifetime, set `noeviction`, or move handles to a dedicated database with JSON. | -| Large results suddenly come back as stubs | `result_handles.enabled` was turned on, which applies to every Gateway with a `databaseId` | Opt tools out with a `resultHandle` policy of `capture: never`, or remove the Gateway's `databaseId`. | +| Large results suddenly come back as stubs | `result_handles.enabled` was turned on, which applies to every Gateway whose `resultHandles` is `enabled` | Opt tools out with a `resultHandle` policy of `capture: never`, or set the Gateway's `resultHandles` to `disabled`. | +| Removing a Gateway's `databaseId` returns `400` | The Gateway's `resultCache` or `resultHandles` is still `enabled` | Send both as `disabled` in the same update. | +| A `resultCache` tool policy returns `400` | The Gateway's `resultCache` is `disabled`, or the Gateway has no `databaseId` | Select a database and enable `resultCache` on the Gateway first. | | Data Plane does not become ready | It cannot reach the Identity Service, or an `http://` Identity Service URL is used without `identityService.allowInsecureTransport: true` | Check `identityService.baseURL` and the network path. | | Context Surface search tools return partial results | Redis is still indexing existing keys after a create, a data model change, or a refresh | Wait until `FT.INFO` on the Surface database shows `percent_indexed` at `1`. | | Deleting a Context Surface keeps answering `503` | Its indexes cannot be dropped, often because the Control Plane's Redis user lacks `FT._LIST` or `FT.DROPINDEX` | Grant the commands, or repeat the delete with `ignoreIndexSweepFailure=true`. |