Create your first surface

Start a new surface

Navigate to Surfaces in the sidebar.

Select Add Surface.

The Start a new surface dialog shows a list of starter templates. Each entry shows the template name, a short description, and its protocol badge. Select an A2A starter template for this guide.

The surface builder opens with the canvas already populated from the template.

The surface is given a default name automatically. To update it, select the blue Surface container on the canvas. The Name field is in the settings panel that opens on the right.

Configure the Access Point

The Access Point element defines how incoming traffic reaches the surface. Select it in the canvas to open its settings panel.

Under Listener, set the following fields:

The Surface Route banner at the top of the panel shows the composed full URL: the listen address, channel prefix, and custom path combined. Copy this URL. You will use it in Step 5.

Configure the Managed Agent

The Managed Agent element forwards requests to your backend service. Select it in the canvas to open its settings panel.

Set Target Endpoint URL to your backend service’s publicly accessible URL.

The Reached at banner shows the same composed URL as the Surface Route — the full address that requests must be sent to.

If required fields are missing:

• Visual alerts appear.
• Elements are highlighted.
• The Elements tab in the sidebar shows incomplete configuration.

Save the surface

Select the green ✓ button in the sidebar to save the surface.

• The surface is saved immediately.
• No restart is required.

A success notification confirms the surface was created, and you are returned to the Surfaces list where the new surface appears.

Send a test request

Use the URL from the Surface Route banner on the Access Point element (Step 2). Replace <YOUR_GATEWAY_HOST> with the listen address and <YOUR_SURFACE_PATH> with the composed path, or copy the full URL directly into the command below.

curl -k -X POST "https://<YOUR_GATEWAY_HOST><YOUR_SURFACE_PATH>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "message/send",
    "id": "test-001",
    "params": {
      "message": {
        "role": "user",
        "messageId": "msg-001",
        "parts": [{ "kind": "text", "text": "Hello from the quickstart" }]
      }
    }
  }'

If using the echo server, a successful response returns 200 OK with a JSON body containing the echoed method, path, headers, and body. The full request is also printed to the echo server’s terminal. For your own backend, a successful response depends on your service.