使用 Core Profile 快速入门
本指南演示在 Kagenti Operator 的 core profile 上完成尽可能小的端到端部署——这是默认安装形态,支持智能体注册和动态发现,但不包含身份 sidecar、Keycloak 或 mesh mTLS。这是验证 operator 安装是否正常工作,并在叠加 secure profile 之前熟悉 AgentRuntime 自定义资源的最快方式。
本场景是一个 天气智能体:它通过调用用于获取实时数据的 weather MCP 工具,并借助大语言模型生成回复,来回答类似 “纽约的天气怎么样?” 这样的问题。请求流如下:
client ──A2A message/send──▶ weather-agent ──OpenAI chat API──▶ InferenceService (qwen36-27b-gguf)
│
└──────────MCP──────────▶ weather-tool-mcp
在 core profile 下没有身份验证或传输安全——下面的每一步都是普通的集群内 HTTP 调用。关于安全版本(Bearer-token 请求、SPIRE mTLS、每个智能体一个 AuthBridge sidecar),请在阅读完本指南后继续查看 Demo with Secure Profile。
前提条件
-
已安装 Kagenti Operator,且其 Kagenti operand 已完成调谐——请参见 Installation。
-
对目标集群具有 kubectl 访问权限。
-
一个演示命名空间。本指南使用 team1:
kubectl create namespace team1
-
一个提供 OpenAI-compatible chat API 的 InferenceService,且可在集群内访问。本指南使用名为 qwen36-27b-gguf 的 InferenceService。任何 chat model 都可以;如果模型支持 tool calling,智能体效果会更好。
找到你的模型端点和名称
智能体通过三个环境变量连接到模型——LLM_API_BASE、LLM_API_KEY 和 LLM_MODEL。请从你的 InferenceService 中解析它们:
# The predictor Service exposes the OpenAI-compatible API in-cluster.
# Base URL pattern: http://<isvc-name>-predictor.<namespace>.svc.cluster.local/v1
kubectl get svc -n <model-namespace> | grep <isvc-name>-predictor
# The model id to send as "model" — list what the endpoint serves:
kubectl run modelq --rm -i --restart=Never -n <model-namespace> \
--image=docker.io/alaudadockerhub/curl:8.1.2 --command -- \
curl -sS http://<isvc-name>-predictor.<model-namespace>.svc.cluster.local/v1/models
对于部署在 models 命名空间中的 qwen36-27b-gguf InferenceService,解析结果如下:
INFO
在本指南中,请将你自己的 InferenceService 名称、命名空间和 model id 替换进去。如果模型是 reasoning model,响应的前几个 token 会是推理内容——请像下面这样保持智能体的 token budget 不受限制,这样最终答案才不会被截断。
MCP(Model Context Protocol)服务器提供智能体调用的 get_weather 工具。部署它并通过 Service 暴露出来。在 core profile 下,该工具以普通 Deployment 运行(单容器、无 sidecar);在 secure profile 下也会继续使用相同的布局,因为 operand 默认值是 spec.featureGates.injectTools: false。
kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
name: weather-tool
namespace: team1
labels:
app.kubernetes.io/name: weather-tool
spec:
replicas: 1
selector:
matchLabels:
app.kubernetes.io/name: weather-tool
template:
metadata:
labels:
app.kubernetes.io/name: weather-tool
spec:
containers:
- name: mcp
image: docker.io/alaudadockerhub/weather_tool:v0.1.0-rc.1
imagePullPolicy: IfNotPresent
env:
- name: PORT
value: "8000"
- name: HOST
value: 0.0.0.0
- name: UV_CACHE_DIR
value: /app/.cache/uv
ports:
- containerPort: 8000
volumeMounts:
- mountPath: /app/.cache
name: cache
volumes:
- name: cache
emptyDir: {}
---
apiVersion: v1
kind: Service
metadata:
name: weather-tool-mcp
namespace: team1
spec:
selector:
app.kubernetes.io/name: weather-tool
ports:
- name: http
port: 8000
targetPort: 8000
EOF
- MCP 服务器镜像已镜像到
docker.io/alaudadockerhub。在 air-gapped 集群上,请使用已迁移到你平台 registry 的副本。
- 智能体将通过
http://weather-tool-mcp.team1.svc.cluster.local:8000/mcp 访问的 Service。operator 不会替你创建这个 Service,因此你需要显式定义它,并选择该工具的 pod。
等待工具就绪:
kubectl rollout status deploy/weather-tool -n team1
kubectl get pod -n team1 -l app.kubernetes.io/name=weather-tool
# NAME READY STATUS RESTARTS AGE
# weather-tool-XXXXXXXXXX-YYYYY 1/1 Running 0 1m
READY 1/1 表示该工具正以单容器方式运行。
步骤 2:部署智能体
智能体只需要在其 Deployment 上添加 protocol.kagenti.io/a2a 标签——控制器会应用 kagenti.io/type,计算配置哈希,并在启用身份栈时触发 sidecar 注入。该协议标签还会告诉 AgentCard 同步控制器该智能体使用的协议,从而启用自动发现。
kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
name: weather-agent
namespace: team1
labels:
app.kubernetes.io/name: weather-agent
protocol.kagenti.io/a2a: ""
spec:
replicas: 1
selector:
matchLabels:
app.kubernetes.io/name: weather-agent
template:
metadata:
labels:
app.kubernetes.io/name: weather-agent
spec:
containers:
- name: agent
image: docker.io/alaudadockerhub/weather_service:v0.1.0-rc.1
imagePullPolicy: IfNotPresent
ports:
- containerPort: 8000
env:
- name: PORT
value: "8000"
- name: UV_CACHE_DIR
value: /app/.cache/uv
- name: MCP_URL
value: http://weather-tool-mcp.team1.svc.cluster.local:8000/mcp
- name: LLM_API_BASE
value: http://qwen36-27b-gguf-predictor.models.svc.cluster.local/v1
- name: LLM_API_KEY
value: dummy
- name: LLM_MODEL
value: qwen36-27b-gguf
---
apiVersion: v1
kind: Service
metadata:
name: weather-agent
namespace: team1
spec:
selector:
app.kubernetes.io/name: weather-agent
ports:
- name: http
port: 8000
targetPort: 8000
---
apiVersion: agent.kagenti.dev/v1alpha1
kind: AgentRuntime
metadata:
name: weather-agent-runtime
namespace: team1
spec:
type: agent
targetRef:
apiVersion: apps/v1
kind: Deployment
name: weather-agent
EOF
protocol.kagenti.io/a2a: "" 将该 Deployment 标记为 A2A 智能体。它会启用自动创建 AgentCard;ValidatingAdmissionPolicy 禁止直接设置 kagenti.io/type,因此注册必须通过 AgentRuntime 完成。
- 智能体镜像已镜像到
docker.io/alaudadockerhub。请使用 v0.1.0 或更高版本——这些版本会从环境中读取 HOST/PORT,这在 secure profile 下是必需的(AuthBridge sidecar 会重新映射应用端口)。
MCP_URL — 来自步骤 1 的 MCP 工具端点(Service 名称加上 /mcp 路径)。
LLM_API_BASE — 你的 InferenceService predictor 的 OpenAI-compatible 基础 URL(.../v1)。
LLM_MODEL — 由 InferenceService 提供的 model id。
该智能体的 Service 以 Deployment(weather-agent)命名;AgentRuntime 控制器会解析它,以获取用于发现的 Agent Card。
创建 AgentRuntime 时,控制器会:
- 解析
targetRef 并验证 Deployment 是否存在。
- 应用
kagenti.io/type: agent 和 app.kubernetes.io/managed-by: kagenti-operator 标签。
- 计算配置哈希,并将其作为
kagenti.io/config-hash 注解设置到 pod template 上,从而触发滚动更新。
步骤 3:检查状态
# AgentRuntime status — only the agent has one in this pattern
kubectl get agentruntime -n team1
# NAME TYPE TARGET READY AGE
# weather-agent-runtime agent weather-agent True 1m
# Conditions (core profile: MTLSReady is False with reason SPIREUnavailable — expected)
kubectl get agentruntime weather-agent-runtime -n team1 \
-o jsonpath='{range .status.conditions[*]}{.type}={.status}{"\n"}{end}'
# TargetResolved=True
# IstioMeshEnrolled=True
# MTLSReady=False
# ConfigResolved=True
# Ready=True
# Labels applied by the operator
kubectl get deployment weather-agent -n team1 --show-labels
# Pods: agent 1/1, tool 1/1 — no sidecars in the core profile
kubectl get pods -n team1
# NAME READY STATUS RESTARTS AGE
# weather-agent-XXXXXXXXX-YYYYY 1/1 Running 0 1m
# weather-tool-XXXXXXXXX-YYYYY 1/1 Running 0 6m
# The AgentCard is created and synced automatically
kubectl get agentcards -n team1
# NAME PROTOCOL KIND TARGET AGENT SYNCED AGE
# weather-agent-deployment-card a2a Deployment weather-agent Weather Assistant True 1m
SYNCED=True 且 AGENT 列已填充(此处为 Weather Assistant),表示同步控制器已获取到该智能体的 A2A card——动态发现已生效。
步骤 4:发送查询(端到端测试)
从集群内的临时 pod 向智能体发送一条 A2A message/send 请求,使用该智能体内部的 Service DNS 名称:
kubectl run curl-wq --rm -i --restart=Never -n team1 \
--image=docker.io/alaudadockerhub/curl:8.1.2 --command -- \
curl -sS -X POST http://weather-agent.team1.svc.cluster.local:8000/ \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":"76CD6BA3-16AA-4CED-8E0E-19156B8C5886","method":"message/send","params":{"message":{"role":"user","parts":[{"kind":"text","text":"What is the weather in NY?"}],"messageId":"DF05857B-98B7-4414-BD63-19E16E684E39"}}}'
智能体调用模型,模型调用 weather MCP 工具,随后智能体返回一个已完成的 A2A task:
{
"id": "76CD6BA3-16AA-4CED-8E0E-19156B8C5886",
"jsonrpc": "2.0",
"result": {
"artifacts": [
{
"parts": [
{
"kind": "text",
"text": "The current weather in New York is 66.4°F with clear skies. The wind speed is 4.4."
}
]
}
],
"kind": "task",
"status": { "state": "completed" }
}
}
完整响应中的 history 数组展示了 tool-calling 流程(assistant → tools → assistant),其中包含 weather MCP 服务器返回的 ToolMessage。
INFO
reasoning model 会先用前几个 token “思考”,然后才给出最终答案,因此第一次请求可能会比 non-reasoning model 明显更慢。后续请求会更快。
你可以在日志中观察交互过程:
# Agent logs
kubectl logs -f -l app.kubernetes.io/name=weather-agent -n team1
# MCP tool logs (in another terminal)
kubectl logs -f -l app.kubernetes.io/name=weather-tool -n team1
更新和删除 AgentRuntime
平台配置变更(集群级或命名空间级 ConfigMaps)会触发滚动更新,使 pod 获取新设置。直接编辑 AgentRuntime 的 spec 本身不会强制重启——新值会在创建 pod 时应用。
删除 AgentRuntime 会执行优雅清理:控制器会移除 kagenti.io/type 标签和 kagenti.io/config-hash 注解(触发滚动更新,从而替换任何已注入的 pod),并移除 app.kubernetes.io/managed-by 标签。
kubectl delete agentruntime weather-agent-runtime -n team1
清理
kubectl delete namespace team1
下一步
你刚刚体验的 core profile 不包含身份验证或传输安全。若要逐步叠加这些能力:
- 安装 Secure-Profile Dependencies — SPIRE、Keycloak、Istio ambient。
- 启用 Secure Profile — 切换 operand feature gates。
- Demo with Secure Profile — 使用智能体上的 AuthBridge sidecar、每个 workload 一个 SPIRE SVID,以及 Bearer-token 认证请求,重新运行同样的天气场景。
- Demo Advanced: AuthBridge on the Tool with Token Exchange — 也为工具添加 AuthBridge,并在智能体与工具之间使用 RFC 8693 token exchange。
故障排查