Belajar A2A - Task Lifecycle & Messages

#Pendahuluan

Di episode 3 kita memahami bagaimana sebuah agent ditemukan lewat Agent Card. Sekarang kita masuk ke inti eksekusi: apa yang terjadi setelah client mengirim pekerjaan. Semua itu diatur oleh Task lifecycle dan Message/Part.

Episode 4 menjawab dua pertanyaan: di mana sebuah task berada dalam perjalanannya? dan bagaimana konten percakapannya direpresentasikan? Dengan menguasai kedua konsep ini, kalian akan membaca dan menulis traffic A2A tanpa kebingungan.

#Task: Unit Kerja dalam A2A

Sebuah Task adalah unit kerja tunggal dalam A2A — satu permintaan dari client agent yang dikerjakan remote agent. Setiap task membawa identifier, status, dan riwayat message. Karena task adalah object JSON, seluruh progress-nya bisa di-query kapan saja.

{
  "id": "task-7f3a",
  "status": {
    "state": "working",
    "message": {
      "role": "agent",
      "parts": [
        {
          "text": "Sedang memproses laporan keuangan..."
        }
      ]
    }
  },
  "messages": [],
  "metadata": {
    "request_id": "req-0001"
  }
}

Field id menjadi pegangan seluruh percakapan berikutnya. status merefleksikan posisi task saat ini, messages menyimpan riwayat lengkap, dan metadata menampung data tambahan yang disepakati kedua belah pihak.

#State Machine Task

Status task mengalir melalui state machine yang telah distandarkan. Tidak ada status di luar daftar ini:

submitted --> working --> input-required <--+--> completed
                  |                            |
                  +-----> failed               |
                  +-----> canceled <-----------+

• submitted — task baru diterima remote agent, belum diproses.
• working — remote agent sedang mengerjakan task.
• input-required — agent butuh informasi tambahan dari client sebelum melanjutkan; task kembali ditunda menunggu pesan baru.
• completed — pekerjaan selesai dan hasil akhir tersedia.
• failed — terjadi error; detail kegagalan dibawa di dalam status.
• canceled — task dibatalkan, baik oleh client maupun remote agent.

Transisi dari working ke input-required adalah mekanisme utama pola human-in-the-loop — saat agent menemui persoalan yang butuh keputusan manusia. Client yang menerima status ini mengirimkan message balasan, dan task melanjutkan dari working kembali. Saat berpraktik nanti, transisi ini bisa diamati langsung lewat curl -s -N http://localhost:8080/sse?taskId=task-7f3a.

#Progress dan Metadata Task

Task yang berjalan lama tidak bisa hanya diam menunggu. A2A menyediakan dua mekanisme untuk membuat progress terlihat:

{
  "status": {
    "state": "working",
    "progress": {
      "current": 2,
      "total": 5,
      "message": "Meringkas halaman 2 dari 5"
    }
  }
}

• progress — pasangan nilai current dan total yang memperlihatkan seberapa jauh pekerjaan berjalan.
• metadata — ruang fleksibel di level task untuk menyimpan identitas request, trace id, atau data konteks lain.

Kedua informasi ini sangat berguna untuk observability — misalnya mengukur durasi setiap tahap. Nanti di episode 15, kita akan melihat bagaimana metadata ini dihubungkan ke OpenTelemetry untuk tracing end-to-end.

#Message dan Role

Percakapan dalam task direpresentasikan sebagai rangkaian Message. Setiap message memiliki satu role yang menunjukkan siapa pengirimnya:

{
  "role": "agent",
  "parts": [
    { "text": "Analisis selesai. Berikut temuan utamanya..." }
  ]
}

Role ini membantu kedua belah pihak memahami konteks percakapan — dan juga menjadi data penting untuk audit log di kemudian hari (topik episode 15). Urutan message di dalam task.messages mencerminkan kronologi percakapan.

#Part Types: Text, File, Structured

Setiap message berisi satu atau lebih Part, dan setiap part memegang satu bentuk konten. Tiga tipe inti:

{
  "role": "agent",
  "parts": [
    {
      "text": "Berikut hasil analisis dalam beberapa format."
    },
    {
      "file": {
        "name": "laporan-triwulan.pdf",
        "mimeType": "application/pdf",
        "url": "https://analisis.example.com/dl/laporan.pdf"
      }
    },
    {
      "structured": {
        "data": {
          "risiko": "tinggi",
          "skor": 87
        }
      }
    }
  ]
}

• text — konten teks biasa; paling sering dipakai.
• file — referensi ke berkas, baik via URL maupun dataURI, lengkap dengan mimeType dan nama berkas.
• structured — data JSON yang dikonformasi ke schema tertentu, menghindari parsing teks bebas.

Kekuatan model Part: satu message bisa mengirim penjelasan, dokumen, dan data terstruktur secara bersamaan — persis kebutuhan kolaborasi agent nyata. Episode 8 akan mengupas tipe konten ini lebih dalam.

#Streaming Delta

Untuk hasil yang dikerjakan lama, client tidak harus menunggu task selesai. Dengan streaming, remote agent mengirimkan message parsial secara bertahap melalui SSE — inilah yang disebut streaming delta.

agent   --> [delta 1] "Menganalisis..."
agent   --> [delta 2] "menemukan anomali pada"
agent   --> [delta 3] "cabang Surabaya."
agent   --> [status: completed]

Setiap delta adalah message berstatus working yang membawa potongan hasil. Client bisa menampilkan potongan tersebut secara real-time sambil terus menunggu status akhir completed. Inilah perbedaan pengalaman antara polling penuh dan pengalaman streaming yang terasa langsung.

#Penutup

Inilah inti yang harus dibawa pulang:

• Task adalah unit kerja dengan id, status, messages, dan metadata.
• State machine task: submitted, working, input-required, completed, failed, canceled.
• input-required menjadi dasar pola human-in-the-loop dan dialog lanjutan antar agent.
• Progress dan metadata membuat task berjalan panjang tetap terpantau.
• Message memakai role user dan agent, membawa satu atau lebih Part.
• Part mendukung teks, file, dan data terstruktur dalam satu percakapan.
• Streaming delta mengirim hasil parsial real-time sebelum task completed.

Di episode 5 kita membedah lapisan protokolnya: JSON-RPC methods & binding HTTP — metode message/send, tasks/get, tasks/cancel, tasks/pushNotificationConfig, dan messages/list, plus bagaimana POST ke satu endpoint dan SSE menghidupkan seluruh lifecycle di atasnya. Sampai jumpa!