Belajar A2A - Content & Structured Output

#Pendahuluan

Di episode 7 kita melihat bagaimana status, pesan, dan artefak mengalir lewat streaming dan push notification. Namun semua contoh itu masih memakai teks polos — agent mengirim kalimat, agent lain menerima kalimat. Di dunia nyata, agent sering perlu bertukar sesuatu yang jauh lebih berstruktur: dataset, dokumen PDF, atau record lead yang harus dibaca tanpa salah tafsir. Episode ini membahas bentuk konten yang bisa dikirim antar agent.

Roadmap episode ini: kita bedah anatomi Part sebagai unit konten terkecil, lalu satu per satu tipe-nya — TextPart, FilePart, dan DataPart — dan diakhiri studi kasus transfer data terstruktur antar agent lengkap dengan praktik yang menghindari parsing bebas.

#Anatomi Part: Unit Konten Terkecil

Di episode 4 kita belajar bahwa Message dan Artifact sama-sama berisi kumpulan Part. Part inilah unit konten terkecil yang bisa dibawa agent — setara "baris" dalam sebuah tabel. Struktur dasarnya sederhana: setiap part membawa kind untuk menandai tipenya, diikuti data spesifik tipe tersebut.

{
  "role": "user",
  "parts": [
    { "kind": "text", "text": "Analisis tren penjualan", "metadata": { "prioritas": "tinggi" } },
    { "kind": "file", "file": { "name": "data-penjualan.csv", "mimeType": "text/csv", "uri": "https://storage.example.com/sales.csv" } },
    { "kind": "data", "data": { "periode": "Q3-2026", "region": "Jawa Timur" } }
  ]
}

Karena Message dan Artifact menerima daftar part, satu pesan bisa memuat semuanya sekaligus: teks instruksi, file pendukung, dan data terstruktur. Agent penerima membaca setiap part sesuai kind-nya. Tiga kind utama yang akan kita bedah: text, file, dan data.

#Teks: TextPart

TextPart adalah jenis paling sederhana dan paling sering dipakai — kita sudah mengirimnya sejak episode 6. Strukturnya hanya dua field: text berisi konten, dan metadata opsional untuk label tambahan seperti prioritas atau bahasa.

{ "kind": "text", "text": "Ringkas artikel ini dalam tiga poin" }

{ "kind": "text", "text": "Analisis tren penjualan", "metadata": { "prioritas": "tinggi", "bahasa": "id" } }

Meski sederhana, TextPart punya batas yang harus disadari: teks tidak membawa struktur. Angka, tanggal, dan status di dalamnya harus diparsing ulang oleh penerima — di sinilah kelemahannya untuk transfer data terstruktur.

#File: FilePart

Untuk konten non-teks — PDF, gambar, spreadsheet, CSV — gunakan FilePart. Strukturnya membawa name untuk nama file dan mimeType untuk jenis media. Isinya sendiri bisa diberikan lewat dua cara: inline sebagai dataUri (data terenkode base64), atau referensi lewat uri ke URL yang bisa diunduh:

{
  "kind": "file",
  "file": {
    "name": "laporan-q2.pdf",
    "mimeType": "application/pdf",
    "dataUri": "data:application/pdf;base64,JVBERi0xLjQK..."
  }
}

{
  "kind": "file",
  "file": {
    "name": "dataset-customer.csv",
    "mimeType": "text/csv",
    "uri": "https://storage.example.com/datasets/customer-2026.csv"
  }
}

dataUri cocok untuk file kecil yang harus dikirim sekaligus; uri lebih hemat bandwidth untuk file besar karena agent penerima tinggal mengunduh. Catatan penting: agent penerima harus memakai mimeType untuk memilih cara memproses — jangan menebak dari ekstensi nama file yang bisa menipu.

#Data Terstruktur: DataPart

Inilah senjata utama untuk konten terstruktur. DataPart membawa field data berisi objek JSON apa pun. Tidak ada parsing teks, tidak ada interpretasi bebas — struktur sudah tersedia langsung. Untuk membungkusnya dengan kontrak yang jelas, spesifikasi A2A menghubungkan DataPart dengan JSON Schema lewat deklarasi input dan output pada skill di Agent Card:

{
  "kind": "data",
  "data": {
    "lead_id": "L-1024",
    "nama_perusahaan": "PT Nusantara Maju",
    "industri": "logistik",
    "estimasi_nilai": 250000000,
    "kontak": { "email": "sales@nusantara.example", "telepon": "+62 21 5555 0101" }
  }
}

