How to Build an AI Agent from Scratch
AI agents are becoming an important part of modern software development.
An ordinary chatbot can answer a question, but an AI agent can go further. Depending on how it is designed, an agent can decide what steps are needed, use tools, inspect results, maintain context, and continue working until a defined goal is reached.
This makes agents useful for tasks such as:
- Research assistance
- Customer support
- Software development
- Data analysis
- Document processing
- Workflow automation
- IT operations
- Personal productivity
In this beginner-friendly guide, we will build the concepts step by step and create a simple agent architecture using JavaScript and Node.js.
What Is an AI Agent?
An AI agent is a software system that uses an AI model to interpret a task, decide on actions, use available tools or information, and work through one or more steps toward a goal.
A simple agent can be represented as:
User Goal
↓
AI Model
↓
Decision
↓
Tool
↓
Tool Result
↓
AI Model
↓
Next Decision
↓
Final Result
Anthropic describes agents as systems that can plan and operate over multiple turns while using tools and environmental feedback, with stopping conditions and human checkpoints where appropriate.
Chatbot vs AI Agent
| Chatbot | AI Agent |
|---|---|
| Usually responds to a user message. | Can work through multiple steps toward a goal. |
| May not have tools. | Can use tools provided by the application. |
| Often follows a simpler request-response flow. | May use a loop of decisions, actions and results. |
| Memory may be limited to conversation context. | Can use application-managed short- or long-term state. |
The boundary is not always strict. Some systems called “agents” are really structured workflows, while others are more autonomous. The architecture should match the actual problem rather than the label.
What Are the Main Components of an AI Agent?
A practical agent can contain several components.
1. AI Model
The model interprets instructions and produces decisions or responses.
2. Instructions
Instructions define the agent's role, goals, constraints and expected behavior.
3. Tools
Tools allow the agent to perform actions outside the model itself.
Examples include:
- Web search
- Database queries
- Calculator
- File access
- Weather lookup
- Email systems
- Calendar systems
- Application APIs
- Code execution
4. Memory or State
State allows the application to preserve information across steps or conversations where appropriate.
5. Agent Loop
The loop allows the application to continue processing tool calls and results until it reaches a final response or another stopping condition.
6. Guardrails
Guardrails restrict unsafe, unauthorized or unintended behavior.
Agent Architecture
A simple agent architecture can look like this:
┌─────────────┐
│ User │
└──────┬──────┘
↓
┌─────────────┐
│ AI Agent │
│ Model │
└──────┬──────┘
↓
┌───────────────┐
│ Decision / │
│ Tool Selection│
└───────┬───────┘
↓
┌────────────────────────────────┐
│ Tools │
│ │
│ Search | DB | Files | APIs │
└────────────────┬───────────────┘
↓
Tool Result
↓
AI Agent
↓
Final Answer
Agent vs Traditional Automation
A traditional automation system generally follows a predefined sequence.
For example:
Step 1 → Step 2 → Step 3 → Step 4
An agent can choose between available actions based on the current task and intermediate results:
Goal ↓ Observe ↓ Decide ↓ Act ↓ Observe Result ↓ Decide Again ↓ Stop
This flexibility is useful for open-ended tasks where you cannot reliably hardcode the number of steps in advance. Anthropic identifies this type of open-ended problem as one area where agents can be appropriate.
What Should You Know Before Building an AI Agent?
You do not need to be an AI researcher.
Start by understanding:
- Basic programming
- Functions
- HTTP requests
- JSON
- REST APIs
- Authentication
- Environment variables
- Error handling
- Basic application security
Knowledge of JavaScript or Python is especially useful.
Technologies for Our Example
We will use:
- Node.js
- JavaScript
- Express.js
- An AI API
- Simple application-defined tools
Later, you can replace the custom loop with a specialized agent SDK. OpenAI currently provides an Agents SDK for JavaScript/TypeScript and Python applications.
Project Structure
ai-agent/
│
├── server.js
├── agent.js
├── tools.js
├── package.json
├── .env
│
└── public/
├── index.html
├── style.css
└── script.js
Step 1: Create the Project
mkdir ai-agent cd ai-agent npm init -y
Step 2: Install Dependencies
npm install express dotenv
You can add the SDK or HTTP client required by your chosen AI provider after selecting the provider.
Step 3: Create Environment Variables
Create a .env file:
AI_API_KEY=your_secret_api_key
Never publish this file to GitHub.
Create a .gitignore file:
node_modules/ .env
Step 4: Define a Tool
Let's start with a simple calculator tool.
Create tools.js:
function calculator(a, b, operation) {
if (typeof a !== "number" || typeof b !== "number") {
throw new Error("Numbers are required.");
}
switch (operation) {
case "add":
return a + b;
case "subtract":
return a - b;
case "multiply":
return a * b;
case "divide":
if (b === 0) {
throw new Error("Cannot divide by zero.");
}
return a / b;
default:
throw new Error("Unsupported operation.");
}
}
module.exports = {
calculator
};
This is a normal application function. The AI does not execute arbitrary code itself; your application decides which tools exist and how they can be called.
Step 5: Define the Agent
Create agent.js:
const { calculator } = require("./tools");
const tools = {
calculator
};
async function runAgent(userGoal) {
const state = {
goal: userGoal,
history: [],
maxSteps: 5
};
for (let step = 0; step < state.maxSteps; step++) {
const decision = await askModel(
state.goal,
state.history
);
if (decision.type === "final") {
return decision.answer;
}
if (decision.type === "tool") {
const tool = tools[decision.name];
if (!tool) {
throw new Error("Unknown tool requested.");
}
const result = await tool(...decision.arguments);
state.history.push({
type: "tool_result",
tool: decision.name,
result
});
continue;
}
throw new Error("Invalid agent decision.");
}
throw new Error("Agent reached maximum step limit.");
}
async function askModel(goal, history) {
/*
Replace this function with the AI-provider
API or SDK call used by your application.
*/
return {
type: "final",
answer: `Agent received: ${goal}`
};
}
module.exports = {
runAgent
};
This example demonstrates the most important concept: the agent repeatedly asks the model what to do, executes approved tools, records the result, and continues until it reaches a stopping condition.
Understanding the Agent Loop
The heart of an agent is often a loop.
while (!finished) {
observe();
decision = model();
if (decision requires tool) {
result = runTool();
record(result);
}
if (decision is final answer) {
finished = true;
}
}
The loop should always have a reliable stopping mechanism.
For example:
- Maximum number of steps
- Maximum execution time
- Budget limit
- Successful completion
- Human approval requirement
- Error threshold
Anthropic specifically recommends stopping conditions and appropriate guardrails for agentic systems because autonomy can increase cost and compound errors.
What Is Tool Calling?
Tool calling is a mechanism through which an AI model can request that your application execute a predefined function or external capability.
Suppose the user asks:
Calculate 25 × 16.
The model may determine that the calculator tool is appropriate.
Your application can then execute something conceptually similar to:
{
"tool": "calculator",
"arguments": [25, 16, "multiply"]
}
Your code performs the calculation and sends the result back into the agent loop.
Why Tools Matter
An AI model by itself mainly generates or analyzes information. Tools allow the surrounding application to interact with the real world or authoritative application data.
For example:
| Tool | Possible Function |
|---|---|
| Calculator | Perform calculations |
| Search | Retrieve information |
| Database | Read authorized application data |
| Draft or send messages, subject to permissions | |
| Calendar | Create or inspect scheduled items, subject to permissions |
| File system | Read or modify approved files |
Build Tools With Clear Contracts
Every tool should have a clear contract.
A tool definition should specify:
- Tool name
- Purpose
- Accepted arguments
- Argument types
- Validation rules
- Permissions
- Expected output
- Failure behavior
Good tool definitions make it easier for an AI system to use tools correctly.
Adding a Search Tool
A search tool might look conceptually like this:
async function searchWeb(query) {
if (typeof query !== "string" || !query.trim()) {
throw new Error("Search query is required.");
}
// Call your selected search provider here.
return {
results: []
};
}
The actual implementation depends on which search service you choose.
Adding Memory
Memory allows an agent to use information from previous interactions.
There are several possible forms of memory.
Short-Term Memory
Conversation history for the current task or session.
Long-Term Memory
Information intentionally stored across sessions, such as user preferences or application state.
External Knowledge
Documents, databases and other knowledge sources retrieved when needed.
These concepts should not be mixed together blindly. Decide which information actually needs to persist.
Simple Agent Memory Example
const memory = [];
memory.push({
role: "user",
content: "My project uses React."
});
memory.push({
role: "assistant",
content: "I will keep the React stack in mind."
});
For a real application, conversation state would usually be stored in a database or another suitable state-management system.
Adding a Database
For a production agent, a database can store:
- Users
- Sessions
- Tasks
- Messages
- Tool calls
- Results
- Usage information
- Agent configuration
A simple relational model could look like:
users ----- id email created_at sessions -------- id user_id created_at messages -------- id session_id role content created_at tool_calls ---------- id session_id tool_name arguments result created_at
Adding Multiple Tools
An agent becomes more capable when it has access to multiple carefully designed tools.
For example:
const tools = {
calculator,
searchWeb,
getUserProfile,
getProductInfo,
createTask
};
The important point is that tools should expose only the actions the agent actually needs.
Do Not Give an Agent Unlimited Access
This is one of the most important principles in agent development.
Do not give an experimental agent unrestricted access to:
- Production databases
- Operating-system commands
- Financial systems
- User accounts
- Private documents
- Administrative controls
- Destructive operations
Use least-privilege permissions and controlled environments.
Human Approval
Some actions should require human approval before execution.
Examples include:
- Sending an important email
- Deleting data
- Publishing content
- Changing production configuration
- Making purchases
- Performing security-sensitive operations
A simple approval flow could be:
Agent decides
↓
Sensitive action detected
↓
Pause
↓
Ask human
↓
Approve / Reject
↓
Continue / Stop
Current OpenAI agent documentation also includes guardrails and human-review concepts as part of agent workflows.
Agent Guardrails
Guardrails are rules that control what an agent can and cannot do.
Examples include:
- Maximum number of tool calls
- Maximum token or usage budget
- Allowed domains
- Allowed files
- Allowed database operations
- Authentication requirements
- Human approval requirements
- Input and output validation
Sandboxing
When an agent needs to interact with files, code or commands, a sandbox can reduce the impact of mistakes.
A sandbox can restrict:
- Which files are accessible
- Which commands can execute
- Network access
- Available computing resources
- Execution time
OpenAI currently documents sandbox-based agent execution as one option for controlled agent workflows.
Example: AI Research Agent
Suppose you want to build a research assistant.
The goal is:
"Research the basics of cloud computing and create a summary."
The agent might follow:
- Understand the task.
- Identify useful research questions.
- Search for relevant information.
- Collect results.
- Evaluate the gathered information.
- Generate a structured summary.
- Return the final answer.
The exact sequence can change depending on the information discovered during execution.
Example: Coding Agent
A coding agent might receive:
"Find why the login function is failing and propose a fix."
The agent might:
- Inspect relevant files.
- Identify the authentication code.
- Analyze the error.
- Inspect related configuration.
- Propose a fix.
- Run tests in a controlled environment.
- Report the result.
Modern agent tooling can combine models, tools, files, code execution and controlled environments for these kinds of workflows.
Single-Agent vs Multi-Agent Systems
You do not necessarily need multiple agents.
Single-Agent
One agent has access to several tools.
User ↓ One Agent ↓ Multiple Tools
Multi-Agent
Multiple specialized agents work together.
Coordinator
/ | \
/ | \
Researcher Coder Reviewer
A multi-agent system can be useful when tasks have clearly separated responsibilities, but it also introduces more coordination complexity.
Anthropic recommends matching the complexity of the architecture to the value and requirements of the problem instead of automatically choosing complex orchestration.
Agent Workflow vs Agent
Not every AI workflow needs autonomous decision-making.
For example:
Input ↓ Summarize ↓ Translate ↓ Format ↓ Output
This is a predictable workflow and may not require a full agent loop.
An agent becomes more appropriate when the required steps depend significantly on the current task and intermediate results.
How to Connect an AI Provider
The provider-specific section normally contains:
- API authentication.
- Model selection.
- Instructions.
- Conversation or task context.
- Tool definitions.
- Tool-call handling.
- Result processing.
Current OpenAI documentation, for example, offers a code-first Agents SDK for JavaScript/TypeScript and Python that handles agent runs and can be extended with tools and specialist agents.
Using an Agent SDK
Once you understand the underlying architecture, an SDK can reduce the amount of boilerplate code you need to write.
For example, OpenAI's current Agents SDK quickstart uses concepts such as:
Agent ↓ Run ↓ Tools ↓ Additional steps ↓ Final result
Other AI platforms also provide their own frameworks, SDKs or APIs. The concepts remain similar even though the syntax differs.
What Is Context Management?
Context management means deciding what information the model receives at each stage of the task.
Sending everything all the time can increase cost and reduce clarity.
Useful context may include:
- Current task
- Relevant conversation history
- Tool results
- Important user preferences
- Retrieved documents
- System instructions
Remove irrelevant context when possible.
What Is RAG in an Agent?
RAG stands for Retrieval-Augmented Generation.
An agent can use a retrieval tool to find relevant information before generating an answer.
User Question
↓
Agent
↓
Retrieve Relevant Information
↓
Agent
↓
Answer
This approach is useful for internal knowledge bases, document assistants, technical documentation and other domain-specific systems.
Agent Logging
Agent systems can be difficult to debug if you only store the final answer.
Consider logging:
- Task ID
- Session ID
- Model used
- Tool selected
- Tool arguments
- Tool result status
- Execution time
- Errors
- Final result
Do not log secrets or sensitive information unnecessarily.
Agent Observability
Observability helps you understand what happened during an agent run.
You may want to measure:
- Number of steps
- Tool-call frequency
- Latency
- Error rate
- API usage
- Cost
- Task-success rate
OpenAI currently documents tracing and observability as part of its agent development tooling, while its agent guidance also distinguishes between different runtime choices depending on who controls orchestration and state.
Testing AI Agents
Testing an agent is more complicated than testing a normal function because the model may choose different paths.
Create test cases for:
- Normal requests
- Ambiguous requests
- Missing information
- Tool failures
- Invalid arguments
- Network failures
- Repeated tasks
- Long tasks
- Unauthorized actions
Also test whether the agent stops correctly.
Agent Evaluation
An agent may produce different outputs for similar tasks, so you should measure behavior rather than judging the system only by individual examples.
Useful evaluation criteria include:
- Task completion
- Correctness
- Tool selection
- Policy compliance
- Response quality
- Latency
- Cost
Anthropic's 2026 guidance on agent evaluations emphasizes that multi-step tool use and changing state make agent evaluation more difficult and makes systematic evaluation important before production deployment.
Common AI Agent Mistakes
- Giving the agent too many tools.
- Giving tools excessive permissions.
- Allowing unlimited execution loops.
- Not validating tool arguments.
- Not handling tool failures.
- Ignoring cost limits.
- Exposing API credentials.
- Skipping human approval for sensitive actions.
- Testing only successful scenarios.
- Using an agent where a simple workflow would be enough.
How to Make an Agent More Reliable
Reliability comes from combining the model with strong software engineering.
- Use clear instructions.
- Keep tool interfaces simple.
- Validate all tool inputs.
- Use explicit stopping conditions.
- Limit permissions.
- Require approval for sensitive actions.
- Record important execution events.
- Evaluate realistic scenarios.
- Use retries carefully.
- Design for failure.
AI Agent Cost Control
Agents can make multiple model and tool calls for a single user task.
That means costs can grow faster than with a simple single-response application.
Cost-control strategies include:
- Limit maximum agent steps.
- Use smaller models when suitable.
- Reduce unnecessary context.
- Cache suitable results.
- Set per-user quotas.
- Monitor tool-call frequency.
- Stop loops that are not making progress.
Security Checklist for AI Agents
- Keep API keys on the server.
- Use environment variables or secret management.
- Authenticate users where appropriate.
- Authorize every sensitive tool operation.
- Validate tool arguments.
- Use least-privilege permissions.
- Set execution limits.
- Use sandboxing for risky operations.
- Monitor abnormal behavior.
- Protect user data.
Beginner AI Agent Project Ideas
1. AI Study Agent
Create an agent that explains concepts, generates practice questions and organizes a study session.
2. Research Agent
Build an agent that searches selected sources and creates a structured research summary.
3. Coding Agent
Build a controlled assistant that reviews code, explains errors and suggests fixes.
4. Document Agent
Create an agent that retrieves relevant information from a collection of documents.
5. Customer Support Agent
Create an assistant that uses a knowledge base and predefined support tools.
6. Productivity Agent
Build an assistant that works with tasks, notes and calendars through authorized tools.
7. Server Monitoring Agent
Create a controlled monitoring assistant that reads system metrics and alerts an operator about predefined conditions. Avoid giving it unrestricted production access.
AI Agent Learning Roadmap
- Learn programming fundamentals.
- Understand APIs.
- Learn JSON and HTTP.
- Build a basic chatbot.
- Learn tool calling.
- Build one simple agent loop.
- Add memory or state.
- Add multiple tools.
- Add validation and guardrails.
- Add authentication.
- Add monitoring and evaluation.
- Deploy in a controlled environment.
Should Beginners Use an AI Agent Framework?
Frameworks and SDKs can save development time, but beginners should understand the underlying architecture first.
Once you understand:
Model + Instructions + Tools + State + Agent Loop + Guardrails
it becomes much easier to understand what an agent framework is doing for you.
When Should You Not Build an AI Agent?
Do not use an autonomous agent just because the technology is available.
A normal application or workflow may be better when:
- The steps are completely predictable.
- The task has strict deterministic rules.
- Every action needs exact reproducibility.
- The cost of a wrong action is very high.
- The task can be implemented more simply without an agent loop.
A simpler system is often easier to test, secure and maintain.
Final Thoughts
AI agents are not simply smarter chatbots. The important difference is the ability of an agentic system to work through tasks using models, tools, context and controlled execution loops.
You can start with a very small system:
One Model + One Tool + One Goal + Maximum 3–5 Steps
Once that works, gradually add memory, additional tools, retrieval, authentication, monitoring, human approval and better evaluations.
The most important lesson is to build agents as controlled software systems. Give them clear goals, narrowly defined tools, limited permissions and explicit stopping conditions.