Bagaimana cara mengonfigurasi Gateway API untuk mengelola trafik agen AI di ACK? - Container Service for Kubernetes

Untuk memungkinkan aplikasi agen AI melayani trafik eksternal, Anda dapat menginstal ekstensi ack-agent-gateway berbasis Gateway API. Ekstensi ini memungkinkan pengelolaan trafik protokol Agent2Agent (A2A) secara presisi.

Cakupan Penerapan

Kluster ACK yang dikelola versi 1.32 atau lebih baru.
Gateway API versi 1.3.0 atau lebih baru telah diinstal di kluster Anda.

Instal ack-agent-gateway

ack-agent-gateway adalah komponen gerbang yang menerapkan standar Gateway API. Komponen ini menggunakan model manajemen trafik terstandarisasi dari Gateway API untuk mengonfigurasi dan mengelola trafik layanan dalam skenario agen AI.

Pada halaman ACK Clusters, klik nama kluster target. Di panel navigasi kiri, pilih Applications > Helm.
Pada halaman Helm, klik Create. Di bagian Chart, cari dan pilih ack-agent-gateway. Pertahankan pengaturan default, lalu klik Next.
Secara default, komponen diinstal di namespace ack-agent-gateway. Aplikasi dipublikasikan menggunakan nama komponen tersebut.
Pada halaman Parameters, pilih versi Chart terbaru, lalu klik OK.
Setelah instalasi selesai, Anda dapat melihat komponen tersebut di halaman Helm. Status komponen tersebut adalah Deployed.

Langkah 1: Menyebar layanan A2A contoh

Pada langkah ini, Anda menyebarkan layanan agen sederhana yang mendukung protokol A2A. Layanan ini berperan sebagai backend untuk menguji routing gerbang pada langkah selanjutnya.

Buat file bernama a2a-server.yaml yang berisi konten berikut. File ini mendefinisikan sebuah Penyebaran (Deployment) dan layanan (Service) untuk mengekspos Penyebaran tersebut di dalam kluster.

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

Sebarkan layanan A2A contoh tersebut.
```
kubectl apply -f a2a-server.yaml
```

Periksa status pod layanan tersebut.

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

Output yang diharapkan: Pod berada dalam status Running.

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

Langkah 2: Membuat gerbang dan aturan routing

Pada langkah ini, Anda membuat instans gerbang dan mendefinisikan aturan routing. Aturan tersebut mengarahkan trafik eksternal ke layanan A2A yang telah Anda sebarkan pada langkah sebelumnya.

Buat file bernama a2a-gateway.yaml yang berisi konten berikut.

---
# Resource Backend kustom yang mendefinisikan layanan A2A backend
apiVersion: agentgateway.alibabacloud.com/v1alpha1
kind: Backend
metadata:
  name: test-a2a
spec:
  type: A2A
  a2a:
    targets:
      - name: a2a-target
        static:
          # Mengarah ke Service yang dibuat di Langkah 1
          host: demo-a2a-agent-server
          port: 9999
---
# Resource Gateway yang mendefinisikan titik masuk trafik
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: test-a2a-gateway
spec:
  # Menentukan ack-agent-gateway sebagai implementer Gateway ini
  gatewayClassName: ack-agent-gateway
  listeners:
    - name: http
      # Port yang diekspos oleh gerbang
      port: 80
      protocol: HTTP
      allowedRoutes:
        namespaces:
          # Hanya mengizinkan HTTPRoute di namespace yang sama untuk menyambung ke Pendengar ini
          from: Same
---
# Resource HTTPRoute yang mendefinisikan aturan routing
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: route-for-a2a-backend
spec:
  parentRefs:
    # Menyambungkan HTTPRoute ini ke Gateway bernama test-a2a-gateway
    - name: test-a2a-gateway
  rules:
    - backendRefs:
        # Merujuk resource Backend kustom sebagai backend
        - group: agentgateway.alibabacloud.com
          kind: Backend
          name: test-a2a

Jalankan perintah berikut untuk membuat gerbang dan resource terkait.
```
kubectl apply -f a2a-gateway.yaml
```
Jalankan perintah berikut untuk mendapatkan alamat akses publik gerbang tersebut.
```
kubectl get gateway test-a2a-gateway
```
Bidang ADDRESS menampilkan alamat IP publik dari instans Server Load Balancer (SLB) yang dikaitkan dengan gerbang tersebut. Catat alamat IP ini untuk digunakan nanti.
```
NAME               CLASS               ADDRESS        PROGRAMMED   AGE
test-a2a-gateway   ack-agent-gateway   8.136.xx.xx    True         4m36s
```

Langkah 3: Menguji konektivitas layanan

Pada langkah ini, Anda menggunakan tool klien A2A untuk mengakses layanan backend melalui gerbang yang telah Anda buat pada langkah sebelumnya. Hal ini memverifikasi bahwa konfigurasi routing berfungsi dengan baik.

