Container Service for Kubernetes:Deploy an Agent2Agent (A2A) protocol server in Knative

Cara kerja

Agen AI memiliki kemampuan inferensi, perencanaan, dan memori sehingga dapat belajar secara otonom serta menyelesaikan tugas untuk pengguna. Mirip dengan cara beberapa protokol menyediakan standar bagi model bahasa besar (LLMs) untuk mengakses data dan alat, protokol A2A mendefinisikan kerangka kerja standar untuk interoperabilitas antar agen.

Penerapan server A2A di Knative melibatkan interaksi inti berikut:

• Discovery: Setelah diterapkan, layanan mengekspos antarmukanya melalui Agent Card standar. Hal ini memungkinkan agen lain melakukan kueri terhadap skill (AgentSkill) dan kemampuan (AgentCapabilities)-nya.

• Komunikasi: Agen berkomunikasi melalui pertukaran pesan HTTP atau gRPC standar, yang ditangani oleh gateway dan routing layanan Knative.

• Kolaborasi: Agen mendelegasikan tugas dan mengoordinasikan aksi melalui API.

Lihat spesifikasi A2A untuk mempelajari arsitektur protokol komunikasi agen dan konsep intinya.

Prasyarat

• Anda telah menerapkan Knative di kluster Anda. Untuk informasi lebih lanjut, lihat Deploy and manage Knative components.

• Anda telah memperoleh alamat gateway.

  Anda dapat menemukan alamat tersebut pada tab Add-ons atau Services di Konsol Knative.

  

Langkah 1: Deploy server A2A

Contoh ini menerapkan layanan agen dasar bernama helloworld-agent-server.

1. Buat file a2a-service.yaml.

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     name: helloworld-agent-server
     # Ubah namespace sesuai kebutuhan Anda.
     namespace: default 
     annotations:
       # Gunakan nama domain wildcard untuk verifikasi cepat.
       knative.aliyun.com/serving-ingress: / 
   spec:
     template:
       spec:
         containers:
         # Ganti {region} dengan wilayah aktual Anda, misalnya cn-hangzhou.
         - image: registry-{region}-vpc.ack.aliyuncs.com/acs/knative-samples-a2a:v1.0-952c112
           name: user-container
           env:
           # INVOKE mendefinisikan URL pemanggilan yang dikembalikan dalam Agent Card. Ganti placeholder dengan alamat gateway akses layanan Anda.
           - name: INVOKE
             value: http://<YOUR_GATEWAY_ADDRESS>/invoke
           ports:
           - containerPort: 9001
             name: http1
             protocol: TCP

2. Terapkan layanan tersebut.

   kubectl apply -f a2a-service.yaml

3. Periksa status layanan Knative.

   kubectl get ksvc helloworld-agent-server

   Output yang diharapkan:

   NAME                      URL                                                  LATESTCREATED                   LATESTREADY                     READY   REASON
   helloworld-agent-server   http://helloworld-agent-server.default.example.com   helloworld-agent-server-00001   helloworld-agent-server-00001   True    

Langkah 2: Verifikasi layanan dan dapatkan Agent Card

Setelah menerapkan layanan, verifikasi bahwa layanan tersebut mengembalikan Agent Card yang sesuai dengan protokol A2A.

1. Dapatkan alamat gateway dan nama domain default layanan.

   1. Pada halaman ACK Clusters, klik nama kluster Anda. Di panel navigasi kiri, klik Applications > Knative.

   2. Pada tab Services, dapatkan Default Domain layanan tersebut.

      Gambar berikut menunjukkan Gateway dan Default Domain.

      

2. Akses titik akhir metadata layanan.

   # Ganti <GATEWAY_ADDRESS> dengan alamat gateway yang Anda peroleh.
   curl http://<GATEWAY_ADDRESS>/.well-known/agent-card.json | jq .

   Lihat hasil keluaran yang diharapkan.
   Hasil keluaran harus mencakup capabilities (kemampuan Agen), description (deskripsi), dan skills (keterampilan).
   
   

   {
     "capabilities": {
       "streaming": true
     },
     "defaultInputModes": [
       "text"
     ],
     "defaultOutputModes": [
       "text"
     ],
     "description": "Just a hello world agent",
     "name": "Hello World Agent",
     "preferredTransport": "JSONRPC",
     "protocolVersion": "",
     "skills": [
       {
         "description": "Returns a 'Hello, world!'",
         "examples": [
           "hi",
           "hello"
         ],
         "id": "hello_world",
         "name": "Hello, world!",
         "tags": [
           "hello world"
         ]
       }
     ],
     "url": "http://XXX/invoke",
     "version": ""
   }

