6.3 A2A & ACP

Tujuan bab

Setelah bab ini kamu bisa:

• Memanggil agent jarak jauh lewat A2A dan menjelaskan peran agent card
• Menjalankan coding agent sebagai tool Mastra lewat ACP
• Menjelaskan apa itu SDK agents dan kapan ia dipilih
• Memilih di antara keempat jenis connection berdasarkan batas yang diseberangi

Prasyarat

• 6.2 Mastra sebagai MCP Server

A2A — memanggil agent milik orang lain

MCP menyeberangi batas ke tool. A2A menyeberangi batas ke agent utuh.

Perbedaannya nyata. Sebuah tool adalah fungsi: kamu memanggilnya, ia mengembalikan hasil. Sebuah agent punya penalarannya sendiri, tool-nya sendiri, memory-nya sendiri — dan semuanya tetap privat di sisi pemiliknya. Kamu hanya melihat endpoint.

Mastra mendukung A2A versi 0.3.0.

// src/mastra/connections/remote.ts
import { A2AAgent } from '@mastra/core/a2a'

const agent = new A2AAgent({
  url: 'https://agent.example.com/.well-known/agent-card.json',
})

const result = await agent.generate('Ringkas laporan terbaru')
console.log(result.text)

Perhatikan bahwa A2AAgent diimpor dari @mastra/core/a2a — tidak perlu paket tambahan.

Agent card

Penemuan di A2A bekerja lewat agent card: dokumen JSON yang disajikan dari URL yang sudah disepakati. Isinya menggambarkan agent jarak jauh itu dan memuat URL eksekusi yang menerima permintaan JSON-RPC.

{
  "protocolVersion": "0.3.0",
  "name": "Weather Agent",
  "description": "Menyediakan informasi cuaca.",
  "url": "https://agent.example.com/api/a2a/weather-agent",
  "version": "1.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "stateTransitionHistory": false
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [
    {
      "id": "weather",
      "name": "weather",
      "description": "Mengambil kondisi cuaca untuk sebuah lokasi.",
      "tags": ["tool"]
    }
  ]
}

Kalau kamu memakai apiPrefix bawaan Mastra Server yaitu /api, sebuah agent yang terdaftar sebagai weather-agent otomatis mengekspos:

• Agent card: /api/.well-known/weather-agent/agent-card.json
• Endpoint eksekusi: /api/a2a/weather-agent

Artinya agent Mastra-mu sudah bisa dipanggil lewat A2A begitu servernya berjalan — kamu tidak perlu menulis kode tambahan untuk menjadi penyedia.

Tugas yang berjalan lama

A2A mewakili pekerjaan sebagai message dan task. Task adalah unit kerja bernegara: punya ID dan status siklus hidup. Klien bisa mengikuti pekerjaan yang berjalan lama, mengirim giliran lanjutan, membatalkan, atau berlangganan ulang setelah koneksi terputus.

Ini yang membedakan A2A dari sekadar memanggil HTTP endpoint biasa. Untuk pekerjaan yang butuh jam, bukan detik, mekanisme itu yang kamu butuhkan.

ACP — menjalankan coding agent

ACP (Agent Client Protocol) menyeberangi batas yang sangat spesifik: ke proses coding agent seperti Claude Code, Cline, OpenCode, Amp, atau Codex.

// src/mastra/connections/coding.ts
import { AcpAgent } from '@mastra/acp'

const agent = new AcpAgent({
  id: 'coding-agent',
  description: 'Memeriksa dan mengubah kode',
  command: 'claude',
  args: ['--acp'],
  persistSession: false,
})

const result = await agent.generate('Tinjau proyek ini')
console.log(result.text)

Paket @mastra/acp membutuhkan @mastra/core versi 1.34.0 atau lebih baru.

Cara kerjanya

@mastra/acp menjalankan perintah coding agent sebagai proses anak, dan berkomunikasi dengannya memakai JSON yang dipisah baris lewat standard input dan output.

Dua hal yang menonjol dari alur itu.

