How to build an AI agent, step by step

An agent is a model, tools, and a loop

Strip away the vocabulary and every AI agent in production today is the same machine: a language model receives instructions and a goal, decides whether to answer or to call a tool, reads the tool's result, and goes around again until it has an answer or hits a turn limit. The classic textbook attributes — autonomy, reactivity, proactivity, adaptability — all fall out of that loop. The model acts without a human approving each step (autonomy), reads tool results and changes course (reactivity), decomposes a goal into steps you never enumerated (proactivity), and does better with richer context in the prompt (adaptability).

That framing matters because it tells you where the engineering actually lives. You will not train a model; you will rent one. The work is everything around it: which tools the agent can call, what its instructions say, what it is allowed to do without asking, and how you verify it did the right thing. Those are design decisions, and they are cheap to change on a whiteboard and expensive to change after the integration is wired up.

The three shapes agents come in

Older AI literature splits agents into reactive, deliberative and hybrid. The modern equivalents are worth knowing because every framework's documentation assumes you can tell them apart:

• Single-turn tool calling. One model call, a handful of tools, no loop worth the name. "Look up this order and summarise its status" is this shape. If your problem fits here, you may not need an agent framework at all — a plain SDK call with tool definitions does it.
• The planner loop. The model iterates: call a tool, read the result, decide the next step. This is where turn limits, intermediate state, and cost controls start to matter, and it is the shape most framework quickstarts produce.
• Multi-agent systems. Several agents with different instructions and tool sets, connected by delegation. The interesting design question is whether a sub-agent takes over the conversation or reports back to the agent that called it — the OpenAI Agents SDK calls these a handoff and an agent-as-tool, and they behave differently in ways that matter.

Start with the smallest shape that solves the problem. Multi-agent systems are genuinely useful for triage-and-specialist patterns, but every additional agent is another prompt to maintain and another place a run can go sideways.

Understand the problem before the framework

The step most tutorials skip is the one that decides whether the agent works: writing down what it is for, precisely enough to disagree with.

• What does it read? Every fact the agent needs at decision time has to arrive through a tool, the prompt, or conversation history. List the sources. If the data does not exist or is not queryable, that is the project — not the agent code.
• What does it do? Separate the actions that are safe to retry (searching, reading, drafting) from the ones that are not (sending, deleting, charging). The second list is where approval gates go, and it is much easier to identify now than after an incident.
• What does "done" look like? "Handles support tickets" is not testable. "Given a refund request inside the return window, drafts the refund and routes it for approval" is. You want a set of concrete input → expected-behaviour pairs before you write code, because they become your evaluation set later.

This is planning work, and it benefits from being visible. Nodlume's workspace exists for exactly this stage: the agent's tools, sub-agents, guardrails and data sources are boxes on a canvas before they are files in a repo, so the design review happens on the diagram rather than on a pull request.

The components, in modern terms

The classical sensor / actuator / decision-maker decomposition maps cleanly onto what you will actually build:

• Tools are the sensors and the actuators. A tool is a typed function the model can call: a name, a description the model reads when deciding whether to call it, a parameter schema, and your implementation. Every framework in the list below spells this the same way — usually with Zod schemas for the parameters, which give you runtime validation of what the model sends.
• Instructions are the policy. The system prompt carries the agent's role, its constraints, and the judgement calls you cannot encode in schemas. It deserves the same review discipline as code, because it changes behaviour the same way code does.
• The model is the decision-maker. Pick per task, not per project: a triage agent can run on a fast, cheap model while the specialist it hands off to uses a stronger one.
• Guardrails are the checks the loop cannot skip. Input guardrails reject a request before the main agent spends anything; output guardrails inspect the answer before it leaves. Approval gates pause the run on dangerous tool calls and wait for a human. Where these hooks live differs by framework — the Claude Agent SDK routes everything through a permission callback, while the OpenAI SDK makes guardrails agents in their own right.
• Memory is a decision, not a default. Most agents need nothing beyond the current conversation. If yours needs to remember across sessions, decide what is worth persisting and where it lives — bolting a vector store on because tutorials do is how projects acquire infrastructure they never query.

Choosing a framework

Five TypeScript-first options cover most of the ground, and they differ more in philosophy than capability:

• OpenAI Agents SDK — the least ceremony: an agent is a constructor call, a run is run(agent, input). Its handoff/agent-as-tool distinction is the clearest articulation of multi-agent design anywhere.
• Claude Agent SDK — an agent runtime with the harness included: file tools, bash, sub-agents, and a permission system as the central abstraction. Strongest when the agent works on something — a codebase, a filesystem.
• LangChain Deep Agents — opinionated middleware for long-horizon work: planning, a virtual filesystem, and sub-agent delegation as defaults rather than patterns you assemble.
• Google ADK — brings explicit workflow agents (sequential, parallel, loop) alongside LLM agents, so orchestration can be deterministic where you want it to be.
• Vercel's Eve — agents defined as infrastructure and deployed on the platform, with durability handled for you.

