Add commands for agent management and enhance functionality

[therealjohn]

New Command Surface

Command	Description
azd ai agent init	Initialize an agent project (from code, manifest, or template)
azd ai agent run	Run the agent locally for development
azd ai agent invoke [message]	Send a message to a local or remote agent
azd ai agent list	List agent services in the project
azd ai agent show	Show details of a deployed agent
azd ai agent monitor	Monitor agent activity

All commands operate in the context of the current azd project and environment.

---

1. Init from Template (init --template)

Scaffolds an agent project from a GitHub template repository and starts the setup of agent.yaml (shortcuts azd init -t & azd ai agent init).

• --template (-t): GitHub repo — full URL, owner/repo, or bare name (resolved to Azure-Samples/{name}).
• --template and --manifest are mutually exclusive.
• Downloads via shallow git clone; falls back to GitHub REST API if git is unavailable.
• Honors GITHUB_TOKEN / GH_TOKEN for authenticated access.

Behavior by project state:

State	Behavior
No existing project	Full scaffold including infra/. Collisions offer overwrite / skip / cancel.
Existing project + --infra	Copy only the infra/ directory from the template.
Existing project (no --infra)	Copy agent source into src/<agent-name>/.

Agent manifest discovery searches root → src/*/ → recursive, looking for agent.yaml, agent.yml, agent.manifest.yaml, agent.manifest.yml.

---

2. Init from Code (init with no flags)

Initializes an agent project from local source code.

• Prompts for agent name (default: agent name from existing agent.yaml, not directory name).
• Service name in azure.yaml defaults to the agent name.
• Creates environment <agent-name>-dev.
• If an existing agent.yaml AgentDefinition is found (has kind, no template), it is preserved — not overwritten.

---

3. Prompt Re-ordering & Startup Commands (All Init Paths)

Azure subscription and location questions are asked only when needed (e.g., deploying a model or querying a Foundry project), not upfront.

Before:

? Enter environment name: my-agent-dev
? Select an Azure subscription: <sub>
? Select an Azure location: <location>
? How would you like to configure a model? > Deploy a new model
? Select a model: gpt-4o

After:

? Enter a name for your agent: my-agent
  Created environment my-agent-dev
? How would you like to configure a model?
  > Deploy a new model from the catalog
  > Select an existing model deployment
  > Skip model configuration
? Select an Azure subscription: <sub>        ← only if needed
? Select an Azure location: <location>        ← only if needed
? Select a model: gpt-4o

Subscription is extracted from --project-id when provided. Resolved values are persisted to the azd environment (AZURE_TENANT_ID, AZURE_SUBSCRIPTION_ID, AZURE_LOCATION).

Startup Commands

To support the run command, use the startupCommand property of a service, already available in the schema. The init steps can attempt to auto-detect defaults:

• for init with code and init -m, look in the cwd/ directory with agent.yaml (manifest).
• for init -t, look in the src/

Look for a main.py, *.csproj

Python: uv run python main.py
.NET: dotnet run <name>.csproj

The interactive experience for init should ask the user for the command, providing these auto-detected experiences as defaults.

For --no-prompt scenarios, add a --startup-command argument to init to allow specifying this.

4. Container Configuration Presets

All init paths present a single question for container resource settings instead of silent defaults or per-field prompts:

? Select a container configuration (can be changed later in azure.yaml):
  > Cost Effective  — 0.25 CPU, 0.5 GB RAM
  > Balanced         — 0.5 CPU, 1.0 GB RAM
  > Performance      — 1.0 CPU, 2.0 GB RAM

---

5. Local Development (run)

Runs the agent locally for interactive development.

azd ai agent run [--src <dir>] [--port <port>] [--name <service>] [--start-command <cmd>]

• Startup command resolution: --start-command → startupCommand in azure.yaml → auto-detect by project type.
• Auto-detect: Python (pyproject.toml/requirements.txt → python main.py), .NET (*.csproj → dotnet run), Node.js (package.json → npm start).
• Dependency install: Python via uv (preferred) or pip; Node.js via npm install; .NET: none needed.
• Sets PORT env var; loads azd environment variables into the child process.
• Forwards stdio; handles Ctrl+C gracefully.

---

6. Agent Invocation (invoke)

Sends a message to a local or remote agent.

azd ai agent invoke [message] [--remote] [--name <agent>] [--port <port>] [--session <id>] [--new-session]

• Local: POST to http://localhost:{port}/responses. Default port: 8088.
• Remote: POST to Foundry Responses API. --name implies --remote. Auto-resolves agent name from azure.yaml + environment.
• Default message: "hello".
• Timeout: 120s.

Session & Conversation State

State is stored as azd environment variables (not a local JSON file):

Variable	Purpose
AZD_AI_AGENT_INVOKE_NAME	Currently active agent name
AZD_AI_AGENT_INVOKE_SESSIONID	Session ID for routing to same container instance
AZD_AI_AGENT_INVOKE_CONVERSATIONID	Conversation ID for multi-turn memory (remote only)

• --new-session resets all three variables.
• --session overrides the session ID for one invocation.
• On first invocation, a random 25-character session ID is generated and saved.
• On first remote invocation, a conversation is created via the Foundry Conversations API and the ID is saved.

---

7. List Agents (list)

Lists the agent services defined in azure.yaml.

azd ai agent list [--output json|table]

• Reads services of type azure.ai.agent from azure.yaml.
• Table format shows columns: NAME, IMAGE, URI.
• Marks the agent matching AZD_AI_AGENT_INVOKE_NAME with an arrow indicator.
• JSON format pretty-prints the service list.

---

8. Error Codes

New error codes: invalid_args, template_download_failed, agent_yaml_not_found.

---

9. Manifest File Naming

Recognized manifest filenames: agent.yaml, agent.yml, agent.manifest.yaml, agent.manifest.yml. User-facing messages use the term "agent manifest file" rather than a specific filename.