diff --git a/workshop/05-agentic-workflows-intro.md b/workshop/05-agentic-workflows-intro.md index 5a71d2f8..da5e53d9 100644 --- a/workshop/05-agentic-workflows-intro.md +++ b/workshop/05-agentic-workflows-intro.md @@ -40,215 +40,16 @@ If you already write Actions YAML, the frontmatter stays the same (triggers, per - **What it produces:** A synthesized report or action the agent composes from live repository data — different every run based on what it finds. - **Why it exists:** Classic Actions handles deterministic CI/CD. Agentic workflows fill the gap for tasks that need judgment — or you can mix both in a single hybrid workflow. -## Classify these tasks - -For each task below: classify it as **agentic workflow** or **standard Actions workflow**, check the box, then reveal the answer before the next task: - -You just saw how a standard Actions workflow follows fixed steps. Agentic workflows replace those fixed steps with a plain-English task brief — use that contrast to classify the tasks below. - -**Task A:** Run unit tests on every pull request, fail if any test exits non-zero, and upload coverage. - -- [ ] I have classified Task A - -
-Check Task A answer - -**Task A — Standard Actions workflow:** every run follows the same fixed steps: start the test job, fail on a non-zero exit code, and upload the coverage artifact. No judgment required. - -
- -**Task B:** Review newly opened issues each morning, group them by theme, flag the urgent ones, and post a short triage summary. - -- [ ] I have classified Task B - -
-Check Task B answer - -**Task B — Agentic workflow:** the agent has to inspect live repo context, group similar issues, and decide what looks urgent before it writes the summary. - -
- -## Reflection - -Before you check the reflection item in the checkpoint below, write one sentence describing what you would want _your_ agentic workflow to do. Put it wherever you keep workshop notes: your editor, a scratch file, or a notes app. Example: summarize new issues and flag urgent ones. Focus on a task that needs judgment, not a test or deploy script. You'll use this idea in later. - -## What the agent decided - -A scheduled agentic workflow generates a report like this: - -```markdown -## Daily Repository Status — July 12 - -- ✅ CI health: 18 workflows succeeded, 1 failed (`docs-link-check`) -- 🔄 Pull requests: 7 open (2 need review, 1 stale > 14 days) -- 🐛 Issues: 4 new, 3 closed, 2 high-priority still open -- 🚀 Releases: No new tags in the last 24 hours - -### Recommended next actions -1. Re-run `docs-link-check` and update broken external URLs. -2. Review PR #412 and PR #415 before noon. -3. Triage high-priority issue #398 with the platform team. -``` - -**Your turn:** Answer in your own words — _what did the agent decide on its own?_ Identify at least two lines where the agent made a judgment call rather than just reading a number. - -## Check your understanding - -Apply what you just saw — answer each question in your notes, then reveal. - -Should the daily report run on a schedule or wait for manual dispatch? State which and why. - -- [ ] I chose a trigger type and explained my reasoning - -
-Check your answer - -A scheduled trigger runs automatically — appropriate for a daily report. `workflow_dispatch` requires a button click in the Actions tab. - -- [ ] Schedule: runs automatically, no button click needed -- [ ] `workflow_dispatch`: requires a manual click each run - -
- -How does the agent post the report if it always operates read-only? - -- [ ] I explained how the agent writes output - -
-Check your answer - -Agents always run read-only. Any writes — including posting the report — go through [safe outputs](https://github.github.com/gh-aw/reference/safe-outputs/) and guardrails. - -- [ ] The agent itself is always read-only -- [ ] Writes happen through safe outputs and guardrails - -
- -Write one sentence for the task brief — this becomes your brief in Step 7. - -- [ ] I wrote my one-sentence brief -- [ ] My brief describes a task that needs judgment, not fixed steps - -## The two files - -An agentic workflow has two files. Here is the `.md` source you write: - -```markdown ---- -on: - schedule: daily -permissions: - issues: read ---- - -Review all open issues, summarize the key themes, and post a short digest as a new issue. -``` - -> [!NOTE] -> `schedule: daily` is fuzzy shorthand that `gh aw compile` converts into a standard Actions cron expression. You never write raw cron syntax in an agentic workflow `.md` file. - -And here is the `.lock.yml` `gh aw compile` generates — what GitHub Actions actually runs: - -```yaml -# Auto-generated by gh aw compile. Do not edit by hand. -name: Review open issues -on: - schedule: - - cron: "0 8 * * *" -permissions: - issues: read -``` - -Both files live in `.github/workflows/`. Look at them and answer: which part of the `.md` is the **task brief**, and which part tells GitHub Actions when to run? - -## Concept check — before you continue - -Before you reveal the answers below, write a one-sentence definition for each term: - -- [ ] Agentic workflow -- [ ] Lock file -- [ ] Engine -- [ ] `workflow_dispatch` - -
-Check your answers - -| Term | Plain-language meaning | -|---|---| -| Agentic workflow | A GitHub Actions workflow that uses an AI model to reason and act | -| [Lock file](https://github.github.com/gh-aw/reference/glossary/#workflow-lock-file-lockyml) | The compiled YAML that GitHub Actions actually runs | -| [Engine](https://github.github.com/gh-aw/reference/engines/) | The AI model provider (for example, GitHub Copilot) used by the workflow | -| `workflow_dispatch` | A manual trigger — you start the run by clicking a button in the Actions tab | - -Confirm each: - -- [ ] Lock file: compiled, not hand-edited -- [ ] Engine: AI model provider -- [ ] `workflow_dispatch`: manual trigger from Actions -- [ ] Agentic workflow: AI reasoning loop - -
- -If you had to look up more than one term, take a moment to review that section before continuing. - -## Classify more tasks - -**Task C:** Each Friday, scan all open issues and pull requests, summarize recent activity by contributor, and post a weekly team progress digest. - -- [ ] I have classified Task C - -
-Check Task C answer - -**Task C — Agentic workflow:** the agent has to read contributor activity across issues and pull requests, decide what counts as meaningful progress, and compose a digest that differs every week. - -
- -**Task D:** On every pull request, run ESLint (fail on errors), then have an AI read the diff and post a summary comment. - -- [ ] I have classified Task D - -
-Check Task D answer - -**Task D — Agentic (hybrid) workflow:** ESLint is deterministic — same result every run. The AI summary requires judgment: reading the diff and deciding how to describe the change. Combining fixed and AI steps makes a workflow agentic. - -- [ ] The ESLint step produces the same pass-or-fail result every run -- [ ] The AI step produces different output based on what it reads in the diff -- [ ] A workflow mixing deterministic and AI steps is still agentic overall - -
- -## Self-check - -What makes a workflow agentic rather than standard? Write your answer in your notes. - -- [ ] I wrote my self-check answer in my notes - -
-Show model answer - -A workflow is agentic when an AI agent makes judgment calls — reading context, deciding what matters, and producing output that differs each run. Standard workflows follow fixed steps. - -Does your answer include: -- [ ] AI making judgment calls on live context -- [ ] Output that varies each run -- [ ] Contrast with standard fixed-step workflows - -
- > [!TIP] -> If this still feels fuzzy, Step 7 makes the distinction concrete. Return here after Step 7. +> Want to go deeper? [Side Quest: Agentic Workflows Deep Dive](side-quest-05-02-aw-deep-dive.md) covers exercises, example output, the two-file structure, and concept checks. ## ✅ Checkpoint -- [ ] I described what an agentic workflow is in one sentence +- [ ] I can describe what an agentic workflow is in one sentence - [ ] I can explain one way an agentic workflow differs from a standard Actions workflow -- [ ] I can point to the task brief and the trigger in the sample `.md` file -- [ ] I can describe the difference between the `.md` source file and the compiled `.lock.yml` +- [ ] I can identify the three parts: trigger → agent → safe output **Next:** [Install the gh-aw CLI Extension](06-install-gh-aw.md) - diff --git a/workshop/README.md b/workshop/README.md index dc0892f7..53b49171 100644 --- a/workshop/README.md +++ b/workshop/README.md @@ -41,6 +41,7 @@ A hands-on workshop that takes you from zero to a fully automated, AI-powered wo ## Optional Side Quests - [Side Quest: Agentic Workflows for GitHub Actions Power Users](side-quest-05-01-actions-power-user.md) — one-page cheat sheet for what changes vs what stays the same in agentic workflows; branches from [Step 5](05-agentic-workflows-intro.md). +- [Side Quest: Agentic Workflows Deep Dive](side-quest-05-02-aw-deep-dive.md) — classification exercises, example agent output, the two-file structure, and concept checks; branches from [Step 5](05-agentic-workflows-intro.md). - [Side Quest: Terminal Basics](side-quest-01-01-terminal-basics.md) — optional primer that branches from [Step 1](01-prerequisites.md). - [Side Quest: Environment Reference](side-quest-01-02-environment-reference.md) — glossary of workshop environments and tool terms with official docs links; branches from [Step 1](01-prerequisites.md). - [Side Quest: Install `gh-aw` Troubleshooting](side-quest-06-01-install-troubleshooting.md) — optional install troubleshooting reference that branches from [Step 6](06-install-gh-aw.md). diff --git a/workshop/side-quest-05-02-aw-deep-dive.md b/workshop/side-quest-05-02-aw-deep-dive.md new file mode 100644 index 00000000..9d2d53ca --- /dev/null +++ b/workshop/side-quest-05-02-aw-deep-dive.md @@ -0,0 +1,221 @@ + + +# Side Quest: Agentic Workflows Deep Dive + +> _Optional: work through this side quest after [What Are Agentic Workflows?](05-agentic-workflows-intro.md) to practise classification, explore the two-file structure, and check your vocabulary._ + +## 📋 Before You Start + +- You've read [What Are Agentic Workflows?](05-agentic-workflows-intro.md) + +## Classify these tasks + +For each task below: classify it as **agentic workflow** or **standard Actions workflow**, check the box, then reveal the answer before the next task: + +You just saw how a standard Actions workflow follows fixed steps. Agentic workflows replace those fixed steps with a plain-English task brief — use that contrast to classify the tasks below. + +**Task A:** Run unit tests on every pull request, fail if any test exits non-zero, and upload coverage. + +- [ ] I have classified Task A + +
+Check Task A answer + +**Task A — Standard Actions workflow:** every run follows the same fixed steps: start the test job, fail on a non-zero exit code, and upload the coverage artifact. No judgment required. + +
+ +**Task B:** Review newly opened issues each morning, group them by theme, flag the urgent ones, and post a short triage summary. + +- [ ] I have classified Task B + +
+Check Task B answer + +**Task B — Agentic workflow:** the agent has to inspect live repo context, group similar issues, and decide what looks urgent before it writes the summary. + +
+ +## Reflection + +Before you check the reflection item in the checkpoint below, write one sentence describing what you would want _your_ agentic workflow to do. Put it wherever you keep workshop notes: your editor, a scratch file, or a notes app. Example: summarize new issues and flag urgent ones. Focus on a task that needs judgment, not a test or deploy script. You'll use this idea in Step 7. + +## What the agent decided + +A scheduled agentic workflow generates a report like this: + +```markdown +## Daily Repository Status — July 12 + +- ✅ CI health: 18 workflows succeeded, 1 failed (`docs-link-check`) +- 🔄 Pull requests: 7 open (2 need review, 1 stale > 14 days) +- 🐛 Issues: 4 new, 3 closed, 2 high-priority still open +- 🚀 Releases: No new tags in the last 24 hours + +### Recommended next actions +1. Re-run `docs-link-check` and update broken external URLs. +2. Review PR #412 and PR #415 before noon. +3. Triage high-priority issue #398 with the platform team. +``` + +**Your turn:** Answer in your own words — _what did the agent decide on its own?_ Identify at least two lines where the agent made a judgment call rather than just reading a number. + +## Check your understanding + +Apply what you just saw — answer each question in your notes, then reveal. + +Should the daily report run on a schedule or wait for manual dispatch? State which and why. + +- [ ] I chose a trigger type and explained my reasoning + +
+Check your answer + +A scheduled trigger runs automatically — appropriate for a daily report. `workflow_dispatch` requires a button click in the Actions tab. + +- [ ] Schedule: runs automatically, no button click needed +- [ ] `workflow_dispatch`: requires a manual click each run + +
+ +How does the agent post the report if it always operates read-only? + +- [ ] I explained how the agent writes output + +
+Check your answer + +Agents always run read-only. Any writes — including posting the report — go through [safe outputs](https://github.github.com/gh-aw/reference/safe-outputs/) and guardrails. + +- [ ] The agent itself is always read-only +- [ ] Writes happen through safe outputs and guardrails + +
+ +Write one sentence for the task brief — this becomes your brief in Step 7. + +- [ ] I wrote my one-sentence brief +- [ ] My brief describes a task that needs judgment, not fixed steps + +## The two files + +An agentic workflow has two files. Here is the `.md` source you write: + +```markdown +--- +on: + schedule: daily +permissions: + issues: read +--- + +Review all open issues, summarize the key themes, and post a short digest as a new issue. +``` + +> [!NOTE] +> `schedule: daily` is fuzzy shorthand that `gh aw compile` converts into a standard Actions cron expression. You never write raw cron syntax in an agentic workflow `.md` file. + +And here is the `.lock.yml` `gh aw compile` generates — what GitHub Actions actually runs: + +```yaml +# Auto-generated by gh aw compile. Do not edit by hand. +name: Review open issues +on: + schedule: + - cron: "0 8 * * *" +permissions: + issues: read +``` + +Both files live in `.github/workflows/`. Look at them and answer: which part of the `.md` is the **task brief**, and which part tells GitHub Actions when to run? + +## Concept check — before you continue + +Before you reveal the answers below, write a one-sentence definition for each term: + +- [ ] Agentic workflow +- [ ] Lock file +- [ ] Engine +- [ ] `workflow_dispatch` + +
+Check your answers + +| Term | Plain-language meaning | +|---|---| +| Agentic workflow | A GitHub Actions workflow that uses an AI model to reason and act | +| [Lock file](https://github.github.com/gh-aw/reference/glossary/#workflow-lock-file-lockyml) | The compiled YAML that GitHub Actions actually runs | +| [Engine](https://github.github.com/gh-aw/reference/engines/) | The AI model provider (for example, GitHub Copilot) used by the workflow | +| `workflow_dispatch` | A manual trigger — you start the run by clicking a button in the Actions tab | + +Confirm each: + +- [ ] Lock file: compiled, not hand-edited +- [ ] Engine: AI model provider +- [ ] `workflow_dispatch`: manual trigger from Actions +- [ ] Agentic workflow: AI reasoning loop + +
+ +If you had to look up more than one term, take a moment to review that section before continuing. + +## Classify more tasks + +**Task C:** Each Friday, scan all open issues and pull requests, summarize recent activity by contributor, and post a weekly team progress digest. + +- [ ] I have classified Task C + +
+Check Task C answer + +**Task C — Agentic workflow:** the agent has to read contributor activity across issues and pull requests, decide what counts as meaningful progress, and compose a digest that differs every week. + +
+ +**Task D:** On every pull request, run ESLint (fail on errors), then have an AI read the diff and post a summary comment. + +- [ ] I have classified Task D + +
+Check Task D answer + +**Task D — Agentic (hybrid) workflow:** ESLint is deterministic — same result every run. The AI summary requires judgment: reading the diff and deciding how to describe the change. Combining fixed and AI steps makes a workflow agentic. + +- [ ] The ESLint step produces the same pass-or-fail result every run +- [ ] The AI step produces different output based on what it reads in the diff +- [ ] A workflow mixing deterministic and AI steps is still agentic overall + +
+ +## Self-check + +What makes a workflow agentic rather than standard? Write your answer in your notes. + +- [ ] I wrote my self-check answer in my notes + +
+Show model answer + +A workflow is agentic when an AI agent makes judgment calls — reading context, deciding what matters, and producing output that differs each run. Standard workflows follow fixed steps. + +Does your answer include: + +- [ ] AI making judgment calls on live context +- [ ] Output that varies each run +- [ ] Contrast with standard fixed-step workflows + +
+ +> [!TIP] +> If this still feels fuzzy, Step 7 makes the distinction concrete. Return here after Step 7. + +## ✅ Checkpoint + +- [ ] I can classify tasks as agentic or standard Actions workflows +- [ ] I can point to the task brief and the trigger in the sample `.md` file +- [ ] I can describe the difference between the `.md` source file and the compiled `.lock.yml` +- [ ] I can define: lock file, engine, and `workflow_dispatch` + +--- + +Return to the main adventure: [What Are Agentic Workflows?](05-agentic-workflows-intro.md).