Should you’re embedded on the earth of software program improvement, AI, and Massive Language Fashions (LLMs), you in all probability discuss and use AI brokers on a regular basis. If you wish to transcend utilizing brokers and begin to create your personal, this text is for you.
However earlier than we construct our first one, have you ever ever stopped to consider what an AI agent is? Let’s pin down precisely what we imply by the time period — agent.
As you would possibly anticipate, there are as many solutions to this query as there are LLMs, however I feel a broad definition that almost all agree with is that …
An AI agent is a software program system that makes use of an LLM that calls a number of instruments in a loop to succeed in a objective.
The “objective” an agent reaches will be something from answering a easy query to controlling your browser to e-book an airline ticket or creating extremely complicated software program.
Keep in mind that in agentic techniques, the loop describes the cycle between the mannequin, the applying and its instruments. It doesn’t require a literal whereas or for assertion. The instance I will use makes one go by way of that cycle: the mannequin requests a software, Python runs it, and the mannequin makes use of the outcome to reply. As a result of one flip is sufficient, the steps are written out explicitly.
In the remainder of this text, I’ll present you learn how to construct your first AI agent. It received’t do something complicated, however that’s by design to maintain issues easy to start with, not as a result of it may well’t.
The issue our AI agent will remedy
Suppose you run a small on-line store and desire a help assistant that may reply questions on orders. The order information sits in a database, so a language mannequin can’t reply these questions by itself. It wants a managed method to ask your utility for the info.
We’ll construct that managed route utilizing a fictional store and a small SQLite database. The database has two tables. The orders desk shops the order quantity, buyer and date. The order_items desk shops the merchandise, portions, and costs for every order.
Our pattern database accommodates order 1001 for Sarah Jones. She purchased one mechanical keyboard for GBP 79.95 and two USB-C cables at GBP 8.50 every. The proper order complete is subsequently GBP 96.95.
Slightly than making the consumer search for the order and write SQL, we’ll allow them to ask an LLM:
What’s the complete worth of order 1001?
The mannequin will recognise that it wants an order complete and request a Python operate referred to as get_order_total. That operate will question SQLite and return the actual worth. The mannequin can then flip the outcome into an extraordinary sentence.
The mannequin can ask for an operation, however Python decides whether or not it’s allowed and performs it.
Our first model has 4 transferring components:
1. A language mannequin receives a query and an outline of a Python operate.
2. The mannequin asks for that operate to be referred to as with some arguments.
3. Python checks the requested operate title, calls the permitted operate and sends its outcome again.
4. The mannequin writes a solution utilizing the outcome.
The mannequin doesn’t run the operate or hook up with SQLite. Your Python program nonetheless controls each. We’ll run the mannequin domestically by way of Ollama, so the instance doesn’t want a cloud account or an API key. This system will even print the requested operate, its arguments and the database outcome, making the change seen relatively than hiding it inside an agent framework.
The code on this article makes use of Ollama’s Python library, however the normal client-side software sample is shared by different LLM APIs, together with OpenAI and Anthropic. SDK courses, discipline names, and message codecs differ by supplier, so this script is not moveable as-is. The components value carrying throughout are the allowlist, argument validation, operate dispatch, returned software outcome and bounded loop.
What you will want
You’ll want Home windows 10 or 11, sufficient free disk house for an area mannequin, and PowerShell. The instance additionally works on macOS and Linux, though the set up instructions differ.
We’ll use uv to put in Python and handle the undertaking. If uv isn’t already put in, open PowerShell and run:
Shut PowerShell, open a contemporary window and examine it:
Subsequent, set up Ollama. Should you’ve by no means heard of Ollama, it’s a flexible, highly effective software that allows you to run massive language fashions straight in your native machine, so long as you’ve got sufficient RAM to accommodate your chosen mannequin. Obtain the Home windows installer from https://ollama.com/obtain/home windows, run it, then open a brand new PowerShell window and run the command proven beneath.
The obtain is about 3.4 GB as of this writing. Mannequin availability and sizes can change, so examine for errors whenever you run the command above, and ensure the mannequin suits in your reminiscence.
Create the undertaking
Create a brand new listing and add the Ollama Python library:
uv will obtain Python 3.14 if it may well’t discover a appropriate copy. You don’t have to activate the digital surroundings; uv run will use it mechanically.
We’ll construct the database earlier than involving the mannequin. That provides us one thing deterministic to examine: if the database accommodates the mistaken information, there’s no level in debugging the agent.
The database will sit beside the Python scripts and will be recreated everytime you wish to reset the instance.
Creating our take a look at database
Create the file build_shop_database.py with this code:
Run it like this:
SQLite is a part of Python’s customary library, so that you don’t want to put in a database server. The closing(…) wrapper is required as a result of, though sqlite3.Connection utilized in a plain with block handles transactions, it doesn’t shut the connection when the block ends. Explicitly closing it avoids a locked database file on Home windows
Creating our AI agent
Create the file single_software.py and insert the next code.
How the agent code works
The MODEL variable accommodates the Ollama mannequin title. Studying it from the OLLAMA_MODEL surroundings allows you to attempt one other put in mannequin with out modifying the script. DATABASE_PATH factors to the database file shop_agent.db in the identical listing as single_software.py, so the command works no matter your present drive or consumer folder.
get_order_total() is extraordinary utility code. It opens SQLite in read-only mode, runs a parameterised question and returns JSON. The mannequin by no means sees the SQL and may’t hook up with the database itself.
The operate’s title, sort annotation and docstring additionally describe the software to Ollama. When the script passes instruments=[get_order_total], the Ollama library converts that info right into a JSON schema. It sends the schema to the mannequin, not the Python supply code.
messages is the dialog to date. The system message tells the mannequin learn how to behave, and the consumer message accommodates the query. The primary chat() name sends these messages together with the software schema
That decision doesn’t execute the get_order_total() software. If the mannequin decides it wants the software, it returns a request in response.message.tool_calls. For this query, the request is equal to:
The script appends response.message to the historical past as a result of the following mannequin name must see its personal software request. It then checks {that a} software was requested and that its title is strictly get_order_total.
This line is the place the software really runs:
**arguments turns {“order_id”: 1001} into the traditional Python name get_order_total(order_id=1001). The result’s added to the dialog with the software function. tool_name tells the mannequin which requested operate produced it.
The second chat() name receives the whole historical past: the unique query, the mannequin’s software request and the JSON outcome returned by Python. The mannequin now has all the data it wants and may write the ultimate sentence.
Operating the agent
Simply run it such as you would another common Python script, like this
The primary run could pause whereas Ollama masses the mannequin into reminiscence. On my take a look at run, this system printed:
The ultimate sentence can range. Native language fashions generate textual content relatively than deciding on a set response, however the worth ought to stay 96.95 as a result of Python calculated it. For instance, after I ran it a second time, I bought a barely totally different output.
Testing the failure paths
What occurs if we modify the query to an order that doesn’t exist:
This was my output.
The operate returns structured error information. The mannequin ought to clarify that the order wasn’t discovered as a substitute of inventing a complete.
Now to ask one thing the software can’t set up:
My response was:
A mannequin should still reply from normal data or guess. The system message helps, however it isn’t a tough safety boundary. If a solution should come from verified information, your program must examine that an applicable software was referred to as and determine what to do when it wasn’t. Nonetheless, the reply we bought was fairly good for my part.
See the schema the mannequin receives
The comfort of passing a Python operate straight can disguise an vital element. Ollama isn’t sending your supply code to the mannequin. The SDK inspects the operate and produces a JSON schema just like this:
The mannequin sees this alongside the dialog. Its process is to determine whether or not the operate is related and, in that case, produce arguments matching the schema. That’s why including a superb docstring to your operate is vital, because the mannequin could make good use of it.
Schema era isn’t validation. A mannequin can nonetheless ship a string the place an integer was requested, add a discipline that doesn’t exist or request a operate that wasn’t marketed. We’ll learn to take care of a few of these points in future components.
Debugging the output if the mannequin will get it mistaken
When an agent offers a mistaken reply, begin with the software hint. Three totally different failures could look just like the consumer.
-
If no tool_calls have been returned, the mannequin determined it may reply with out the operate. Tighten the system message, enhance the software description or use a mannequin with stronger tool-calling behaviour.
-
Double-check what you despatched as an argument to Python by analyzing the output of the print name.operate.arguments, as this script does. The database can’t return order 1001 when the mannequin requested for 1010.
-
If the Python outcome was appropriate however the ultimate reply was mistaken, the failure occurred whereas the mannequin interpreted the software output. Maintain outcomes quick and structured. For instance, {“total_gbp”: 96.95} is tougher to misinterpret than a paragraph containing a number of numbers. If all else fails, you could want a stronger mannequin.
Utilizing a distinct mannequin
The script reads the OLLAMA_MODEL surroundings variable, making it simple to modify fashions if wanted. Use Ollama to tug one other tool-capable mannequin, then set the variable for one PowerShell session. For instance,
A bigger mannequin wants extra reminiscence and disk house and can often reply extra slowly on the identical {hardware}. Don’t assume {that a} fluent ultimate sentence means higher software use. Strive lacking order IDs, irrelevant questions and ambiguous wording, then examine the requested operate and arguments.
Abstract
Beginning with a definition of what an AI agent actually is, this text confirmed you learn how to construct a easy agent utilizing Python, Ollama and SQLite, operating domestically and not using a cloud account or API key.
Utilizing a fictional store’s order information, it walked by way of how a language mannequin requests a software, how Python checks and executes that request, and the way the mannequin turns the outcome into a solution.
Alongside the way in which, you discovered how software schemas work, and learn how to diagnose points when the mannequin will get issues mistaken.
This intentionally easy instance retains the mechanics seen and supplies a place to begin for brokers that use a number of instruments throughout a number of steps.
That’s the job of the following article.