Langkah 3: Panggil layanan dengan klien A2A

Gunakan Go untuk menulis kode klien yang mensimulasikan agen lain berkomunikasi dengan server A2A yang telah diterapkan.

1. Siapkan lingkungan pengembangan Anda. Instal lingkungan bahasa Go.

2. Buat file main.go dan tambahkan kode berikut.

   package main
   
   import (
   	"context"
   	"flag"
   	"log"
   
   	// Impor library inti untuk protokol A2A.
   	"github.com/a2aproject/a2a-go/a2a"
   	"github.com/a2aproject/a2a-go/a2aclient"
   	"github.com/a2aproject/a2a-go/a2aclient/agentcard"
   
   	// Impor library terkait gRPC.
   	"google.golang.org/grpc"
   	"google.golang.org/grpc/credentials/insecure"
   )
   
   // Ganti <GATEWAY_ADDRESS> dengan alamat gateway aktual Anda.
   var cardURL = flag.String("card-url", "http://<GATEWAY_ADDRESS>", "Base URL of AgentCard client.")
   
   func main() {
   	flag.Parse()
   	ctx := context.Background()
   
   	// Temukan layanan.
   	card, err := agentcard.DefaultResolver.Resolve(ctx, *cardURL)
   	if err != nil {
   		log.Fatalf("Failed to resolve an AgentCard: %v", err)
   	}
   
   	// Konfigurasikan lapisan transport.
   	withInsecureGRPC := a2aclient.WithGRPCTransport(grpc.WithTransportCredentials(insecure.NewCredentials()))
   
   	// Buat klien.
   	client, err := a2aclient.NewFromCard(ctx, card, withInsecureGRPC)
   	if err != nil {
   		log.Fatalf("Failed to create a client: %v", err)
   	}
   
   	// Bangun pesan.
   	msg := a2a.NewMessage(a2a.MessageRoleUser, a2a.TextPart{Text: "Hello, world"})
   	resp, err := client.SendMessage(ctx, &a2a.MessageSendParams{Message: msg})
   	if err != nil {
   		log.Fatalf("Failed to send a message: %v", err)
   	}
   
   	log.Printf("Server responded with: %+v", resp)
   }

3. Jalankan kode untuk mengujinya.

   go mod init a2a-demo
   go mod tidy
   go run main.go

   Output berikut menunjukkan bahwa klien berhasil terhubung ke layanan Knative dan menerima tanggapan.

   2025/11/27 17:24:21 Server responded with: &{ID:019ac4a0-c386-7cdc-9aad-d40fb8f98ae2 ContextID: Extensions:[] Metadata:map[] Parts:[{Text:Hello, world! Metadata:map[]}] ReferenceTasks:[] Role:agent TaskID:}

Rekomendasi untuk lingkungan produksi

• Nama domain kustom dan HTTPS: Untuk lingkungan produksi, jangan gunakan nama domain uji. Kami merekomendasikan mengonfigurasi nama domain kustom dan mengaktifkan sertifikat HTTPS untuk mengamankan komunikasi antar agen.

• Optimalisasi cold start: Jika agen jarang dipanggil, Knative akan menurunkan jumlah instans hingga nol. Untuk mencegah latensi cold start memengaruhi pengalaman pengguna, Anda dapat mengonfigurasi jumlah minimum instans (MinScale) atau mengonfigurasi instans terjadwal.

Tagihan

Tidak ada biaya tambahan untuk Knative itu sendiri. Namun, Anda bertanggung jawab atas biaya sumber daya cloud yang disediakan selama menggunakan Knative, seperti sumber daya komputasi (ECS) dan sumber daya jaringan (Application Load Balancer). Sumber daya ini ditagih secara terpisah oleh masing-masing layanan cloud. Untuk informasi harga detail, lihat Cloud resource fees.