Skip to content

docs: reflect Foundry's :2 first-publish version in prompt-agent quickstart#189

Merged
placerda merged 1 commit into
developfrom
feature/tutorial-foundry-version-correction
May 29, 2026
Merged

docs: reflect Foundry's :2 first-publish version in prompt-agent quickstart#189
placerda merged 1 commit into
developfrom
feature/tutorial-foundry-version-correction

Conversation

@placerda
Copy link
Copy Markdown
Contributor

Fixes a couple of accuracy bugs in the prompt-agent quickstart tutorial that surfaced during a real run-through.

What was wrong

  1. First-publish version is :2, not :1. When you save+publish a prompt agent for the first time in the Foundry portal, Foundry numbers the unpublished draft as :1 and assigns :2 on first publish. The tutorial assumed :1 throughout the sandbox-author narrative, so the seed pointer in agentops.yaml, the wizard prompt, and the playground walkthrough were all off by one.
  2. Example foundry-agent.json had the wrong field names. The tutorial showed agent_source / agent_candidate and a nested agentops.* block. pipeline/prompt_deploy.py actually writes flat source_agent / candidate_agent / prompt_sha256 / git_sha / workflow_url. Anyone copying the example to script against would break.

What changed

  • All sandbox-author references updated from travel-agent:1 to travel-agent:2: prereqs row, mental-model diagram, journey table, microsoft-foundry skill prompt (Path B), section 4 header + Save callout, section 5 playground, section 7 init wizard, section 9 agentops.yaml example, and the section 11 PR-workflow narrative.
  • Section 13 example foundry-agent.json rewritten to match what the deploy artifact actually contains today (flat field names, full set of identifiers).
  • Added a callout explaining the SDK vs. portal version-numbering asymmetry: because CI uses the Foundry SDK and starts at :1 in an empty project, the bootstrap may fire on the first one or two deploys per environment before the env catches up to the sandbox seed (:2). After that, normal reuse/create flow takes over. The durable identity is prompt_sha256 + git_sha, not the per-project version numbers — the existing mental-model section already says this; the new callout just makes the practical consequence explicit so readers don't think CI is misbehaving when they see action: bootstrapped twice in a row.
  • Success criteria and Where to go next blocks updated to drop stale travel-agent:1 claims about the dev seed.

Validation

  • python -m pytest tests/unit/test_prompt_deploy.py -x -q → 7 passed.
  • Cross-checked docs/tutorial-end-to-end.md — already says travel-agent:2 after first publish (line 181). No change needed there.
  • docs/tutorial-hosted-agent-quickstart.md does not mention prompt-agent version numbers — no change needed.

Out of scope

  • No code change. prompt_deploy already handles the bootstrap-fires-twice case correctly; the only ask was that the tutorial stop misrepresenting what the user will observe.

…ent.json field names

The prompt-agent quickstart tutorial assumed Foundry assigns version
:1 when you save+publish a prompt agent for the first time in the
portal. In practice, Foundry numbers the unpublished draft :1 and
assigns :2 on first publish, so the seed pointer in agentops.yaml
should be travel-agent:2, not :1.

Also correct the example foundry-agent.json: the artifact written by
prompt_deploy uses flat field names (source_agent, candidate_agent,
prompt_sha256, git_sha, workflow_url), not the nested agentops.* shape
the tutorial previously showed.

Add a callout explaining the SDK vs. portal numbering asymmetry:
because CI uses the SDK and starts at :1 in an empty project, the
bootstrap may fire on the first one or two deploys per environment
before the env catches up to the seed value. After that, normal
reuse/create flow takes over. This is fine because prompt_sha256 +
git_sha are the durable cross-environment identity, not the per-
project version numbers.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@placerda placerda merged commit bba6b35 into develop May 29, 2026
12 checks passed
@placerda placerda deleted the feature/tutorial-foundry-version-correction branch May 29, 2026 01:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant