使用 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,解析结果如下:

变量值
LLM_API_BASEhttp://qwen36-27b-gguf-predictor.models.svc.cluster.local/v1
LLM_MODELqwen36-27b-gguf
LLM_API_KEYdummy(任意非空值均可;集群内端点不需要密钥)
INFO

在本指南中,请将你自己的 InferenceService 名称、命名空间和 model id 替换进去。如果模型是 reasoning model,响应的前几个 token 会是推理内容——请像下面这样保持智能体的 token budget 不受限制,这样最终答案才不会被截断。

步骤 1:部署 MCP 工具服务器

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
  1. MCP 服务器镜像已镜像到 docker.io/alaudadockerhub。在 air-gapped 集群上,请使用已迁移到你平台 registry 的副本。
  2. 智能体将通过 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
  1. protocol.kagenti.io/a2a: "" 将该 Deployment 标记为 A2A 智能体。它会启用自动创建 AgentCard;ValidatingAdmissionPolicy 禁止直接设置 kagenti.io/type,因此注册必须通过 AgentRuntime 完成。
  2. 智能体镜像已镜像到 docker.io/alaudadockerhub。请使用 v0.1.0 或更高版本——这些版本会从环境中读取 HOST/PORT,这在 secure profile 下是必需的(AuthBridge sidecar 会重新映射应用端口)。
  3. MCP_URL — 来自步骤 1 的 MCP 工具端点(Service 名称加上 /mcp 路径)。
  4. LLM_API_BASE — 你的 InferenceService predictor 的 OpenAI-compatible 基础 URL(.../v1)。
  5. LLM_MODEL — 由 InferenceService 提供的 model id。

该智能体的 Service 以 Deployment(weather-agent)命名;AgentRuntime 控制器会解析它,以获取用于发现的 Agent Card。

创建 AgentRuntime 时,控制器会:

  1. 解析 targetRef 并验证 Deployment 是否存在。
  2. 应用 kagenti.io/type: agent 和 app.kubernetes.io/managed-by: kagenti-operator 标签。
  3. 计算配置哈希,并将其作为 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 不包含身份验证或传输安全。若要逐步叠加这些能力:

  1. 安装 Secure-Profile Dependencies — SPIRE、Keycloak、Istio ambient。
  2. 启用 Secure Profile — 切换 operand feature gates。
  3. Demo with Secure Profile — 使用智能体上的 AuthBridge sidecar、每个 workload 一个 SPIRE SVID,以及 Bearer-token 认证请求,重新运行同样的天气场景。
  4. Demo Advanced: AuthBridge on the Tool with Token Exchange — 也为工具添加 AuthBridge,并在智能体与工具之间使用 RFC 8693 token exchange。

故障排查

症状检查
AgentRuntime 不是 Readykubectl describe agentruntime <name> -n team1 —— 确认 TargetResolved。常见原因是目标 Deployment 或其 Service 尚未存在。
智能体无响应 / 超时检查智能体是否能够访问模型:LLM_API_BASE 是否可解析,并且 /v1/models 是否列出了 LLM_MODEL。查看 kubectl logs -l app.kubernetes.io/name=weather-agent -n team1 以排查 LLM 连接错误。
智能体回答中没有实时数据验证 MCP_URL 是否指向 weather-tool-mcp Service,并且工具 pod 是否处于 Running:kubectl logs -l app.kubernetes.io/name=weather-tool -n team1。
ImagePullBackOff在没有 docker.io 出站访问的集群上,请将镜像迁移到你的平台 registry(例如通过 violet),并引用该副本。
MTLSReady=False在 core profile 下这是预期行为(原因是 SPIREUnavailable);它不会影响智能体或工具功能。