A hands-on teaching tool built by the QUT Digital Observatory to demonstrate how agentic AI workflows operate — and where they break down.
This repository contains a small web application that lets you interrogate a fictional crime network using an AI agent. You ask questions in plain English ("Who is the most connected actor in Group A?"), and a large language model autonomously decides which analytical tools to call, combines the results, and streams its reasoning back to you in real time.
The dataset is entirely synthetic — 160 made-up people, 320 invented police reports, two rival gangs who traffic counterfeit Pokémon cards — so there are no privacy or sensitivity concerns. The point is to watch the agent think, not to do real criminology.
This is a demo. It is deliberately incomplete. Parts of the workflow are broken or artificially limited so that workshop participants can experience the failure modes of agentic systems first-hand. If you find something that doesn't work, that's often by design.
Primarily researchers and academics who want a concrete, low-stakes environment to understand:
- How agentic AI systems orchestrate tool use
- What "streaming reasoning" looks like in practice
- Where these workflows succeed and where they fall apart
- How network analysis and LLMs can be combined
No prior programming experience is needed to use the app. Some familiarity with Python is helpful if you want to explore or modify the code.
The app has three panels:
| Panel | Purpose |
|---|---|
| Chat | Ask natural-language questions about the crime network |
| Network graph | Interactive visualisation of actors and their connections |
| Trace | Step-by-step log of every tool the agent called and why |
The agent has access to eight analytical tools covering entity lookup, network centrality, shortest-path finding, community detection, crime report search, and location statistics.
Workshop_agentic_workflow/
├── app.py # FastAPI web server (4 endpoints)
├── agents/
│ ├── supervisor.py # AI agent orchestrator (Google Gemini)
│ └── tools.py # 8 network analysis tools
├── data/
│ ├── actors.json # 160 synthetic actors
│ ├── crime_reports.json # 320 synthetic police reports
│ ├── locations.json # 22 incident locations
│ └── networks/ # Graph edge-list files
├── ground_truth/ # Reference answers (kept aside during workshops)
├── static/
│ └── index.html # Frontend UI
├── generate_data.py # Script that produced the synthetic dataset
├── smoke_test.py # Validates the 8 tools without hitting the API
├── verify_network.py # Network integrity checks
└── requirements.txt # Python dependencies
app.py— starts the web server, serves the UI, and exposes/api/askas a Server-Sent Events endpoint so agent responses stream to the browser in real time.agents/supervisor.py— the agent brain. Sends your question to Gemini, interprets which tools to call, loops until it has a complete answer, and streams intermediate steps.agents/tools.py— the tools themselves, implemented with NetworkX. Each tool has a well-defined schema that the LLM can read and invoke.generate_data.py— how the synthetic dataset was built. You can re-run it to regenerate or modify the data.
| Requirement | Notes |
|---|---|
| Python 3.9 or later | 3.11+ recommended |
| A Google Gemini API key | Free tier is sufficient for workshop use |
| Internet access | Required for Gemini API calls |
Note — LLM provider: This app is built specifically for Google Gemini via the
google-genaiSDK. It is not currently compatible with OpenAI, Anthropic, or other providers without code changes. All agent logic inagents/supervisor.pycalls the Gemini API directly.
- Go to https://aistudio.google.com/apikey and sign in with a Google account.
- Click Create API key and copy the key shown.
- The free tier is sufficient for workshop use — no billing setup required.
- Keep the key private; do not commit it to version control.
If you're new to working with code, we recommend Visual Studio Code (VS Code) — it's free, works on Windows, Mac, and Linux, and has a built-in terminal so you can run all the commands below without leaving the editor. Install the Python extension from the Extensions panel once VS Code is open.
Step 1 — Clone the repository
git clone https://github.com/qut-digital-observatory/workshop_agentic_workflow.git
cd workshop_agentic_workflowStep 2 — Create a virtual environment
A virtual environment keeps this project's dependencies separate from other Python projects on your machine. This step is optional but strongly recommended.
python -m venv venvThen activate it:
- Mac / Linux:
source venv/bin/activate - Windows (Command Prompt):
venv\Scripts\activate.bat - Windows (PowerShell):
venv\Scripts\Activate.ps1
You should see (venv) appear at the start of your terminal prompt when it's active.
Step 3 — Install dependencies
pip install -r requirements.txtStep 4 — Add your Gemini API key
The app reads your API key from a file called .env in the project root. A template file called .env.example is already included to show you the exact format.
- In your file explorer (or VS Code), find the file
.env.examplein the project folder. - Make a copy of it in the same folder and rename the copy to
.env(just remove the.examplepart). - Open
.envin a text editor. You will see:GEMINI_API_KEY="your key here" - Replace
your key herewith the API key you copied from Google AI Studio, keeping the quote marks. It should look something like:GEMINI_API_KEY="AIzaSyABC123examplekeyDEF456" - Save the file.
Important: The
.envfile contains a secret. Never share it, email it, or commit it to GitHub. The.gitignorefile in this project already prevents it from being accidentally uploaded.
uvicorn app:app --reloadThen open http://localhost:8000 in your browser.
| Package | Version | Purpose |
|---|---|---|
fastapi |
0.110+ | Web framework |
uvicorn |
0.27+ | ASGI server |
networkx |
3.2+ | Graph algorithms |
google-genai |
1.7+ | Gemini API client |
python-dotenv |
any | Loads .env file |
python smoke_test.pyThis runs all eight tools against the local dataset without making any API calls — useful to confirm your environment is set up correctly before using Gemini.
This is a toy system built to surface the real constraints of agentic workflows:
- The dataset is small and static. The agent cannot browse the internet or access external databases.
- The agent will sometimes call the wrong tool, hallucinate connections, or loop unnecessarily. This is expected and instructive.
- Certain analytical paths are intentionally incomplete to give workshop participants something to fix or reason about.
- Response quality depends heavily on how questions are phrased — prompt engineering matters.
Fixing broken parts is entirely fine and encouraged. See the attribution note below if you build on this publicly.
This software was created by the QUT Digital Observatory and is provided as-is, free of charge, for educational and research purposes.
A few things to keep in mind:
- It is deliberately broken in places. That is a feature, not a bug. Please use it in the spirit it was created — as a learning tool for understanding agentic AI workflows, not as production software.
- You are welcome to fix it, extend it, and build on it. If you do use this work in a public setting — a publication, a presentation, a course, a public repository — we ask that you credit the QUT Digital Observatory.
- Questions are welcome. For general queries about how the code works, feel free to open a GitHub issue. If you need more substantial assistance (customisation, integration into a research project, running a workshop), that can be arranged — get in touch.
Contact: digitalobservatory@qut.edu.au
Suggested credit line:
Agentic Workflow Workshop Demo, QUT Digital Observatory (https://www.digitalobservatory.net.au/)
QUT Digital Observatory — making computational research methods accessible to the academic community.