Skip to content

fix(05): split agentic-workflows-intro to reduce cognitive load #1787

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
pelikhan merged 3 commits into from
Jul 21, 2026
Merged

fix(05): split agentic-workflows-intro to reduce cognitive load #1787

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
dafd994
Initial plan
Copilot Jul 21, 2026
e5ee050
fix(05): split agentic-workflows-intro into overview + side quest to …
Copilot Jul 21, 2026
85bd51e
fix: clarify step reference in side quest reflection section
Copilot Jul 21, 2026
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
205 changes: 3 additions & 202 deletions workshop/05-agentic-workflows-intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

<details>
<summary>Check Task A answer</summary>

**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.

</details>

**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

<details>
<summary>Check Task B answer</summary>

**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.

</details>

## 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

<details>
<summary>Check your answer</summary>

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

</details>

How does the agent post the report if it always operates read-only?

- [ ] I explained how the agent writes output

<details>
<summary>Check your answer</summary>

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

</details>

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`

<details>
<summary>Check your answers</summary>

| 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

</details>

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

<details>
<summary>Check Task C answer</summary>

**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.

</details>

**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

<details>
<summary>Check Task D answer</summary>

**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

</details>

## 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

<details>
<summary>Show model answer</summary>

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

</details>

> [!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

<!-- journey: all -->
**Next:** [Install the gh-aw CLI Extension](06-install-gh-aw.md)
<!-- /journey -->


1 change: 1 addition & 0 deletions workshop/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
Loading
Loading