feat(azure.ai.agents): add doctor local checks 4-6 (agent service, project endpoint, agent.yaml)

Phase 4.3 of PR Azure#8057. Extends the doctor package with the last three
MVP local checks, completing the local-checks slate the spec calls for.

What the three new checks do (in plain English):

- local.agent-service-detected — re-fetches the project config and
  counts services whose `host` is `azure.ai.agent`. Passes with the
  count and sorted service names so the user can verify at a glance
  what the doctor saw. Fails with "Run `azd ai agent init`" when no
  agent service is configured. Skip-cascades off local.azure-yaml.

- local.project-endpoint-set — reads AZURE_AI_PROJECT_ENDPOINT via the
  EnvironmentService gRPC. Empty EnvName defaults to the current azd
  environment, so this check does not need to re-resolve the env
  name. Fails with "Run `azd provision` ... or `azd env set ...`" when
  the value is missing/whitespace-only. Skip-cascades off
  local.environment-selected.

- local.agent-yaml-valid — for each agent service in azure.yaml,
  reads <projectPath>/<svc.RelativePath>/agent.yaml and parses it as
  agent_yaml.ContainerAgent. Collects ALL failures rather than
  short-circuiting so multi-service projects get one actionable
  report listing every offending service. Skip-cascades off
  local.agent-service-detected.

Architectural notes:

- Local `agentHost = "azure.ai.agent"` constant mirrors
  cmd.AiAgentHost (init.go:113) and nextstep.agentHost (state.go:28).
  The doctor package cannot import cmd (cmd will import doctor for
  Cobra wiring in Phase 4.4, which would form a cycle).

- protobuf `Services` is a map, so iteration order is non-deterministic.
  Both checks 4 and 6 sort by service name before formatting messages
  and Details, so output is reproducible across runs (and across
  goroutines once the runner gains concurrency in Phase 5).