Instal tool Git dan unduh kode contoh resmi untuk protokol A2A.
Pada contoh ini, Anda menjalankan git checkout pada commit tertentu untuk memastikan kode contoh kompatibel dengan dokumen ini. Dalam proyek dunia nyata, Anda sebaiknya melakukan checkout pada tag rilis stabil.
```
git clone https://github.com/a2aproject/a2a-samples.git && \
cd a2a-samples && git checkout d4fa006438e52 && \
cd samples/python/hosts/cli
```
Pastikan lingkungan Python lokal telah diinstal. Kemudian, gunakan tool uv untuk menginstal dependensi program klien.
```
uv sync
```

Akses layanan A2A melalui gerbang. Ganti <GATEWAY_IP> dalam perintah berikut dengan alamat gerbang (ADDRESS) yang Anda peroleh pada langkah sebelumnya.

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

Output yang diharapkan: Setelah koneksi berhasil dibuat, kartu informasi agen (Agent Card) ditampilkan dan program menunggu input.

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):

Pada prompt, masukkan hello lalu tekan Enter. Klien mengirim pesan tersebut ke layanan backend. Ikuti petunjuk untuk menerima balasan 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"}

Masukkan quit untuk keluar dari program klien.

Langkah 4: Menambahkan otentikasi kunci API ke layanan (Opsional)

Langkah ini menunjukkan cara menambahkan otentikasi kunci API ke layanan agen menggunakan resource TrafficPolicy tanpa mengubah kode aplikasi.

TrafficPolicy (CRD): CRD yang disediakan oleh ack-agent-gateway untuk menambahkan fitur lanjutan ke aturan routing. Ini merupakan implementasi Policy Attachment yang memisahkan kebijakan—seperti otentikasi dan pembatasan laju—dari HTTPRoute.
Secret: Digunakan untuk menyimpan kredensial kunci API secara aman.

Autentikasi kunci API adalah metode autentikasi yang sederhana. Jika kredensial bocor, kredensial tersebut dapat disalahgunakan. Anda harus mengelola dan melindungi kredensial Anda dengan hati-hati.

Buat file bernama a2a-api-key.yaml yang berisi konten berikut. File YAML ini mendefinisikan sebuah Secret yang berisi dua kunci API dan sebuah TrafficPolicy yang melampirkan kebijakan otentikasi kunci API ke HTTPRoute.

---
apiVersion: v1
kind: Secret
metadata:
  name: a2a-api-key
stringData:
  # Kunci (misalnya key1) hanya berupa pengenal. Nilai (misalnya key-value-foo) adalah kredensial aktual yang harus disediakan klien.
  key1: 'key-value-foo'
  key2: 'key-value-bar'
---
apiVersion: agentgateway.alibabacloud.com/v1alpha1
kind: TrafficPolicy
metadata:
  name: test-a2a-apikey-auth
spec:
  targetRefs:                              # Target pelampiran kebijakan
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: route-for-a2a-backend          # Melampirkan ke HTTPRoute yang telah dibuat sebelumnya
  traffic:
    authentication:
      apiKeyAuth:
        secretRef:
          name: a2a-api-key                # Merujuk Secret yang menyimpan kredensial

Terapkan kebijakan otentikasi tersebut.
```
kubectl apply -f a2a-api-key.yaml
```

Uji otentikasi tersebut.

Pertama, coba akses layanan tanpa menyediakan kredensial apa pun. Ganti <GATEWAY_IP> dengan alamat gerbang Anda.
```
uv run . --agent http://<GATEWAY_IP>
```
Output yang diharapkan: Gerbang menolak permintaan karena kunci API yang valid tidak disediakan. Program gagal dimulai dan mengembalikan error 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' ...
```

Selanjutnya, akses layanan kembali. Gunakan parameter --bearer-token untuk menyediakan kunci API yang valid, seperti key-value-foo.

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

Output yang diharapkan: Header permintaan berisi Authorization: Bearer key-value-foo. Gerbang mengotentikasi kredensial tersebut, meneruskan permintaan ke layanan backend, dan program berhasil dimulai.

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):

Membersihkan sumber daya

Untuk menghindari biaya yang tidak perlu, hapus semua resource Kubernetes dan resource cloud yang Anda buat dalam tutorial ini setelah eksperimen selesai.

Hapus semua resource Kubernetes yang Anda buat dalam tutorial ini.

# Jika Anda melakukan Langkah 4 opsional, hapus terlebih dahulu resource terkait otentikasi
kubectl delete -f a2a-api-key.yaml

# Hapus gerbang dan aturan routing
kubectl delete -f a2a-gateway.yaml

# Hapus layanan contoh backend
kubectl delete -f a2a-server.yaml

Konfirmasi bahwa instans SLB telah dilepas. Saat Anda menghapus resource Gateway, instans SLB yang terkait akan dihapus secara otomatis. Anda dapat login ke Konsol Server Load Balancer untuk memastikan instans tersebut telah dihapus.