Azure / Azure/azure-dev

Create a clearer get started pathway

Open
#7,057 2 comments 0 reactions 0 assignees View on GitHub
agentic area/ux feature golden-path
Dominant language
Go
Stars
569
Forks
364
Avg merge
2d 19h
Merged PRs (30d)
136

Description

## Current experience

When an AI agent (e.g., Copilot, Amp) is asked to **create a new azd project from scratch** — such as *"Create an azd project that deploys a container app"* — it fails because azd does not provide a clear, agent-friendly pathway for greenfield project creation.

### What the agent experiences

1. **No way to discover or select starter templates programmatically.** `azd init --template` requires the user (or agent) to already know the template name/URL. There is no non-interactive CLI command that returns a curated list of **starter** templates with metadata (e.g., tags like `container-app`, `function-app`, `web-app`) that an agent can filter and select from.

2. **`azd add` is interactive-only.** The compose workflow (`azd add`) prompts the user to select components via an interactive console UI. There is no `--non-interactive` JSON/flag-based equivalent that an agent could call to add a service or resource to a project.

### Root issues

- **No template discovery for agents.** `azd template list` exists as a CLI command but the output isn't structured for programmatic consumption with filtering by use-case (e.g., "container apps", "functions", "static web apps"). Agents have no way to discover which templates are available or which ones are recommended starters.
- **No non-interactive `azd add`.** The compose workflow can't be driven programmatically.

## Proposed solutions

### Option A: Bake starter templates directly into `azd init`

Support well-known starter template names as a positional argument to `azd init`:

```bash
azd init containerapp
azd init functionapp
azd init webapp
azd init staticwebapp
```

Each name maps to a curated starter template. This is simple, discoverable (agents and users can see the list via `azd init --list-starters` or help text), and requires no prior knowledge of template URLs.

This would let an agent handle: *"Create an azd project that deploys a container app"* → `azd init containerapp --environment myenv` — a single, non-interactive command.

### Option B: Non-interactive `azd add`

Generalize `azd add` as the single command for adding anything to an azd project — not just resources, but services, hooks, extensions, etc. The root namespace maps directly to the top-level keys in `azure.yaml` (`resources`, `services`, `hooks`, `extensions`, `pipeline`), and the dotted path drills into the type.

#### Example syntax

```bash
# Resources
azd add resource --type host.containerapp --input '{"name":"myapi","language":"python","port":8080}'
azd add resource --type db.postgres --input '{"name":"mydb"}'
azd add resource --type ai.openai.model --input '{"name":"gpt4","model":"gpt-4o","version":"2024-08-06"}'

# Services (linked to a host resource)
azd add service --type containerapp --input '{"name":"web","host":"containerapp","language":"python","project":"./src/web"}'

# Extensions
azd add extension --input '{"name":"ai","source":"github.com/Azure/azd-extensions/ai"}'

# Hooks
azd add hook --type preprovision --input '{"run":"./scripts/setup.sh"}'
```

## Impact

- **Who is affected:** Any AI agent or automation trying to use azd for new project creation.
- **Severity:** High — this is one of the most common first interactions ("help me get started on Azure"), and it fails completely for agents.
- **Workaround:** The agent must have pre-baked knowledge of template URLs, which is less ideal and doesn't scale well.

## Environment

- `azd` version: latest (main branch)
- Agent: Any AI coding agent (Copilot, etc.)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.