Berkas melewati Workspace Mastra. Baca dan tulis berkas oleh coding agent tidak langsung ke sistem berkas, melainkan melalui abstraksi Workspace yang kamu sediakan. Artinya coding agent bekerja di dalam ruang yang kamu tentukan, bukan di seluruh mesinmu. Ini dibahas lagi di 7.4.

Permintaan izin ditangani. Coding agent bisa meminta izin sebelum membaca berkas, menulis berkas, atau menjalankan tindakan — dan klien ACP menanganinya.

Agent yang kompatibel

Setiap executable yang mengimplementasikan ACP lewat stdin/stdout bisa dipakai. Tidak perlu paket Mastra khusus per agent — pasang agent-nya, lalu berikan perintah peluncurannya:

Agent	command	args
Cline	cline	['--acp']
OpenCode	opencode	['acp']
Gemini CLI	gemini	['--acp']

Flag peluncuran berubah antar rilis

Dokumentasi Mastra mencatat bahwa tiap agent mendokumentasikan mode ACP-nya sendiri, dan flag peluncurannya berubah antar rilis. Tabel di atas adalah keadaan saat materi ini ditulis; periksa dokumentasi agent yang bersangkutan sebelum memakainya.

persistSession

Opsi ini menentukan apakah proses coding agent tetap hidup di antara pemanggilan:

Nilai	Perilaku	Cocok untuk
false	Proses dihentikan setelah tiap prompt	Tugas sekali jalan yang berdiri sendiri
Default AcpAgent	Proses dipertahankan dan dipakai ulang	Percakapan berlanjut yang butuh konteks sesi

Mempertahankan sesi berarti coding agent mengingat apa yang sudah ia lakukan — berguna untuk pekerjaan bertahap, tapi berarti ada proses yang hidup dan memakai sumber daya.

SDK agents — runtime tetap milik penyedia

Jenis connection keempat menyelesaikan masalah yang berbeda dari ketiganya.

Kadang kamu ingin memakai agent dari SDK penyedia — Claude Agent SDK, Cursor Agent SDK, atau OpenAI Agents SDK — tanpa menggantikan runtime-nya. SDK itu tetap memegang kendali atas tool, izin, dan agent loop-nya sendiri.

// src/mastra/connections/sdk.ts
import { OpenAISDKAgent } from '@mastra/openai'

const agent = new OpenAISDKAgent({
  id: 'openai-agent',
  description: 'Menjawab pertanyaan tentang proyek',
  sdkOptions: {
    name: 'Project assistant',
    model: 'gpt-5',
  },
})

Kapan ini masuk akal: kamu sudah punya agent yang berjalan baik di SDK penyedia, dan ingin memakainya dari Mastra tanpa menulis ulang. Mastra menjadi lapisan orkestrasi; runtime agent-nya tetap di tempat asalnya.

Memilih di antara keempatnya

Ringkasnya, dalam satu tabel:

	Yang dijangkau	Runtime dimiliki oleh	Paket
MCP	Tool dan resource	Server MCP	@mastra/mcp
A2A	Agent jarak jauh	Layanan lain	@mastra/core/a2a
ACP	Proses coding agent	Proses anak di mesinmu	@mastra/acp
SDK agents	Agent SDK penyedia	SDK penyedia	@mastra/openai, dll.

Kesalahan umum

Gejala: Memakai A2A untuk sesuatu yang sebenarnya cukup satu tool, lalu merasa protokolnya terlalu rumit untuk hasil yang didapat. Penyebab: Salah memilih batas. A2A membawa serta agent card, task bernegara, dan siklus hidup — semuanya berguna untuk mendelegasikan pekerjaan ke agent lain, dan semuanya berlebihan untuk memanggil satu fungsi. Perbaikan: Tanyakan apakah yang di seberang punya penalaran sendiri. Kalau tidak — kalau ia hanya menerima masukan dan mengembalikan keluaran — itu tool, dan MCP atau HTTP biasa lebih tepat.

