Skip to content

Commit b587140

Browse files
github-actions[bot]github-actions[bot]
authored
Add node: Step 9 — Reading Workflow Output (#55)
1 parent 06ec9bf commit b587140

2 files changed

Lines changed: 123 additions & 1 deletion

File tree

‎workshop/09-understand-output.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# Step 9: Reading Workflow Output
2+
3+
> _An agentic workflow is only as useful as what you can learn from its output — knowing how to read the results is the skill that lets you improve fast._
4+
5+
## 🎯 What You'll Do
6+
7+
You'll learn how to interpret the three places where agentic workflow results appear: the live run log, the run summary, and the safe-output record. By the end you'll know what a healthy run looks like, how to spot a misbehaving agent, and where to look first when something goes wrong.
8+
9+
## 📋 Before You Start
10+
11+
- Completed [Step 8: Run and Watch Your Workflow](08-run-your-workflow.md)
12+
- Your **Hello Agent** workflow has at least one completed run
13+
14+
---
15+
16+
## Where Does Output Live?
17+
18+
An agentic workflow produces output in three distinct places. Think of them as three different lenses on the same run.
19+
20+
| Location | What it shows | Best for |
21+
|----------|--------------|----------|
22+
| **Live log** | The agent's reasoning steps and tool calls, streamed in real time | Debugging |
23+
| **Run summary** | A structured recap written by the agent after it finishes | Quick health check |
24+
| **Safe-output record** | Every write action the agent actually performed (comments posted, issues created, etc.) | Audit and verification |
25+
26+
---
27+
28+
## Step 1: Anatomy of the Live Log
29+
30+
Open the **Actions** tab, click your completed **Hello Agent** run, then click the job name to open the log.
31+
32+
The log entries follow a predictable pattern:
33+
34+
```
35+
🤔 [plan] Deciding what to do next
36+
🔧 [tool] github.list_issues → {state: open, sort: reactions}
37+
📥 [result] 3 issues returned
38+
🤔 [plan] Issue #4 has 7 👍 reactions — this is the target
39+
🔧 [tool] github.add_comment → {issue_number: 4, body: "..."}
40+
📤 [output] safe-output: add-comment (1 of 1 allowed)
41+
✅ [done] Task complete
42+
```
43+
44+
Each line type tells you something different:
45+
46+
- `[plan]` — the agent is reasoning. No API call has been made yet.
47+
- `[tool]` — the agent is calling an external API. You can see exactly which API and what parameters were sent.
48+
- `[result]` — the raw data that came back from the tool call.
49+
- `[output]` — a write operation is about to be committed (or was blocked by a safe-output limit).
50+
- `[done]` — the agent finished its task.
51+
52+
> [!TIP]
53+
> If you see many `[plan]` lines followed by no `[tool]` lines, the agent may be confused by unclear instructions. Go back to your workflow body and add more specific guidance.
54+
55+
---
56+
57+
## Step 2: Reading the Run Summary
58+
59+
Scroll past the job logs to the **Summary** section of the run page.
60+
61+
The summary is generated by the agent itself at the end of a successful run. A healthy summary looks like this:
62+
63+
```
64+
### Summary
65+
66+
I found 3 open issues. Issue #4 had the most 👍 reactions (7).
67+
I posted a comment on issue #4 summarising the top-voted requests.
68+
69+
**Safe outputs used:**
70+
- add-comment: 1 / 1 allowed
71+
```
72+
73+
Key things to check:
74+
75+
1. **Does the action described match what you asked for?** If you asked for a comment on the top-voted issue but the summary mentions a different issue, check the instructions in your workflow body.
76+
2. **Safe outputs used** — this line shows you whether the agent hit its write limit. A `1 / 1` result means it used its one allowed write. A `0 / 1` means it either had nothing to write or was blocked.
77+
78+
> [!NOTE]
79+
> Not all runs produce a summary section. If the run fails mid-way, the summary may be empty or missing. In that case, the live log is your best diagnostic tool.
80+
81+
---
82+
83+
## Step 3: Verifying the Safe-Output Record
84+
85+
The live log and summary are the agent's own account of what happened. The safe-output record is the ground truth — what was actually written to GitHub.
86+
87+
To see what a run committed, click the **Details** link next to the completed job, then look for the `safe-outputs` step in the job timeline.
88+
89+
Alternatively, go directly to where the output landed. For **Hello Agent**, that's the Issues tab of your repository. Open the issue the agent commented on and check:
90+
91+
- Is the comment text what you expected?
92+
- Does the timestamp match when the run completed?
93+
- Is the format and tone consistent with your instructions?
94+
95+
If the comment exists but the content is wrong, the agent followed your instructions but your instructions were ambiguous. If no comment exists at all, check the safe-output limit (`max:`) in your workflow frontmatter.
96+
97+
> [!WARNING]
98+
> Never edit a comment the agent created just to fix a typo. Instead, fix the agent's instructions and re-run. Editing manually means the next run will post a second comment — now you have two.
99+
100+
---
101+
102+
## Step 4: Common Output Patterns (and What They Mean)
103+
104+
| What you see | What it means | What to do |
105+
|-------------|--------------|-----------|
106+
| Long `[plan]` chains with no `[tool]` calls | Agent is stuck reasoning | Simplify or clarify the task in your workflow body |
107+
| `[tool]` calls that return empty results | The API returned no data | Check permissions — is the required scope listed under `permissions:`? |
108+
| `safe-output: BLOCKED (limit reached)` | Agent tried to write more than `max:` allows | Increase `max:` if the extra write was intentional |
109+
| Run fails with `permission denied` | A tool call was attempted for a scope not in `permissions:` | Add the missing scope (e.g., `issues: write`) |
110+
| Summary says "done" but nothing was written | The agent completed but had nothing to write — or the instructions were satisfied without a write | Review the guidelines in your workflow body |
111+
112+
---
113+
114+
## ✅ Checkpoint
115+
116+
- [ ] I can locate the live log for a completed run and identify `[plan]`, `[tool]`, `[result]`, and `[output]` lines
117+
- [ ] I found the run summary for my **Hello Agent** run
118+
- [ ] I verified the comment the agent posted matches what I asked for
119+
- [ ] I understand what the `safe-outputs used` line in the summary means
120+
- [ ] I know the first place to look when a run produces unexpected output
121+
122+
**Next:** [Step 10: Design Your Daily Repo Status Report](10-design-daily-status.md)

‎workshop/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ A hands-on workshop that takes you from zero to a fully automated, AI-powered da
1616
| 6 | [06-install-gh-aw.md](06-install-gh-aw.md) | Install the gh-aw CLI Extension | ⏳ |
1717
| 7 | [07-your-first-workflow.md](07-your-first-workflow.md) | Write Your First Agentic Workflow | ✅ |
1818
| 8 | [08-run-your-workflow.md](08-run-your-workflow.md) | Run and Watch Your Workflow | ✅ |
19-
| 9 | [09-understand-output.md](09-understand-output.md) | Reading Workflow Output | ⏳ |
19+
| 9 | [09-understand-output.md](09-understand-output.md) | Reading Workflow Output | ✅ |
2020
| 10 | [10-design-daily-status.md](10-design-daily-status.md) | Design: Your Daily Repo Status Report | ⏳ |
2121
| 11 | [11-build-daily-status.md](11-build-daily-status.md) | Build: Daily Repo Status Workflow | ⏳ |
2222
| 12 | [12-test-and-iterate.md](12-test-and-iterate.md) | Test and Improve Your Workflow | ⏳ |

0 commit comments

Comments
 (0)