Skip to content

Commit 825c83a

Browse files
Copilotimran-siddique
Copilot
and
imran-siddique
authored
docs: Add 2-hour AI agent governance workshop kit (microsoft#1195)
* Initial plan * feat: add 2-hour AI agent governance workshop materials Adds a complete workshop kit in docs/workshop/: - README.md: overview, agenda, quick-start for facilitators - slides.md: 22-slide Markdown deck (why governance, trust/identity, production patterns) - lab-guide.md: participant lab guide with 3 hands-on exercises - facilitator-notes.md: per-slide talking points, timing guide, FAQ, common issues - prerequisites.md: participant setup checklist with self-test script - labs/lab1_first_policy.py: starter template for YAML policy evaluation lab - labs/lab2_multi_agent_trust.py: starter template for multi-agent trust handshake lab - labs/lab3_full_governance_stack.py: starter template for full governance pipeline lab Also updates docs/tutorials/README.md to reference the workshop as the recommended entry point for new learners. Resolves #<workshop-issue> Agent-Logs-Url: https://github.com/microsoft/agent-governance-toolkit/sessions/20bcfefe-4e96-489c-9ead-36b413ab4067 Co-authored-by: imran-siddique <45405841+imran-siddique@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: imran-siddique <45405841+imran-siddique@users.noreply.github.com>
1 parent 85a0085 commit 825c83a

9 files changed

Lines changed: 1838 additions & 3 deletions

File tree

‎docs/tutorials/README.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,12 @@ first policy rule to production-grade observability. Each tutorial includes
55
runnable code examples, API reference tables, and cross-references to related
66
guides.
77

8-
> **New here?** Start with [Tutorial 01 — Policy Engine](01-policy-engine.md),
9-
> then follow the numbered sequence. Each tutorial builds on concepts from
10-
> earlier ones.
8+
> **New here?** Try the [2-hour hands-on workshop](../workshop/README.md) first —
9+
> it covers policy, trust, and audit with guided labs. Then work through the
10+
> numbered tutorials for deeper dives.
11+
>
12+
> Already comfortable with the basics? Start with
13+
> [Tutorial 01 — Policy Engine](01-policy-engine.md) and follow the numbered sequence.
1114
1215
---
1316

‎docs/workshop/README.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# 🎓 Workshop: Introduction to AI Agent Governance
2+
3+
> **Duration:** 2 hours · **Level:** Beginner–Intermediate · **Format:** Lecture + Hands-on Labs
4+
5+
A complete, self-contained workshop kit for teaching AI agent governance using the
6+
Agent Governance Toolkit. All materials are in this folder — facilitators need only
7+
a laptop and the prerequisites below.
8+
9+
---
10+
11+
## Workshop Materials
12+
13+
| File | Purpose |
14+
|------|---------|
15+
| [slides.md](slides.md) | Slide deck — 22 slides covering governance concepts |
16+
| [lab-guide.md](lab-guide.md) | Participant lab guide with 3 hands-on exercises |
17+
| [facilitator-notes.md](facilitator-notes.md) | Facilitator guide with talking points and timing |
18+
| [prerequisites.md](prerequisites.md) | Participant setup checklist (share 48 h before the session) |
19+
| [labs/lab1_first_policy.py](labs/lab1_first_policy.py) | Starter template for Lab 1 |
20+
| [labs/lab2_multi_agent_trust.py](labs/lab2_multi_agent_trust.py) | Starter template for Lab 2 |
21+
| [labs/lab3_full_governance_stack.py](labs/lab3_full_governance_stack.py) | Starter template for Lab 3 |
22+
23+
---
24+
25+
## Agenda (2 hours)
26+
27+
| Time | Segment | Format |
28+
|------|---------|--------|
29+
| 0:00–0:20 | Why governance matters | Slides 1–7 |
30+
| 0:20–0:40 | **Lab 1** — Your first policy | Hands-on |
31+
| 0:40–0:55 | Trust and identity concepts | Slides 8–14 |
32+
| 0:55–1:15 | **Lab 2** — Multi-agent trust | Hands-on |
33+
| 1:15–1:25 | Break | — |
34+
| 1:25–1:40 | Production patterns | Slides 15–22 |
35+
| 1:40–2:00 | **Lab 3** — Full governance stack | Hands-on |
36+
37+
---
38+
39+
## Quick Start for Facilitators
40+
41+
1. **Share prerequisites 48 h before the session** — send participants [prerequisites.md](prerequisites.md).
42+
2. **Open the slide deck** — render [slides.md](slides.md) with any Markdown presenter
43+
(e.g., [Marp](https://marp.app/), [Slidev](https://sli.dev/), GitHub preview).
44+
3. **Distribute lab templates** — participants work in the `labs/` folder.
45+
4. **Reference facilitator notes** — [facilitator-notes.md](facilitator-notes.md) has per-slide
46+
talking points, common questions, and timing cues.
47+
48+
---
49+
50+
## Skills Needed
51+
52+
- **Facilitator:** comfort with Python, familiarity with AI agents concepts
53+
- **Participants:** Python basics (`for` loops, dictionaries, `pip install`)
54+
55+
---
56+
57+
## Related Resources
58+
59+
- [Tutorial 01 — Policy Engine](../tutorials/01-policy-engine.md) — deep-dive after Lab 1
60+
- [Tutorial 02 — Trust & Identity](../tutorials/02-trust-and-identity.md) — deep-dive after Lab 2
61+
- [Tutorial 04 — Audit & Compliance](../tutorials/04-audit-and-compliance.md) — deep-dive after Lab 3
62+
- [QUICKSTART.md](../../QUICKSTART.md) — 10-minute overview of the full toolkit

‎docs/workshop/facilitator-notes.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Facilitator Notes — Introduction to AI Agent Governance
2+
3+
> For facilitator use only. Keep this tab open alongside the slide deck.
4+
5+
---
6+
7+
## Before the Session
8+
9+
- [ ] Send [prerequisites.md](prerequisites.md) to participants **48 hours** in advance.
10+
- [ ] Test all three lab scripts on your own machine and note any errors.
11+
- [ ] Confirm the venue has reliable Wi-Fi — participants need `pip install` access.
12+
- [ ] Prepare a backup: download the packages and serve them locally with
13+
`pip install --find-links ./wheels/ agent-os-kernel agentmesh-platform agent-governance-toolkit`
14+
in case the internet is unavailable.
15+
- [ ] Open [slides.md](slides.md) in your presenter tool and rehearse transitions.
16+
- [ ] Identify 2–3 volunteers in advance who have completed prerequisites — they
17+
can help other participants during lab time.
18+
19+
---
20+
21+
## Agenda and Timing
22+
23+
| Segment | Duration | Cumulative | Notes |
24+
|---------|----------|------------|-------|
25+
| Intro + agenda (Slides 1–2) | 3 min | 0:03 | Keep this brief |
26+
| Why governance matters (Slides 3–6) | 12 min | 0:15 | Invite 1–2 audience questions |
27+
| Lab 1 intro (Slide 7) | 5 min | 0:20 | Live-code Step 1 on projector |
28+
| **Lab 1 — First policy** | 20 min | 0:40 | Circulate; most issues are YAML indentation |
29+
| Lab 1 debrief | 2 min | 0:42 | Ask: "Who got all 5 scenarios matching?" |
30+
| Trust & identity (Slides 8–13) | 13 min | 0:55 | Walk through the handshake diagram slowly |
31+
| Lab 2 intro (Slide 14) | 5 min | 1:00 | Live-code Step 1 on projector |
32+
| **Lab 2 — Multi-agent trust** | 20 min | 1:20 | Common issue: forgetting to record events |
33+
| Break ☕ | 10 min | 1:30 | Hard stop — labs 3 must start on time |
34+
| Production patterns (Slides 15–20) | 10 min | 1:40 | Keep slides 18–19 to 2 min each |
35+
| Lab 3 intro (Slide 21) | 3 min | 1:43 | Show pipeline diagram |
36+
| **Lab 3 — Full stack** | 20 min | 2:03 | The tampering step usually draws "wow" reactions |
37+
| Wrap-up & next steps (Slide 22) | 5 min | 2:08 | OK to run over by 8 min |
38+
39+
---
40+
41+
## Slide-by-Slide Talking Points
42+
43+
### Slide 3 — The Problem
44+
45+
> "Raise your hand if you've deployed a web service with no authentication. No
46+
> one? Right — we learned that lesson in the 1990s. AI agents are at exactly
47+
> that point today. Most agents run with no policy, no identity, and no audit
48+
> trail."
49+
50+
Good analogy: an agent without governance is like `chmod 777` on a production
51+
server — it works, until it doesn't.
52+
53+
### Slide 4 — OWASP ASI Top 10
54+
55+
Don't go through every item. Highlight three:
56+
57+
- **ASI-01 Prompt Injection** — the most common attack today
58+
- **ASI-03 Excessive Agency** — agents doing more than they should
59+
- **ASI-08 Inadequate Logging** — you can't investigate what you can't see
60+
61+
### Slide 5 — The Toolkit
62+
63+
Emphasise: these aren't theoretical controls. Every layer has runnable Python.
64+
65+
### Slide 6 — Three Layers
66+
67+
Spend 30 seconds per layer. The YAML snippet for policies often surprises people
68+
with how simple it is — lean into that.
69+
70+
### Slides 8–11 — Trust and Identity
71+
72+
The trust handshake diagram (Slide 11) is the most complex diagram in the deck.
73+
Walk through it step by step:
74+
75+
1. Initiator sends a random challenge (nonce)
76+
2. Responder signs with Ed25519 private key
77+
3. Initiator verifies with public key
78+
4. Initiator checks trust score ≥ threshold
79+
80+
If anyone asks "why not JWT?" — JWTs require a central issuer and don't
81+
naturally support dynamic trust scores.
82+
83+
### Slides 15–20 — Production Patterns
84+
85+
These are reference slides. Don't try to cover every cell in the tables.
86+
Instead, pick whichever 2–3 patterns are most relevant to the audience
87+
(enterprise? → compliance gates; startup? → policy-as-code and circuit breakers).
88+
89+
---
90+
91+
## Common Issues and Fixes
92+
93+
### Lab 1
94+
95+
| Symptom | Cause | Fix |
96+
|---------|-------|-----|
97+
| `yaml.scanner.ScannerError` | YAML indentation error | Check that `rules:` is flush-left; list items indent 2 spaces |
98+
| All calls return `allow` | `defaults.action` is `allow` and no rules matched | Add `print(decision.reason)` to debug which rule matched |
99+
| `ImportError: agent_os` | Package not installed | `pip install agent-os-kernel` |
100+
101+
### Lab 2
102+
103+
| Symptom | Cause | Fix |
104+
|---------|-------|-----|
105+
| Trust score stays at 500 | `record_event()` not called | Confirm the loop is executing: add `print(i)` |
106+
| `AttributeError: revoke` | Old package version | `pip install --upgrade agentmesh-platform` |
107+
| Handshake never succeeds | Threshold too high | Lower `min_trust_score` to 540 for demonstration purposes |
108+
109+
### Lab 3
110+
111+
| Symptom | Cause | Fix |
112+
|---------|-------|-----|
113+
| Tampering check returns `True` | Mutated the wrong field | Make sure you mutate `audit.entries[0].outcome`, not a copy |
114+
| `AuditLog` has no `entries` | Using wrong import | Use `from agentmesh.governance.audit import AuditLog` |
115+
116+
---
117+
118+
## Frequently Asked Questions
119+
120+
**Q: Does this work with LangChain / CrewAI / AutoGen?**
121+
122+
A: Yes — see [Tutorial 03 — Framework Integrations](../tutorials/03-framework-integrations.md).
123+
The `agent-os-kernel` package ships middleware adapters for all major frameworks.
124+
125+
**Q: Can I use my own policy format (OPA/Rego)?**
126+
127+
A: Yes — [Tutorial 08](../tutorials/08-opa-rego-cedar-policies.md) covers OPA,
128+
Rego, and Cedar. The policy engine supports pluggable backends.
129+
130+
**Q: Is there a cloud-hosted version?**
131+
132+
A: The toolkit is designed to run wherever your agents run — on-premises, cloud,
133+
or local. There's no SaaS dependency.
134+
135+
**Q: What about Python < 3.10?**
136+
137+
A: Python 3.10 is the minimum for all packages. Most features work on 3.9 but
138+
it's not officially supported.
139+
140+
**Q: How do I handle secrets / API keys in policies?**
141+
142+
A: Never hardcode secrets. Use environment variables and reference them in policy
143+
YAML as `${ENV_VAR_NAME}`. See [SECURITY.md](../../SECURITY.md).
144+
145+
---
146+
147+
## Post-Session
148+
149+
- [ ] Collect feedback (1-minute written form or quick show-of-hands on value/difficulty).
150+
- [ ] Share the GitHub repo link and encourage participants to star it.
151+
- [ ] Point advanced participants at the full tutorial series in
152+
[docs/tutorials/README.md](../tutorials/README.md).
153+
- [ ] File any bugs or content improvements found during the session as GitHub issues.

0 commit comments

Comments
 (0)