{
  "id": "analisis_lead",
  "name": "Analisis Lead",
  "description": "Menerima data lead dan mengembalikan skor serta rekomendasi.",
  "inputModes": ["application/json"],
  "outputModes": ["application/json"],
  "inputSchema": {
    "$ref": "https://schema.internal.example.com/lead-input.json"
  }
}

Dengan inputModes: ["application/json"] dan referensi inputSchema, client tahu persis bentuk data yang diharapkan — dan agent yang menghasilkan data bisa divalidasi terhadap skema yang sama. Ini menjadikan DataPart jembatan untuk skenario machine-to-machine tanpa ambiguitas.

#Studi Kasus: Transfer Lead Antar Agent

Mari kita rangkai semuanya. Ada dua agent: CRM agent yang menemukan prospek, dan sales agent yang memberi skor. CRM agent mengirim hasil lewat DataPart, dan sales agent membaca kind: "data" untuk mengambil field secara langsung:

Artifact dari CRM agentSales agent membaca DataPart tanpa parsing bebas

{
  "kind": "data",
  "data": {
    "lead_id": "L-1024",
    "nama_perusahaan": "PT Nusantara Maju",
    "industri": "logistik",
    "estimasi_nilai": 250000000,
    "sumber": "pameran-logistics-2026"
  }
}

async def execute(self, context, event_queue):
    lead = None
    for part in context.message.parts:
        if part.kind == "data":
            lead = part.data
            break
    if lead is None:
        await updater.update_status(TaskState.TASK_STATE_INPUT_REQUIRED)
        return
    skor = await hitung_skor(lead["nama_perusahaan"], lead["estimasi_nilai"])
    await updater.add_artifact(parts=[DataPart(data={"lead_id": lead["lead_id"], "skor": skor})])
    await updater.update_status(TaskState.TASK_STATE_COMPLETED)

Perhatikan alurnya. CRM agent tidak merangkai kalimat yang harus diurai — ia menyusun objek JSON. Sales agent mencari part berjenis data, membaca lead_id dan estimasi_nilai sebagai field, dan membalas dengan DataPart baru berisi skor. Seluruh rantai berjalan tanpa regex, tanpa parsing string, tanpa asumsi format.

#Best Practice: Jangan Parsing Bebas

Berbekal tiga tipe Part, berikut praktik yang menjaga pertukaran data tetap sehat di production:

• Gunakan DataPart untuk data, bukan teks. Apapun yang punya struktur — lead, product, order, konfigurasi — kirim sebagai data, bukan rangkuman kalimat.
• Deklarasikan skema di skill. Isi inputSchema dan outputSchema agar client bisa membangun dan memvalidasi payload dengan benar.
• Patuhi mimeType dan versi skema. File besar lewat uri; skema diberi versi (v1, v2) dan disimpan di URL yang stabil agar agent lama tidak patah saat skema berubah.
• Bersikap tegas pada data invalid. Bila struktur tak sesuai skema, minta input ulang lewat state input-required, jangan menebak atau mengisi default diam-diam.
• Hindari ekspektasi implisit. Jangan membaca field yang tidak dideklarasikan di skema; jadikan skema satu-satunya kontrak.

#Penutup

Episode 8 melengkapi vocabulary konten A2A: TextPart untuk teks, FilePart untuk file dengan dataUri atau uri plus mimeType, dan DataPart untuk data terstruktur berbasis JSON schema. Lewat studi kasus transfer lead, kalian melihat bagaimana agent membangun dan membaca struktur secara langsung — tanpa parsing bebas yang rapuh. Kunci utamanya adalah menjadikan skema sebagai kontrak, bukan sekadar dokumentasi.

Inti yang harus dibawa pulang:

• Part adalah unit konten terkecil, dikelompokkan dalam Message dan Artifact.
• TextPart untuk teks; FilePart untuk file inline (dataUri) atau referensi (uri) dengan mimeType.
• DataPart membawa objek JSON terstruktur yang dibaca langsung sebagai field, bukan diurai.
• Deklarasi inputSchema/outputSchema di skill mengikat pertukaran data pada kontrak JSON schema.
• Data terstruktur antar agent menghilangkan parsing bebas dan membuat pipeline multi-agent dapat diprediksi.

Begitu konten bisa terstruktur dan aman, pertanyaan berikutnya yang mencuat di produksi: siapa yang boleh memanggil agent kita? Di episode 9 kita membahas Authentication & Security — alur OAuth 2.1, API key, dan JWT pada field authentication di Agent Card, plus signed agent card untuk verifikasi identitas dan integritas capabilities. Sampai jumpa!