すべてのプロダクト
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) プロトコルのトラフィックを正確に管理できます。

    適用範囲

    • バージョン 1.32 以降の Container Service for Kubernetes (ACK) マネージドクラスター。

    • クラスターにバージョン 1.3.0 以降の Gateway API がインストールされていること。

    ack-agent-gateway のインストール

    ack-agent-gateway は、Gateway API 標準を実装するゲートウェイコンポーネントです。Gateway API の標準化されたトラフィック管理モデルを使用して、AI エージェントシナリオのサービストラフィックを設定および管理します。

    1. ACK クラスターページで、対象クラスターの名前をクリックします。左側のナビゲーションウィンドウで、Applications > [Helm] を選択します。

    2. Helm ページで 作成 をクリックします。[Chart] セクションで ack-agent-gateway を検索して選択します。デフォルト設定のまま 次 をクリックします。

      デフォルトでは、コンポーネントは ack-agent-gateway 名前空間にインストールされます。アプリケーションはコンポーネント名を使用して公開されます。

    3. 値 ページで、最新の Chart バージョンを選択し、OK をクリックします。

    4. インストールが完了したら、Helm ページでコンポーネントを表示できます。コンポーネントのステータスは デプロイ済み です。

    ステップ 1：サンプル 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

    ステップ 2：ゲートウェイとルーティングルールの作成

    このステップでは、ゲートウェイインスタンスを作成し、ルーティングルールを定義します。このルールは、前のステップでデプロイした A2A サービスに外部トラフィックを転送します。

    1. 次の内容を含む a2a-gateway.yaml という名前のファイルを作成します。

      ---
# バックエンドの A2A サービスを定義するカスタム Backend リソース
apiVersion: agentgateway.alibabacloud.com/v1alpha1
kind: Backend
metadata:
  name: test-a2a
spec:
  type: A2A
  a2a:
    targets:
      - name: a2a-target
        static:
          # ステップ 1 で作成した Service を指す
          host: demo-a2a-agent-server
          port: 9999
---
# トラフィックのエントリポイントを定義する Gateway リソース
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: test-a2a-gateway
spec:
  # この Gateway の実装者として ack-agent-gateway を指定
  gatewayClassName: ack-agent-gateway
  listeners:
    - name: http
      # ゲートウェイによって公開されるポート
      port: 80
      protocol: HTTP
      allowedRoutes:
        namespaces:
          # 同じ名前空間の HTTPRoute のみがこのリスナーにアタッチすることを許可
          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 フィールドには、ゲートウェイに関連付けられている Server Load Balancer (SLB) インスタンスのパブリック IP アドレスが表示されます。この IP アドレスを後で使用するために記録しておきます。

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

    ステップ 3：サービス接続性のテスト

    このステップでは、A2A クライアントツールを使用して、前のステップで作成したゲートウェイ経由でバックエンドサービスにアクセスします。これにより、ルーティング設定が有効であることを確認します。

    1. Git ツールをインストールし、A2A プロトコルの公式サンプルコードをダウンロードします。

      この例では、サンプルコードがこのドキュメントと互換性があることを確認するために、特定のコミットで git checkout を実行します。実際のプロジェクトでは、安定したリリースタグをチェックアウトする必要があります。
      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 と入力して Enter キーを押します。クライアントはメッセージをバックエンドサービスに送信します。プロンプトに従って、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 と入力してクライアントプログラムを終了します。

    ステップ 4：サービスへの API キー認証の追加 (任意)

    このステップでは、アプリケーションコードを変更せずに TrafficPolicy リソースを使用して、エージェントサービスに API キー認証を追加する方法を説明します。

    • TrafficPolicy (CRD)：ack-agent-gateway が提供する CRD で、ルーティングルールに高度な機能をアタッチします。これは Policy Attachment の実装であり、認証やレート制限などのポリシーを HTTPRoute から分離します。

    • Secret：API キーの認証情報を安全に保存するために使用されます。

    API キー認証は単純な認証方式です。認証情報が漏洩すると悪用される可能性があります。認証情報は慎重に管理および保護する必要があります。

    1. 次の内容を含む a2a-api-key.yaml という名前のファイルを作成します。この YAML ファイルは、2 つの API キーを含む Secret と、API キー認証ポリシーを HTTPRoute にアタッチする TrafficPolicy を定義します。

      ---
apiVersion: v1
kind: Secret
metadata:
  name: a2a-api-key
stringData:
  # キー (key1 など) は識別子にすぎません。値 (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 キーが提供されていないため、ゲートウェイはリクエストを拒否します。プログラムは起動に失敗し、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 パラメーターを使用して、key-value-foo などの有効な API キーを提供します。

        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 リソースを削除します。

      # (任意) のステップ 4 を実行した場合は、まず認証関連のリソースを削除します
kubectl delete -f a2a-api-key.yaml

# ゲートウェイとルーティングルールを削除
kubectl delete -f a2a-gateway.yaml

# バックエンドのサンプルサービスを削除
kubectl delete -f a2a-server.yaml

    2. SLB インスタンスが解放されたことを確認します。Gateway リソースを削除すると、関連付けられている SLB インスタンスは自動的に削除されます。Server Load Balancer コンソールにログインして、インスタンスが削除されたことを確認できます。