Repository navigation
Skills and MCP wording cleanup - #608
Conversation
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Docs preview
Both are uploaded Worker versions and serve no production traffic. |
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
|
|
||
| ### Tool selection on the Claude harness | ||
|
|
||
| Claude's MCP configuration has no per-tool allowlist. On the Claude harness, the `tools` list does not narrow a server, and the agent reaches every tool that the server serves. kagent admits the {{< gloss "Revision" >}}revision{{< /gloss >}} either way. If the list that you wrote does not already cover every tool that the server offers, kagent also records a warning on the Agent. |
There was a problem hiding this comment.
Should fix (accuracy). The warning condition is narrower than "does not already cover every tool". In go/core/internal/translator/claude/mcp.go (mcpSelectionWarning), kagent skips the warning only when the tools list exactly matches the tool set that kagent last discovered on the server. It also warns when the list names tools that the server does not offer, and when no current discovered tool set exists.
Suggested wording: "kagent records a warning on the Agent unless the list exactly matches the tools that kagent last discovered on the server."
| | `subAgent.templateRef.name` | The AgentTemplate to bind, in the same namespace. | | ||
|
|
||
| A bound template compiles under the parent {{< gloss "Agent" >}}Agent{{< /gloss >}}'s Harness and runs inside the parent's {{< gloss "Actor" >}}Actor{{< /gloss >}}, so nesting does not add compute and the two agents share one sandbox. A subagent does not need an Agent of its own. | ||
| kagent compiles the bound template into the parent agent's own configuration, and both agents then run in the same place. A bound template is not an MCP server and has no endpoint of its own. A bound template also does not need an {{< gloss "Agent" >}}Agent{{< /gloss >}} resource because the parent's Agent runs it. |
There was a problem hiding this comment.
Should fix. "Run in the same place" is vaguer than the text it replaces ("runs inside the parent's Actor, so ... the two agents share one sandbox"). about/core-concepts.md:172 still uses the specific wording, so the two pages now describe the same behavior at different levels of precision. Could we keep "sandbox" here? The same applies to the stdio row in plugins.md:82.
| - `mcp`: Binds tools from an MCP server. | ||
| - `agent`: Binds another AgentTemplate, so that the agent can hand work to it. | ||
| - `mcp`: Tools from a {{< gloss "Model Context Protocol" >}}Model Context Protocol{{< /gloss >}} (MCP) server. | ||
| - `subAgent`: Another agent that takes work from the agent that you are configuring. |
There was a problem hiding this comment.
Should fix. Now that Agent is a resource kind, "Another agent" reads as an Agent resource, but line 73 says that a bound template does not need an Agent. "Another AgentTemplate that takes work from the agent that you are configuring" avoids the ambiguity. The same wording is in data/glossary.yaml:122.
| kubectl get agent <name> -n <namespace> -o jsonpath='{.status.warnings}' | ||
| ``` | ||
|
|
||
| To keep an agent on the Claude harness away from a tool, limit what the server exposes rather than what the binding selects. For example, put the MCP server behind agentgateway and apply [tool access](https://agentgateway.dev/docs/kubernetes/latest/documentation/mcp/tool-access/) rules to the route. Those rules filter a disallowed tool out of the `tools/list` response, so the agent never sees it. Then point the RemoteMCPServer at that route. To put more than one MCP server behind one route, see [Virtual MCP](https://agentgateway.dev/docs/kubernetes/latest/documentation/mcp/virtual/). |
There was a problem hiding this comment.
Should fix. The previous version offered a simpler option that this rewrite drops: give the agent its own RemoteMCPServer that serves only the tools that you intend. Now the only example requires a second product. Could we keep the dedicated RemoteMCPServer option first, and the agentgateway approach as the stronger alternative?
| - **No reuse within one tree.** The same AgentTemplate cannot appear twice in the same tree. | ||
| - **Unique binding names.** Two bindings on one AgentTemplate cannot share a `name`. | ||
|
|
||
| When kagent rejects a tree, the Agent's `Compatible` condition becomes `False`. The condition reports the reason `UnsupportedConfiguration`, and its message identifies the rule that failed. Read both in the output of the following command. |
There was a problem hiding this comment.
Nit. True for rule violations. A missing subagent template is a different case: it reports ResolvedRefs with ReferenceResolutionFailed, not Compatible (go/core/internal/translator/compiler.go, subagent template lookup). One clause would cover it.
| ## Troubleshooting | ||
|
|
||
| A schema problem appears on the AgentTemplate's status, in the entry for each Harness under `status.harnesses`. `ResolvedRefs` reports a ConfigMap or key that kagent cannot find, and `Compatible` reports a schema that kagent found but cannot accept, or a Harness that does not use the `kagent` runtime. | ||
| A schema problem appears on the Agent's status conditions. `ResolvedRefs` reports a ConfigMap or key that kagent cannot find. `Compatible` reports a schema that kagent found but cannot accept, or a Harness that does not use the `kagent` harness. |
There was a problem hiding this comment.
Should fix. "A Harness that does not use the kagent harness" defines a Harness in terms of a harness. The table row for Harness runtime "x" does not support structured output has the same wording. Suggest:
| A schema problem appears on the Agent's status conditions. `ResolvedRefs` reports a ConfigMap or key that kagent cannot find. `Compatible` reports a schema that kagent found but cannot accept, or a Harness that does not use the `kagent` harness. | |
| A schema problem appears on the Agent's status conditions. `ResolvedRefs` reports a ConfigMap or key that kagent cannot find. `Compatible` reports a schema that kagent found but cannot accept, or a Harness whose runtime is not `kagent`. |
| No error appears on either resource, because the Harness has no status to write one to and the AgentTemplate was never paired. The failure surfaces only when you try to use the template. | ||
| ## A new AgentTemplate never runs | ||
|
|
||
| When you create an AgentTemplate directly, it never becomes ready. An AgentTemplate is not runnable by itself, and nothing prepares a template until an Agent references it. The template also has no status for a failure to appear on, so the problem surfaces only when you try to start a conversation. |
There was a problem hiding this comment.
Nit. The page says that an AgentTemplate has no status, so "never becomes ready" describes a state that it cannot have. Suggest:
| When you create an AgentTemplate directly, it never becomes ready. An AgentTemplate is not runnable by itself, and nothing prepares a template until an Agent references it. The template also has no status for a failure to appear on, so the problem surfaces only when you try to start a conversation. | |
| An AgentTemplate on its own never runs. An AgentTemplate is not runnable by itself, and nothing prepares a template until an Agent references it. The template also has no status for a failure to appear on, so the problem surfaces only when you try to start a conversation. |
| Pinning has a practical consequence worth planning for. Publishing a new version means updating the AgentTemplate to name the new digest, commit, or object version, which compiles a new revision. Agents that are already running keep the content that they started with. | ||
| If a source sets more than one kind, or none of them, the API server rejects the AgentTemplate with the error `exactly one of the fields in [oci git bucket] must be set`. | ||
|
|
||
| Keep in mind that publishing a new version means updating the AgentTemplate to reference the new digest, commit, or object version, which produces a new revision. However, agents that are already running keep the content that they started with. |
There was a problem hiding this comment.
Nit. Nothing contrasts with "However", and "Keep in mind that" is filler. Suggest:
| Keep in mind that publishing a new version means updating the AgentTemplate to reference the new digest, commit, or object version, which produces a new revision. However, agents that are already running keep the content that they started with. | |
| Publishing a new version means updating the AgentTemplate to reference the new digest, commit, or object version, which produces a new revision. Agents that are already running keep the content that they started with. |
|
|
||
| Tool binding: | ||
| short: "One entry in an AgentTemplate's spec.tools list. Each binding selects exactly one source: tools from a Model Context Protocol server, or another AgentTemplate used as a tool." | ||
| short: "One entry in an AgentTemplate's spec.tools list. Each binding connects the agent to one source: tools from a Model Context Protocol server, or another agent that takes work from it." |
There was a problem hiding this comment.
Should fix. Same ambiguity as about-tools.md:11: "another agent" reads as the Agent kind. Suggest "another AgentTemplate that takes work from it".
| ```bash | ||
| kubectl get agenttemplate <template-name> -n kagent \ | ||
| -o jsonpath='{range .status.harnesses[0].conditions[?(@.type=="Ready")]}{.status} {.reason} {.message}{end}' | ||
| kubectl get agent <agent-name> -n kagent \ |
There was a problem hiding this comment.
Nit. The example already names the Agent release-writer, so the reader does not need a placeholder here.
| kubectl get agent <agent-name> -n kagent \ | |
| kubectl get agent release-writer -n kagent \ |
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
2 participants
No description provided.