Protocol extension

Declare the extension protocol

Add the URI of this document to the capabilities.extensions field of the AgentCard. This declares support for the extension protocol defined in this document.

The URI for this document is https://help.aliyun.com/en/model-studio/multimodal-integration-a2a-protocol.

Example:

{
  ...
  "capabilities": {
    "extensions": [
      {
        "uri": "https://help.aliyun.com/en/model-studio/multimodal-integration-a2a-protocol"
      },
      ...
    ],
    ...
  },
  ...
}

Field descriptions

Agent call request fields

Message

For more information about other Message fields, see Message.

Field name	Type	Required	Description
metadata	Map<String, Object>	Yes	The metadata associated with this message. user: User information device: Device information location: Location information userDefinedParams: Custom parameters commandResults: Instruction execution results images: Image information chatId: The ID of a conversation round

Example

{
  "jsonrpc": "2.0",
  "id": "request-1",
  "method": "message/send",
  "params": {
    "message": {
      "messageId": "msg-1",
      "kind": "message",
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "Will it rain today?"
        }
      ],
      "metadata": {
        "user": {
          "userId": "your_user_id"
        },
        "device": {
          "clientIp": "your_device_ip",
          "deviceId": "your_device_id"
        },
        "location": {
          "city": "your_city",
          "longitude": "your_longitude",
          "latitude": "your_latitude"
        },
        "userDefinedParams": {
          "param1": "value1"
        },
        "images": [
          {
            "type": "url",
            "value": "https://image_url****"
          }
        ],
        "chatId": "3eca6a13-fcfd-48b0-b1b7-34bfe735****"
      }
    }
  }
}

Agent call response fields

Artifact

Field name	Type	Required	Description
metadata	Map<String, Command[]>	No	The metadata associated with this message. Add extension fields to the last Artifact structure in the response.

Command

An instruction sent to the client.

Field name	Type	Required	Description
name	String	Yes	The instruction name.
params	Param[]	No	The instruction parameters.
commandRequestId	String	No	The request ID of the instruction.

Param

Field	Type	Required	Description
name	String	Yes	The instruction parameter name.
value	String	Yes	The instruction parameter value.
normValue	String	No	The normalized value of the instruction parameter.

Example

{
  "id": "request-1",
  "jsonrpc": "2.0",
  "result": {
    "id": "task-1",
    "contextId": "context-1",
    "kind": "task",
    "status": {
      "state": "completed",
      "timestamp": "2025-07-15T14:50:28.575338Z"
    },
    "artifacts": [
      {
        "artifactId": "c3fee4d5-7234-48a1-8d2c-cfb715c5ce9e",
        "parts": [
          {
            "kind": "text",
            "text": "The weather is sunny today, "
          }
        ]
      },
      {
        "artifactId": "c3fee4d5-7234-48a1-8d2c-cfb715c5ce9e",
        "parts": [
          {
            "kind": "text",
            "text": "no rain."
          }
        ],
        "metadata": {
          "commands": [
              {
                  "name": "instruction_name_to_send",
                  "params": [
                      {
                          "name": "parameter_name",
                          "value": "parameter_value",
                          "normValue": "normalized_parameter_value"
                      }
                  ],
                  "commandRequestId": "instruction_request_id"
              }
          ]
        }
      }
    ]
  }
}