bio_img_matlab

The MATLAB Blog

Practical Advice for People on the Leading Edge

AI Agent Demystified – Building a Minimalist Agent in MATLAB

Posted by Mike Croucher,

19 views (all time)  |   Likes   |   0 comment
Bio: This is a guest post by Toshi Takeuchi, Community Advocate active in online communities. Toshi has held many marketing roles at MathWorks over the last 20 years
You hear about AI agents everywhere these days, but you are not sure what they are, or how real they are. Is it just a hype? I was impressed by what they can do, but couldn't understand how they were possible, until I read somewhere that:
Agents are just LLM + loop + tools.
So, I decided to build a tiny one in MATLAB so that I can learn how it actually works.
Now, agents have stopped feeling mysterious. They start looking like something MATLAB users already understand: a program, a loop, and a few functions.
In this video, I run a small MATLAB agent with a local model served by Ollama. The project uses the MATLAB AI Agent SDK, so most of the agent machinery is handled for us.
You can also find my project on File Exchange.

The Agentic Loop

Most people are familiar with chat-based AI: ask a question, get an answer. Agents go further by taking actions on your behalf. That sounds like a big jump, but the basic building blocks are surprisingly ordinary:
  • LLM - the model that decides what to do next, with reasoning and tool call capabilities.
  • Loop - the program that keeps asking the model for the next step
  • Tools - ordinary functions the model is allowed to call
In MATLAB terms, that can look like this:
conversation = {}; % conversation history
while true % start agentic loop
response = LLMclient(conversation); % call the LLM
conversation{end+1} = response; % append response
if has_tool_calls(response) % if it contains a tool call
results = run_tools(response); % execute requested tools
conversation{end+1} = results; % append tool results
else
disp(response.text); % no more tool calls
break % done
end
end
Real agents also need boundaries: which tools can be called, how many rounds are allowed, and which operations require approval. But the loop is the core.

Tools

This is the part I like most: in my minimal MATLAB agent, tools are just MATLAB functions. Here is tool_read_file, a tool that reads the contents of a text file.
function result = tool_read_file(path)
%TOOL_READ_FILE Read text from a file.
path = resolve_path(path);
if ~isfile(path)
result = "Error: file not found: " + path;
return
end
result = join(readlines(path), newline);
if strlength(result) == 0
result = "(empty file)";
end
end

MATLAB AI Agent SDK

I wanted this project to stay small enough that you could read it in one sitting. Instead of writing my own agentic loop, I used MATLAB AI Agent SDK. I also used Ollama to run a local model and avoid API-key setup. The SDK can also use frontier models through OpenAI-compatible APIs.
The key is that the SDK owns the LLM client, message history, and agentic tool-calling loop, including user approvals.
With the SDK, the loop becomes one line of code.
response = run(bot, prompt);
That is a nice tradeoff for a learning project: the SDK handles the loop, and I get to focus on what the agent can actually do.

A Note About Minimal MATLAB Agent

My goal was to understand how AI coding agents like Claude Code or Codex work, using familiar MATLAB code. I added support for MATLAB MCP Server so I can use existing tools it provides, instead of rolling my own. MCP stands for model context protocol, a standardized way for LLMs to talk to external tools, such as MATLAB.
This is not meant to be production guidance. It is not clear that it makes practical sense to create a MATLAB coding agent that calls a second MATLAB session via MCP to generate MATLAB code, since you can run any MATLAB code directly in MATLAB. I released it as a personal, exploratory project because it makes the moving parts visible. If you build your own agent, you can likely find a better use case.
Please follow the README and install all the dependencies you need:

Project Layout

Minimal MATLAB Agent is small enough to inspect directly:
agent.m Main SDK/Ollama REPL entry point
config.json Runtime configuration
get_tools.m SDK tool registration
load_config.m Config loader
get_system_prompt.m Agent instructions
tools/ Local tools and MCP wrapper tools
mcp/ Stdio MCP client and Python subprocess shim
agent.m is the main file. It loads configuration, creates an Ollama client, connects to the MATLAB MCP Server, registers tools, creates the SDK agent, and then starts a simple command-line prompt.

Configuration

The default model is qwen3:8b running through Ollama:
{
"model": "qwen3:8b",
"ollama_endpoint": "http://127.0.0.1:11434",
"max_tokens": 8192,
"timeout": 600,
"max_iterations": 10,
"verbose": false
}
This keeps the example local. Ollama serves the model, and MATLAB talks to Ollama through an OpenAI-compatible endpoint.
You can pull the model from a terminal:
```bash
ollama pull qwen3:8b
ollama serve
```
If Ollama is already running as a background service, ollama serve may report that the port is already in use. That usually just means the server is already available.