- Transport-error suggestion swap (Phase 4.2.1's isTransportFailure)
  applies to all three new checks, matching the pattern established
  in checks 2 and 3.

- `priorFailed(prior, id)` is a small new helper used by all three
  cascades. The Phase 4.2 checks (1-3) inline their own skip logic
  because they don't have any predecessors — extracting them is a
  separate refactor candidate, not in scope here.

Files changed:

- internal/cmd/doctor/checks_local.go — NewLocalChecks now returns
  6 entries (3 → 6) in the canonical execution order.

- internal/cmd/doctor/checks_project.go — new file. Three Check
  factories, `validateAgentYAML` helper, `priorFailed` helper, and
  the `agentHost` / `projectEndpointVar` constants.

- internal/cmd/doctor/checks_local_test.go — `fakeEnvironmentServer`
  gains `valueResp` / `valueErr` fields and a `GetValue` method
  (Phase 4.3 check 5 needs it). `TestNewLocalChecks_OrderAndIDs`
  updated for the new 3 → 6 size and ordering.

- internal/cmd/doctor/checks_project_test.go — new file. ~25 test
  cases across all three checks: cascade-skip behavior, transport-
  error suggestion swap, nil-response handling, malformed-yaml,
  missing-file, mixed valid+invalid, multi-agent ordering. Real
  temp-dir agent.yaml files for check 6 (t.TempDir() + writeYAML
  helper).

Pre-flight: gofmt clean, go vet clean, go build clean, doctor tests
10.1s (38 tests, all green), full extension test suite green,
golangci-lint 0 issues, cspell 0 issues, go fix no-op.

No live smoke yet — doctor command is not Cobra-wired until Phase
4.4. Logic is locked by unit tests at the check level.

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

Author: Antriksh Jain

cli/azd/extensions/azure.ai.agents/internal/cmd/doctor/checks_local.go

@@ -42,13 +42,17 @@ type Dependencies struct {
 }
 
 // NewLocalChecks returns the canonical sequence of local doctor checks
-// in execution order. Phase 4.2 covers checks 1-3; phase 4.3 will append
-// checks 4-6 (agent service, project endpoint, agent.yaml).
+// in execution order. Phase 4.2 covered checks 1-3; Phase 4.3 adds
+// checks 4-6 (agent service detected, project endpoint set, agent.yaml
+// valid).
 func NewLocalChecks(deps Dependencies) []Check {
 	return []Check{
 		newCheckGRPCAndVersion(deps),
 		newCheckProjectConfig(deps),
 		newCheckEnvironmentSelected(deps),
+		newCheckAgentServiceDetected(deps),
+		newCheckProjectEndpointSet(deps),
+		newCheckAgentYAMLValid(deps),
 	}
 }
 

cli/azd/extensions/azure.ai.agents/internal/cmd/doctor/checks_local_test.go

@@ -37,6 +37,10 @@ type fakeEnvironmentServer struct {
 	azdext.UnimplementedEnvironmentServiceServer
 	resp *azdext.EnvironmentResponse
 	err  error
+
+	// GetValue stub fields (Phase 4.3).
+	valueResp *azdext.KeyValueResponse
+	valueErr  error
 }
 
 func (s *fakeEnvironmentServer) GetCurrent(
@@ -48,6 +52,15 @@ func (s *fakeEnvironmentServer) GetCurrent(
 	return s.resp, nil
 }
 
+func (s *fakeEnvironmentServer) GetValue(
+	context.Context, *azdext.GetEnvRequest,
+) (*azdext.KeyValueResponse, error) {
+	if s.valueErr != nil {
+		return nil, s.valueErr
+	}
+	return s.valueResp, nil
+}
+
 // newTestAzdClient spins up an in-process gRPC server with the supplied
 // Project + Environment server stubs and returns a client wired to its
 // address. The server, listener, and client are all torn down via
@@ -430,7 +443,7 @@ func TestNewLocalChecks_OrderAndIDs(t *testing.T) {
 	t.Parallel()
 
 	checks := NewLocalChecks(Dependencies{})
-	require.Len(t, checks, 3)
+	require.Len(t, checks, 6)
 
 	want := []struct {
 		id     string
@@ -440,6 +453,9 @@ func TestNewLocalChecks_OrderAndIDs(t *testing.T) {
 		{"local.grpc-extension", "azd extension reachable", false},
 		{"local.azure-yaml", "azure.yaml present and parseable", false},
 		{"local.environment-selected", "azd environment selected", false},
+		{"local.agent-service-detected", "agent service in azure.yaml", false},
+		{"local.project-endpoint-set", "AZURE_AI_PROJECT_ENDPOINT set", false},
+		{"local.agent-yaml-valid", "agent.yaml valid (per service)", false},
 	}
 	for i, w := range want {
 		require.Equal(t, w.id, checks[i].ID, "index %d", i)

cli/azd/extensions/azure.ai.agents/internal/cmd/doctor/checks_project.go

@@ -0,0 +1,279 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package doctor
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"azureaiagent/internal/pkg/agents/agent_yaml"
+
+	"github.com/azure/azure-dev/cli/azd/pkg/azdext"
+	"gopkg.in/yaml.v3"
+)
+
+// agentHost is the value used in azure.yaml for an azure.ai.agent service.
+// Must stay in sync with cmd.AiAgentHost ("azure.ai.agent") in
+// `internal/cmd/init.go`; duplicated here so the doctor package does not
+// have to import cmd (which would form an import cycle once the Cobra
+// wiring lands in Phase 4.4).
+const agentHost = "azure.ai.agent"
+
+// projectEndpointVar is the azd environment variable that points at the
+// Foundry project. Must stay in sync with the rest of the extension
+// (`agent_context.go`, `listen.go`, `service_target_agent.go`).
+const projectEndpointVar = "AZURE_AI_PROJECT_ENDPOINT"
+
+// newCheckAgentServiceDetected produces Check `local.agent-service-detected`.
+// It re-fetches the project config and counts services whose `host` is
+// `azure.ai.agent`. Pass surfaces the count and service names so users
+// can verify the doctor saw what they expected; Fail tells them to run
+// `azd ai agent init` to scaffold one. Skips when the gRPC client is
+// unavailable or when `local.azure-yaml` failed.
+func newCheckAgentServiceDetected(deps Dependencies) Check {
+	return Check{
+		ID:   "local.agent-service-detected",
+		Name: "agent service in azure.yaml",
+		Fn: func(ctx context.Context, _ Options, prior []Result) Result {
+			if deps.AzdClient == nil {
+				return Result{Status: StatusSkip, Message: "skipped: azd extension not reachable"}
+			}
+			if priorFailed(prior, "local.azure-yaml") {
+				return Result{Status: StatusSkip, Message: "skipped: azure.yaml check failed"}
+			}
+
+			resp, err := deps.AzdClient.Project().Get(ctx, &azdext.EmptyRequest{})
+			if err != nil {
+				suggestion := "Run `azd ai agent init` to add an azure.ai.agent service to azure.yaml."
+				if isTransportFailure(err) {
+					suggestion = "Re-run via `azd ai agent doctor`; the extension cannot reach azd's gRPC channel."
+				}
+				return Result{
+					Status:     StatusFail,
+					Message:    fmt.Sprintf("failed to get project config: %v", err),
+					Suggestion: suggestion,
+				}
+			}
+			if resp == nil || resp.Project == nil {
+				return Result{
+					Status:     StatusFail,
+					Message:    "failed to get project config (is there an azure.yaml?)",
+					Suggestion: "Run from a directory containing `azure.yaml`, or initialize one with `azd init`.",
+				}
+			}
+
+			var agentServices []string
+			for _, s := range resp.Project.Services {
+				if s != nil && s.Host == agentHost {
+					agentServices = append(agentServices, s.Name)
+				}
+			}
+			// Sort for deterministic display: protobuf Services is a map,
+			// so iteration order is unstable across runs.
+			sort.Strings(agentServices)
+			if len(agentServices) == 0 {
+				return Result{
+					Status:     StatusFail,
+					Message:    "no `azure.ai.agent` service found in azure.yaml",
+					Suggestion: "Run `azd ai agent init` to add an azure.ai.agent service to azure.yaml.",
+				}
+			}
+			return Result{
+				Status: StatusPass,
+				Message: fmt.Sprintf(
+					"%d agent service(s) in azure.yaml: %s",
+					len(agentServices), strings.Join(agentServices, ", ")),
+				Details: map[string]any{
+					"agentServices":     agentServices,
+					"agentServiceCount": len(agentServices),
+				},
+			}
+		},
+	}
+}
+
+// newCheckProjectEndpointSet produces Check `local.project-endpoint-set`.
+// It reads `AZURE_AI_PROJECT_ENDPOINT` from the currently-selected azd
+// environment via the EnvironmentService gRPC. An empty EnvName in
+// GetEnvRequest defaults to the current environment, so this check does
+// not need to re-resolve the environment name itself.
+//
+// Skips when the gRPC client is unavailable or when
+// `local.environment-selected` failed. Fails when the value is missing
+// or empty, telling users to run `azd provision` (the production path)
+// or `azd env set` (for pointing at an existing project).
+func newCheckProjectEndpointSet(deps Dependencies) Check {
+	return Check{
+		ID:   "local.project-endpoint-set",
+		Name: "AZURE_AI_PROJECT_ENDPOINT set",
+		Fn: func(ctx context.Context, _ Options, prior []Result) Result {
+			if deps.AzdClient == nil {
+				return Result{Status: StatusSkip, Message: "skipped: azd extension not reachable"}
+			}
+			if priorFailed(prior, "local.environment-selected") {
+				return Result{Status: StatusSkip, Message: "skipped: environment check failed"}
+			}
+
+			resp, err := deps.AzdClient.Environment().GetValue(ctx, &azdext.GetEnvRequest{
+				Key: projectEndpointVar,
+			})
+			if err != nil {
+				suggestion := fmt.Sprintf(
+					"Run `azd provision` to create the Foundry project, or `azd env set %s <https://...>` to point at an existing one.",
+					projectEndpointVar)
+				if isTransportFailure(err) {
+					suggestion = "Re-run via `azd ai agent doctor`; the extension cannot reach azd's gRPC channel."
+				}
+				return Result{
+					Status:     StatusFail,
+					Message:    fmt.Sprintf("failed to read %s: %v", projectEndpointVar, err),
+					Suggestion: suggestion,
+				}
+			}
+			if resp == nil || strings.TrimSpace(resp.Value) == "" {
+				return Result{
+					Status:  StatusFail,
+					Message: fmt.Sprintf("%s is not set in the current azd environment", projectEndpointVar),
+					Suggestion: fmt.Sprintf(
+						"Run `azd provision` to create the Foundry project, or `azd env set %s <https://...>` to point at an existing one.",
+						projectEndpointVar),
+				}
+			}
+			return Result{
+				Status:  StatusPass,
+				Message: fmt.Sprintf("%s = %s", projectEndpointVar, resp.Value),
+				Details: map[string]any{
+					"projectEndpoint": resp.Value,
+				},
+			}
+		},
+	}
+}
+
+// newCheckAgentYAMLValid produces Check `local.agent-yaml-valid`. For
+// each agent service in azure.yaml, it reads `<projectPath>/<svc.RelativePath>/agent.yaml`
+// and parses it as `agent_yaml.ContainerAgent`. Fails when any service's
+// file is missing, unreadable, or fails to parse — collecting all errors
+// rather than short-circuiting so multi-service projects get a single
+// actionable report.
+//
+// Skips when the gRPC client is unavailable or when
+// `local.agent-service-detected` failed (no services to validate). The
+// suggestion mirrors the spec's "fix YAML" guidance.
+func newCheckAgentYAMLValid(deps Dependencies) Check {
+	return Check{
+		ID:   "local.agent-yaml-valid",
+		Name: "agent.yaml valid (per service)",
+		Fn: func(ctx context.Context, _ Options, prior []Result) Result {
+			if deps.AzdClient == nil {
+				return Result{Status: StatusSkip, Message: "skipped: azd extension not reachable"}
+			}
+			if priorFailed(prior, "local.agent-service-detected") {
+				return Result{Status: StatusSkip, Message: "skipped: no agent services detected"}
+			}
+
+			resp, err := deps.AzdClient.Project().Get(ctx, &azdext.EmptyRequest{})
+			if err != nil {
+				suggestion := "Run from a directory containing `azure.yaml`, or initialize one with `azd init`."
+				if isTransportFailure(err) {
+					suggestion = "Re-run via `azd ai agent doctor`; the extension cannot reach azd's gRPC channel."
+				}
+				return Result{
+					Status:     StatusFail,
+					Message:    fmt.Sprintf("failed to get project config: %v", err),
+					Suggestion: suggestion,
+				}
+			}
+			if resp == nil || resp.Project == nil {
+				return Result{
+					Status:     StatusFail,
+					Message:    "failed to get project config (is there an azure.yaml?)",
+					Suggestion: "Run from a directory containing `azure.yaml`, or initialize one with `azd init`.",
+				}
+			}
+
+			projectPath := resp.Project.Path
+			// Collect agent service entries in a stable order. protobuf
+			// `Services` is a map, so iteration order is non-deterministic
+			// — sorting by service name keeps the failure list (and the
+			// validatedPaths Detail) reproducible.
+			type agentSvc struct {
+				name string
+				rel  string
+			}
+			var agents []agentSvc
+			for _, s := range resp.Project.Services {
+				if s == nil || s.Host != agentHost {
+					continue
+				}
+				agents = append(agents, agentSvc{name: s.Name, rel: s.RelativePath})
+			}
+			sort.Slice(agents, func(i, j int) bool { return agents[i].name < agents[j].name })
+
+			var validatedPaths []string
+			var failures []string
+			for _, a := range agents {
+				yamlPath := filepath.Join(projectPath, a.rel, "agent.yaml")
+				if pathErr := validateAgentYAML(yamlPath); pathErr != nil {
+					failures = append(failures, fmt.Sprintf("%s: %v", a.name, pathErr))
+					continue
+				}
+				validatedPaths = append(validatedPaths, yamlPath)
+			}
+
+			if len(failures) > 0 {
+				return Result{
+					Status: StatusFail,
+					Message: fmt.Sprintf(
+						"agent.yaml validation failed for %d service(s): %s",
+						len(failures), strings.Join(failures, "; ")),
+					Suggestion: "Fix the YAML syntax or ensure agent.yaml exists in each service directory.",
+					Details: map[string]any{
+						"failures":       failures,
+						"validatedPaths": validatedPaths,
+					},
+				}
+			}
+
+			return Result{
+				Status:  StatusPass,
+				Message: fmt.Sprintf("agent.yaml valid for %d service(s)", len(validatedPaths)),
+				Details: map[string]any{
+					"validatedPaths": validatedPaths,
+				},
+			}
+		},
+	}
+}
+
+// validateAgentYAML reads the file at path and ensures it parses as a
+// ContainerAgent. Returns the underlying read/parse error verbatim so
+// the caller can attribute it to the offending service.
+func validateAgentYAML(path string) error {
+	data, err := os.ReadFile(path) //nolint:gosec // G304: path is constructed from azd-resolved project root + service-relative path
+	if err != nil {
+		return fmt.Errorf("read %s: %w", path, err)
+	}
+	var parsed agent_yaml.ContainerAgent
+	if err := yaml.Unmarshal(data, &parsed); err != nil {
+		return fmt.Errorf("parse %s: %w", path, err)
+	}
+	return nil
+}
+
+// priorFailed reports whether the prior results contain a Fail entry
+// for the given check ID. Used for skip-cascade decisions across the
+// local-checks chain.
+func priorFailed(prior []Result, id string) bool {
+	for _, p := range prior {
+		if p.ID == id && p.Status == StatusFail {
+			return true
+		}
+	}
+	return false
+}