全部產品
Search

搜尋本產品

    Container Service for Kubernetes：使用ack-agent-gateway實現Agent2Agent（A2A）流量治理與認證

    文件中心

    Container Service for Kubernetes：使用ack-agent-gateway實現Agent2Agent（A2A）流量治理與認證

    更新時間：Jan 06, 2026

    為了讓 AI 智能體應用快速具備對外服務能力，可基於Gateway API安裝ack-agent-gateway擴充，實現Agent2Agent（A2A）協議流量的精準管理。

    適用範圍

    • ACK託管叢集版本在1.32及以上。

    • 已在叢集中安裝Gateway API，且版本在1.3.0及以上。

    安裝ack-agent-gateway

    ack-agent-gateway 是一個實現了 Gateway API 標準的網關組件。它利用Gateway API 這套標準化的流量管理模型，可便捷地配置和管理面向 AI 智能體情境的服務流量。

    1. 在ACK叢集列表頁面，單擊目的地組群名稱，在叢集詳情頁左側導覽列，選擇应用 > Helm。

    2. 在Helm頁面，單擊建立，在Chart地區搜尋並選中ack-agent-gateway，其他設定保持預設，然後單擊下一步。

      組件預設安裝在ack-agent-gateway命名空間，並以組件名稱發布應用。

    3. 在參數頁面中，選擇最新的Chart版本，然後單擊確定。

    4. 安裝完成後，可在Helm頁面查看組件，狀態為已部署。

    步驟一：部署樣本 A2A 服務

    此步驟旨在部署一個簡單的、支援 A2A 協議的智能體服務作為後端，用於後續的網關路由測試。

    1. 使用以下內容，建立名為 a2a-server.yaml 的檔案。該檔案定義了一個 Deployment 和一個用於在叢集內部暴露該服務的 Service。

      apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo-a2a
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: demo-a2a
  template:
    metadata:
      labels:
        app.kubernetes.io/name: demo-a2a
    spec:
      containers:
        - image: registry-cn-hangzhou.ack.aliyuncs.com/dev/sample-a2a-agent-helloworld:v0.2.0
          imagePullPolicy: IfNotPresent
          name: agent
          ports:
            - containerPort: 9999
              name: server
              protocol: TCP
---
apiVersion: v1
kind: Service
metadata:
  name: demo-a2a-agent-server
spec:
  ports:
    - name: server
      port: 9999
      protocol: TCP
      targetPort: 9999
  selector:
    app.kubernetes.io/name: demo-a2a
  sessionAffinity: None
  type: ClusterIP

    2. 部署樣本 A2A 服務。

      kubectl apply -f a2a-server.yaml

    3. 檢查服務的 Pod 狀態。

      kubectl get pod -l app.kubernetes.io/name=demo-a2a

      預期輸出：請確保 Pod 處於 Running 狀態。

      NAME                        READY   STATUS    RESTARTS   AGE
demo-a2a-77dd75ddcf-qn9jx   1/1     Running   0          13s

    步驟二：建立 Gateway 和路由規則

    此步驟旨在建立一個網關執行個體，並定義一條路由規則，將外部流量引導至上一步部署的 A2A 服務。

    1. 使用以下內容，建立名為 a2a-gateway.yaml 的檔案。

      ---
# 自訂 Backend 資源，定義後端 A2A 服務
apiVersion: agentgateway.alibabacloud.com/v1alpha1
kind: Backend
metadata:
  name: test-a2a
spec:
  type: A2A
  a2a:
    targets:
      - name: a2a-target
        static:
          # 指向步驟一中建立的 Service
          host: demo-a2a-agent-server
          port: 9999
---
# Gateway 資源，定義流量入口
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: test-a2a-gateway
spec:
  # 指定 ack-agent-gateway 作為此 Gateway 的實現者
  gatewayClassName: ack-agent-gateway
  listeners:
    - name: http
      # 網關對外暴露的連接埠
      port: 80
      protocol: HTTP
      allowedRoutes:
        namespaces:
          # 僅允許在相同命名空間下的 HTTPRoute 綁定到此 Listener
          from: Same
---
# HTTPRoute 資源，定義路由規則
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: route-for-a2a-backend
spec:
  parentRefs:
    # 將此 HTTPRoute 綁定到名為 test-a2a-gateway 的 Gateway 上
    - name: test-a2a-gateway
  rules:
    - backendRefs:
        # 引用自訂的 Backend 資源作為後端
        - group: agentgateway.alibabacloud.com
          kind: Backend
          name: test-a2a

    2. 執行以下命令，建立網關及相關資源。

      kubectl apply -f a2a-gateway.yaml

    3. 執行以下命令，擷取網關的公網訪問地址。

      kubectl get gateway test-a2a-gateway

      ADDRESS 欄位即為該網關關聯的 CLB 執行個體的公網 IP 位址。請記錄此 IP，後續步驟將使用它。

      NAME               CLASS               ADDRESS        PROGRAMMED   AGE
test-a2a-gateway   ack-agent-gateway   8.136.xx.xx    True         4m36s

    步驟三：測試服務連通性

    此步驟旨在使用一個 A2A 用戶端工具，通過上一步建立的網關訪問後端服務，以驗證路由配置是否生效。

    1. 安裝Git工具。下載 A2A 協議的官方範例程式碼。

      此處 git checkout 一個特定的提交（commit）是為了確保範例程式碼與本文檔的相容性。實際專案中，建議檢出（checkout）一個穩定的發布標籤（tag）。
      git clone https://github.com/a2aproject/a2a-samples.git && \
