From 934022ee4a535896b4bcad12735158a388572a2c Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 21 Aug 2026 10:47:02 +0000 Subject: [PATCH] docs(ai): correct the `agent.knowledge` row to a retirement (#10730) The "shape of an agent" field table documented `knowledge` as live RAG access and noted only that its nested `topics` alias was removed, pointing the reader at `os migrate meta --from 16` to "rewrite it". But the whole key is retired: `packages/spec/src/ai/agent.zod.ts` declares `knowledge: retiredKey(...)`, so it types as `never` and any value reaching the runtime is rejected at parse. The page already carried the correct prescription 64 lines further down, in the Sales Assistant example. This rewrites the row from the tombstone's own words so the two agree: the key is gone (#3896 audit close-out), it is not a rename, restrict retrieval at the knowledge-service / source level, and describe intended grounding in `instructions`. No migration command is offered, because none moves a `knowledge` block forward - the tombstone's `os migrate meta --from 16` only LISTS edits to apply by hand, matching how the sibling `tools` row is documented. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01DdCnBGcHeufjrq7drTD3wt --- content/docs/ai/agents.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/ai/agents.mdx b/content/docs/ai/agents.mdx index c4219cdecb..fbd1c5fe7e 100644 --- a/content/docs/ai/agents.mdx +++ b/content/docs/ai/agents.mdx @@ -208,7 +208,7 @@ own `ask` / `build` records use exactly these fields): | `model` | Provider + model config (`provider`: `openai` \| `azure_openai` \| `anthropic` \| `local`) | | `skills` | Skill names to attach (the primary Agent → Skill → Tool capability model) | | `tools` | **Removed in protocol 17 (#3894)** — typed `never`, so writing it fails `tsc`, and a value that reaches the runtime is rejected at parse. This is **not** a rename: there is no key the value moves to. Declare each tool on a **skill** instead — a platform tool by its registered name, or `action_` for one of your own AI-exposed Actions — and attach that skill through `skills` (ADR-0064) | -| `knowledge` | RAG access: `{ sources: string[], indexes: string[] }`. `sources` is the only key; the `topics` alias was removed in protocol 17 (#3855) — `os migrate meta --from 16` rewrites it | +| `knowledge` | **Removed in protocol 17 (#3896)** — typed `never`, so writing it fails `tsc`, and a value that reaches the runtime is rejected at parse. Declaring `sources` / `indexes` here never scoped retrieval: `search_knowledge` takes `sourceIds` from the LLM's own tool-call arguments, not from the agent record, so an author who “scoped” access here scoped nothing. This is **not** a rename: there is no key the value moves to — delete the block. Restrict retrieval at the knowledge-service / source level (per-source permissions), and describe intended grounding in `instructions` so the model asks for the right sources | There is no `type` field and no fixed agent "type" taxonomy — behaviour comes from persona, instructions, skills, and tools. There are no `triggers` / `schedule`