docs(agents): propose explicit init and add commands#9135
Open
hund030 wants to merge 1 commit into
Open
Conversation
hund030
requested review from
JeffreyCA,
RickWinter,
hemarina,
tg-msft and
vhvb1989
as code owners
|
Azure Pipelines: 20 pipeline(s) were filtered out due to trigger conditions. There may be pipelines that require an authorized user to comment /azp run to run. |
microsoft-github-policy-service
Bot
added
the
customer-reported
Contributor
|
Thank you for your contribution @hund030! We will review the pull request and get back to you soon. |
Contributor
There was a problem hiding this comment.
Pull request overview
Proposes separating agent project creation from adding agents to existing projects.
Changes:
- Defines
agent initandagent addcontracts. - Documents source selection and
--infrabehavior. - Records scope and compatibility decisions.
| ### Sources | ||
|
|
||
| ```text | ||
| --template |
| | `init` | No | Yes | Yes | Initialize, then generate IaC. | | ||
| | `init` | No | No | No | Interactive: choose source; non-interactive: fail. | | ||
| | `init` | No | No | Yes | Interactive: choose source, initialize, generate IaC; non-interactive: fail. | | ||
| | `init` | Yes | No | Yes | Generate IaC only. | |
| add + source -> validate existing project -> merge/register agent | ||
| ``` | ||
|
|
||
| Both `init` and `add` share source resolution and agent-registration logic. Registration merges the complete service graph instead of replacing existing Foundry services one at a time. The detailed engineering design defines concurrency, retry, and compatibility mechanics. |
|
|
||
| 3. **Should `init` ever automatically call `add` when it finds a project?** Proposed: No. Fail before mutation and print the exact replacement command. | ||
|
|
||
| 4. **Should existing positional and `--src` forms remain temporarily?** Proposed: Yes, with deprecation warnings and deterministic translation to the new source options. |
jongio
reviewed
Jul 14, 2026
jongio
left a comment
jongio
left a comment
Member
There was a problem hiding this comment.
One consistency gap I didn't see raised yet, noted inline on the decision table.
| | `init` | No | Yes | Yes | Initialize, then generate IaC. | | ||
| | `init` | No | No | No | Interactive: choose source; non-interactive: fail. | | ||
| | `init` | No | No | Yes | Interactive: choose source, initialize, generate IaC; non-interactive: fail. | | ||
| | `init` | Yes | No | Yes | Generate IaC only. | |
Member
There was a problem hiding this comment.
The behavioral rules scope IaC-only to an existing compatible project (lines 110-111), and Non-scope rejects unsafe shapes like Aspire projects or multiple Foundry project services. This table only keys on Project found, so init --infra against an incompatible existing project resolves to Generate IaC only here instead of failing. Consider carrying the compatibility gate into the table (or a note) so an unsupported project shape maps to a fail-with-guidance result rather than IaC generation.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Design proposal for #8383.
azd ai agent initcurrently creates or modifies projects based on directory context, making behavior difficult to predict and debug.Changes
agent init/add contract: separate new-project initialization from adding agents to existing projects.--infracompatibility: retain post-init and standalone IaC generation with explicit decision rules.review decisions: document scope, migration behavior, command matrix, and open product questions.