[WIP] feat: update microsoft-foundry skill to improve the hosted agent getting started with coding agent#2486
Open
zhenjiao-ms wants to merge 2 commits into
Open
[WIP] feat: update microsoft-foundry skill to improve the hosted agent getting started with coding agent#2486zhenjiao-ms wants to merge 2 commits into
zhenjiao-ms wants to merge 2 commits into
Conversation
…eploy workflows - Streamline create-hosted.md and deploy.md with clearer step-by-step flows - Add reference docs for azd-ai-cli, local-run, and tools - Add environment verification scripts (PowerShell and Bash) - Update direct-code-deployment reference with consistent CPU/memory defaults - Update SKILL.md description for better routing Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
zhenjiao-ms
requested review from
RickWinter,
XOEEst,
XiaofuHuang,
anchenyi,
ankitbko,
jugonzales,
tendau and
vebudumu
as code owners
Contributor
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
This PR overhauls the Microsoft Foundry agent skill documentation to make the azd ai CLI the primary code-first path for hosted agent creation, deploy, and local iteration. It rewrites create-hosted.md and deploy.md around azd ai agent init/run/deploy, promotes direct code deployment as the recommended hosted deployment method, and adds new reference docs (azd-ai-cli.md, local-run.md, tools.md) plus verify-environment.{sh,ps1} scripts. It also adds explicit guidance for session_not_ready recovery (capability host + Cognitive Services User role) and bumps default agent resources to 1 CPU / 2Gi.
Changes:
- Refocus
create-hosted.mdanddeploy.mdon theazd aiworkflow with new sub-references and verification scripts. - Promote direct code deployment as the default hosted-agent path; add Tasks 8/9 (RBAC + capability host) and bump default CPU/memory.
- Add
session_not_readytriage guidance ininvoke.mdand an auto-generated project name flow increate-foundry-project.md.
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 11 comments.
Show a summary per file
| File | Description |
|---|---|
| plugin/skills/microsoft-foundry/SKILL.md | Updates sub-skill descriptions to reflect azd-centric workflows. |
| plugin/skills/microsoft-foundry/project/create/create-foundry-project.md | Adds auto-generated project name flow with bash/PowerShell snippets. |
| plugin/skills/microsoft-foundry/foundry-agent/invoke/invoke.md | Expands session_not_ready guidance with retries and resource hints. |
| plugin/skills/microsoft-foundry/foundry-agent/deploy/deploy.md | Full rewrite around direct code deploy + azd container fallback. |
| plugin/skills/microsoft-foundry/foundry-agent/deploy/references/direct-code-deployment.md | Promotes to default; adds Tasks 8 (RBAC) and 9 (capability host); bumps defaults. |
| plugin/skills/microsoft-foundry/foundry-agent/create/create-hosted.md | Rewrites around azd ai agent init/run with new step structure. |
| plugin/skills/microsoft-foundry/foundry-agent/create/references/azd-ai-cli.md | New reference for azd ai CLI surface and file layout. |
| plugin/skills/microsoft-foundry/foundry-agent/create/references/local-run.md | New reference for azd ai agent run and local invoke. |
| plugin/skills/microsoft-foundry/foundry-agent/create/references/tools.md | New reference for toolboxes and connection-backed tools. |
| plugin/skills/microsoft-foundry/foundry-agent/create/scripts/verify-environment.sh | New bash script for one-shot environment verification. |
| plugin/skills/microsoft-foundry/foundry-agent/create/scripts/verify-environment.ps1 | New PowerShell counterpart for environment verification. |
Comments suppressed due to low confidence (1)
plugin/skills/microsoft-foundry/foundry-agent/deploy/references/direct-code-deployment.md:324
- This snippet uses placeholders like
<agent-principal-id>,<sub>,<rg>, and<account>without explaining how to retrieve them in the direct-code flow. Earlier in the doc the response field is described asinstance_identity.principal_id, but readers also need to know how to obtain<sub>/<rg>/<account>(e.g., fromazd env get-valuesoraz account show). Consider adding a one-line example of extracting these (e.g.,jq -r '.instance_identity.principal_id'from the version response) so the snippet is directly runnable.
| Delete agent | `DELETE <project-endpoint>/agents/<agent-name>?api-version=2025-11-15-preview` | Deletes the agent and all versions; pull logs before deletion if needed |
Comment on lines
+336
to
+338
| Loop until the version status is no longer `creating`. Poll every 15 seconds. Typical `remote_build` completes in 60-120 seconds (4-8 polls). The upload + poll cycle together takes roughly 2-3 minutes, not longer. | ||
|
|
||
| - `active` -> proceed directly back to [deploy.md Step 7: Test the Agent](../deploy.md#step-7-test-the-agent). | ||
| - `active` -> proceed to Task 8 (role assignment) before smoke-testing. |
| exit 1 | ||
| fi | ||
|
|
||
| AZD_VERSION="$(azd version --output json 2>/dev/null | python3 -c 'import json,sys; print(json.load(sys.stdin).get("azd",{}).get("version","unknown"))' 2>/dev/null || echo unknown)" |
Comment on lines
+17
to
+19
| function Note-Ok { param([string]$m) Write-Output "[OK] $m" } | ||
| function Note-Warn { param([string]$m) Write-Output "[WARN] $m" } | ||
| function Note-Action { param([string]$m) Write-Output "[ACTION] $m"; $script:actionRequired = $true } |
| } | ||
|
|
||
| # Refresh PATH to pick up recently-installed tools (e.g. azd installed in same session) | ||
| $env:Path = [System.Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path", "User") |
| - **Framework** — `Microsoft Agent Framework` | ||
|
|
||
| If the user's request clearly requires another supported lane, use that lane instead of forcing the defaults. | ||
| Defaults when unspecified: greenfield + Python + `azd ai agent sample list --featured-only --language python`, plus `--no-prompt` on every write. If creating a new project and the user did not provide a project name, auto-generate one using the pattern `ai-project-<random>` (6-8 lowercase alphanumeric characters). Show the generated name to the user but do not block on confirmation. If project ID is missing and the user wants to use an existing project, stop and ask. If the manifest declares secret parameters, collect them with `ask_user` and set them via `azd env set PARAM_...` before init -- keep `--no-prompt` (do not fall into azd's interactive prompts). |
| - `yes` → Proceed | ||
| - `VAR_NAME=new_value` → Update the value, show updated table, ask again | ||
| - `cancel` → Abort deployment | ||
| ## Deployment Method Selection -- Hosted agents |
| | Hosted agent not active | Version still provisioning or failed | Check version status via `agent_get` | | ||
| | Session not found | Invalid ID or expired | Create new session with `session_create` | | ||
| | `424 FailedDependency` or `session_not_ready` | Hosted agent session is still warming up or readiness has not completed | Wait 15-30 seconds, check `session_logstream` if needed, then retry `agent_invoke` with the same `sessionId` if one was returned; if no `sessionId` was returned, retry `session_create` | | ||
| | `424 FailedDependency` or `session_not_ready` | Hosted agent session is still warming up or readiness has not completed | Wait 15-30 seconds, check `session_logstream` if needed, then retry `agent_invoke` with the same `sessionId` if one was returned; if no `sessionId` was returned, retry `session_create`. If this persists across 3+ retries (with exponential backoff: 15s, 30s, 60s), the container likely cannot start within the readiness probe deadline — redeploy with higher CPU/memory (recommended minimum: `1` CPU / `2Gi` for direct-code deployments). Also verify the model deployment name is correct via `model_deployment_get`. | |
|
|
||
| 1. **Project name** — used as azd environment name and resource group (`rg-<name>`). Must contain only alphanumeric characters and hyphens. | ||
| - If the user provided a name, use it as-is. | ||
| - If the user did NOT provide a name, **auto-generate a unique name** using the pattern `ai-project-<random>` where `<random>` is a short random suffix (6-8 lowercase alphanumeric characters). Generate the suffix with a platform-appropriate method: |
| ### Minimal `agent.yaml` (hosted) | ||
|
|
||
| ```yaml | ||
| # yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml |
Comment on lines
+69
to
+70
| --auth-type custom-keys \ | ||
| --custom-key Authorization="Bearer ghp_xxx..." |
The previous defaults of 0.5 CPU / 1Gi often cause session_not_ready timeouts during cold start. Update all prose and JSON examples to use 1 CPU / 2Gi as the recommended default. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Collaborator
|
/foundry-e2e |
Contributor
|
Dispatched Microsoft Foundry E2E eval on |
Contributor
|
Microsoft Foundry E2E eval finished for PR #2486. Workflow run: https://github.com/microsoft/GitHub-Copilot-for-Azure/actions/runs/26870972112 eval-results.mdEval Results
E2E evaluation for the microsoft-foundry skill in a workflow that has already logged into Azure CLI and configured azd to use Azure CLI authentication.
[1] Failed grader(s):
|
3 tasks
3 tasks
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.
…eploy workflows
Description
Checklist
cd tests && npm test)npm run test:skills:integration -- <skill>)USE FOR/DO NOT USE FOR/PREFER OVERclauses: confirmed no routing regressions for competing skillsRelated Issues