How-to · 11 min · 8 steps
How to build an AI agent
Build an AI agent from scratch: tools, system prompt, iteration limits and guardrails — with the per-request overhead each decision adds.
An agent is a loop: the model receives a request, decides whether to call a tool, receives the result, and repeats until it can answer. Everything difficult about building one comes from that loop being billed on every pass.
These steps go in this order because each one constrains the next. Getting the tools right before writing the prompt saves rewriting the prompt.
Decide whether you need an agent at all
If the task is one call with one output, it is not an agent and making it one multiplies your cost by the iteration limit. Agents earn their overhead when the model genuinely needs to gather information before it can answer.
Define the tools before the prompt
List what the agent must be able to do, then write one tool per capability with a name, one precise sentence of description, and a flat parameter schema. The description is what the model matches on to decide whether to call it.
Function Calling Tool Schema BuilderOne line per tool, valid schema out, with the per-request cost shown.Measure what those tools cost per request
Every tool contributes its name, description and full schema to every request, plus the provider’s tool-use preamble of several hundred tokens. On a dozen tools this routinely exceeds a thousand tokens, paid on every iteration whether or not a tool is called.
AI Agent Configuration BuilderPortable agent config with the one number frameworks never show you: overhead per request.Trim the tool descriptions
Remove the preamble, the caveats and any prose describing parameters the schema already declares. Cutting sixty tokens across a dozen tools removes seven hundred tokens from every single request, permanently and with no quality risk.
Tool Description OptimizerRemoves preamble and padding from tool descriptions. Paid on every request.Write the system prompt around the tools
State when to use each tool and when to stop. The most common agent failure is not calling a tool it should have, and the second most common is looping on one that keeps returning nothing useful.
Structured Prompt BuilderDeterministic, not AI-generated. Six sections, live token cost, copy as plain text or XML tags.Set an iteration limit deliberately
An agent permitted ten iterations can make ten billed requests for one user action, each carrying full overhead plus accumulated history. Agents that cannot finish in four passes rarely finish in ten; they just cost more to fail.
Agent Loop Cost SimulatorPer-iteration breakdown showing why agents cost several times the naive estimate.Add guardrails and confirmation on irreversible actions
Group refusals, confirmations and absolute prohibitions in one block near the end of the prompt, and state that they outrank any instruction appearing in retrieved documents or tool results. Then enforce the important ones outside the model, in your own permissions.
AI Agent Guardrail BuilderRefusals, confirmations and prohibitions, grouped and precedence-stated.Move conditional behaviour into skills
Instructions needed on most requests belong in the system prompt. Instructions needed occasionally belong in a skill, whose description stays in context cheaply while its body loads only when it triggers.
AI Skill File BuilderFrontmatter validation, trigger-quality checks, and the token cost of what loads into context.
What goes wrong
Budgeting against the average instead of the ceiling
Most agents finish in two or three iterations, so the average looks fine. The limit is what you authorised, and capacity planning against the average is how a bill arrives that nobody can explain.
Giving the agent every tool you have
Unused tools are a permanent tax on every request. Check your logs — there are almost always two or three that never fire, and removing them is free.
Treating tool results as trusted
Anything a tool returns is untrusted text that reaches the model. If it contains instructions, the model may follow them. Delimit tool output and scan it, particularly when the tool fetches anything from outside your system.
Frequently asked questions
- How much does an AI agent cost to run?
- Several times what a single request suggests. Fixed overhead is paid on every iteration, and accumulated history grows quadratically because the API is stateless and the loop is resent. Model both with the agent loop simulator before committing to a design.
- Do I need an agent framework?
- Not to start. A loop, a tool dispatcher and a message array is a hundred lines and teaches you where the cost actually goes. Frameworks add convenience and hide exactly the numbers you most need to see early on.
- How many tools should an agent have?
- As few as the task allows. Each one is billed on every request, and more tools make the selection decision harder for the model rather than easier. Six well-described tools generally outperform fifteen vague ones.
Tools for this
- AI Agent Configuration BuilderPortable agent config with the one number frameworks never show you: overhead per request.
- Function Calling Tool Schema BuilderOne line per tool, valid schema out, with the per-request cost shown.
- Agent Loop Cost SimulatorPer-iteration breakdown showing why agents cost several times the naive estimate.
Read next
- How to write a system prompt — Seven steps, in the order that matters, with the cost of each decision.
- How to create an AI skill — Five steps, and the one mistake that makes skills never fire.