Build a Kagent Q&A agent-Container Service for Kubernetes(ACK)-阿里云帮助中心

This topic describes how to deploy a simple agent with Kagent. The agent uses the qwen3-coder-plus model from Alibaba Cloud Model Studio and a fetch MCP service to retrieve web page content by URL, which enables the agent to fetch and summarize web content in real time.

Prerequisites

Create a namespace named kagent in your ACK cluster.
In the kagent namespace, install the kagent-crds and kagent applications from the ACK Applications or by navigating to Applications > Helm.
Activate the Alibaba Cloud Model Studio service and create an API key.

Step 1: Create ModelConfig

Connect to the cluster using kubectl and the cluster's KubeConfig.

Export your Model Studio API key as an environment variable and create a Secret to store and use it.

export PROVIDER_API_KEY=${YOUR_MODEL_STUDIO_API_KEY}
kubectl create secret generic bailian-apikey -n kagent --from-literal credential="$PROVIDER_API_KEY"

Create the ModelConfig.

kubectl -n kagent apply -f - <<EOF
apiVersion: kagent.dev/v1alpha2
kind: ModelConfig
metadata:
  name: bailian-provider-config
spec:
  model: qwen3-coder-plus
  apiKeySecret: bailian-apikey
  apiKeySecretKey: credential
  openAI:
    baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1
  provider: OpenAI
EOF

Step 2: Deploy fetch MCP server

Deploy the fetch MCP server in your ACK cluster.

kubectl -n kagent apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: streamablehttp-fetch-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: streamablehttp-fetch
  template:
    metadata:
      labels:
        app: streamablehttp-fetch
    spec:
      containers:
      - name: streamablehttp-fetch-container
        image: registry-cn-hangzhou.ack.aliyuncs.com/dev/streamablehttp-fetch:latest
---
apiVersion: v1
kind: Service
metadata:
  name: streamablehttp-fetch-service
spec:
  selector:
    app: streamablehttp-fetch
  ports:
    - protocol: TCP
      port: 3000
      targetPort: 3000
  type: ClusterIP
EOF

Step 3: Register MCP server

Create the RemoteMCPServer resource.

kubectl -n kagent apply -f - <<EOF
apiVersion: kagent.dev/v1alpha2
kind: RemoteMCPServer
metadata:
  name: streamablehttp-fetch
spec:
  description: A Model Context Protocol server that provides web content fetching capabilities. This server enables LLMs to retrieve and process content from web pages, converting HTML to markdown for easier consumption.
  protocol: STREAMABLE_HTTP
  sseReadTimeout: 5m0s
  terminateOnClose: true
  timeout: 30s
  url: http://streamablehttp-fetch-service:3000/
EOF

Verify the status of the RemoteMCPServer.

kubectl get RemoteMCPServer -n kagent

Expected output:

NAME                   PROTOCOL          URL                                         ACCEPTED
streamablehttp-fetch   STREAMABLE_HTTP   http://streamablehttp-fetch-service:3000/   True

Step 4: Create the agent

Create the Q&A agent.

kubectl -n kagent apply -f - <<EOF
apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
  name: gateway-api-professor
  namespace: kagent
spec:
  declarative:
    modelConfig: bailian-provider-config
    stream: true
    systemMessage: |-
      You are a friendly and helpful agent. Use the streamablehttp-fetch tool to get GatewayAPI information from the following URLs to answer user questions about GatewayAPI.
      # Links
      - intro: https://gateway-api.sigs.k8s.io/
      - api-overview: https://gateway-api.sigs.k8s.io/concepts/api-overview/
      - use-case: https://gateway-api.sigs.k8s.io/concepts/use-cases/
      - servicemesh: https://gateway-api.sigs.k8s.io/mesh/
      - implementations: https://gateway-api.sigs.k8s.io/implementations/
      - v1.4 support overview: https://gateway-api.sigs.k8s.io/implementations/v1.4/
      - Full spec, large page: https://gateway-api.sigs.k8s.io/reference/spec/
      # Instructions
      - If a user's question is unclear, ask for clarification before running any tools.
      - Be friendly and enthusiastic in your responses to the user.
      - If you do not know how to answer a question, do not make up an answer.
        Reply with "Sorry, I don't know how to answer that question" and ask the user to clarify.
      - If the user asks for a summary or an overview, make sure to read the entire text before answering.
      # Response format
      - Always reply in Markdown format.
      - Your response must include a summary of the actions you performed and an explanation of the results.
    tools:
    - type: McpServer
      mcpServer:
        apiGroup: kagent.dev
        kind: RemoteMCPServer
        name: streamablehttp-fetch
        toolNames:
        - fetch
  description: This agent primarily answers questions related to the GatewayAPI specification.
  type: Declarative
EOF

Verify that the agent pod is running.

kubectl get pod -n kagent

Expected output:

NAME                                               READY   STATUS    RESTARTS   AGE
gateway-api-professor-7cb6496b9d-l7nlj             1/1     Running   0          3m1s
kagent-controller-794fc765df-hqswt                 1/1     Running   0          45m
kagent-ui-569cb875c6-h55mg                         1/1     Running   0          45m
streamablehttp-fetch-deployment-75d5cd86cf-h9rvp   1/1     Running   0          4m3s

Step 5: Access the agent

Kagent includes a built-in web UI to interact with the agent.

Use port forwarding to expose the kagent-ui Service to your local machine.
```
kubectl port-forward -n kagent service/kagent-ui 8082:8080
```
In a web browser, access the agent at http://localhost:8082.
1. Example question 1: What APIs does GatewayAPI provide?
  
  After receiving the question, the AI agent makes two fetch tool calls to access the official GatewayAPI documentation. The target URL for the first call is https://gateway-api.sigs.k8s.io/concepts/api-overview/. Both calls show a Completed status.
  
  The AI agent (kagent/gateway-api-professor) answers: The primary resource types in GatewayAPI include GatewayClass, which defines a set of gateways with a common configuration and behavior; Gateway, which describes how traffic is translated to services within the cluster; and Route resources, which define protocol-specific routing rules from a Gateway to Kubernetes services. The Route resources include HTTPRoute, TLSRoute, TCPRoute, UDPRoute, and GRPCRoute. These resources work together to form a load balancer configuration. Extension points include BackendRefs, HTTPRouteFilter, and custom Route types.
2. Example question 2: Which implementation currently provides the most comprehensive support for GatewayAPI features?
  
  After receiving this question, the AI agent makes three fetch tool calls with the target URL https://gateway-api.sigs.k8s.io/implementations/. All three calls show a Completed status, indicating that the content from the official GatewayAPI implementations list page was successfully fetched.
  
  The AI agent answers: GatewayAPI supports five Route types: HTTPRoute (for HTTP/HTTPS), TLSRoute (for SNI-based TLS), TCPRoute (for TCP), UDPRoute (for UDP), and GRPCRoute (for gRPC). When evaluated on both core conformance and extended features, the implementations with the most comprehensive support are Envoy Gateway (offering excellent support for HTTPRoute, GRPCRoute, and TLSRoute, plus many extended features), Istio (performing well in both Gateway and Mesh modes), and Traefik (providing good support for multiple Route types). In summary, while Envoy Gateway and Istio are generally considered the most feature-rich, the best choice ultimately depends on your specific needs and environment.