About tools

Give an agent tools by binding Model Context Protocol servers or other agents to an AgentTemplate.

An AgentTemplateAgentTemplateA Kubernetes custom resource defining what an agent does: its model, system prompt, tools, skills, and plugins. It runs only once an Agent pairs it with a Harness.Learn more’s spec.tools list defines what an agent can do beyond its system prompt. Each entry is a tool bindingTool bindingOne 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.Learn more, and every binding selects exactly one source: a Model Context ProtocolModel Context ProtocolAn open protocol for exposing tools and resources to a model. kagent reaches an MCP server through a RemoteMCPServer resource, and an AgentTemplate binds individual tools from it.Learn more (MCP) server, or another AgentTemplate used as a tool. A binding that names both, or neither, is rejected.

mcp: Binds tools from an MCP server.
agent: Binds another AgentTemplate, so that the agent can hand work to it.

Both kinds resolve within the AgentTemplate’s own namespace, so a binding cannot reach a server or a template in another namespace.

MCP tools

An mcp binding names a server, and optionally the tools to take from it. On the kagent and Codex harnesses, listing tools narrows the binding to those tools. Omitting the list, or leaving it empty, exposes every tool that the server offers.

tools:
  - mcp:
      server:
        kind: RemoteMCPServer
        name: my-mcp-server
      tools:
        - search_docs
        - fetch_page
      requireApproval: true

Field	Description
`mcp.server.kind`	The kind of server resource. `RemoteMCPServer` is the only accepted value.
`mcp.server.name`	The server’s name, in the AgentTemplate’s namespace.
`mcp.tools`	Optional. The names of the tools to bind, up to 50. Duplicates are collapsed. An omitted or empty list exposes every tool on the server, and so does any list on the Claude harness.
`mcp.requireApproval`	Optional. Pauses the agent for a person’s approval before each call to a tool that this binding exposes. Omit to run the bound tools without approval. For more information, see Human in the loop.

Warning

The Claude HarnessHarnessA Kubernetes custom resource defining how an agent is allowed to run: its runtime, workload image, and WorkerPool and snapshot storage. An Agent pairs it with the AgentTemplate it runs.Learn more ignores mcp.tools and exposes the whole server. Claude’s MCP configuration has no per-tool allowlist, so kagent cannot narrow a server there. The compiler records the tools that you selected in a warning on the AgentTemplate’s status.harnesses[].warnings and then admits the revisionRevisionThe compiled, immutable output of one Agent, identified by a content digest. A Session runs the revision it was created from for its whole life, so editing the Agent affects only sessions created afterward. anyway, so the agent becomes ready with every tool that the server serves. Read the warning after you bind a server:

kubectl get agenttemplate <name> -n <namespace> \
  -o jsonpath='{range .status.harnesses[*]}{.harness}{": "}{.warnings}{"\n"}{end}'

Where an agent on the Claude harness must not reach a tool, narrow the server rather than the binding. Set requireApproval: true, which does apply on this harness and pauses every call to the server, or give the agent its own RemoteMCPServer that serves only the tools you intend. For the bundled tool server, see the installation-level settings that drop providers and write tools in Tools ecosystem.

Subagents as tools

A subAgent binding points at another AgentTemplate. The binding allows one agent to route work to another agent. The model reads the description when it decides whether to route work here. A description that states plainly what the bound agent is for therefore matters more than the detail of its configuration.

tools:
  - subAgent:
      name: log-searcher
      description: Search application logs for a time range and a query string.
      templateRef:
        name: log-search-agent

Every field is required. For the complete schema, see the API reference.

Field	Description
`subAgent.name`	The name that the model sees for this binding.
`subAgent.description`	The text that tells the parent agent when to route work here.
`subAgent.templateRef.name`	The AgentTemplate to bind, in the same namespace.

A bound template compiles under the parent AgentAgentA Kubernetes custom resource that pairs one AgentTemplate with one Harness. Each side takes either an inline spec or a reference to an existing resource, and the controller compiles the pair into a revision.Learn more’s Harness and runs inside the parent’s ActorActorThe sandboxed unit of compute, provided by Agent Substrate, that runs a Session's conversation loop. Every Session is backed by one.Learn more, so nesting costs no extra compute and the two agents share one sandbox. A subagent needs no Agent of its own.

Note

Dedicated subagents, which would give a bound agent its own Harness, Session, and Actor and reach it over A2A, are not part of the served API. The subAgent.agentRef field that would select one is deferred until a dedicated subagent can create and invoke its own Session, so the only binding a reader can write today is templateRef.

What a subagent tree allows

A subagent binding nests one agent inside another’s runtime, so kagent constrains the shape of the resulting tree. The compiler enforces each of the following rules, and a violation surfaces as a failed revisionRevisionThe compiled, immutable output of one Agent, identified by a content digest. A Session runs the revision it was created from for its whole life, so editing the Agent affects only sessions created afterward. rather than a failure at run time.

One level of nesting. A bound agent cannot itself bind another agent. A second consecutive binding is rejected as exceeding the kagent runtime boundary.
No cycles. An AgentTemplate cannot reach itself through a chain of bindings.
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.

Skills