kagent: what "agent" means
Part of Agent Definition Research. Produced by running RESEARCH_PROMPT. Evidence from kagent.dev docs and the kagent-dev/kagent source (CRD Go types, controller/translator, ADK runtimes, in-repo architecture docs). kagent is a CNCF sandbox framework for running AI agents on Kubernetes.
Source anchors
Sources retrieved 2026-07-13. Source-level claims are pinned to the kagent v0.9.11 release (2026-07-01) at commit 14dcbfc. The kagent.dev docs pages are unversioned live pages built from a separate kagent-dev/website repository, so doc quotes are not release-pinned; where docs and pinned source could diverge, this dossier prefers the pinned source.
- Product concepts: Agents, Tools, Architecture, Agent Memory, Agent Substrate, Agent Harness, and What is kagent.
- Reference: API reference, FAQ, A2A example, and operational considerations.
- Stable CRD symbols:
Agent,AgentSpec,Tool,TypedReference,A2AConfig,AgentStatus,ModelConfig, and database models. - Stable runtime symbols: agent-as-tool compiler, reconciler, remote A2A tool, and in-repo architecture docs.
The agent noun (primary-source quotes)
- Concepts, Agents: "An AI agent is an application that can interact with users in natural language. Agents use LLMs to generate responses to user queries and can also execute actions on behalf of the user." The same page decomposes it into exactly three components: instructions ("A set of instructions that define the agent's behavior and capabilities. This is also called a system prompt"), "Tools: Functions that the agent can use to interact with its environment," and "Skills: Descriptions of capabilities that help the agent act more autonomously."
- Operationally the agent is a Kubernetes custom resource: kind
Agent, groupkagent.dev, namespaced, current storage versionv1alpha2(v1alpha1 is retained unserved). "Agent is the Schema for the agents API" (agent_types.go:664-674; CRD manifest). A persistent, identified, GitOps-able record, not a run. - The spec bifurcates the noun into two agent kinds (
AgentTypeenum): "Declarative configures an agent that is fully described by this resource (model, instructions, tools) and runs on one of kagent's built-in runtimes," versus BYO: "a 'bring your own' agent backed by a user-provided container image. Kagent deploys the image and expects it to serve the agent over the A2A protocol on port 8080" (agent_types.go:58-68). - Two sibling CRDs extend the noun: SandboxAgent ("declares an agent that runs in an isolated sandbox on Agent Substrate", per the API reference) and AgentHarness, which "provisions the execution environment itself and runs a third-party coding agent inside it" (backend enum:
openclaw;nemoclaw;hermes,agentharness_types.go:19-21), explicitly distinguished fromAgent, which "runs a kagent-managed agent runtime" (Agent Harness). - Conceptual model: agent-as-config reconciled into agent-as-deployed-service. The CRD spec is the complete definition (config); the controller continuously materializes it into a running A2A-speaking workload (one Deployment per agent, or a substrate actor). Execution state lives in separate Session/Task/Memory records scoped to the agent's identity.
Subagents
- Agent-as-tool, declared in the CRD roster. The
Toolunion type on a Declarative agent has exactly two provider kinds:McpServerandAgent(ToolProviderType). Docs: "You also have an option of using agents as tools. Any agent you create can be referenced and used by other agents you have. You can refer to agents in other namespaces by using thenamespace/nameformat" (Tools, "Agents as Tools"). The worked example is a PromQL agent used as a tool by a second agent "whenever it needs to create a PromQL query" (Agents, "Agents as Tools"). - The subagent is not spawned; it is referenced. The
agentfield is a bareTypedReference(kind/apiGroup/name/namespace). The referenced agent is an independently deployed workload with its own Service; the compiler resolves the reference to a URL (http://{name}.{namespace}:8080, or a controller-proxied path for sandbox agents,toolAgentURL). - Inheritance is nothing; the contract is identity-only. The parent's compiled config carries per child only
RemoteAgentConfig{Name, Url, Headers, Description}; no model, tools, memory, or approval lists cross the boundary, in either the Go or the Python runtime. What does cross: the end user's identity (x-user-idheader) and conversation lineage headers (x-kagent-parent-context-id,x-kagent-root-context-id), plus a staticx-kagent-source: agentmarker that "hides the session from the agent's session history sidebar" (remote_a2a_tool.go; a2a-subagents.md). - Fresh child session per delegation edge. Each remote-agent tool mints its own A2A context ID at construction, independent of the parent's session: "KAgentRemoteA2ATool.init generates a UUID (
_last_context_id) that is used as the A2Acontext_idfor every message sent to the subagent. On the subagent side, thiscontext_idbecomes the session ID" (a2a-subagents.md:13). - Communication is a single blocking A2A
SendMessage(JSON-RPC), results only; child failures come back as an error string in the tool output rather than aborting the parent's turn, and HITL pauses tunnel through a two-phase resume protocol (remote_a2a_tool.go:255-272). - Nesting: a DAG with depth 10. Reconcile-time validation recurses the tool chain: "cycle detected in agent tool chain," "recursion limit reached in agent tool chain," and "agent tool cannot be used to reference itself" errors, bounded by
const MAX_DEPTH = 10(the chain may nest up to 10 levels) (compiler.go:23,:174-180,:199-201). - Lifetime coupling: none, and nothing protects the edge. No finalizer, webhook, or reference count prevents deleting an agent that others use as a tool; the parent's
Acceptedcondition flips to False (reasonReconcileFailed) on its next reconcile while itsReadycondition, computed only from its own Deployment, can stay stale-True (reconciler.go:190-193,:287-299). Cross-namespace referencing is gated byallowedNamespaces, which "follows the Gateway API pattern for cross-namespace route attachments" (agent_types.go:84-90).
Configuration surface (what, where, why)
- Declarative agent fields (
DeclarativeAgentSpec):runtime(pythonADK, default, orgoADK),systemMessage/systemMessageFrom(mutually exclusive by CEL rule) with GopromptTemplatecomposition,modelConfig(by-name reference, default"default-model-config"),tools(max 20),a2aConfig(publishedAgentSkilllist),memory(modelConfigembedder reference plusttlDays, default 15),stream,executeCodeBlocks, anddeployment. Agent-level extras:skills(OCI images or Git repos, "made available to the agent under the/skillsfolder") andallowedNamespaces. - The environment knob is the Kubernetes pod surface:
SharedDeploymentSpecexposes replicas (default 1), resources, env, volumes, node placement, security contexts, service accounts, andextraContainers("Useful for sidecars such as token proxies, log shippers, or security agents"). - Model and tools are separate CRDs referenced by name.
ModelConfigenumerates nine providers (Anthropic, OpenAI, AzureOpenAI, Ollama, Gemini, GeminiVertexAI, AnthropicVertexAI, Bedrock, SAPAICore) with per-provider blocks gated by CEL rules;RemoteMCPServer(v1alpha2) carries MCP endpoint, protocol, and header config. Credentials are always Secret references (apiKeySecret,headersFrom), never inline values. - Permissions are per-tool HITL:
requireApprovallists tool names that pause for human approval, CEL-enforced to be a subset oftoolNames(agent_types.go:533). Docs: "Tools listed inrequireApprovalpause execution and present Approve/Reject buttons in the UI." - Where config lives: CRD YAML via
kubectlis canonical; Helm values install the platform and bundled agents; the dashboard UI has a create/edit wizard; the CLI manages resources and invokes agents. No triggers: there is no cron or webhook field onAgent; the only trigger-adjacent surface isAgentHarness.spec.channels(Slack/Telegram bindings for harness-run coding agents). - Stated rationale, quoted: declarativeness is the product thesis: "kagent is designed from the ground up to be declarative. You define the agents, tools, and instructions and kagent will take care of the rest. Most other frameworks are procedural and require you to write code to tell the LLM what to do" (FAQ). CRDs exist so you can "Define, version, and roll out agents with kubectl and GitOps" (What is kagent). Prompt templates take ConfigMaps only: "Secret references are intentionally excluded to avoid leaking sensitive data into prompts sent to LLM providers." HITL exists "to keep humans in control of agent actions." Cross-namespace references let you "share tool servers across namespaces without duplicating them" (Agents; Tools).
- The protocol choices are asserted, not argued. The A2A feature bullet says only "Agents discover and invoke each other. Compose multi-agent workflows with first-class delegation" (features); MCP is justified by traction: "a protocol, originally created by Anthropic, which is meant as a flexible way to provide tools and other information to Agents... it has begun to gain traction and more and more tools are adopting it" (Tools). The interoperability rationale exists only as an outbound link to Google's A2A announcement, never restated in kagent's own prose.
Binding time
- Reconcile time is the binding moment. The controller resolves ModelConfig, prompt templates, and MCP references into one fully resolved
config.jsonbaked into a Secret before the pod starts: "Prompt templates are resolved by the controller, not at runtime. The agent receives a fully resolved string. This makes debugging easier and keeps the runtime simple" (architecture README). - Rebinding means a pod roll, not a mutation. The pod reads
config.jsononce at startup; a config-hash annotation on the pod template forces a rolling update when the serialized config or referenced Secrets change (manifest_builder.go:27-30). Docs make secret rotation the sanctioned live path: "kagent automatically restarts agents when you update the secrets that the agents reference" (operational considerations). - Per-request bindings: session identity binds at invocation (get-or-create by
app_name,user_id,session_idin the ADK executor), and each HITL approval decision binds per tool call at runtime. - Versioning is Kubernetes versioning. Nothing beyond
generation/resourceVersionplus GitOps; theversionspec field is only "the agent's version string, surfaced on the A2A AgentCard" (API reference). The platform database guarantees an n-1 rollback window (upgrade guide).
Relationships between nouns
- CRD kinds (v1alpha2): Agent, AgentHarness, ModelConfig, ModelProviderConfig, RemoteMCPServer, SandboxAgent. ToolServer and Memory survive as v1alpha1-only leftovers never promoted. There is no Session CRD and no Team kind; Team was an AutoGen-era concept that disappeared with the v0.6 ADK migration (release notes: "The
apiVersionfield in the kagent CRDs is nowkagent.dev/v1alpha2"). The intro page still promises that agents "can also be grouped into teams where a planning agent comes up with a plan and assigns tasks to individual agents in the team," but no CRD, controller path, or docs page backs it at the pinned commit; agent-as-tool is the only implemented composition. - Agent 1:1 ModelConfig (by name), 1:N tools (max 20), each tool an MCP server or another Agent. Agent-as-tool edges make the agent graph many-to-many, validated as a DAG.
- Session is a database row, not a resource:
Session{ID, Name, UserID, AgentID, Source}in the controller's SQLite/Postgres store, whereSourcedistinguishesuserfromagent("created by a parent agent's A2A call",models.go:55-77). One agent, many sessions. Task is the A2A unit of work, N:1 to Session. Memory rows are agent-plus-user scoped vectors with TTL: "Each agent has its own isolated memory store. You cannot share memories across agents," and memory is "built on the Google ADK memory implementation and cannot be swapped" (Agent Memory). - The CRD is the source of truth; the DB is a cache. "The DB provides fast lookups for the HTTP API and UI, while the CRDs remain the source of truth for agent configuration" (architecture README).
- Agent implies its own environment: one Deployment plus Service plus config Secret per agent; SandboxAgent swaps that for a substrate actor. "Session" is overloaded across subsystems: on Agent Substrate it means "The execution context that tracks an actor's activity and checkpoints" (Agent Substrate).
Lifecycle
- Create:
kubectl applyfires the reconciler pipeline: translate spec into manifests, reconcile owned resources, upsert the DB record, update status (controller-reconciliation.md). Status carriesAccepted(spec compiled) andReady(Deployment replicas available), plusUnsupportedFeatures. - The platform deploys; the pod owns the loop. "The kagent engine is the core component of kagent. It runs the agent's conversation loop and supports two runtimes": Python ADK (default, built on Google ADK) and a Go ADK (Architecture). The controller never runs the loop; it proxies: "The controller HTTP server proxies A2A requests to agent pods. The UI never talks directly to agent pods" (architecture README).
- Update: rolling update with
MaxUnavailable=0,MaxSurge=1; the old pod drains gracefully on SIGTERM. Delete: standard owner-reference garbage collection, no finalizer on the base Agent; the controller drops the cached DB row when the Get returns NotFound. - Pause/resume exists only on Agent Substrate: "Substrate decouples an agent's lifecycle from pod infrastructure. Idle agents are snapshotted to object storage and rehydrated on demand, so a small pool of pre-warmed workers can host far more agents than there are pods" (Agent Substrate). Regular agents are always-on Deployments.
- Persists across runs: sessions, tasks, and events in the controller database; memory vectors until TTL expiry; substrate actor snapshots.
- Invocation surfaces all speak A2A: the dashboard POSTs A2A JSON-RPC through the controller proxy;
kagent invokesends the task as an A2A call; and "Every AI agent created with kagent implements the A2A protocol and can be invoked by an A2A client" at/api/a2a/{namespace}/{agent-name}, with the agent card at.well-known/agent.json(A2A example). Agents double as tools for outsiders too: "A2A-enabled agents are automatically exposed as an MCP server on the kagent controller" (Agents).
What makes it "an agent" here (our inference)
Our inference: kagent defines an agent infrastructurally, as a namespaced Kubernetes resource whose spec declares persona and capability (instructions, model reference, tools, skills) and whose reconciler materializes it into a long-running service that speaks A2A. Agent-ness is not a property of the loop (that is delegated wholesale to an embedded ADK runtime); it is the property of being a declaratively managed, addressable workload. The distinctive datum for the study is that kagent pushes the entire multi-agent question onto the network: a subagent is just another agent's Service called over A2A with a fresh session, identity headers forwarded, and nothing else shared, so delegation inherits Kubernetes semantics (references can dangle, readiness is per-workload, and isolation is the default) rather than framework semantics.
Open questions
- Whether an explicit protocol-choice rationale for A2A/MCP exists outside the docs and blog (maintainer talks, the CNCF sandbox proposal) is unchecked; on kagent.dev itself the choice is asserted, not argued.
- Why ToolServer and Memory were left behind as v1alpha1-only CRDs while their replacements (RemoteMCPServer, inline
memory) moved to v1alpha2 is undocumented. - What happens to an in-flight multi-turn loop (mid tool-call) during a rolling update is unconfirmed: graceful SIGTERM drain is implemented, but no source states whether a mid-loop turn survives pod replacement.
- The broken agent-as-tool failure mode (Accepted=False with stale Ready=True) is only inferable from source; no docs page describes it.
- The docs site is built from a separate unversioned repository, so doc quotes cannot be pinned to the v0.9.11 source snapshot; treat doc-only claims as current-site claims.
