Agent Design Workshop

Agent Design Workshop is a Streamlit demo that helps people understand how AI agents work internally.

It is a glass-box teaching tool, not a production assistant. The goal is to make planning, execution, memory, tools, validation, policy checks, approval gates, and failure handling visible. Instead of hiding the internal logic behind a chat interface, the app exposes the workflow step by step so students can see how an agent system reasons about a task.

This version is not connected to a live LLM. The behavior is driven by structured demo cases and local datasets so the experience stays predictable, inspectable, and easy to teach. That makes it useful for workshops, classroom demos, design reviews, and internal training sessions where the point is to understand agent architecture rather than to optimize model performance.

What this demo shows

The app is designed as a live walkthrough of how an agent system can behave when it receives a user request such as scheduling a meeting.

It demonstrates:

• how a raw user request is turned into structured data
• how a planning loop builds and revises a plan
• how tool selection depends on workflow availability and risk
• how temporary state evolves during execution
• how central memory differs from task-scoped memory
• how validation differs from policy
• how high-risk actions require human approval
• how outputs can fail, retry, pause, or wait for user input
• how an agent system can be observable and auditable

The emphasis is on decisions and looping. The user does not just see the final answer. The user can click through each stage and inspect what changed, what was skipped, what was blocked, and why.

Core idea

Most chatbot demos compress everything into one interaction: prompt in, answer out.

This workshop does the opposite. It treats the agent as a system composed of:

• planning
• workflow decisions
• tools
• memory
• quality checks
• policy and guardrails
• human approval
• execution state
• logs and traces

That makes it easier to teach a more realistic mental model of modern agent design.

Current teaching surface

The app uses a persistent chat panel on the left and a debugger-style teaching surface on the right.

The main tabs are:

• Planning Status
• Execution
• Dataset
• Memory
• Tools
• Quality Checks
• Policy / Guardrails
• Graph Layer
• Logs / Trace

These tabs make the internal layers visible without requiring students to read code first.

How it works

The current implementation uses hard-coded scenario files and local data instead of a live model backend.

At a high level:

1. A user enters a request in chat.
2. The system moves through a staged planning flow.
3. The user clicks Next step to reveal each internal transition.
4. The plan is reviewed against available tools, rules, and memory.
5. Once planning is approved, execution begins.
6. Each execution step updates task state, memory, and logs.
7. Wait states such as Wait for answer and Wait for approval are handled explicitly.

This design keeps the workshop deterministic enough for teaching while still feeling like a real agent debugger.

Why it is useful for teaching

This project is meant to help people answer questions like:

• What is the difference between a tool and a workflow?
• When should the system ask the user instead of acting?
• What belongs in short-lived memory versus durable memory?
• Why is a plan revised before execution?
• What should happen when a tool fails or returns incomplete output?
• Why should approval be explicit for high-risk actions?
• How do we know what the system did and why?

In short, it teaches agent design as systems design.

Enterprise-readiness lens

Although this repo is a teaching demo, it is intentionally framed around patterns that matter in enterprise agent systems.

Structured, atomic workflows

The system breaks work into explicit, named steps rather than allowing an opaque end-to-end jump from request to action. That supports inspection, replay, and controlled orchestration.

Assistive before autonomous

The flow is designed to help the user and pause often. It asks clarifying questions, waits for answers, and gates risky actions instead of assuming the system should act independently.

Least-privileged tool access by severity

Read-only steps, draft-creation steps, and high-risk send steps are treated differently. This reinforces the principle that not all tools should have the same authority.

Evaluations as a first-class citizen

Even though this is a demo, the design treats checks, review logic, and outcome quality as part of the system rather than as an afterthought.

Observable and auditable by default

The app exposes plan state, tool usage, memory, checks, and trace events. A user can inspect the workflow instead of trusting a black box.

Explicit failure handling and graceful fallback

The workflow models retry, wait, skip, fail, block, and approval states directly. Failures are not hidden. They are part of the teaching surface.

Stateful memory with clear separation of temporal vs. canonical memory

The app distinguishes between task-scoped memory and central memory. This helps explain why some facts should change during a run while others should remain durable and curated.

Grounded outputs with provenance

Outputs are tied back to the tool, dataset, rule, or user reply that produced them. The point is to show where information came from and why it should be trusted.

Human approval for high-risk actions

The workflow requires explicit approval before send-like actions. This models a practical human-in-the-loop control point.

Secure, compliant, and policy-driven

Validation and policy are separated on purpose. Something can be structurally valid but still blocked by policy. That distinction matters in real organizations.

Cost-efficient and latency-aware

The demo uses stepwise execution and local structured data so each stage is small, inspectable, and cheap to run. This also helps teach why not every problem should trigger a large autonomous loop.

Responsive UX with streaming and user control

The user controls progression. The system does not race ahead invisibly. That makes the demo easier to understand and reflects a safer design pattern for sensitive workflows.

Versioned, testable, and rollback-safe

The workshop models plan revision explicitly. Plans are reviewed, changed, and approved before execution, which mirrors the discipline needed in robust operational systems.

Important limitation

This is not a production agent framework.

It does not:

• connect to real Gmail, Calendar, Slack, or external APIs
• rely on a live LLM for reasoning
• manage enterprise auth, tenancy, or access control
• provide production-grade persistence or scale guarantees
• replace formal observability or governance infrastructure

That limitation is intentional. The workshop is optimized for clarity, not for deployment scale.

Repository structure

• /Users/lfinger/Lutz_Dev/Workshop-Agents/app.py — main Streamlit app
• /Users/lfinger/Lutz_Dev/Workshop-Agents/cases/ — hard-coded demo scenarios in markdown
• /Users/lfinger/Lutz_Dev/Workshop-Agents/datasets/contacts.json — local demo dataset
• /Users/lfinger/Lutz_Dev/Workshop-Agents/requirements.txt — minimal dependency list

Run locally

Create and activate a virtual environment if needed, then install the dependency and run Streamlit:

cd /Users/lfinger/Lutz_Dev/Workshop-Agents
pip install -r requirements.txt
streamlit run app.py

Then open the local URL shown by Streamlit, usually:

• http://localhost:8501

Suggested demo flow

For a short workshop, a good sequence is:

1. Enter a simple request in chat.
2. Walk through planning one click at a time.
3. Compare the plan against tools and rules.
4. Move into execution and inspect task memory changes.
5. Show a wait state such as user input or approval.
6. Highlight how policy, validation, and logs differ.

That gives students a usable mental model of agent architecture in one session.

Why this repo exists

This repo exists to answer a practical question:

How does an AI agent actually work when we make its internal system visible?

The answer is not just “it calls an LLM.” A useful agent depends on workflow structure, memory boundaries, tool design, approvals, validations, fallbacks, and observability. This workshop is a compact demo of those ideas.