fix(agents): return actionable auth error when Graph token is missing

cli/azd/extensions/azure.ai.agents/cspell.yaml

@@ -1,4 +1,5 @@
 words:
+  - aadsts
   - aiservices
   - agentserver
   - anonymousconnection

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

@@ -6,6 +6,7 @@ package cmd
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -112,6 +113,16 @@ func postdeployHandler(ctx context.Context, azdClient *azdext.AzdClient, args *a
 	// Ensure agent identity RBAC is configured when vnext is enabled.
 	// Runs post-deploy because the platform provisions the identity during agent deployment.
 	if err := project.EnsureAgentIdentityRBAC(ctx, azdClient); err != nil {
+		// If the error is already structured, return it unchanged so gRPC
+		// serialization preserves the message, code, and suggestion.
+		var localErr *azdext.LocalError
+		if errors.As(err, &localErr) {
+			return err
+		}
+		var svcErr *azdext.ServiceError
+		if errors.As(err, &svcErr) {
+			return err
+		}
 		return fmt.Errorf("agent identity RBAC setup failed: %w", err)
 	}
 

cli/azd/extensions/azure.ai.agents/internal/exterrors/codes.go

@@ -62,6 +62,7 @@ const (
 	CodeNotLoggedIn              = "not_logged_in"
 	CodeLoginExpired             = "login_expired"
 	CodeAuthFailed               = "auth_failed"
+	CodeRbacAuthFailed           = "rbac_auth_failed"
 )
 
 // Error codes for compatibility errors.

cli/azd/extensions/azure.ai.agents/internal/project/agent_identity_rbac.go

@@ -5,13 +5,16 @@ package project
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"os"
 	"strconv"
 	"strings"
 	"sync"
 	"time"
 
+	"azureaiagent/internal/exterrors"
+
 	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
 	"github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/authorization/armauthorization/v3"
 	"github.com/azure/azure-dev/cli/azd/pkg/azdext"
@@ -183,6 +186,15 @@ func ensureAgentIdentityRBACWithCred(
 	for attempt := range identityLookupMaxAttempts {
 		agentIdentities, err = discoverAgentIdentity(ctx, graphClient, displayName)
 		if err != nil {
+			if isCredentialAuthError(err) {
+				return exterrors.Auth(
+					exterrors.CodeRbacAuthFailed,
+					"agent identity RBAC setup failed: "+
+						"could not acquire a Microsoft Graph token",
+					"run 'azd auth login --scope https://graph.microsoft.com/.default' "+
+						"and re-run 'azd deploy'",
+				)
+			}
 			return fmt.Errorf("failed to discover agent identity: %w", err)
 		}
 		if len(agentIdentities) > 0 {
@@ -453,3 +465,16 @@ func extractSubscriptionID(resourceID string) string {
 	}
 	return ""
 }
+
+// isCredentialAuthError returns true when an error originates from the Azure Identity
+// library failing to acquire a token (e.g. expired login, missing scope consent).
+func isCredentialAuthError(err error) bool {
+	if err == nil {
+		return false
+	}
+	if _, ok := errors.AsType[*azidentity.AuthenticationFailedError](err); ok {
+		return true
+	}
+	// Fallback: AADSTS codes may appear in errors not wrapped as AuthenticationFailedError.
+	return strings.Contains(err.Error(), "AADSTS")
+}

cli/azd/extensions/azure.ai.agents/internal/project/agent_identity_rbac_test.go

@@ -4,8 +4,12 @@
 package project
 
 import (
+	"errors"
+	"fmt"
+	"net/http"
 	"testing"
 
+	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -198,3 +202,54 @@ func TestConstants(t *testing.T) {
 	assert.Equal(t, "5e0bd9bd-7b93-4f28-af87-19fc36ad61bd", roleCognitiveServicesOpenAIUser)
 	assert.Equal(t, "3913510d-42f4-4e42-8a64-420c390055eb", roleMonitoringMetricsPublisher)
 }
+
+func TestIsCredentialAuthError(t *testing.T) {
+	tests := []struct {
+		name string
+		err  error
+		want bool
+	}{
+		{
+			name: "nil error",
+			err:  nil,
+			want: false,
+		},
+		{
+			name: "unrelated error",
+			err:  fmt.Errorf("network timeout"),
+			want: false,
+		},
+		{
+			name: "typed AuthenticationFailedError",
+			err: &azidentity.AuthenticationFailedError{
+				RawResponse: &http.Response{StatusCode: 401},
+			},
+			want: true,
+		},
+		{
+			name: "wrapped AuthenticationFailedError",
+			err: fmt.Errorf("graph query failed: %w",
+				&azidentity.AuthenticationFailedError{
+					RawResponse: &http.Response{StatusCode: 401},
+				}),
+			want: true,
+		},
+		{
+			name: "AADSTS error code fallback",
+			err:  fmt.Errorf("AADSTS70043: The refresh token has expired"),
+			want: true,
+		},
+		{
+			name: "string-only error without AADSTS not matched",
+			err:  errors.New("AzureDeveloperCLICredential: please run azd auth login"),
+			want: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := isCredentialAuthError(tt.err)
+			assert.Equal(t, tt.want, got)
+		})
+	}
+}