Creating the LLM Client

In agent.m, the project creates an SDK LLM client:
client = aisdk.LLMClient("ollama", model, ...
MaxNumTokens=cfg.max_tokens, ...
TimeOut=cfg.timeout, ...
BaseURL=endpoint);
This is the LLM part of "LLM + loop + tools." The model can be changed in config.json or overridden when starting the agent:
agent(Model="qwen3:8b", Endpoint="http://127.0.0.1:11434")

Defining the tools

The project defines a small set of local tools:
  • read_file
  • write_file
  • list_files
  • ask_user
It also defines MATLAB tools backed by the MATLAB MCP Server:
  • evaluate_matlab_code
  • detect_matlab_toolboxes
  • check_matlab_code
  • run_matlab_file
  • run_matlab_test_file
The tool definitions are ordinary MATLAB code. Here is the read_file tool registration:
readFile = aisdk.LLMTool(@tool_read_file, ...
Name="read_file", ...
Description="Read the contents of a text file.", ...
InputArguments=aisdk.LLMToolArgument("path", ...
DataType="string", ...
Description="Absolute or relative path to the file."));
This tells the model that a tool named read_file exists, describes when to use it, and defines the input argument. The function handle points to the MATLAB implementation.
Some tools can require approval. For example, writing files is useful, but it changes the workspace. The project marks write_file with:
RequiresApproval="always"
That is an important part of agent design. The human user and the host program decide what the agent is allowed to do.

Creating the Agent

Once the client and tools exist, agent.m creates the SDK agent:
workspace = struct("mcpClient", mcpClient, "projectDir", projectDir);
tools = get_tools();
bot = aisdk.AIAgent(client, ...
SystemPrompt=get_system_prompt(), ...
Tools=tools, ...
Workspace=workspace, ...
MaxIterations=cfg.max_iterations, ...
DisplayMode="detailed");
get_system_prompt gives the model its operating instructions. In this project, the prompt tells the model that it is a coding assistant running inside MATLAB, and that it should use tools to inspect files, write files, ask clarifying questions, and execute MATLAB work through the MATLAB MCP Server.
MaxIterations is the loop limit. This prevents the agent from calling tools forever.

Running the Agent

From the project folder, start the agent with:
agent
Or run a single prompt and return immediately:
agent(Prompt="List files in the current directory.")
In my project, the command-line interface is deliberately plain:
Minimal MATLAB Agent - Ollama (type "quit" to exit)
====================================================
You>>

Why This Is Enough to Feel Agentic

This is what surprised me while working on the project: the interesting behavior does not come from a complicated framework. It comes from the loop and the tools.
The model can ask to inspect the workspace. The tool result changes what the model knows. Then the model can ask for the next tool call. After several rounds, the final answer can reflect what actually happened, not just what the model guessed might happen.

What This Means to MATLAB Users

For MATLAB users, the important point is that the tools are just functions. A tool can list files, read a table, run a script, check code, run a test, or ask the user a question. The agentic part is the loop that lets the model choose and use those tools one step at a time.
This means you can use your familiar MATLAB environment and toolboxes to build your own agent with your own domain knowledge, and the SDK takes care of the hard part.
  • You build your agent, so you know what's going on inside, and you can add as much guardrails as you need
  • Reuse your existing MATLAB code assets, such as functions, algorithms, toolboxes, apps, etc. that you trust
  • Use local models to keep the data on premise
  • While LLMs may not be deterministic, the MATLAB part of your agent will be.
One example - you are running an automated process on thousands of test results in MATLAB, but you have a lot of edge cases to inspect. Using the SDK, you can incorporate LLM as a classifier to prioritize those edge cases for human review.

Closing Thought

Once you see an agent as LLM + loop + tools, it becomes much easier to imagine building one yourself.
Try starting small. Pick one useful task from your own MATLAB workflow, expose one or two MATLAB functions as tools, and let the MATLAB AI Agent SDK handle the model client, message history, tool calls, approvals, and loop.
You can also use my project as a starting point for customization. Just for fun, I added a Telegram interface so that I can send voice messages to MATLAB on my smartphone.
Ready to get started with MATLAB AI Agent SDK? Share your thoughts and questions with the MATLAB community, and share your agents on File Exchange.
|
Category: 
Agentic AI,
Gen-AI
  • print

Comments

To leave a comment, please click here to sign in to your MathWorks Account or create a new one.