Skip to content

Document Aspire agent lifecycle options #1745

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
David Pine (IEvangelist) merged 1 commit into from
Sep 24, 2026
Merged

Document Aspire agent lifecycle options #1745

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions src/frontend/src/content/docs/get-started/ai-coding-agents.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,8 @@ With the [Aspire VS Code extension](/get-started/aspire-vscode-extension/#let-co

> Use #aspireStartAppHost to start my AppHost in debug mode, then inspect the resource status.

The start tool can also select a launch profile or request isolated ports and user secrets. When the agent omits the isolation choice, linked Git worktrees start isolated automatically to avoid conflicts with the primary checkout.

The extension checks for an existing AppHost session before launching, so the agent doesn't need to start a second CLI process. These VS Code tools manage the AppHost lifecycle; they are separate from the optional runtime MCP tools that inspect its resources and telemetry.

Use the Aspire CLI workflow when your agent runs outside VS Code or doesn't have access to the extension's tools.
Expand Down
23 changes: 13 additions & 10 deletions src/frontend/src/content/docs/get-started/aspire-skills.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ import { Kbd } from 'starlight-kbd/components';

Aspire skills are Markdown instruction bundles for AI coding agents. Each skill lives in a folder with a `SKILL.md` file that describes when the skill applies and what workflow the agent should follow. Skills don't run services or expose application data; they teach the agent how to use Aspire tools correctly.

Aspire ships multiple skills for different parts of the app lifecycle. The exact list can vary by Aspire CLI version and project type, but the [`microsoft/aspire-skills`](https://github.com/microsoft/aspire-skills) bundle includes six workflow skills: `aspire`, `aspire-init`, `aspire-orchestration`, `aspire-monitoring`, `aspire-deployment`, and `aspireify`.
Aspire ships multiple skills for different parts of the app lifecycle. The exact list can vary by Aspire CLI version and project type, but the [`microsoft/aspire-skills`](https://github.com/microsoft/aspire-skills) bundle includes seven workflow skills: `aspire`, `aspire-init`, `aspire-orchestration`, `aspire-monitoring`, `aspire-deployment`, `aspire-project-v2-migration`, and `aspireify`.

<LearnMore>
To configure AI coding agents end to end, see [Use AI coding
Expand Down Expand Up @@ -243,16 +243,17 @@ In that command, `-a github-copilot` selects the target agent, `-g` installs glo

## Aspire workflow skills

| Skill | Use it for | What it teaches |
| ---------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `aspire` | Routing Aspire tasks to the right workflow | Detect the AppHost, apply Aspire safety guardrails, and choose the appropriate workflow for the user's request |
| `aspire-init` | Starting a new Aspire app or adding Aspire to an existing repo | Choose `aspire new` or `aspire init`, create the AppHost skeleton, and hand off existing-codebase wiring to `aspireify` |
| `aspire-orchestration` | Managing the local AppHost lifecycle | Start, stop, restart, wait for, and inspect Aspire resources, including recovery from port conflicts and orphaned processes |
| `aspire-monitoring` | Observing running Aspire apps | Inspect resource state, logs, traces, metrics, browser telemetry, and dashboard data before making changes |
| `aspire-deployment` | Publishing, deploying, and tearing down Aspire apps | Use AppHost-modeled deployments for targets such as Docker Compose, Kubernetes, Azure, and AWS |
| `aspireify` | Completing Aspire initialization in an existing codebase after `aspire init` drops an AppHost skeleton | Scan the repo, propose a resource graph, wire projects and containers into the AppHost, connect resources, configure telemetry when appropriate, and validate the wiring |
| Skill | Use it for | What it teaches |
| ----------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `aspire` | Routing Aspire tasks to the right workflow | Detect the AppHost, apply Aspire safety guardrails, and choose the appropriate workflow for the user's request |
| `aspire-init` | Starting a new Aspire app or adding Aspire to an existing repo | Choose `aspire new` or `aspire init`, create the AppHost skeleton, and hand off existing-codebase wiring to `aspireify` |
| `aspire-orchestration` | Managing the local AppHost lifecycle | Start, stop, restart, wait for, and inspect Aspire resources, including recovery from port conflicts and orphaned processes |
| `aspire-monitoring` | Observing running Aspire apps | Inspect resource state, logs, traces, metrics, browser telemetry, and dashboard data before making changes |
| `aspire-deployment` | Publishing, deploying, and tearing down Aspire apps | Use AppHost-modeled deployments for targets such as Docker Compose, Kubernetes, Azure, and AWS |
| `aspire-project-v2-migration` | Migrating eligible AppHosts to Project v2 resource APIs | Assess legacy project resources, require approval for exact edits, and preserve supported behavior while migrating to `DotnetProjectResource` APIs |
| `aspireify` | Completing Aspire initialization in an existing codebase after `aspire init` drops an AppHost skeleton | Scan the repo, propose a resource graph, wire projects and containers into the AppHost, connect resources, configure telemetry when appropriate, and validate the wiring |

Use the top-level `aspire` skill when the request is about an Aspire app and the right workflow isn't obvious. Use a workflow-specific skill directly when the task is clear, such as `aspire-orchestration` for local lifecycle work, `aspire-monitoring` for telemetry investigation, `aspire-deployment` for publish and deploy workflows, or `aspireify` for existing-codebase AppHost wiring.
Use the top-level `aspire` skill when the request is about an Aspire app and the right workflow isn't obvious. Use a workflow-specific skill directly when the task is clear, such as `aspire-orchestration` for local lifecycle work, `aspire-monitoring` for telemetry investigation, `aspire-deployment` for publish and deploy workflows, `aspire-project-v2-migration` for eligible legacy project resources, or `aspireify` for existing-codebase AppHost wiring.

## GitHub Copilot app canvas extensions

Expand Down Expand Up @@ -307,6 +308,8 @@ Install skills to a single location for the agent environment you actively use.
- SKILL.md
- aspire-deployment/
- SKILL.md
- aspire-project-v2-migration/
- SKILL.md
- aspireify/
- SKILL.md
- playwright-cli/
Expand Down
13 changes: 12 additions & 1 deletion src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,9 +93,20 @@ Open a trusted workspace with the Aspire extension installed and an AppHost visi

Both tools request confirmation for the resolved target. Review its path and, for start, the requested mode before approving. These are extension-provided tools; configuring a runtime MCP server isn't required to use them.

The start tool accepts these inputs:

| Input | Required | Description |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `appHostPath` | Yes | The workspace-relative path of a discovered AppHost. |
| `mode` | Yes | Use `run` to start without a debugger or `debug` to attach supported debuggers. |
| `isolated` | No | Use `true` for randomized ports and isolated user secrets or `false` to disable isolation. Linked Git worktrees use isolation when omitted. |
| `launchProfile` | No | The exact profile name from the AppHost's `launchSettings.json` file. |

The tools accept only buildable AppHosts returned by the extension's discovery service, not arbitrary filesystem paths supplied by an agent. If a selector is unknown or ambiguous, the result includes `knownAppHosts` so the agent can choose a discovered target. Multi-root workspaces use folder-qualified selectors.

Before starting, the extension checks its own sessions and running AppHosts to avoid duplicate launches. Stop coordinates the editor's matching Aspire debug session when one exists; otherwise, it uses `aspire stop --apphost` for the resolved AppHost. It doesn't mean "stop every Aspire process."
Before starting, the extension checks its own sessions and running AppHosts to avoid duplicate launches. A successful new launch reports the effective isolation setting. Results for an AppHost that was already starting or running omit that setting because the tool didn't create a new process.

Stop coordinates the editor's matching Aspire debug session when one exists; otherwise, it uses `aspire stop --apphost` for the resolved AppHost. It doesn't mean "stop every Aspire process."

:::note[Tool availability]
The workspace must be trusted, and the VS Code host must support the language model tool API. If the tools aren't available, update VS Code and the Aspire extension, confirm that discovery finds your AppHost, and check that your agent chat has access to these tools.
Expand Down
Loading