From d42dd31023ebc420b0809a6cfcdc395ba0532158 Mon Sep 17 00:00:00 2001 From: Paulo Lacerda Date: Sun, 31 May 2026 07:57:07 -0300 Subject: [PATCH] docs: show steady-state foundry-agent.json (action reused) in step 13 The example JSON in step 13 previously showed action: bootstrapped with candidate_agent: travel-agent:1 and an explanation that the two version numbers are expected to differ until the environment has caught up to the seed. In practice the merge-triggered deploy is almost never the run that bootstraps by the time the user reaches step 13, the skill's verification dispatch in step 12 plus the first PR run have already settled dev to travel-agent:2, so the merge deploy reports action: reused with candidate_agent: travel-agent:2 matching source_agent. The example now: - shows the steady-state shape taken from a real recording, - uses runner-resolved absolute paths the user actually sees /home/runner/work//..., - uses a real 64-char prompt_sha256 and a real ISO timestamp. The three-outcome list reused / created / bootstrapped below the JSON keeps the bootstrap case as the documented edge condition. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CHANGELOG.md | 15 ++++++ docs/tutorial-prompt-agent-quickstart.md | 64 ++++++++++++++---------- 2 files changed, 53 insertions(+), 26 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b63264f..850c525 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,21 @@ This format follows [Keep a Changelog](https://keepachangelog.com/) and adheres ## [Unreleased] ### Fixed +- **Tutorial: prompt-agent step 13 now shows the steady-state `foundry-agent.json` (action: reused) instead of the bootstrap edge case.** + The example JSON in step 13 previously showed `action: bootstrapped` + with `candidate_agent: "travel-agent:1"` and a "the two numbers are + expected to differ until the environment has caught up to the seed" + explanation. In practice the merge-triggered deploy is almost never + the run that bootstraps — by the time the user reaches step 13, the + skill's verification dispatch in step 12 plus the first PR run have + already settled dev to `travel-agent:2`, so the merge deploy reports + `action: reused` with `candidate_agent: "travel-agent:2"` (matching + `source_agent`). The example now shows the steady-state shape (taken + from a real recording), uses the runner-resolved absolute paths the + user actually sees (`/home/runner/work//...`), and uses a + real 64-char `prompt_sha256` + a real ISO timestamp. The + three-outcome list (`reused` / `created` / `bootstrapped`) below the + JSON keeps the bootstrap case as the documented edge condition. - **Tutorial: prompt-agent step 13 now matches what the workflow skill actually does (dispatches both workflows).** PR #211 mistakenly narrowed the step 13 callout to say the workflow skill only dispatches `agentops-pr.yml` as a verification run, based diff --git a/docs/tutorial-prompt-agent-quickstart.md b/docs/tutorial-prompt-agent-quickstart.md index b3b5011..8126f67 100644 --- a/docs/tutorial-prompt-agent-quickstart.md +++ b/docs/tutorial-prompt-agent-quickstart.md @@ -887,45 +887,57 @@ it, runs `prompt_deploy summarize` to write the dev deployment summary, and uploads the deployment artifact. Open the deploy run and download the `foundry-agent-dev-deployment` -artifact. Inside, open `foundry-agent.json`. If this merge-triggered -run is the one that finally settles the bootstrap (the seed -`travel-agent:2` did not exist yet and is created here), the file -looks like this — note the actual field names AgentOps writes: +artifact. Inside, open `foundry-agent.json`. In the **steady-state** +case (the most common — the seed `travel-agent:2` already exists in +dev and matches the prompt the PR shipped), the file looks like +this — note the actual field names AgentOps writes: ```json { "version": 1, "type": "foundry_prompt_agent_deployment", "environment": "dev", - "action": "bootstrapped", + "action": "reused", "agent_name": "travel-agent", "source_agent": "travel-agent:2", - "candidate_agent": "travel-agent:1", + "candidate_agent": "travel-agent:2", "source_version": "2", - "candidate_version": "1", + "candidate_version": "2", "project_endpoint": "https://.services.ai.azure.com/api/projects/travel-agent-dev", - "prompt_file": ".agentops/prompts/travel-agent.md", - "prompt_sha256": "9c3a...e0b1", - "eval_config": ".agentops/deployments/agentops.candidate.yaml", - "created_at": "2025-...", - "git_sha": "5f1a2c...", - "workflow_url": "https://github.com/.../actions/runs/...", - "foundry_agent_version_id": "..." + "prompt_file": "/home/runner/work///.agentops/prompts/travel-agent.md", + "prompt_sha256": "9727437db863b00d52bc8ef1f314b70ed22e3e562f5a3a1f9dd68e26f7ea0975", + "eval_config": "/home/runner/work///.agentops/deployments/agentops.candidate.yaml", + "created_at": "2026-05-30T17:57:53.135435+00:00", + "git_sha": "3078df74c3b18625553dec8ecd4ed4282f1ca1ca", + "workflow_url": "https://github.com///actions/runs/26690922142", + "foundry_agent_version_id": "travel-agent:2" } ``` -The `source_agent` field records what `agent:` in `agentops.yaml` -pointed at (`travel-agent:2`, the sandbox seed). The `candidate_agent` -field records what CI actually produced and evaluated in this -environment (`travel-agent:1`, because dev was empty and the SDK -assigned `:1`). The two numbers are expected to differ until the -environment has caught up to the seed. - -On every subsequent deploy, `action` switches to either `reused` (when -the prompt is byte-identical to the previous seed) or `created` (when -Foundry auto-created a new version because the prompt changed), and -`candidate_agent` reflects the actual version that was evaluated and -recorded. +In the steady-state, `source_agent` and `candidate_agent` are +**identical** (`travel-agent:2`) because the dev project already had +`travel-agent:2` with the same instructions as the PR's `prompt_file`, +so `prompt_deploy stage` reported `action: reused` and nothing new +was created. The `prompt_file` and `eval_config` paths are absolute +because they are resolved inside the GitHub Actions runner workspace +(`/home/runner/work///...`). + +`action` will be one of: + +- **`reused`** — dev already had `travel-agent:2` with byte-identical + instructions. No new Foundry version was created. (Steady-state and + most-common case.) +- **`created`** — dev had `travel-agent:2` but with **different** + instructions, so Foundry auto-created the next number (e.g. + `travel-agent:3`). `candidate_agent` would then be `travel-agent:3`. +- **`bootstrapped`** — dev did not yet have `travel-agent:2` at all, + so the stage step fell back to `prompt_agent_bootstrap` defaults + plus `prompt_file` and asked the SDK to create the first version. + In a fresh, empty dev project the SDK starts at `:1`, so you would + see `candidate_agent: "travel-agent:1"` and `candidate_version: "1"` + while `source_agent` still reports the seed (`travel-agent:2`). The + two numbers stay different until subsequent runs catch dev up to + the seed. That `prompt_sha256` + `git_sha` pair is what the mental-model diagram at the start of the tutorial referred to as **cross-environment