❝本文档阐述 Kagent 的云原生设计理念——将 Agent 定义为 Kubernetes CRD,使其成为集群的一等公民❞
「Kagent 的核心理念可以用一句话概括:Agent 应该像 Deployment、Service 一样,成为 Kubernetes 的一等公民。」
这不是简单地"把 Agent 跑在 K8s 上",而是深度融入 Kubernetes 的资源模型,让 Agent 天然具备云原生基础设施的所有能力。
传统 Agent 框架 Kagent
┌─────────────────┐ ┌─────────────────┐
│ Agent 平台 │ │ Kubernetes │
│ ┌───────────┐ │ │ ┌───────────┐ │
│ │ 调度系统 │ │ │ │ Scheduler │ │ ← 复用
│ ├───────────┤ │ │ ├───────────┤ │
│ │ 配置管理 │ │ → │ │ ConfigMap │ │ ← 复用
│ ├───────────┤ │ │ ├───────────┤ │
│ │ 权限控制 │ │ │ │ RBAC │ │ ← 复用
│ ├───────────┤ │ │ ├───────────┤ │
│ │ 监控告警 │ │ │ │Prometheus │ │ ← 复用
│ └───────────┘ │ │ └───────────┘ │
│ 自建轮子 ❌ │ │ 站在巨人肩上 ✅ │
└─────────────────┘ └─────────────────┘
「Kagent」 是一个 Kubernetes 原生的 AI Agent 框架,它将 Agent 定义为 Kubernetes CRD(Custom Resource Definition),让用户可以像管理 Deployment 一样管理 Agent。
「核心特性」:
特性 | 说明 | 价值 |
|---|---|---|
「CRD 定义」 | Agent 是 K8s 自定义资源 | 声明式管理,GitOps 友好 |
「Controller 模式」 | 自动协调期望状态与实际状态 | 自愈、自动化运维 |
「多租户隔离」 | Namespace + RBAC | 企业级安全隔离 |
「MCP 工具协议」 | 标准化工具接入 | 生态可扩展 |
「多 LLM 支持」 | OpenAI/Anthropic/Ollama 等 | 厂商中立 |
「可观测性」 | OpenTelemetry + Prometheus | 生产级监控 |
Kagent 将 Agent 定义为 Kubernetes CRD,直接复用 Kubernetes 十年积累的基础设施能力。
Kubernetes 已经解决了分布式系统中最难的问题:调度、扩缩容、服务发现、配置管理、权限控制、故障恢复。Agent 作为 CRD 可以直接继承这些能力:
能力 | CRD 方案 | 收益 |
|---|---|---|
调度与编排 | Scheduler 开箱即用 | 零开发成本 |
自动扩缩容 | HPA/VPA 原生支持 | 弹性伸缩 |
配置管理 | ConfigMap/Secret | 安全可审计 |
权限控制 | RBAC 原生支持 | 企业级安全 |
服务发现 | Service/DNS | 自动注册 |
故障恢复 | Controller 自动协调 | 秒级自愈 |
监控告警 | Prometheus 生态 | 开箱即用 |
日志采集 | ELK/Loki 自动采集 | 统一管理 |
# 声明式:描述期望状态(Kagent 方式)
apiVersion:kagent.dev/v1alpha2
kind:Agent
metadata:
name:k8s-assistant
spec:
declarative:
systemMessage:"你是 Kubernetes 专家"
modelConfig:"gpt-4-config"
tools:
-type:McpServer
mcpServer:
name:"k8s-toolserver"
# 命令式:告诉系统如何操作(传统方式)
curl -X POST /api/agents \
-d '{"name": "k8s-assistant", "model": "gpt-4", ...}'
curl -X PUT /api/agents/k8s-assistant/tools \
-d '{"tools": [...]}'
curl -X POST /api/agents/k8s-assistant/deploy
CRD 声明式配置带来的收益:
维度 | 效果 |
|---|---|
「幂等性」 | 重复 apply 无副作用 |
「版本控制」 | YAML 直接入 Git |
「状态一致性」 | Controller 持续协调,无状态漂移 |
「审计追踪」 | kubectl 操作记录 + etcd 历史 |
「回滚能力」 | Git revert + kubectl apply |
Agent 定义作为 YAML 文件,天然支持 GitOps 工作流:
┌─────────────────────────────────────────────────────────┐
│ GitOps 工作流 │
└─────────────────────────────────────────────────────────┘
Git Repository Kubernetes Cluster
┌──────────────┐ ┌──────────────────┐
│ agents/ │ │ │
│ ├── dev/ │ ArgoCD/ │ ┌────────────┐ │
│ │ └── *.yaml│ Flux │ │ Agent CRD │ │
│ ├── staging/ │ ──────────→ │ └────────────┘ │
│ │ └── *.yaml│ 自动同步 │ ↓ │
│ └── prod/ │ │ ┌────────────┐ │
│ └── *.yaml│ │ │ Controller │ │
└──────────────┘ │ └────────────┘ │
↑ │ ↓ │
PR Review │ ┌────────────┐ │
版本控制 │ │ Agent Pod │ │
变更审计 │ └────────────┘ │
└──────────────────┘
git revert + 自动同步即可恢复Agent 作为 CRD 资源,直接复用 Kubernetes 的多租户隔离机制:
┌─────────────────────────────────────────────────────────┐
│ Kubernetes 多租户模型 │
└─────────────────────────────────────────────────────────┘
Cluster
┌─────────────────────────────────────────────────────────┐
│ Namespace: team-a Namespace: team-b │
│ ┌───────────────────┐ ┌───────────────────┐ │
│ │ Agent: assistant │ │ Agent: assistant │ │ ← 同名不冲突
│ │ Agent: analyzer │ │ Agent: reviewer │ │
│ │ Secret: api-key │ │ Secret: api-key │ │ ← 数据隔离
│ │ ResourceQuota: │ │ ResourceQuota: │ │
│ │ cpu: 4, mem: 8G │ │ cpu: 8, mem: 16G│ │ ← 资源隔离
│ └───────────────────┘ └───────────────────┘ │
│ ↓ ↓ │
│ RBAC: team-a-users RBAC: team-b-users │ ← 权限隔离
│ 只能操作 team-a 资源 只能操作 team-b 资源 │
└─────────────────────────────────────────────────────────┘
隔离维度 | K8s 机制 | 效果 |
|---|---|---|
「命名空间」 | Namespace | 资源逻辑隔离 |
「权限控制」 | RBAC | 操作权限隔离 |
「资源配额」 | ResourceQuota | 资源用量隔离 |
「网络策略」 | NetworkPolicy | 网络流量隔离 |
「密钥管理」 | Secret | 敏感数据隔离 |
CRD 配合 Controller 模式,Agent 具备自动故障恢复能力:
┌─────────────────────────────────────────────────────────┐
│ Controller 自动协调循环 │
└─────────────────────────────────────────────────────────┘
期望状态 (Agent CRD) 实际状态 (K8s 资源)
┌─────────────────┐ ┌─────────────────┐
│ replicas: 3 │ │ Running Pods: 3 │
│ image: v1.2 │ │ Image: v1.2 │
│ tools: [a,b,c] │ │ ConfigMap: OK │
└────────┬────────┘ └────────┬────────┘
│ │
│ Controller │
│ ┌─────────────────┐ │
└───→│ Reconcile() │←────────┘
│ │
│ 比较差异 │
│ 执行修复 │
│ 持续监控 │
└─────────────────┘
│
┌────────────┼────────────┐
↓ ↓ ↓
Pod 崩溃 配置变更 节点故障
自动重启 自动更新 自动迁移
故障场景 | Controller 行为 | 恢复时间 |
|---|---|---|
Agent Pod 崩溃 | 自动重启 Pod | 秒级 |
节点故障 | 自动迁移到健康节点 | 分钟级 |
配置被误删 | 自动重建 ConfigMap/Secret | 秒级 |
镜像版本不一致 | 自动滚动更新 | 分钟级 |
Agent Pod 自动接入 Kubernetes 可观测性生态:
┌─────────────────────────────────────────────────────────┐
│ 云原生可观测性栈 │
└─────────────────────────────────────────────────────────┘
Agent Pod
┌─────────┐
│ kagent │
│ -adk │
└────┬────┘
│
┌──────────────┼──────────────┐
│ │ │
↓ ↓ ↓
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Traces │ │ Metrics │ │ Logs │
│ │ │ │ │ │
│ Jaeger │ │Prometheu│ │ Loki │
│ Tempo │ │Grafana │ │ ELK │
└─────────┘ └─────────┘ └─────────┘
│ │ │
└──────────────┼──────────────┘
↓
┌─────────────┐
│ Grafana │
│ Dashboard │
└─────────────┘
维度 | CRD 带来的能力 |
|---|---|
「资源模型」 | Kubernetes 原生资源,统一管理 |
「配置方式」 | 声明式 YAML,GitOps 友好 |
「状态管理」 | Controller 自动协调,持续保证期望状态 |
「多租户」 | Namespace + RBAC,企业级隔离 |
「高可用」 | Deployment + ReplicaSet,自动故障转移 |
「监控」 | Prometheus 生态,开箱即用 |
「运维工具」 | kubectl + 生态工具,零学习成本 |
┌─────────────────────────────────────────────────────────────────┐
│ Kagent 架构 │
└─────────────────────────────────────────────────────────────────┘
用户/系统
│
┌───────────────┼───────────────┐
↓ ↓ ↓
┌────────┐ ┌────────┐ ┌────────┐
│ CLI │ │ UI │ │kubectl │
└────┬───┘ └────┬───┘ └────┬───┘
│ │ │
└───────────────┼───────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ Kubernetes API Server │
└─────────────────────────────────────────────────────────────────┘
│
┌──────────────────┼──────────────────┐
↓ ↓
┌─────────────────┐ ┌─────────────────────────┐
│ Controller │ │ Agent Pods │
│ ┌───────────┐ │ │ ┌─────────────────┐ │
│ │ Reconcile │ │ ──创建管理───→ │ │ kagent-adk │ │
│ │ Loop │ │ │ │ (Python Runtime)│ │
│ └───────────┘ │ │ └────────┬────────┘ │
└─────────────────┘ │ │ │
│ ↓ │
│ ┌─────────────────┐ │
│ │ Google ADK │ │
│ │ Agent Engine │ │
│ └────────┬────────┘ │
│ │ │
└───────────┼─────────────┘
│
┌───────────────────────┼───────────────────────┐
↓ ↓ ↓
┌────────────┐ ┌────────────┐ ┌────────────┐
│ LLM 服务 │ │ MCP Server │ │ 其他 Agent │
│ OpenAI/... │ │ (工具服务) │ │ (A2A 协议) │
└────────────┘ └────────────┘ └────────────┘
「四大核心组件」:
组件 | 职责 | 技术栈 |
|---|---|---|
「Controller」 | 监听 Agent CRD,协调资源状态 | Go + controller-runtime |
「Engine (kagent-adk)」 | Agent 运行时,执行对话循环 | Python + Google ADK |
「UI」 | 可视化管理界面 | React |
「CLI」 | 命令行工具 | Go |
┌─────────────────────────────────────────────────────────────────┐
│ Kagent CRD 资源体系 │
└─────────────────────────────────────────────────────────────────┘
Agent CRD
│
┌────────────────┼────────────────┐
↓ ↓ ↓
┌───────────┐ ┌────────────┐ ┌────────────┐
│ModelConfig│ │ MCPServer │ │ Agent │
│ CRD │ │ CRD │ │ CRD │
│ │ │ │ │ (as Tool) │
│ 模型配置 │ │ 工具服务 │ │ Agent 嵌套 │
└───────────┘ └────────────┘ └────────────┘
│ │ │
└────────────────┼────────────────┘
↓
Controller 解析
↓
┌─────────────┴─────────────┐
↓ ↓
┌─────────┐ ┌─────────────┐
│ Secret │ │ Deployment │
│config.json│ │ + Service │
│agent-card │ │ │
└─────────┘ └─────────────┘
Agent CRD 的设计遵循以下原则:
原则 | 体现 |
|---|---|
「配置驱动」 | Agent 行为完全由 YAML 配置决定 |
「关注点分离」 | 模型配置、工具配置、部署配置各自独立 |
「引用优于内联」 | 通过名称引用 ModelConfig、MCPServer |
「合理默认值」 | 大部分字段可选,有合理默认值 |
Kagent 支持两种 Agent 类型,满足不同场景:
类型 | 适用场景 | 镜像 |
|---|---|---|
「Declarative」 | 标准 Agent,配置驱动 | 默认 kagent-adk |
「BYO (Bring Your Own)」 | 自定义 Agent,完全控制 | 用户自定义镜像 |
「Declarative Agent」:
apiVersion: kagent.dev/v1alpha2
kind:Agent
metadata:
name:k8s-ops-agent
namespace:default
spec:
type:Declarative
description:"Kubernetes 运维助手"
declarative:
# 系统提示词:定义 Agent 角色
systemMessage:"你是一个 Kubernetes 专家,擅长集群管理和故障排查"
# 引用 ModelConfig CRD
modelConfig:"gpt-4-config"
# 响应配置
stream:false
executeCodeBlocks:false
# 工具配置:引用 MCPServer 或其他 Agent
tools:
-type:McpServer
mcpServer:
name:"k8s-toolserver"
toolNames:["list_pods","get_pod_logs","describe_pod"]
-type:Agent
agent:
name:"log-analyzer-agent"
# 部署配置
deployment:
replicas:2
resources:
requests:
cpu:"200m"
memory:"512Mi"
limits:
cpu:"1"
memory:"2Gi"
status:
observedGeneration:1
conditions:
-type:Accepted
status:"True"
-type:Ready
status:"True"
「BYO Agent」(自定义镜像):
apiVersion: kagent.dev/v1alpha2
kind:Agent
metadata:
name:custom-agent
spec:
type:BYO
byo:
deployment:
image:"myregistry.com/my-agent:v1.0"
cmd:"python"
args:["-m","my_agent.main"]
字段 | 类型 | 说明 |
|---|---|---|
systemMessage | string | 系统提示词,定义 Agent 角色和行为 |
modelConfig | string | 引用 ModelConfig CRD 名称 |
tools[].mcpServer | object | 引用 MCPServer CRD |
tools[].agent | object | 引用其他 Agent(Agent 嵌套) |
deployment | object | 副本数、资源限制等部署配置 |
当用户创建 Agent CRD 后,Controller 自动执行以下协调逻辑:
Agent CRD 创建/更新
│
↓
┌───────────────────────────────────────────────────┐
│ Controller Reconcile │
├───────────────────────────────────────────────────┤
│ 1. 解析 Agent CRD │
│ 2. 读取关联的 ModelConfig CRD │
│ 3. 读取关联的 MCPServer CRD │
│ 4. 生成 config.json 和 agent-card.json │
│ 5. 创建/更新 Secret(存储配置) │
│ 6. 创建/更新 Deployment │
│ 7. 创建/更新 Service │
│ 8. 更新 Agent Status │
└───────────────────────────────────────────────────┘
│
↓
生成的 Kubernetes 资源:
├── Secret (配置文件)
│ ├── config.json # Agent 运行时配置
│ └── agent-card.json # A2A 协议元数据
├── ServiceAccount
├── Deployment
│ └── Pod (kagent-adk 容器)
└── Service (暴露 8080 端口)
「kagent-adk」 是 Agent 的运行时镜像,基于 Google ADK 框架构建:
┌─────────────────────────────────────────────────────────────────┐
│ kagent-adk 运行时 │
└─────────────────────────────────────────────────────────────────┘
容器启动
↓
ENTRYPOINT: kagent-adk static --filepath=/config
↓
┌─────────────────────────────────────────────────────────────────┐
│ 1. 读取配置文件 │
│ /config/config.json → AgentConfig │
│ /config/agent-card.json → AgentCard │
│ │
│ 2. 构建 Agent 实例 │
│ AgentConfig.to_agent() │
│ ├── 创建 LLM 实例 (OpenAI/Anthropic/...) │
│ ├── 连接 MCP Server,加载工具 │
│ └── 配置远程 Agent (A2A 协议) │
│ │
│ 3. 构建 FastAPI 应用 │
│ KAgentApp.build() │
│ ├── POST /invoke → 同步调用 │
│ ├── POST /stream → 流式调用 │
│ └── GET /.well-known/agent-card → Agent 元数据 │
│ │
│ 4. 启动 HTTP 服务器 │
│ uvicorn.run(app, host="0.0.0.0", port=8080) │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ 工具加载流程 │
└─────────────────────────────────────────────────────────────────┘
Agent 启动
│
┌──────────────┼──────────────┐
↓ ↓ ↓
MCP 工具加载 远程 Agent 加载 技能包加载
│ │ │
↓ ↓ ↓
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 连接 MCP │ │ 读取 Agent │ │ 扫描 /skills │
│ Server │ │ Card │ │ 目录 │
├─────────────┤ ├─────────────┤ ├─────────────┤
│ 查询工具列表 │ │ 创建 Remote │ │ 加载工具 │
│ │ │ A2aAgent │ │ 定义 │
├─────────────┤ ├─────────────┤ ├─────────────┤
│ 按 filter │ │ 包装为 │ │ 注册到 │
│ 过滤工具 │ │ AgentTool │ │ Agent │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
└────────────────┼────────────────┘
↓
注册到 Agent.tools[]
从 Agent CRD YAML 到运行时 Agent 实例的完整转换链路:
┌─────────────────────────────────────────────────────────────────┐
│ 配置转换全流程 │
└─────────────────────────────────────────────────────────────────┘
Agent CRD (YAML)
│
↓
┌─────────────────────┐
│ Controller (Go) │
│ ┌───────────────┐ │
│ │ 解析 Agent │ │
│ │ 解析 ModelConfig│ │
│ │ 解析 MCPServer │ │
│ │ 生成 JSON 配置 │ │
│ └───────────────┘ │
└──────────┬──────────┘
│
↓
┌─────────────────────┐
│ Secret (配置存储) │
│ ├── config.json │
│ └── agent-card.json│
└──────────┬──────────┘
│
Volume 挂载到 /config
│
↓
┌─────────────────────┐
│ kagent-adk (Python)│
│ ┌───────────────┐ │
│ │ 读取 JSON │ │
│ │ 创建 LLM 实例 │ │
│ │ 连接 MCP Server│ │
│ │ 构建 Agent │ │
│ └───────────────┘ │
└──────────┬──────────┘
│
↓
Google ADK Agent 实例
「Agent CRD → config.json」:
Agent CRD 字段 | config.json 字段 | 转换说明 |
|---|---|---|
spec.description | description | 直接映射 |
spec.declarative.systemMessage | instruction | 直接映射 |
spec.declarative.modelConfig | model | 解析 ModelConfig CRD |
spec.declarative.stream | stream | 直接映射 |
spec.declarative.tools[].mcpServer | http_tools[] | 解析 MCPServer CRD |
spec.declarative.tools[].agent | remote_agents[] | 解析 Agent Service URL |
「ModelConfig CRD → config.json.model」:
type「输入:Agent CRD」
apiVersion: kagent.dev/v1alpha2
kind:Agent
metadata:
name:k8s-ops-agent
spec:
type:Declarative
description:"Kubernetes 运维助手"
declarative:
systemMessage:"你是一个 Kubernetes 专家"
modelConfig:"gpt-4-config"
tools:
-type:McpServer
mcpServer:
name:"k8s-toolserver"
toolNames:["list_pods","get_pod_logs"]
「中间产物:config.json」
{
"model": {
"type": "openai",
"model": "gpt-4o",
"base_url": "https://api.openai.com/v1",
"temperature": 0.7
},
"description": "Kubernetes 运维助手",
"instruction": "你是一个 Kubernetes 专家",
"http_tools": [{
"params": {
"url": "http://k8s-toolserver.default:8080/mcp"
},
"tools": ["list_pods", "get_pod_logs"]
}]
}
「最终产物:Agent 实例 (Python)」
Agent(
name="k8s_ops_agent",
model=OpenAINative(model="gpt-4o", base_url="..."),
instruction="你是一个 Kubernetes 专家",
tools=[
McpToolset(
url="http://k8s-toolserver.default:8080/mcp",
tool_filter=["list_pods", "get_pod_logs"]
)
]
)
用户通过 UI 向 k8s-agent 发送请求:"帮我查下这个集群是否有 pod 异常"
┌─────────────────────────────────────────────────────────────────┐
│ 完整请求流程 │
└─────────────────────────────────────────────────────────────────┘
用户 (UI)
│
│ POST /api/a2a/default/k8s-agent
│ {"task": "帮我查下这个集群是否有 pod 异常"}
↓
┌─────────────────┐
│ Controller │ ← 查找 Agent Service 地址
└────────┬────────┘
│
│ 转发请求
↓
┌─────────────────┐
│ Agent Pod │
│ (kagent-adk) │
└────────┬────────┘
│
│ 发送 Prompt
↓
┌─────────────────┐
│ LLM Provider │ ← 返回工具调用请求
│ (OpenAI) │ {"tool": "list_pods", ...}
└────────┬────────┘
│
│ Agent 执行工具调用
↓
┌─────────────────┐
│ MCP Server │ ← 执行 kubectl,返回 Pod 列表
│ (k8s-toolserver)│
└────────┬────────┘
│
│ 工具结果返回给 LLM
↓
┌─────────────────┐
│ LLM Provider │ ← 生成最终回复
│ (OpenAI) │
└────────┬────────┘
│
│ 响应返回
↓
用户 (UI) ← "发现 1 个异常 Pod:redis-2 处于 CrashLoopBackOff 状态..."
协议 | 用途 | 说明 |
|---|---|---|
「A2A」 | Agent 间通信 | Google 的 Agent-to-Agent 协议 |
「MCP」 | 工具调用 | Anthropic 的 Model Context Protocol |
设计决策 | 带来的能力 |
|---|---|
「CRD 资源模型」 | 复用 K8s 十年积累的基础设施能力 |
「声明式配置」 | GitOps 友好,状态自动协调 |
「Controller 模式」 | 自愈能力,持续保证期望状态 |
「Namespace 隔离」 | 企业级多租户安全隔离 |
「Prometheus 集成」 | 开箱即用的可观测性 |
┌─────────────────────────────────────────────────────────────────┐
│ Kagent 核心价值 │
└─────────────────────────────────────────────────────────────────┘
传统方式 Kagent 方式
──────── ────────────
自建 Agent 平台 → Kubernetes CRD
命令式 API → 声明式 YAML
自建多租户 → Namespace + RBAC
自建高可用 → Deployment + ReplicaSet
自建监控对接 → Prometheus 生态
专有运维工具 → kubectl + GitOps
核心理念:
┌──────────────────────────────────┐
│ Agent 应该像 Deployment 一样, │
│ 成为 Kubernetes 的一等公民 │
└──────────────────────────────────┘
# 安装 Kagent
helm install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent
# 创建 Agent
kubectl apply -f - <<EOF
apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
name: my-agent
spec:
type: Declarative
declarative:
systemMessage: "你是一个有用的助手"
modelConfig: "default-model-config"
EOF
# 查看 Agent 状态
kubectl get agents
kubectl describe agent my-agent