# kagent > Explore concepts, guides, and reference docs for running declarative AI agents on Kubernetes with Agent Substrate, from install through day-two operations. ## Get started - [Your first agent](https://kagent.dev/docs/kagent/1.x/get-started/your-first-agent.md): This guide walks you through creating an agent, from applying a Harness and an AgentTemplate to … - [Your first MCP tool](https://kagent.dev/docs/kagent/1.x/get-started/your-first-mcp-tool.md): A system prompt tells an agent how to behave. Tools tell it what it can do. This guide binds a Model … ## About - [What is kagent?](https://kagent.dev/docs/kagent/1.x/about/what-is-kagent.md): kagent is an open-source, Kubernetes-native platform for running AI agents. It defines an … - [Core concepts](https://kagent.dev/docs/kagent/1.x/about/core-concepts.md): kagent 1.0 kagent 1.0 replaces 0.x’s Deployment-based Agent custom resource with a new model … ### Architecture - [kagent architecture](https://kagent.dev/docs/kagent/1.x/about/architecture/kagent.md): The previous page defined the core concepts of Harness, AgentTemplate, Agent, Session, and Actor. … - [Agent Substrate architecture](https://kagent.dev/docs/kagent/1.x/about/architecture/agent-substrate.md): The kagent architecture page established that every SessionSessionA running conversation with one … ### Substrate runtime - [Sandboxing](https://kagent.dev/docs/kagent/1.x/about/substrate-runtime/sandboxing.md): An agent runs an agentic loop. A model proposes the next step, the agent carries it out by running a … - [Suspend and resume](https://kagent.dev/docs/kagent/1.x/about/substrate-runtime/suspend-and-resume.md): An agent spends most of its life waiting. It waits on a person to reply, and it waits on a large … - [Standalone sandboxes](https://kagent.dev/docs/kagent/1.x/about/substrate-runtime/standalone-sandboxes.md): A Sandbox is a scratch environment for running commands and working with files. It is scoped to the … - [Identity](https://kagent.dev/docs/kagent/1.x/about/substrate-runtime/identity.md): A kagent installation identifies each kind of caller with a different system. An operator applying a … - [Egress control](https://kagent.dev/docs/kagent/1.x/about/substrate-runtime/networking-and-egress.md): An agent reaches the network only through Agent Substrate’s egress gateway, and the gateway … ## Setup - [Install kagent](https://kagent.dev/docs/kagent/1.x/setup/installation.md): kagent 1.0 runs every agent on Agent Substrate, so an installation sets up two systems in the same … - [Serve the UI under a sub-path](https://kagent.dev/docs/kagent/1.x/setup/reverse-proxy.md): The kagent UI is a static bundle served by nginx, which answers on port 8080 inside the pod. By … ### Configure model providers - [About model providers](https://kagent.dev/docs/kagent/1.x/setup/model-providers/about-model-providers.md): A ModelConfig is a Kubernetes custom resource that names one model at one provider, along with the … - [OpenAI](https://kagent.dev/docs/kagent/1.x/setup/model-providers/openai.md): The OpenAI provider calls the OpenAI API directly. Note This provider works on the kagent, byo, and … - [agentgateway](https://kagent.dev/docs/kagent/1.x/setup/model-providers/byo-agentgateway.md): agentgateway is an AI-native proxy that adds traffic management, observability, and security to … - [Amazon Bedrock](https://kagent.dev/docs/kagent/1.x/setup/model-providers/amazon-bedrock.md): Amazon Bedrock serves models from several families behind one AWS API. kagent reaches it two ways: … - [Anthropic](https://kagent.dev/docs/kagent/1.x/setup/model-providers/anthropic.md): The Anthropic provider calls the Anthropic API directly. Note This provider works on the kagent, … - [Azure AI Foundry](https://kagent.dev/docs/kagent/1.x/setup/model-providers/azure-ai-foundry.md): The Foundry provider calls a model deployment in an Azure AI Foundry resource. The chat model must … - [Azure OpenAI](https://kagent.dev/docs/kagent/1.x/setup/model-providers/azure-openai.md): The AzureOpenAI provider calls an Azure OpenAI deployment. It differs from the OpenAI provider in … - [Gemini](https://kagent.dev/docs/kagent/1.x/setup/model-providers/gemini.md): The Gemini provider reaches Google’s Gemini models through the Google AI Studio API, … - [Google Vertex AI](https://kagent.dev/docs/kagent/1.x/setup/model-providers/google-vertexai.md): Neither Vertex AI provider runs on kagent 1.0. AnthropicVertexAI and GeminiVertexAI both … - [Ollama](https://kagent.dev/docs/kagent/1.x/setup/model-providers/ollama.md): Ollama runs large language models on hardware that you control. The Ollama provider points kagent at … - [SAP AI Core](https://kagent.dev/docs/kagent/1.x/setup/model-providers/sap-ai-core.md): The SAPAICore provider does not run on kagent 1.0. SAP AI Core authenticates with OAuth2 client … - [xAI](https://kagent.dev/docs/kagent/1.x/setup/model-providers/xai.md): xAI’s Grok models are served through an OpenAI-compatible API, so a ModelConfigModelConfigA … - [BYO OpenAI-compatible endpoint](https://kagent.dev/docs/kagent/1.x/setup/model-providers/byo-openai.md): Many providers serve the OpenAI API rather than an API of their own. To use one, set provider: … ## Agents - [Agent harness](https://kagent.dev/docs/kagent/1.x/agents/agent-harness.md): A Harness defines how an agent is allowed to run. It names what executes the agent, the container … - [Declarative agents](https://kagent.dev/docs/kagent/1.x/agents/declarative-agents.md): A declarative agent is an agent that you describe rather than build. In an … - [Bring your own agent](https://kagent.dev/docs/kagent/1.x/agents/bring-your-own-agent.md): The byo harness runs a container image that you build, and treats what is inside it as opaque. … - [System prompts](https://kagent.dev/docs/kagent/1.x/agents/system-prompts.md): An AgentTemplateAgentTemplateA Kubernetes custom resource defining what an agent does: its model, … - [Structured output](https://kagent.dev/docs/kagent/1.x/agents/structured-output.md): An AgentTemplateAgentTemplateA Kubernetes custom resource defining what an agent does: its model, … - [Context management](https://kagent.dev/docs/kagent/1.x/agents/context-management.md): An agent’s prompt grows with the conversation: every message, tool call, and tool result … - [Agent memory](https://kagent.dev/docs/kagent/1.x/agents/agent-memory.md): A SessionSessionA running conversation with one Agent. Unlike the resources it is built from, a … - [Human in the loop](https://kagent.dev/docs/kagent/1.x/agents/human-in-the-loop.md): Some agents only answer questions, and those can run unattended. Others call tools that change a … - [Egress policies](https://kagent.dev/docs/kagent/1.x/agents/egress-policies.md): An AgentAgentA Kubernetes custom resource that pairs one AgentTemplate with one Harness. Each side … ## Skills and MCP - [About tools](https://kagent.dev/docs/kagent/1.x/skills-and-mcp/about-tools.md): An AgentTemplateAgentTemplateA Kubernetes custom resource defining what an agent does: its model, … - [Skills](https://kagent.dev/docs/kagent/1.x/skills-and-mcp/skills.md): A skillSkillA packaged piece of know-how that an agent can pick up: a directory holding a SKILL.md … - [Plugins](https://kagent.dev/docs/kagent/1.x/skills-and-mcp/plugins.md): A pluginPluginA bundle that an AgentTemplate attaches with spec.plugins. A plugin contains skills … ## Observability - [Launch the UI](https://kagent.dev/docs/kagent/1.x/observability/launch-ui.md): The kagent UI is a read-and-write console for everything the controller knows about: the agents you … - [OTel stack](https://kagent.dev/docs/kagent/1.x/observability/otel-stack.md): Deploy an open source observability stack based on OpenTelemetry (OTel) that collects telemetry from … - [Lightweight OTel stack](https://kagent.dev/docs/kagent/1.x/observability/lightweight-otel-stack.md): Deploy a small observability stack based on OpenTelemetry (OTel) that collects traces and metrics … - [Tracing](https://kagent.dev/docs/kagent/1.x/observability/tracing.md): A trace records one agent request as a tree of timed spans, so you can see where a slow or failed … - [Metrics](https://kagent.dev/docs/kagent/1.x/observability/metrics.md): kagent and Agent Substrate report metrics in two different ways. The kagent controller serves a … - [Agent Substrate telemetry](https://kagent.dev/docs/kagent/1.x/observability/substrate-telemetry.md): Every kagent agent runs as an ActorActorThe sandboxed unit of compute, provided by Agent Substrate, … - [Audit prompts](https://kagent.dev/docs/kagent/1.x/observability/audit-prompts.md): Audit the prompts (inputs) and replies (outputs) that pass between your agents and their models. … ## Examples - [Agent Substrate](https://kagent.dev/docs/kagent/1.x/examples/agent-substrate.md): Agent Substrate runs every agent as an Actor: a sandboxed unit of compute that holds a WorkerWorkerA … - [Use agents from an MCP client](https://kagent.dev/docs/kagent/1.x/examples/agents-via-mcp.md): The kagent controller runs a Model Context ProtocolModel Context ProtocolAn open protocol for … - [Call an agent over A2A](https://kagent.dev/docs/kagent/1.x/examples/a2a-agents.md): Every AgentAgentA Kubernetes custom resource that pairs one AgentTemplate with one Harness. Each … - [Add a skill to an agent](https://kagent.dev/docs/kagent/1.x/examples/skills.md): A skillSkillA packaged piece of know-how that an agent can pick up: a directory holding a SKILL.md … - [Delegate work to another agent](https://kagent.dev/docs/kagent/1.x/examples/agent-delegation.md): An AgentTemplateAgentTemplateA Kubernetes custom resource defining what an agent does: its model, … - [Build a documentation agent](https://kagent.dev/docs/kagent/1.x/examples/documentation-agent.md): An agent answers from its model unless you give it a source, such as in a vector database. This … - [Run your own agent image](https://kagent.dev/docs/kagent/1.x/examples/a2a-byo.md): The byo runtime runs a container image that you build, so long as the image implements … - [Block PII in an agent's model requests](https://kagent.dev/docs/kagent/1.x/examples/agentgateway.md): An agent sends every turn of a conversation to a model provider, and each of those requests carries … ## Operations - [Operational considerations](https://kagent.dev/docs/kagent/1.x/operations/operational-considerations.md): A default kagent installation runs one controller replica against the development database that … - [Tune Agent Substrate](https://kagent.dev/docs/kagent/1.x/operations/tune-agent-substrate.md): kagent runs every agent on Agent Substrate. A default installation creates one WorkerPoolWorkerPoolA … - [Debug](https://kagent.dev/docs/kagent/1.x/operations/debug.md): Most kagent failures surface in one place: the readiness conditions on the AgentAgentA Kubernetes … - [Upgrade from 0.x](https://kagent.dev/docs/kagent/1.x/operations/upgrade-from-0x.md): kagent 1.0 has no in-place upgrade path from the 0.10.x line. Moving to 1.0 means installing kagent … - [Uninstall](https://kagent.dev/docs/kagent/1.x/operations/uninstall.md): The kagent uninstall command removes everything that kagent install created. That includes the … ## Reference - [API reference](https://kagent.dev/docs/kagent/1.x/reference/api-ref.md): Packages api.kagent.dev/v1alpha3 api.kagent.dev/v1alpha3 Package v1alpha3 contains API Schema … - [Helm reference](https://kagent.dev/docs/kagent/1.x/reference/helm.md): A Helm chart for kagent, built with Google ADK Requirements Repository Name Version … - [Environment variables](https://kagent.dev/docs/kagent/1.x/reference/env-vars.md): Review the environment variables that a kagent installation reads, grouped by the component that … - [Tools ecosystem](https://kagent.dev/docs/kagent/1.x/reference/tools-ecosystem.md): A kagent installation ships with two Model Context ProtocolModel Context ProtocolAn open protocol … - [Frequently asked questions](https://kagent.dev/docs/kagent/1.x/reference/faq.md): How do I get started with kagent? Install kagent first, with a WorkerPoolWorkerPoolA Kubernetes … - [Version support](https://kagent.dev/docs/kagent/1.x/reference/versions.md): Only the latest kagent release is supported. The versions on this page apply to that release. What a … - [Community and contributing](https://kagent.dev/docs/kagent/1.x/reference/community.md): kagent is developed in the open. Use the following links to follow the project, ask questions, and … - [Glossary](https://kagent.dev/docs/kagent/1.x/reference/glossary.md): kagent 1.0 introduces vocabulary that the rest of these docs use without re-explaining: the … ### CLI docs - [kagent agent](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-agent.md): Discover agents and work with their conversations kagent agent [command] Subcommands: kagent agent … - [kagent agent get](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-agent-get.md): Get an Agent kagent agent get NAME [flags] Flags: -h, --help - help for get Global Flags: --api-url … - [kagent agent invoke](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-agent-invoke.md): Invoke an existing Session through the A2A API. kagent agent invoke [flags] Flags: -f, --file string … - [kagent agent list](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-agent-list.md): List Agents kagent agent list [flags] Flags: -h, --help - help for list --page-size int - Number of … - [kagent agent session](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-agent-session.md): Manage agent conversations kagent agent session [command] Subcommands: kagent agent session create - … - [kagent agent session create](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-agent-session-create.md): Create a Session kagent agent session create [flags] Flags: --agent string - Agent name -h, --help - … - [kagent agent session delete](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-agent-session-delete.md): Delete a Session kagent agent session delete ID [flags] Flags: -h, --help - help for delete Global … - [kagent agent session get](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-agent-session-get.md): Get a Session kagent agent session get ID [flags] Flags: -h, --help - help for get Global Flags: … - [kagent agent session list](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-agent-session-list.md): List your Sessions kagent agent session list [flags] Flags: -h, --help - help for list --page-size … - [kagent agent session push](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-agent-session-push.md): Manage A2A task push callbacks kagent agent session push [command] Subcommands: kagent agent session … - [kagent agent session push create](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-agent-session-push-create.md): Add or replace a task callback kagent agent session push create SESSION_ID TASK_ID [flags] Flags: … - [kagent agent session push delete](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-agent-session-push-delete.md): Remove a task callback kagent agent session push delete SESSION_ID TASK_ID CONFIG_ID [flags] Flags: … - [kagent agent session push get](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-agent-session-push-get.md): Get a task callback kagent agent session push get SESSION_ID TASK_ID CONFIG_ID [flags] Flags: -h, … - [kagent agent session push list](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-agent-session-push-list.md): List active task callbacks kagent agent session push list SESSION_ID TASK_ID [flags] Flags: -h, … - [kagent agent template](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-agent-template.md): Discover reusable agent templates kagent agent template [command] Subcommands: kagent agent template … - [kagent agent template get](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-agent-template-get.md): Get an AgentTemplate kagent agent template get NAME [flags] Flags: -h, --help - help for get Global … - [kagent agent template list](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-agent-template-list.md): List AgentTemplates kagent agent template list [flags] Flags: -h, --help - help for list --page-size … - [kagent apply](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-apply.md): Create or update an Agent or AgentTemplate kagent apply -f FILE [flags] Flags: -f, --file string - … - [kagent bug-report](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-bug-report.md): Generate a bug report kagent bug-report [flags] Flags: -h, --help - help for bug-report Global … - [kagent completion](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-completion.md): Generate the autocompletion script for kagent for the specified shell. See each sub-command’s … - [kagent completion bash](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-completion-bash.md): Generate the autocompletion script for the bash shell. This script depends on the … - [kagent completion fish](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-completion-fish.md): Generate the autocompletion script for the fish shell. To load completions in your current shell … - [kagent completion powershell](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-completion-powershell.md): Generate the autocompletion script for powershell. To load completions in your current shell … - [kagent completion zsh](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-completion-zsh.md): Generate the autocompletion script for the zsh shell. If shell completion is not already enabled in … - [kagent config](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-config.md): Inspect and validate configuration kagent config [command] Subcommands: kagent config schema - Print … - [kagent config schema](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-config-schema.md): Print the protobuf descriptor set, including validation rules kagent config schema [flags] Flags: … - [kagent config validate](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-config-validate.md): Validate configuration without connecting to services kagent config validate [flags] Flags: -h, … - [kagent config view](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-config-view.md): Print effective configuration without expanding secret files kagent config view [flags] Flags: -h, … - [kagent dashboard](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-dashboard.md): Open the kagent dashboard kagent dashboard [flags] Flags: -h, --help - help for dashboard Global … - [kagent db](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-db.md): Database operations (migrations, inspection) kagent db [command] Subcommands: kagent db migrate - … - [kagent db migrate](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-db-migrate.md): Apply, roll back, and inspect database migrations. Migrations run as the owner login. Connection … - [kagent db migrate down](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-db-migrate-down.md): Roll back the latest N migrations. A down migration can delete data. kagent db migrate down N … - [kagent db migrate goto](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-db-migrate-goto.md): Move one source to version V. Version zero removes its schema. kagent db migrate goto V [flags] … - [kagent db migrate status](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-db-migrate-status.md): Show migration status kagent db migrate status [flags] Flags: -h, --help - help for status --output … - [kagent db migrate up](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-db-migrate-up.md): Apply all pending migrations kagent db migrate up [flags] Flags: -h, --help - help for up Global … - [kagent db migrate version](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-db-migrate-version.md): Show the applied migration version kagent db migrate version [flags] Flags: -h, --help - help for … - [kagent install](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-install.md): Install kagent kagent install [flags] Flags: -h, --help - help for install --profile string - … - [kagent sandbox](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-sandbox.md): Run commands and transfer files in standalone sandboxes kagent sandbox [command] Subcommands: kagent … - [kagent sandbox create](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-sandbox-create.md): Create a sandbox. Retain –request-id and all inputs for retries; each call makes one lifecycle … - [kagent sandbox delete](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-sandbox-delete.md): Inspect or change sandbox lifecycle. Mutations make one attempt; retry the same mutation on … - [kagent sandbox download](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-sandbox-download.md): Download a file, replacing the local destination only after success kagent sandbox download ID … - [kagent sandbox exec](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-sandbox-exec.md): Start a process once. By default, stream available output while waiting. A timeout stops waiting, … - [kagent sandbox get](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-sandbox-get.md): Inspect or change sandbox lifecycle. Mutations make one attempt; retry the same mutation on … - [kagent sandbox kill](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-sandbox-kill.md): Terminate a process and its children kagent sandbox kill ID PROCESS_ID [flags] Flags: -h, --help - … - [kagent sandbox list](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-sandbox-list.md): List your sandboxes kagent sandbox list [flags] Flags: -h, --help - help for list --page-size int32 … - [kagent sandbox process](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-sandbox-process.md): Inspect process status without waiting kagent sandbox process ID PROCESS_ID [flags] Flags: -h, … - [kagent sandbox resume](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-sandbox-resume.md): Inspect or change sandbox lifecycle. Mutations make one attempt; retry the same mutation on … - [kagent sandbox suspend](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-sandbox-suspend.md): Inspect or change sandbox lifecycle. Mutations make one attempt; retry the same mutation on … - [kagent sandbox templates](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-sandbox-templates.md): List SandboxTemplates in the selected namespace kagent sandbox templates [flags] Flags: -h, --help - … - [kagent sandbox upload](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-sandbox-upload.md): Stream a local file into a sandbox (replaces the remote file) kagent sandbox upload ID LOCAL_FILE … - [kagent sandbox wait](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-sandbox-wait.md): Collect output and wait for an existing process without restarting it kagent sandbox wait ID … - [kagent uninstall](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-uninstall.md): Uninstall kagent kagent uninstall [flags] Flags: -h, --help - help for uninstall Global Flags: … - [kagent version](https://kagent.dev/docs/kagent/1.x/reference/cli/kagent-version.md): Print the kagent version kagent version [flags] Flags: -h, --help - help for version Global Flags: … ### Release notes - [1.0](https://kagent.dev/docs/kagent/1.x/reference/release-notes/1.0.md): Each section covers one patch release in the kagent 1.0 line, newest first. For the commit-level … --- Generated on 2026-10-23 16:47:13 UTC