What Makes This an Agent?

A technician asks Botie whether pump P7 needs an inspection. A language model can produce a plausible paragraph about pumps. It cannot establish what the current P7 manual says from that question alone. We need to give it a way to find the record.

We could always look up the manual first and ask the model to explain it. That is a useful workflow. Sometimes the reply raises another question: which revision applies, or has this fault already been inspected? An agent can choose a next step using what it has observed. Our application still decides which proposed steps are allowed.

Filter the available manuals, then decide whether Botie has enough evidence for this small routing task.

answer from evidence

For this first version, Botie must return a short answer supported by the approved manual for the requested asset, or explain that it needs a person to help. It cannot book an inspection. That smaller job lets us see whether reading the right record works before we add effects outside the conversation.

Write down what would count as success and what information is missing. “Be a helpful maintenance agent” does not tell us when to stop.

An agent is useful when choosing the next operation helps the task. A fixed lookup followed by an explanation may be enough for many requests.

A tool definition gives the model a name, an explanation and an argument structure. A proposed call might name read_manual and supply asset P7. Our code checks that structure and the technician’s access before invoking the function.

The function returns data or an explicit error. The application associates that result with the original call and passes it back to the model. A message claiming “I checked the manual” is not evidence that any tool ran.

Proposed call: read_manual(asset="P7")
Tool observation: {"asset": "P7", "revision": "4", "approved": true}

We will implement contracts and permission checks in later lessons. No prompt can replace an enforced permission check.

Suppose the lookup returns no matching manual. Botie might ask which asset the technician meant, consult an authorised index, or hand the task to a person. The appropriate next step depends on the observation.

In an agent, a model may choose among permitted next steps. In a workflow, code may prescribe them. Real applications often combine both: a fixed approval step can surround a model-controlled search.

More autonomy creates more possible paths to test. We will compare those paths against a simple workflow before assuming an agent is necessary.

For the workshop, use a deliberately small controller. Keep approved records for the requested asset. If at least one remains, return answer from evidence. Otherwise request a lookup while any allowance remains, then hand off when it is exhausted.

This controller does not write the answer or validate whether a passage supports every claim. It makes one routing decision. A real run would decrement its allowance when dispatching a lookup and call the controller again with the new observation.

Matching approved evidence exists → answer from evidence
No matching evidence; lookups remaining > 0 → request manual lookup
No matching evidence; lookups remaining = 0 → hand off

The limit stops an unproductive loop. It does not turn missing evidence into permission to guess.

records = [{"asset": "P8", "approved": True},
           {"asset": "P7", "approved": False}]
matching = [r for r in records
            if r["asset"] == "P7" and r["approved"]]
print(matching)

[]

Pydantic AI connects typed inputs and outputs with dependency injection and tool execution. LangChain provides agent construction and integrations. LangGraph exposes graph-based control flow and state, which is useful when a task needs explicit branches or resumable execution. Their responsibilities overlap; choosing one does not settle the design of the task.

We will introduce each with the same maintenance job, so the code has a purpose before we discuss its abstractions. Follow the prompt and tool lessons first if those pieces are still unfamiliar.

Keep application state, provider message history and authoritative business records distinct. A conversation saying an inspection exists is not the work-order database.

Change the requested asset and approval flag in the workshop. Then remove the remaining lookup allowance. The same construction should choose the correct route each time.

These recorded cases make control flow inspectable. Later evaluations must also measure model choices, answer quality, latency and actual tool effects. A deterministic controller test cannot supply that evidence by itself.

These are invented, recorded examples. The browser runs your construction without calling a language model. Passing them checks the surrounding program, not the quality of a live model.