There has never been more free material for learning AI. A developer in Durban or Polokwane can follow a retrieval tutorial on Monday, an agent framework quick-start on Tuesday and a voice assistant demo by Friday. At the end of the month the GitHub profile is full, and the developer still struggles to answer the questions an architect asks in the first five minutes of a review: why did you add that, what happens when it fails, and what does one request cost?
The problem is not effort. It is the shape of the learning. Tutorials are designed to succeed. They pick the input, skip the edge cases and stop at the moment the happy path works. That is exactly the moment where engineering starts.
This eight-part series takes a different route. It builds one system and lets it grow, one capability at a time, and each capability has to earn its place by fixing a specific failure in the version before it. It is written for developers, architects and technical graduates in South Africa who want to do AI engineering as a job, and for the people who hire them and want to know what good evidence looks like.
The position the whole series rests on is simple:
A portfolio project is credible when it proves how the system fails, not only that the happy path works.
Why tutorials plateau
A tutorial teaches a component in isolation. You learn how to call an embedding model, or how to declare a tool, or how to stream a response. Each is useful. None tells you when to use it, what it costs to keep, or how it interacts with everything else.
Real systems are mostly made of those interactions. Retrieval changes what the model sees, which changes what the output validator has to catch. A tool that books an appointment means the agent loop now needs a stop condition and the logs need a policy decision. Memory reduces repeated questions and creates a data retention obligation. You only meet these consequences when one system carries several capabilities at once.
There is also a hiring problem. A reviewer looking at ten tutorial repositories sees ten variations of the same thing: the code the tutorial author wrote, lightly renamed. A reviewer looking at one system that has gone through five stages, with tests for each failure it was changed to handle, sees judgement.
The system we will grow
Umgeni Fibre is fictional, and its systems and figures are illustrative. Umgeni is a fibre internet provider in Durban with about 38,000 connected homes and small businesses across eThekwini. Its support desk of 16 agents receives roughly 9,000 tickets a month by email, web form and WhatsApp. Most fall into five groups: outages, billing, new installations, router faults and "other".
Today every ticket is read and routed by hand. On a normal day that works. When a fibre break takes out three suburbs, hundreds of tickets arrive in an hour, the billing queries sit behind them, and the one ticket from a business customer whose card machines are offline waits with everything else.
Umgeni's small engineering team, two developers and the support team lead, wants to use AI to help. They do not start by choosing an agent framework. They start with the smallest useful job and a rule: nothing is added until the current design fails at something they can name and measure.
Five stages, each with a reason
The series follows the system through five stages. Every stage adds one new capability and leaves behind evidence that it works.
| Stage | What Umgeni builds | New capability | Evidence it works |
|---|---|---|---|
| 1 | Ticket triage | A structured contract around model output | Schema-valid routing, measured accuracy, cost per ticket |
| 2 | Support assistant | State across turns | Tests for follow-up questions |
| 3 | Knowledge answers | Retrieval and grounding | Retrieval and citation evaluation |
| 4 | Acting assistant | Scoped tools with approval | Audit trail and policy tests |
| 5 | Production desk | Harness, guardrails and observability | Known failure modes and a runbook |
The order matters. Triage comes first because it is small, has a clear right answer for most tickets, and can be checked against history. Memory comes before retrieval because the first thing a conversational assistant gets wrong is forgetting what the customer just said. Retrieval comes before tools because answering from current knowledge is lower risk than changing anything. Tools come before extra agents because most systems never need a second agent at all.
Parts 2 to 7 take those steps one at a time. Part 8 turns the result into a portfolio that an architect and a business leader can both evaluate.
Learn one stack deeply before comparing ten
A common trap is to treat framework choice as the first decision. Developers spend weeks comparing orchestration libraries, vector databases and agent toolkits, and never build anything that runs for more than an afternoon.
For learning, pick one model provider, one programming language you already know well, one way to store data and one way to log. Use them until you understand where they hurt. You will learn more about agents from discovering that your loop retries a failed tool call forever than from reading three comparison tables.
The concepts in this series transfer across stacks. A structured contract, a state record, a retrieval evaluation, a tool permission and a stop condition look much the same whichever library you use. Frameworks change every few months. Those ideas do not, and they are what a reviewer is testing for.
There is a South African reason too. Model usage is priced in US dollars and budgeted in rand, local data rules apply to the customer records you will be handling, and many teams run with a handful of engineers rather than a platform department. A learner who has run one system cheaply and carefully on a single stack is more useful to those teams than one who has sampled many.
What "done" means at each stage
Each stage in this series has a finishing line that is stricter than "it works on my machine". Before moving on, Umgeni's team requires four things:
- A named failure the stage fixes. "Agents forget the account number between turns" is a reason for state. "It would be cool to have memory" is not.
- A test set that shows the fix. Realistic cases, including awkward ones, run automatically.
- A cost and latency figure. Measured per case, not estimated from a pricing page.
- A note of what the stage made worse. Every capability adds risk or cost somewhere. Writing it down is how the next stage gets its reason.
That fourth item is the one most learners skip, and it is the one that most clearly separates engineering from assembly. Retrieval makes answers current and creates an access-control problem. Tools make the assistant useful and create the possibility of a wrong action. Saying so is not pessimism. It is how a design review works.
How this connects to the rest of CloudNala Insights
This series is practical and project-based. Several other CloudNala series go deeper on individual topics, and the parts link to them where it helps. From Chatbot to Agent explains the concepts from the ground up. Memory Is an Architecture Decision, RAG That Survives Production and MCP Without the Hype each take one capability much further than a learning project needs to. If you are a manager rather than a builder, the agent development lifecycle is a better starting point.
Key points
Tutorials stop where engineering starts. They are built to succeed, so they rarely teach failure, cost or interaction between parts.
Grow one system. Five stages, each adding one capability, teach more than many unrelated demos.
Every capability needs a reason. Add it only when the current design fails at something you can name and measure.
Depth before breadth. Learn one stack until you know where it hurts; the concepts transfer, the frameworks churn.
Write down what each stage makes worse. That note is the next stage's justification and the reviewer's favourite page.
Next: Part 2, Your first AI project should include failure and cost. All parts are on the series page.
How CloudNala can help
We work with teams who want to build their first production AI system properly rather than quickly: choosing one small, measurable job, setting up the test set and cost tracking before the first model call, and growing the system only when the evidence says it should grow. The same approach works for internal teams learning on the job and for organisations deciding what a credible first build looks like.
Work with CloudNala
CloudNala helps organisations move from technology ambition to practical execution across cloud, AI, data, platform engineering and digital services.
Whether you are exploring AI, modernising your cloud environment, building a public-sector digital service, or turning an idea into a working MVP, we can help you shape the roadmap and deliver the next step.
Plan an AI MVP Build Sprint or write to us at consult@cloudnala.co.za