Gejala: Perintah ACP gagal dijalankan, dengan pesan bahwa perintahnya tidak ditemukan. Penyebab: Bisa karena agent-nya memang belum terpasang, atau karena flag peluncurannya sudah berubah di versi yang kamu pakai. Perbaikan: Pastikan perintahnya bisa dijalankan langsung dari terminal lebih dulu, lalu periksa dokumentasi agent tersebut untuk flag mode ACP yang berlaku sekarang.

Coba sendiri

Tantangan: Bab ini membahas empat protokol yang tiap satunya butuh sistem di seberang. Alih-alih memaksakan keempatnya, latihan ini fokus pada satu yang bisa kamu buktikan sendiri tanpa bantuan pihak lain: A2A dua arah, dengan kedua sisi milikmu.

Ketentuan:

1. Jalankan aplikasi Mastra pertama yang punya agent bernama spesialis-agent — beri ia satu keahlian sempit, misalnya mengubah teks menjadi ringkasan terstruktur
2. Jalankan servernya, lalu ambil agent card-nya lewat browser atau curl. Catat URL lengkapnya
3. Baca isi agent card dan cocokkan dengan definisi agent-mu — bagian mana yang berasal dari name, description, dan id
4. Buat aplikasi Mastra kedua di port berbeda, yang memakai A2AAgent untuk memanggil agent pertama itu
5. Panggil dari aplikasi kedua dan pastikan jawabannya benar
6. Matikan aplikasi pertama, lalu panggil lagi dari aplikasi kedua dan amati bagaimana kegagalannya muncul
7. Tulis satu paragraf: apa yang tidak terlihat oleh aplikasi kedua tentang aplikasi pertama?

Checklist penerimaan:

• [ ] Agent card berhasil diambil dan isinya sesuai dengan definisi agent
• [ ] Kamu bisa menunjukkan bagian agent card mana yang berasal dari properti mana pada new Agent()
• [ ] Aplikasi kedua berhasil memanggil agent di aplikasi pertama
• [ ] Kegagalan di langkah 6 tertangani, bukan membuat aplikasi kedua jatuh
• [ ] Paragraf di langkah 7 menyebutkan minimal tiga hal yang tetap privat: misalnya tool, instruksi, memory, atau model yang dipakai
• [ ] Kamu bisa menjelaskan kapan kasus ini sebaiknya memakai MCP saja alih-alih A2A

Petunjuk: Langkah 7 adalah inti pemahaman bab ini. Yang membuat A2A berbeda dari sekadar HTTP endpoint bukan formatnya, melainkan apa yang disembunyikannya. Aplikasi kedua tahu ada agent yang bisa meringkas; ia tidak tahu model apa yang dipakai, tool apa yang dipanggil, atau apakah ada memory di baliknya. Itu batas yang sehat antar tim.

Ikhtisar

• A2A menyeberangi batas ke agent utuh milik layanan lain. Mastra mendukung versi 0.3.0, dan A2AAgent ada di @mastra/core/a2a.
• Penemuan lewat agent card — JSON di URL yang disepakati. Agent Mastra yang terdaftar otomatis mengeksposnya di /api/.well-known/<id>/agent-card.json.
• A2A punya task bernegara dengan ID dan siklus hidup — untuk pekerjaan panjang yang perlu dipantau, dibatalkan, atau dilanjutkan setelah terputus.
• ACP menjalankan proses coding agent lewat stdin/stdout. Berkasnya melewati Workspace Mastra, bukan langsung ke sistem berkas.
• Flag peluncuran agent ACP berubah antar rilis — periksa dokumentasi agent yang bersangkutan.
• SDK agents memakai agent dari SDK penyedia sambil membiarkan runtime, tool, dan agent loop tetap milik SDK itu.
• Cara memilih: tool → MCP; agent jarak jauh → A2A; proses coding agent → ACP; runtime penyedia → SDK agents.

Lanjut ke mana

Bagian 6 selesai. Agent-mu kini bisa menjangkau ke luar dirinya. Berikutnya: apa yang terjadi ketika pekerjaan tidak selesai dalam satu permintaan — Bagian 7 — Harness & Subagents.