feat(azure.ai.agents): add A2A endpoint protocol and agent card support (#7999)

* feat(azure.ai.agents): add A2A endpoint protocol and agent card support

Add support for setting A2A as an agent endpoint protocol and including
agent card metadata in create/update agent requests.

Changes:
- Add AgentProtocolA2A constant and IsInvokable() helper to distinguish
  invokable vs deploy-only protocols
- Add AgentEndpoint, AgentCard, and AgentCardSkill types to API models
- Add corresponding YAML types and fields on ContainerAgent
- Map YAML agentEndpoint/agentCard to API request in createAgentAPIRequest
- Add PatchAgent operation (HTTP PATCH) for partial agent updates
- Deploy path: create version first, then PATCH agent-level endpoint/card
- Protocol resolution: require --protocol flag when multiple protocols declared
- Invoke validation: use IsInvokable() to block non-invokable protocols
- Add comprehensive tests for all new types and behaviors

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: adamra-msft

cli/azd/extensions/azure.ai.agents/internal/cmd/helpers.go

@@ -724,8 +724,12 @@ func resolveAgentProtocol(
 }
 
 // protocolFromAgentYaml reads and parses the agent.yaml file at the given path
-// and extracts the protocol. Returns an error with a contextual suggestion when
-// the file cannot be read, parsed, or does not declare exactly one protocol.
+// and extracts the protocol to use for invocation. Returns an error with a
+// contextual suggestion when the file cannot be read, parsed, or does not
+// declare exactly one invocable protocol.
+//
+// When multiple protocols are declared (e.g. "responses" + "a2a"), the caller
+// must use --protocol to disambiguate.
 func protocolFromAgentYaml(
 	agentYamlPath string,
 ) (agent_api.AgentProtocol, error) {
@@ -753,15 +757,18 @@ func protocolFromAgentYaml(
 		)
 	}
 
-	switch len(hosted.Protocols) {
-	case 0:
+	if len(hosted.Protocols) == 0 {
 		return "", exterrors.Validation(
 			exterrors.CodeInvalidParameter,
 			"agent.yaml does not declare any protocols",
 			"add a protocols section to agent.yaml",
 		)
-	case 1:
-		p := strings.TrimSpace(hosted.Protocols[0].Protocol)
+	}
+
+	// Validate that no protocol entry has an empty value, and collect invocable ones.
+	var invocable []agent_api.AgentProtocol
+	for _, rec := range hosted.Protocols {
+		p := agent_api.AgentProtocol(strings.TrimSpace(rec.Protocol))
 		if p == "" {
 			return "", exterrors.Validation(
 				exterrors.CodeInvalidParameter,
@@ -770,19 +777,60 @@ func protocolFromAgentYaml(
 				"set a non-empty protocol value in agent.yaml",
 			)
 		}
-		return agent_api.AgentProtocol(p), nil
-	default:
+		if p.IsInvocable() {
+			invocable = append(invocable, p)
+		}
+	}
+
+	switch len(invocable) {
+	case 0:
 		names := make([]string, len(hosted.Protocols))
 		for i, p := range hosted.Protocols {
 			names[i] = p.Protocol
 		}
 		return "", exterrors.Validation(
 			exterrors.CodeInvalidParameter,
 			fmt.Sprintf(
-				"agent.yaml declares multiple protocols: %s",
+				"agent.yaml declares only non-invocable protocols: %s",
 				strings.Join(names, ", "),
 			),
-			"use --protocol to specify which protocol to use",
+			"azd can only invoke agents using the responses or invocations protocols",
 		)
+	case 1:
+		// Exactly one invocable protocol — but if the agent declares
+		// multiple protocols overall, require --protocol to be explicit.
+		if len(hosted.Protocols) > 1 {
+			return "", multiProtocolError(hosted.Protocols)
+		}
+		return invocable[0], nil
+	default:
+		return "", multiProtocolError(hosted.Protocols)
 	}
 }
+
+// multiProtocolError builds a validation error for agents that declare
+// multiple protocols, listing the valid invocable choices.
+func multiProtocolError(
+	protocols []agent_yaml.ProtocolVersionRecord,
+) error {
+	names := make([]string, len(protocols))
+	for i, p := range protocols {
+		names[i] = p.Protocol
+	}
+	supported := make([]string, len(agent_api.InvocableProtocols()))
+	for i, p := range agent_api.InvocableProtocols() {
+		supported[i] = string(p)
+	}
+	return exterrors.Validation(
+		exterrors.CodeInvalidParameter,
+		fmt.Sprintf(
+			"agent.yaml declares multiple protocols (%s)",
+			strings.Join(names, ", "),
+		),
+		fmt.Sprintf(
+			"use --protocol to specify which invocable protocol "+
+				"to use (supported: %s)",
+			strings.Join(supported, ", "),
+		),
+	)
+}

cli/azd/extensions/azure.ai.agents/internal/cmd/helpers_test.go

@@ -245,6 +245,20 @@ func TestProtocolFromAgentYaml(t *testing.T) {
 			wantErr:    true,
 			errContain: "declares multiple protocols",
 		},
+		{
+			name: "responses plus a2a requires --protocol",
+			yaml: "protocols:\n  - protocol: responses\n" +
+				"    version: \"1.0\"\n  - protocol: a2a\n" +
+				"    version: \"1.0\"\n",
+			wantErr:    true,
+			errContain: "declares multiple protocols",
+		},
+		{
+			name:       "a2a only is not invocable",
+			yaml:       "protocols:\n  - protocol: a2a\n    version: \"1.0\"\n",
+			wantErr:    true,
+			errContain: "non-invocable protocols",
+		},
 	}
 
 	for _, tt := range tests {

cli/azd/extensions/azure.ai.agents/internal/cmd/invoke.go

@@ -131,14 +131,11 @@ session automatically. Pass --new-session to force a reset.`,
 			}
 
 			if flags.protocol != "" {
-				switch agent_api.AgentProtocol(flags.protocol) {
-				case agent_api.AgentProtocolResponses,
-					agent_api.AgentProtocolInvocations:
-					// valid
-				default:
+				p := agent_api.AgentProtocol(flags.protocol)
+				if !p.IsInvocable() {
 					return exterrors.Validation(
 						exterrors.CodeInvalidParameter,
-						fmt.Sprintf("unsupported protocol %q", flags.protocol),
+						fmt.Sprintf("unsupported protocol %q for invocation", flags.protocol),
 						"supported protocols are: responses, invocations",
 					)
 				}

cli/azd/extensions/azure.ai.agents/internal/pkg/agents/agent_api/models.go

@@ -17,8 +17,29 @@ const (
 	AgentProtocolActivityProtocol AgentProtocol = "activity_protocol"
 	AgentProtocolInvocations      AgentProtocol = "invocations"
 	AgentProtocolResponses        AgentProtocol = "responses"
+	AgentProtocolA2A              AgentProtocol = "a2a"
 )
 
+// InvocableProtocols returns the set of protocols that azd can invoke directly.
+// A2A and activity_protocol are deployment-only — they cannot be used for local
+// or remote invocation through azd.
+func InvocableProtocols() []AgentProtocol {
+	return []AgentProtocol{
+		AgentProtocolResponses,
+		AgentProtocolInvocations,
+	}
+}
+
+// IsInvocable reports whether the protocol can be used for invocation through azd.
+func (p AgentProtocol) IsInvocable() bool {
+	switch p {
+	case AgentProtocolResponses, AgentProtocolInvocations:
+		return true
+	default:
+		return false
+	}
+}
+
 // AgentKind represents the different types of agents
 type AgentKind string
 
@@ -58,6 +79,27 @@ type ProtocolVersionRecord struct {
 	Version  string        `json:"version"`
 }
 
+// AgentEndpoint describes the endpoint protocols an agent supports.
+type AgentEndpoint struct {
+	Protocols []AgentProtocol `json:"protocols"`
+}
+
+// AgentCardSkill describes a single capability that an agent can perform.
+type AgentCardSkill struct {
+	ID          string   `json:"id"`
+	Name        string   `json:"name"`
+	Description string   `json:"description"`
+	Tags        []string `json:"tags,omitempty"`
+	Examples    []string `json:"examples,omitempty"`
+}
+
+// AgentCard is the A2A agent card that advertises an agent's capabilities.
+type AgentCard struct {
+	Description string           `json:"description"`
+	Version     *string          `json:"version,omitempty"`
+	Skills      []AgentCardSkill `json:"skills"`
+}
+
 // WorkflowDefinition represents a workflow agent
 type WorkflowDefinition struct {
 	AgentDefinition
@@ -88,7 +130,9 @@ type CreateAgentVersionRequest struct {
 
 // CreateAgentRequest represents a request to create an agent
 type CreateAgentRequest struct {
-	Name string `json:"name"`
+	Name          string         `json:"name"`
+	AgentEndpoint *AgentEndpoint `json:"agent_endpoint,omitempty"`
+	AgentCard     *AgentCard     `json:"agent_card,omitempty"`
 	CreateAgentVersionRequest
 }
 
@@ -97,6 +141,14 @@ type UpdateAgentRequest struct {
 	CreateAgentVersionRequest
 }
 
+// PatchAgentRequest represents a partial update to agent-level fields.
+// Only the fields set here are sent; Definition is intentionally excluded
+// to avoid accidentally clearing it.
+type PatchAgentRequest struct {
+	AgentEndpoint *AgentEndpoint `json:"agent_endpoint,omitempty"`
+	AgentCard     *AgentCard     `json:"agent_card,omitempty"`
+}
+
 // AgentIdentityInfo represents the instance identity assigned to an agent version.
 type AgentIdentityInfo struct {
 	PrincipalID string `json:"principal_id"`