kagent 是一个用于构建 AI 代理的 Kubernetes 原生框架。Kubernetes 是运行工作负载最流行的编排平台，而 kagent 则让在 Kubernetes 中构建、部署和管理 AI 代理变得轻而易举。kagent 框架旨在易于理解与使用，并提供一种灵活而强大的方式来构建和管理 AI 代理。

入门指南

• 快速入门
• 安装指南

技术细节

核心概念

• 代理（Agents）：代理是 kagent 的主要构建模块。它们由系统提示、一组工具和代理，以及用名为“Agent”的 Kubernetes 自定义资源表示的 LLM 配置组成。
• LLM 提供者：kagent 支持多种 LLM 提供者，包括 OpenAI、Azure OpenAI、Anthropic、Google Vertex AI、Ollama，以及任何可通过 AI 网关访问的其他 自定义提供商和模型。提供商由 ModelConfig 资源表示。
• MCP 工具：代理可以连接到任何提供工具的 MCP 服务器。kagent 自带一个 MCP 服务器，其中包含适用于 Kubernetes、Istio、Helm、Argo、Prometheus、Grafana、Cilium 等的工具。所有工具都是 Kubernetes 自定义资源（ToolServers），可供多个代理使用。
• 可观测性：kagent 支持 OpenTelemetry 跟踪，使您能够监控代理和工具的运行情况。

核心原则

• Kubernetes 原生：kagent 旨在易于理解与使用，并提供一种灵活而强大的方式来构建和管理 AI 代理。
• 可扩展性：kagent 设计为可扩展的，因此您可以添加自己的代理和工具。
• 灵活性：kagent 设计为灵活的，以适应任何 AI 代理用例。
• 可观测性：kagent 设计为可观测的，因此您可以使用所有常见的监控框架来监控代理和工具。
• 声明式：kagent 设计为声明式的，因此您可以在 YAML 文件中定义代理和工具。
• 可测试性：kagent 设计为易于测试和调试的。这一点对于 AI 代理应用尤为重要。

架构

kagent 框架旨在易于理解与使用，并提供一种灵活而强大的方式来构建和管理 AI 代理。

kagent 具有 4 个核心组件：

• 控制器：控制器是一个 Kubernetes 控制器，它监视 kagent 自定义资源，并创建运行代理所需的必要资源。
• UI：UI 是一个 Web 界面，允许您管理代理和工具。
• 引擎：引擎使用 ADK 运行您的代理。
• CLI：CLI 是一个命令行工具，让您能够管理代理和工具。

参与贡献

我们欢迎各位贡献！请遵守 kagent 行为准则

有许多方式可以参与贡献：

• 🐛 报告错误和问题
• 💡 建议新功能
• 📖 改进文档
• 🔧 提交拉取请求
• ⭐ 星标仓库
• 💬 在 Discord 上帮助他人
• 💬 参加 kagent 社区会议
• 🤝 在 CNCF #kagent Slack 频道分享技巧
• 🔒 报告安全问题

路线图

kagent 目前正处于积极开发中。您可以在项目的看板上查看完整路线图 这里。

本地开发

有关如何在本地运行所有内容的说明，请参阅 DEVELOPMENT.md 文件。

贡献者

感谢所有帮助使 kagent 更加完善的贡献者。

星标历史

参考

许可证

本项目采用 Apache 2.0 许可证。

kagent 是一个 云原生计算基金会 项目。

kagent 快速上手指南

kagent 是一个原生支持 Kubernetes 的 AI Agent 构建框架。它允许你通过声明式的 YAML 文件在 Kubernetes 集群中轻松构建、部署和管理 AI Agent，并支持连接多种大模型提供商及 MCP 工具服务器。

1. 环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows (WSL2)
• Kubernetes 集群: 需要一个正在运行的 Kubernetes 集群 (版本 1.25+)。
  • 本地开发推荐使用 kind, minikube 或 Docker Desktop 自带的 K8s。
• kubectl: 已安装并配置好连接到你的集群。
• Helm (可选但推荐): 用于简化安装过程 (版本 3.0+)。
• API Keys: 准备好你所使用的大模型提供商的 API Key (如 OpenAI, Azure OpenAI, Anthropic, Google Vertex AI 或本地 Ollama)。

2. 安装步骤

你可以通过 Helm 或直接应用 YAML 清单来安装 kagent。以下是使用 Helm 的标准安装流程：

添加 Helm 仓库

helm repo add kagent https://kagent-dev.github.io/kagent-helm-charts
helm repo update

安装 kagent

在目标命名空间（例如 kagent-system）中安装 kagent：

kubectl create namespace kagent-system --dry-run=client -o yaml | kubectl apply -f -

helm install kagent kagent/kagent \
  --namespace kagent-system \
  --create-namespace

验证安装

等待所有 Pod 运行正常：

kubectl get pods -n kagent-system

当看到 kagent-controller, kagent-ui, kagent-engine 等 Pod 状态为 Running 时，表示安装成功。

访问 UI 界面

可以通过端口转发访问 kagent 的 Web 管理界面：

kubectl port-forward svc/kagent-ui -n kagent-system 8080:80

然后在浏览器中打开 http://localhost:8080。

3. 基本使用

kagent 的核心是通过 Kubernetes 自定义资源 (CRD) 来定义 Agent。以下是一个最简单的示例，展示如何创建一个连接到 OpenAI 的 Agent。

第一步：配置模型凭证 (Secret)

首先，将你的 LLM API Key 存储为 Kubernetes Secret：

kubectl create secret generic openai-secret \
  --from-literal=apiKey="YOUR_OPENAI_API_KEY" \
  -n default

第二步：定义模型配置 (ModelConfig)

创建一个 ModelConfig 资源来指定使用的模型提供商和模型名称。创建文件 model-config.yaml：

apiVersion: kagent.dev/v1alpha1
kind: ModelConfig
metadata:
  name: openai-gpt4
  namespace: default
spec:
  provider: OpenAI
  model: gpt-4o
  apiKeySecretRef:
    name: openai-secret
    key: apiKey

应用配置：

kubectl apply -f model-config.yaml

第三步：定义 Agent

创建一个 Agent 资源，绑定上述模型配置并设定系统提示词。创建文件 my-agent.yaml：

apiVersion: kagent.dev/v1alpha1
kind: Agent
metadata:
  name: hello-world-agent
  namespace: default
spec:
  description: "A simple agent that says hello."
  modelConfigRef:
    name: openai-gpt4
  systemPrompt: "You are a helpful assistant. Keep your responses short and friendly."
  tools: [] # 此处可添加 MCP 工具引用

应用 Agent 配置：

kubectl apply -f my-agent.yaml

第四步：与 Agent 交互

配置完成后，你可以通过以下方式与 Agent 交互：

1. 通过 UI: 在之前打开的 Web 界面 (http://localhost:8080) 中找到 hello-world-agent 并进行对话测试。
2. 通过 CLI: 如果你安装了 kagent CLI 工具，可以使用命令行发送消息。
3. 通过 API: 直接调用 kagent 暴露的服务端点。

现在，你已经成功在 Kubernetes 上运行了一个基本的 AI Agent。接下来你可以尝试添加 MCP 工具（如 Kubernetes 管理工具、Prometheus 查询工具等）来增强 Agent 的能力。