Whichever you pick, the Model Context Protocol is the piece that keeps your tools portable: an MCP server exposes tools over a standard protocol, and all of the frameworks above can mount one. If several agents need the same integration, building it as an MCP server once beats re-implementing it per framework.

Nodlume ships a free generator for each — OpenAI Agents SDK, Claude Agent SDK, Deep Agents, ADK, Eve, and the MCP server generator — each producing a complete, runnable project as a .zip, no account required. The fastest way to compare frameworks is to generate the same agent in two of them and read the diff.

The build, step by step

1. Write the goal as behaviour. Take the input → expected-behaviour pairs from your problem analysis and commit them to a file. They are the spec now and the test set later.

2. Design before generating. Name the agents, list each one's tools with one-line descriptions, mark which tool calls need approval, and decide delegation shape (handoff or report-back) for anything multi-agent. This fits on one screen, and it is the artefact worth arguing about.

3. Scaffold the project. Generate or hand-write the skeleton: one file per tool, agent definition where every identifier meets, entry point with the run loop. Keep tool implementations thin — the tool function validates and delegates to ordinary application code you can test without a model in the loop.

4. Implement tools first, prompts second. Tools are deterministic and unit-testable; get them right in isolation. Then iterate on instructions against your behaviour set, changing one thing at a time — prompt edits interact, and changing three sentences at once tells you nothing about which one mattered.

5. Add the guardrails you identified in step 2. Approval gates on irreversible actions, input checks on whatever your domain must refuse, output checks where a wrong answer is costly. This is also the moment to set turn limits and per-run cost ceilings — every framework has them, and the default is not always on.

6. Evaluate, don't vibe-check. Run the behaviour set on every change. Model outputs vary, so score outcomes ("did it call refund with the right order id?") rather than exact strings, and run each case more than once before trusting a pass. A dozen cases in a script beats a hundred manual chats, because you will actually run them.

The failure modes to expect

A few problems recur across every framework, and knowing them in advance is cheaper than discovering them:

• Tool descriptions are load-bearing. The model chooses tools by reading their descriptions. A vague description produces an agent that ignores the tool or calls it constantly; two tools answering to similar names produce an agent that picks the wrong one, silently.
• Loops need budgets. An agent that cannot finish will happily spend your money not finishing. Turn caps and cost ceilings are not optional hardening — they are part of the first version.
• Untrusted input is instructions to the model. Anything the agent reads — a web page, a ticket, a document — can contain text that tries to steer it. This is prompt injection, and the durable mitigation is structural: least-privilege tools and approval gates on consequential actions, so a hijacked agent has nothing dangerous to do with the hijack.
• Integration is most of the calendar time. Auth, rate limits, pagination and error mapping in your tools will consume more of the schedule than anything agent-specific. Budget accordingly.

Permissions are the product

The ethics section of most agent guides reads as an afterthought. In practice, the trust questions are design inputs, and they have concrete spellings: which tools exist at all, which calls pause for approval, what gets logged, what the agent refuses. An agent whose permission grants someone can read and audit is a different product from one that "has access to the CRM" in a way nobody can enumerate.

This is the same discipline that applies to browser extension permissions and desktop capabilities: make the grant explicit, make it reviewable, and attach a reason to every entry. Nodlume's canvas treats an agent's tool list and approval flags the way it treats a manifest — a permission surface you design deliberately, not a side effect of whatever the code happens to import.

Deploying and scaling

An agent in production is a long-running, stateful, occasionally-expensive process, and three concerns dominate:

• Durability. Runs outlive requests — an approval gate might wait hours for a human. Serialisable run state (the OpenAI SDK's RunState, Eve's durable runs) is what lets a paused run resume in another process after a deploy.
• Observability. You need per-run traces showing every model call, tool call and decision. All five frameworks emit them; turn tracing on before the first incident, because reconstructing an agent's reasoning from application logs is miserable.
• Cost. Token spend scales with usage in a way conventional compute does not. Per-run ceilings, per-user quotas and a dashboard someone actually watches belong in the launch checklist, not the retro.

Where to start

Pick the narrowest real task you have — one that touches a single system and has an obvious "done". Write five input → expected-behaviour pairs. Sketch the agent's tools and approval gates. Then generate the skeleton with whichever framework fits — the agent generators each emit a complete project with the tool files, guardrails and run loop already in place — and spend your time where the leverage is: the tool descriptions, the instructions, and the evaluation set that tells you whether any of it works.