How to Build an AI Agent on a VPS: A Step-by-Step Guide
AI agents are slowly moving from being a hobbyist's toy to a real working tool: they answer support tickets, monitor servers, parse data, and automate routine tasks that used to take hours. Many people start by trying out ready-made cloud platforms, but quickly run into limits, subscription costs, or simply want more control over where their data lives and how the agent actually behaves. The solution is to deploy it on your own server.
In this article, we'll cover what an AI agent actually is, how it's structured under the hood, and walk through the whole path: from choosing and preparing a VPS to running an agent as a permanent service. The material is aimed at people who already know their way around a terminal but don't necessarily have a deep background in machine learning — every step is explained in plain language.
What is an AI agent and how is it different from a chatbot
Put simply, a chatbot is a program that answers a question with text and stops there. An AI agent goes further: it can break a task into subtasks, call external tools — a search engine, a database, a calculator, a third-party API — and adjust its next steps based on the results it gets back.
Technically, an agent is made up of several parts:
- Language model (LLM) — the agent's brain, which analyzes the task and decides what to do next.
- Tools — functions the agent can call: web search, code execution, API requests, file operations.
- Memory — short-term (the current conversation's context) and long-term (a vector database for storing facts and history).
- Orchestrator — the logic that ties everything together: it receives the task, runs it through a "reason → act → observe" loop, and decides when the task is done.
This loop is often called ReAct (reasoning + acting): the model reasons out loud, picks a tool, gets a result, reasons again — and so on until it produces a final answer. This ability to take several steps in a row is exactly what sets an agent apart from a single request to a neural network.
How it works: the agent's architecture step by step
At first glance an agent looks like something monolithic and complex, but in practice the whole system is assembled from a handful of independent blocks that talk to each other through an API.
- A user or an external system sends the agent a task — for example, "check whether disk load has spiked and send me a report."
- The orchestrator passes the task to the LLM along with a list of available tools and their descriptions.
- The model decides which tool is needed — say, a function that runs df -h on the server.
- The orchestrator executes the tool and returns the result to the model.
- The model analyzes the result and decides: either another step is needed (for example, sending a Telegram notification), or the task is done and it's time to form a final answer.
What's worth noting is that this loop can repeat dozens of times if the task is complex. That's why it's important to plan limits in advance: a maximum number of steps, timeouts for tool execution, and a budget for calls to the model's API.
Preparing a VPS for an AI agent
The server requirements depend heavily on how the agent talks to the language model. If it works through an external provider's API (OpenAI, Anthropic, and so on), the server only acts as a "dispatcher": it accepts requests, calls tools, talks to the API, and returns the answer. For this scenario, a server with 2 vCPU and 4 GB of RAM is enough — that covers a Python application, a task queue, and a small database.
The picture changes if you plan to run a local model (for example, via Ollama or vLLM). Then the load falls on the server itself: 7-8 billion parameter models run comfortably starting from 16 GB of RAM, and larger models — or acceptable generation speed — will require a GPU. For most practical tasks — a support agent, monitoring, report automation — models accessed via API turn out cheaper and easier to maintain, so it makes sense to start with those.
For this kind of environment, a VPS server from Serverspace works well — you can pick a configuration that fits the task and scale resources later as the load on the agent grows.
After ordering the server, connect via SSH and update the system:
sudo apt update && sudo apt upgrade -y
sudo apt install -y software-properties-common curl gitSetting up the environment for the agent
Most AI agent frameworks are written in Python, so the first step is installing the right interpreter version and creating an isolated environment — this keeps the project's dependencies from clashing with system packages.
sudo apt install -y python3 python3-venv python3-pip
mkdir ~/ai-agent && cd ~/ai-agent
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pipNext, you'll need an API key for whichever model the agent will use. It's best not to store it in the code itself, but in environment variables — for example, in a .env file that's excluded from version control. It's a basic security measure that's easy to overlook during quick prototyping.
Choosing a framework for the agent
You can write an orchestrator from scratch, but it's almost always easier to lean on a ready-made framework — it handles the reasoning loop, prompt formatting, and tool integration for you. Here are the main options people reach for most often right now:
| Framework | Key features | Best for |
|---|---|---|
| LangChain | Large ecosystem, plenty of ready integrations with databases, search engines, and APIs | General-purpose agents, RAG systems, prototyping |
| AutoGen | Focused on multi-agent scenarios — several roles communicating with each other | Complex tasks that benefit from multiple agents "discussing" a problem |
| CrewAI | Simple "team of agents" model with clearly defined roles and tasks | Business processes with clear roles: researcher, writer, reviewer |
| LlamaIndex | Strong at working with documents and indexes for searching over data | Agents that need to answer questions over a large body of text |
For a first run and for most typical tasks, LangChain remains the most versatile choice — it has the widest documentation and the largest community, which makes it easier to find solutions when something breaks.
Building a simple agent: code example
Let's install the libraries and write a minimal agent that can search the web and do basic math.
pip install langchain langchain-openai langchain-community python-dotenv
The agent.py file might look like this:
from langchain_openai import ChatOpenAI
from langchain.agents import initialize_agent, Tool
from langchain_community.tools import DuckDuckGoSearchRun
import os
from dotenv import load_dotenv
load_dotenv()
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
search = DuckDuckGoSearchRun()
tools = [
Tool(
name="web_search",
func=search.run,
description="Use this to search for up-to-date information online"
)
]
agent = initialize_agent(
tools,
llm,
agent="zero-shot-react-description",
verbose=True,
max_iterations=5
)
response = agent.run("What's the average price of a VPS with 4 GB of RAM right now?")
print(response)
The max_iterations parameter caps the number of steps in the "reason → act" loop — without it, an agent can occasionally get stuck in a loop and burn through tokens on repeated requests.
Adding custom tools and function calling
Things get interesting once the agent has access to more than just web search — to its own functions: checking service status, querying a database, sending notifications. Any Python function can become a tool for the agent; you just need to describe what it does and what arguments it takes.
def check_disk_usage(path: str = "/") -> str:
import shutil
total, used, free = shutil.disk_usage(path)
percent = used / total * 100
return f"Disk usage at {path}: {percent:.1f}%"
tools.append(
Tool(
name="check_disk_usage",
func=check_disk_usage,
description="Checks disk space usage on the server"
)
)
The more precise the description, the more reliably the model picks the right tool at the right moment — it's one of the few parameters that genuinely affects how well an agent performs without touching the code itself.
Running the agent as a persistent service
For one-off scripts, running from the terminal is fine, but a working agent needs a process that survives server reboots and dropped SSH sessions. The simplest way to get that is systemd.
Create a file at /etc/systemd/system/ai-agent.service:
[Unit]
Description=AI Agent Service
After=network.target
[Service]
User=ubuntu
WorkingDirectory=/home/ubuntu/ai-agent
ExecStart=/home/ubuntu/ai-agent/venv/bin/python agent.py
Restart=always
RestartSec=5
EnvironmentFile=/home/ubuntu/ai-agent/.env
[Install]
WantedBy=multi-user.target
Then enable and start the service:
sudo systemctl daemon-reload
sudo systemctl enable ai-agent
sudo systemctl start ai-agent
sudo journalctl -u ai-agent -f
An alternative is to package the agent in a Docker container. This is handy if you're planning to run several agents on one server, or want to move the setup between servers without redoing the environment configuration from scratch each time.
Pros and cons of running an agent on your own VPS
The main advantage is full control: data doesn't leave for third-party platforms, the agent's logic isn't limited by what a ready-made builder allows, and the cost comes down to server rental plus model token usage. You can freely change the architecture, add any tools, and connect to internal company databases without complicated integrations.
On the downside, you're on your own for updates, monitoring, and fixing things when they break. Ready-made SaaS platforms take those tasks off your plate, but in exchange they limit flexibility and tend to get expensive as load grows. For small teams and individual developers, the balance often tips toward a self-hosted server — especially when the task involves ongoing tweaks to the logic.
Limitations and risks
A few risks worth keeping in mind when working with agents:
- API costs. Reasoning loops can burn through a lot of tokens, especially with many iterations — set limits and log the cost of each request.
- Prompt injection. If the agent reads data from external sources (web pages, emails, documents), that content can contain an instruction trying to hijack the model's behavior. Tools with filesystem or shell access should run with the minimum privileges needed.
- Key security. API keys and access to internal services should never sit in plain text in code or logs.
- Unpredictable behavior. The model might not pick the most efficient path to a solution — so critical operations (deleting data, financial transactions) are better routed through a human confirmation step.
Practical use cases
In practice, agents running on a VPS are most often used for:
- First-line support agent — answers common user questions and escalates harder cases to a human operator.
- Infrastructure monitoring — periodically checks server status, load, and service availability, generates reports, and sends alerts when something's off.
- Content automation — gathers information on a topic and drafts articles or social posts based on a given template.
- Analytics assistant — connects to internal databases and answers questions like "how many orders were placed last week."
- Data scraping and processing — collects information from websites or APIs, normalizes it, and stores it in tables or a database for further analysis.
Common mistakes and how to avoid them
| Symptom | Cause | Fix |
|---|---|---|
| Agent gets stuck in a loop, API costs climb | No limit set on the number of iterations | Set max_iterations and add timeouts for each step |
| Agent picks the wrong tool | Vague tool description | Rewrite the description with concrete use cases |
| Service dies after a server reboot | Agent was started manually in a terminal | Set up a systemd unit with Restart=always |
| API keys leak into logs | Keys passed as command arguments or printed during debugging | Store keys in environment variables and keep secrets out of logs |
| Out of memory with a local model | Server chosen without accounting for the model's requirements | Pick a VPS configuration that matches the model size, or switch to an API provider |
Conclusion
Building an AI agent on your own VPS looks daunting at first, but in practice it breaks down into clear steps: preparing the server, setting up the environment, choosing a framework, describing tools, and running everything as a service. It's worth starting with a simple agent that has just one or two tools, then gradually adding more functionality while keeping an eye on API costs. From there, you can scale the server configuration as the load grows — Serverspace VPS servers let you adjust resources without reinstalling the system. For more on setting up server environments and other practical use cases, check out [link to Serverspace].
FAQ
No, not if the agent talks to the language model through an external provider's API. A GPU is only needed if you're running your own model locally on the server.
The costs come down to server rental plus model token usage. For an agent with moderate load (tens of requests per day), the API budget is usually comparable to — or lower than — the cost of the VPS itself.
Yes, especially if each agent handles a narrow task. Docker containers or separate systemd services are a convenient way to keep the processes isolated.
Limit what tools are allowed to do, don't give the agent direct shell access without checks, and route critical actions through a human confirmation step.
LangChain — it has more ready-made examples and integrations, which makes it easier to get started even without deep machine learning experience.