cd a2a-samples && git checkout d4fa006438e52 && \
cd samples/python/hosts/cli

    2. 請確保本地已安裝Python環境。使用uv工具安裝用戶端程式的依賴。

      uv sync

    3. 通過網關訪問 A2A 服務。請將命令中的 <GATEWAY_IP> 替換為上一步擷取的網關地址（ADDRESS）。

      uv run . --agent http://<GATEWAY_IP>

      預期輸出：串連成功後，列印出智能體的資訊卡（Agent Card），然後繼續等待輸入資訊。

      Will use headers: {}
======= Agent Card ========
{"capabilities":{"streaming":true},"defaultInputModes":["text"],"defaultOutputModes":["text"],"description":"Just a hello world agent","name":"Hello World Agent",...}
=========  starting a new task ========

What do you want to send to the agent? (:q or quit to exit):

    4. 在提示符後輸入 hello 並按斷行符號，用戶端會將訊息發送給後端服務，然後根據提示操作，會收到 Hello World 的回複。

      What do you want to send to the agent? (:q or quit to exit): hello
Select a file path to attach? (press enter to skip):
stream event => {"kind":"message","messageId":"...","parts":[{"kind":"text","text":"Hello World"}],"role":"agent"}

{"kind":"message","messageId":"...","parts":[{"kind":"text","text":"Hello World"}],"role":"agent"}

    5. 輸入 quit 退出用戶端程式。

    步驟四：為服務增加 API Key 認證（可選）

    本步驟將示範如何在不修改任何業務代碼的前提下，通過 TrafficPolicy 資源為智能體服務增加 API Key 認證能力。

    • TrafficPolicy （CRD）：這是 ack-agent-gateway 提供的一個自訂資源，用於為路由規則附加進階功能。這是一種策略附著（Policy Attachment）的實現，可以將認證、限流等策略與 HTTPRoute 解耦。

    • Secret：用於安全地儲存 API Key 憑證。

    API Key 認證是一種簡單的認證方式。憑證若被泄露，可能被濫用，請注意憑證的管理與保護。

    1. 使用以下內容，建立名為 a2a-api-key.yaml 的檔案。 此 YAML 檔案定義了一個包含兩個 API Key 的 Secret，以及一個TrafficPolicy，用於將 API Key 認證策略附加到 HTTPRoute。

      ---
apiVersion: v1
kind: Secret
metadata:
  name: a2a-api-key
stringData:
  # key（如 key1）僅作標識；value（如 key-value-foo）是用戶端需提供的實際憑證
  key1: 'key-value-foo'
  key2: 'key-value-bar'
---
apiVersion: agentgateway.alibabacloud.com/v1alpha1
kind: TrafficPolicy
metadata:
  name: test-a2a-apikey-auth
spec:
  targetRefs:                              # 策略附加的目標
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: route-for-a2a-backend          # 附加到之前建立的 HTTPRoute
  traffic:
    authentication:
      apiKeyAuth:
        secretRef:
          name: a2a-api-key                # 引用儲存憑證的 Secret

    2. 應用認證策略。

      kubectl apply -f a2a-api-key.yaml

    3. 測試認證效果。

      1. 首先，嘗試不帶任何憑證再次訪問服務。請將 <GATEWAY_IP> 替換為實際的網關地址。

        uv run . --agent http://<GATEWAY_IP>

        預期輸出：由於缺少有效 API Key，請求將被網關拒絕，程式會因收到 401 Unauthorized 錯誤而啟動失敗。

        a2a.client.errors.A2AClientHTTPError: HTTP Error 401: Failed to fetch agent card from http://8.136.xx.xx/.well-known/agent-card.json: Client error '401 Unauthorized' ...

      2. 接下來，使用 --bearer-token 參數攜帶正確的 API Key（如key-value-foo）再次訪問。

        uv run . --bearer-token 'key-value-foo' --agent http://<GATEWAY_IP>

        預期輸出：要求標頭中會包含 Authorization: Bearer key-value-foo。網關驗證憑證通過後，會將請求轉寄至後端服務，程式成功啟動。

        Will use headers: {'Authorization': 'Bearer key-value-foo'}
======= Agent Card ========
{"capabilities":{"streaming":true},"defaultInputModes":["text"],"defaultOutputModes":["text"],"description":"Just a hello world agent","name":"Hello World Agent",...}
=========  starting a new task ========

What do you want to send to the agent? (:q or quit to exit):

    清理資源

    為避免產生不必要的費用，請在完成實驗後刪除本教程建立的所有 Kubernetes 資源和雲資源。

    1. 刪除本教程中建立的所有 Kubernetes 資源。

      # 如果執行了可選的步驟四，請先刪除認證相關的資源
kubectl delete -f a2a-api-key.yaml

# 刪除網關和路由規則
kubectl delete -f a2a-gateway.yaml

# 刪除後端的樣本服務
kubectl delete -f a2a-server.yaml

    2. 確認 CLB 執行個體已釋放。 刪除 Gateway 資源後，會自動刪除其關聯的 CLB 執行個體。可登入到負載平衡控制台，確認對應的執行個體已被刪除。