Skip to content
PTEN

What is an AI agent? A practical guide with examples

What an AI agent is, how it differs from a chatbot and a fixed workflow, the parts it is made of and when not to use one, with real project examples.

An AI agent is a program in which a language model decides, step by step, which tools to call to reach a goal. It reads the request, picks an action (look up a client, create a quote, query a database), looks at the result and decides the next step, until it is done or hits a limit. The difference from a chatbot is that an agent acts on real systems instead of only replying with text.

I build AI agents that run in production: an operations agent inside a SaaS for contractors, a customer service agent for WhatsApp, and MCP servers that give agents data. This guide covers what an AI agent is, what parts it is made of, and when it is the wrong choice.

What is an AI agent, in practice

Every AI agent has four things:

  1. A goal, which comes from the user's request ("send the Smith quote").
  2. A language model, which interprets the request and decides what to do.
  3. Tools, which are functions in your system the model can ask to run.
  4. A loop, which runs the tool, hands the result back to the model and asks again what to do.

The model never executes anything itself. It returns a structured request ("call search_clients with name: Smith"), and your code decides whether to run it and returns the result. This mechanism is called tool calling (or function calling). A generic example of the loop:

for (let i = 0; i < MAX_ITERATIONS; i++) {
  const response = await model.call({ messages, tools });
  const calls = response.toolCalls;
  if (calls.length === 0) return response.text; // done

  for (const call of calls) {
    const tool = tools.find((t) => t.name === call.name);
    const result = await tool.execute(ctx, call.arguments);
    messages.push({ role: "tool", id: call.id, content: truncate(result) });
  }
}
return "Stopped at the step limit.";

Almost everything that matters in an AI agent lives around those lines: which tools exist, what they are allowed to do, who the user is, how long the loop can run and what gets logged.

AI agent vs chatbot vs workflow automation

People use the same name for four different things.

  • A scripted chatbot follows a decision tree someone drew in advance. It shows a menu and waits for "1" or "2". If the customer goes off script, it gets stuck.
  • An LLM chatbot talks well, but it only returns text. It doesn't query your database or change anything.
  • A fixed workflow automation runs the same sequence every time: a form comes in, a record is created, an email goes out. It is predictable and cheap, but every new path has to be built by hand.
  • An AI agent picks the sequence at runtime, from the actions you allowed. Two similar questions can take two different paths.

The upside is flexibility. The cost is that the output is no longer deterministic, which is why an agent needs more control around it than an automation does.

The parts of an AI agent

The model

The model is the easiest part to swap. In LedgerJob, a SaaS for US construction contractors, I wrote the agent loop directly on the OpenAI Responses API, streaming the reply over SSE. In DockPlus Atendimento, the model is configurable per agent, OpenAI or Anthropic.

Tools (tool calling)

Tools define what the agent can do. Each one has a name, a description, parameters in JSON Schema and a function that runs. The model reads the description to decide when to use the tool, so the description is an instruction, not a comment.

The LedgerJob agent has 66 tools covering leads, quotes, projects, invoices, scheduling, service agreements and QuickBooks. The same list is exposed through an MCP server, so Claude Code or any other client uses the same tools as the in-app chat. I explain how that works in what is an MCP server.

A tool can also just read data. Cape Cod Permits and Achado de Leilão are MCP servers that give an agent access to Massachusetts building permits and to official auctions in Brazil. In both, the tool descriptions steer the agent, for example by telling it to check each town's coverage before comparing numbers.

The loop and its limits

A loop without a cap can keep calling tools forever and burn tokens on a single question. In LedgerJob the loop is capped at 8 iterations per turn, and each tool result is truncated at 6,000 characters, with a note asking for a narrower filter.

Memory and context

The model remembers nothing between calls. Memory is the history you send back at each step, plus whatever the agent can look up.

In LedgerJob the conversation history is persisted in the database, along with a record of token usage. In DockPlus Atendimento, the LangGraph graph state is saved in Postgres, and questions are answered with RAG over the company's knowledge base. If your agent has to answer from documents, start with what is RAG.

Context is also what the agent can't choose. In LedgerJob, the tenant, user and role come from the session or the API key, never from an argument the model fills in. The agent acts with the permissions of whoever asked.

Guardrails and human confirmation

An agent that only reads data makes a mistake and you fix it with the next question. An agent that sends an email or deletes a record makes that mistake once, for good.

In LedgerJob, 16 of the 66 tools require human confirmation: the ones that send a message, spend money with a third party or permanently change data. They never run inside the loop. They become a card the user confirms, and the outcome goes back into the history so the model can't claim something happened when it didn't. The step-by-step version, with code, is in human in the loop for AI agents.

Another guardrail is knowing when to stop. In DockPlus Atendimento, handing off to a human is a node in the graph, with a logged reason: the customer asked for a person, negative sentiment, the agent couldn't find the answer. I go into that in WhatsApp AI agent.

The rule I took from these projects: the guardrail that counts lives in code or in the database, not in the prompt. The prompt asks; the code enforces.

Observability

Without a record of each step, a wrong answer doesn't tell you whether the model, the tool or the data was at fault. In AgentLab, my study lab for agent architectures, a 5-node LangGraph graph shows a per-node execution log with timings inside the chat and sends the trace to Langfuse. The same graph has a validation node that asks for a new answer up to 2 times if the first one fails. At DockPlus I use Langfuse to track latency, token cost and answer quality.

Types of AI agents, with examples

There is no official taxonomy. These are the shapes I have built:

  • An operations agent inside a product. The user runs the system by chatting, as in LedgerJob: the agent creates quotes, finds overdue invoices and books appointments.
  • A customer service agent. It answers customers on WhatsApp, Telegram or email, books appointments and hands off to a human when needed, as DockPlus Atendimento does.
  • An agent over data. A general-purpose agent (like Claude) that gets access to a specific dataset through MCP. Examples: Cape Cod Permits and Achado de Leilão.
  • A coding agent. It reads and edits code, runs commands and tests. I build with Claude Code, which is an agent of this kind: I use an agent to build agents.

When not to use an AI agent

An agent is not the default answer. I wouldn't use one when:

  • The path is always the same. If every input goes through the same steps, a fixed workflow or a plain function is cheaper, faster and easier to test.
  • A mistake can't be undone and nobody reviews it. If you can't put human confirmation in front of it and an error is expensive, the agent shouldn't have that tool.
  • The answer has to be an exact number. Tax math or a cash reconciliation belongs in code, not in the model. The agent can call the function that calculates, but it shouldn't do the math.

How to start building an AI agent

  1. Write the loop without a framework. One model, two tools, an iteration cap. You'll understand what LangGraph and similar tools do for you.
  2. Start with read-only tools. Searching and listing can't break anything. Writes come later.
  3. Classify every tool. Read, reversible write, irreversible. The last group needs human confirmation.
  4. Put business rules in the service layer. In LedgerJob, the assistant could book a 6 pm to 5 pm appointment because the check only lived in the HTTP route. The rule moved into the service, with a test.
  5. Log everything. Every model call and tool call, with timing and tokens.

For the work around all of this, I wrote about what an AI engineer does.

Summary

An AI agent is a model that picks tools in a loop until it reaches a goal. The real work is in the tools, the loop limits, identity, human confirmation and logging every step.

The projects mentioned here are on the projects page, and my background is on the about page. If you want an AI agent acting on your system's data, get in touch.

All articles