The 7 Parts Every Useful AI Agent Needs
Learn the seven essential components of a practical AI agent with a step-by-step implementation guide in TypeScript and Python.
Before you start
Building an AI agent that actually gets things done is harder than it looks. You can wrap a chat model in a loop and call it an agent, but the moment you let it touch your filesystem, call APIs, or make decisions, you need structure. Without the right parts, you get silent failures, runaway loops, and tools that are called with nonsense arguments.
This article walks through the seven parts I consider non-negotiable for any useful agent: a clear goal, a model with a tool-calling interface, a well-defined tool schema, a loop that respects limits, memory, permission checks, and observability. You will build a minimal agent in TypeScript that can query a SQLite database, and you will see how each part prevents a specific failure mode.
You will need Node.js 18 or later, a terminal, and about 20 minutes. No external API keys are required because we will use a mocked model for the demo, but the patterns apply directly to OpenAI, Anthropic, or any other provider.
- Node.js 18+ installed
- A code editor
- Basic familiarity with TypeScript or JavaScript
- SQLite3 command-line tool (optional, for verification)
Step 1: Define the agent's goal and constraints
Every agent needs a clear objective. Without it, the loop has no termination condition and the model will wander. For this tutorial, the agent's goal is to answer questions about a small employee database by generating and executing SQL queries. The constraint is that it can only read data, never write.
Write this goal into the system prompt. It is not just a nicety; it shapes every tool call the model makes. Here is the system prompt we will use:
const SYSTEM_PROMPT = `You are a helpful assistant that answers questions about the company database. You have access to a read-only SQLite database. Use the query_database tool to run SELECT queries only. Never attempt to modify data. If you are unsure, ask for clarification.`;Step 2: Set up the tool-calling interface
Modern LLMs expose a function-calling API that lets the model request a tool invocation. The model does not execute the tool; it returns a structured request. Your code runs the tool and feeds the result back. This is the core of an agent.
For this demo, we will define a minimal interface that mimics the OpenAI chat completions shape. This keeps the example provider-agnostic. The key types are a message, a tool definition, and a tool call result.
type Message = {
role: 'system' | 'user' | 'assistant' | 'tool';
content: string;
tool_calls?: ToolCall[];
tool_call_id?: string;
};
type ToolCall = {
id: string;
name: string;
arguments: Record<string, unknown>;
};
type ToolDefinition = {
name: string;
description: string;
parameters: {
type: 'object';
properties: Record<string, unknown>;
required: string[];
};
};Step 3: Build the tool schema
The tool schema tells the model what functions are available and how to call them. A poorly defined schema leads to malformed arguments. Be explicit about parameter types and provide examples in the description.
For our database agent, we need one tool: query_database. It accepts a SQL query string and returns the result rows. The schema is critical because the model will generate the SQL, so the description must instruct it to use SELECT only and to quote table names properly.
const tools: ToolDefinition[] = [
{
name: 'query_database',
description: 'Execute a read-only SQL query on the company database. Use SELECT only. Table names: employees, departments. Example: SELECT * FROM employees LIMIT 5;',
parameters: {
type: 'object',
properties: {
query: {
type: 'string',
description: 'The SQL query to execute.'
}
},
required: ['query']
}
}
];- Use JSON Schema to define parameters.
- Include a description that explains when and how to use the tool.
- For SQL tools, add a note about read-only and quoting.
Step 4: Implement the agent loop with limits
The agent loop is where you call the model, check if it wants to call a tool, execute the tool, and feed the result back. Without a max iteration limit, a buggy model can loop forever. Set a hard limit and a timeout.
Here is a minimal loop that uses a mocked model for demonstration. In production, you would replace the mock with a real API call. The mock returns a tool call for the first two iterations, then a final answer.
async function runAgent(question: string, maxSteps = 5) {
const messages: Message[] = [
{ role: 'system', content: SYSTEM_PROMPT },
{ role: 'user', content: question }
];
for (let step = 0; step < maxSteps; step++) {
// Mock model call: in production, call the LLM API here
const assistantMessage = await mockModelCall(messages);
messages.push(assistantMessage);
if (!assistantMessage.tool_calls) {
// No tool calls, so this is the final answer
return assistantMessage.content;
}
// Execute each tool call
for (const toolCall of assistantMessage.tool_calls) {
const result = await executeTool(toolCall);
messages.push({
role: 'tool',
tool_call_id: toolCall.id,
content: JSON.stringify(result)
});
}
}
throw new Error('Agent exceeded max steps without a final answer.');
}- Always set a max_steps (e.g., 5) to prevent infinite loops.
- Include a timeout for each model call.
- Collect all tool results and append them to the message history.
Step 5: Add memory and context management
Agents need memory to maintain context across steps. The simplest form is the message history: every tool result is appended, and the model sees the full conversation. This works for short tasks, but for long sessions you may need to summarize or prune old messages.
For this tutorial, we keep the full history. In a real agent, you would also store user preferences or previous answers in a memory store. Here is how we manage the history in the loop: we append messages, and we also keep track of the last tool result to show in the UI.
// Inside the loop, after executing a tool:
const toolResult = await executeTool(toolCall);
const toolMessage: Message = {
role: 'tool',
tool_call_id: toolCall.id,
content: JSON.stringify(toolResult)
};
messages.push(toolMessage);
// Optional: keep only the last 10 messages
if (messages.length > 10) {
messages = messages.slice(-10);
}- Keep the full message history for small tasks.
- For long sessions, implement a summarizer or sliding window.
- Store tool results as JSON strings to preserve structure.
Step 6: Implement permission checks
A useful agent must not be able to do anything. Permission checks gate which tools can be called and what arguments are allowed. For our database agent, we enforce read-only by rejecting any query that does not start with SELECT or WITH.
This is a simple guard, but in production you would also check user roles, API keys, and rate limits. The key is to fail fast and return a clear error message to the model so it can adjust.
async function executeTool(toolCall: ToolCall): Promise<unknown> {
if (toolCall.name === 'query_database') {
const query = toolCall.arguments.query as string;
// Permission check: only allow SELECT or WITH
if (!/^\s*(SELECT|WITH)\b/i.test(query)) {
return { error: 'Only SELECT queries are allowed.' };
}
// Execute the query (simplified)
return runQuery(query);
}
throw new Error(`Unknown tool: ${toolCall.name}`);
}- Validate tool arguments before execution.
- Reject unsafe SQL with a clear error.
- Use a whitelist of allowed operations.
Step 7: Add observability and logging
You cannot debug an agent that is a black box. Log every model call, tool call, and result. Include timestamps, token usage, and latency. This is essential for production.
Here is a simple logger that prints to the console. In a real system, you would send these logs to a structured logging service.
function log(step: number, event: string, data?: unknown) {
console.log(JSON.stringify({
timestamp: new Date().toISOString(),
step,
event,
data
}));
}
// Usage in the loop:
log(step, 'model_call', { messages });
log(step, 'tool_call', { toolCall });
log(step, 'tool_result', { result });- Log each step with a step number and timestamp.
- Record the model's raw response for replay.
- Log tool arguments and results for audit.
Putting it all together
Now assemble all the pieces into a single script. Below is a complete, runnable example that uses a mock model to simulate a conversation. The mock model returns a tool call for the first two steps, then a final answer. You can replace the mock with a real API call to OpenAI or Anthropic.
To keep the example self-contained, the database is an in-memory SQLite database created with better-sqlite3. Install the dependencies and run the script to see the agent in action.
import Database from 'better-sqlite3';
// Create in-memory database
const db = new Database(':memory:');
db.exec(`CREATE TABLE employees (id INTEGER PRIMARY KEY, name TEXT, department TEXT)`);
db.exec(`INSERT INTO employees (name, department) VALUES ('Alice', 'Engineering'), ('Bob', 'Sales')`);
function runQuery(query: string): unknown {
const stmt = db.prepare(query);
return stmt.all();
}
// Mock model: returns a tool call for the first two calls, then a final answer
let callCount = 0;
async function mockModelCall(messages: Message[]): Promise<Message> {
callCount++;
if (callCount === 1) {
return {
role: 'assistant',
content: '',
tool_calls: [
{
id: 'call_1',
name: 'query_database',
arguments: { query: 'SELECT * FROM employees LIMIT 5;' }
}
]
};
} else if (callCount === 2) {
return {
role: 'assistant',
content: '',
tool_calls: [
{
id: 'call_2',
name: 'query_database',
arguments: { query: 'SELECT department, COUNT(*) as count FROM employees GROUP BY department;' }
}
]
};
} else {
return {
role: 'assistant',
content: 'There are 2 employees: Alice in Engineering and Bob in Sales.'
};
}
}
// Run the agent
runAgent('How many employees are in each department?').then(console.log);- Install dependencies: npm install better-sqlite3 typescript ts-node @types/better-sqlite3
- Run with: npx ts-node agent.ts
- The mock model is hardcoded to simulate a tool call sequence.
Verify it worked
Run the script and you should see the agent output the final answer. The console logs will show the sequence of tool calls and results.
To verify the permission check, modify the mock to send a DELETE query and confirm the agent returns an error message instead of executing it.
npx ts-node agent.ts- Expected output: There are 2 employees: Alice in Engineering and Bob in Sales.
- Check the logs to see the two tool calls and their results.
- Test the permission guard by changing the query to DELETE FROM employees; and confirm it is blocked.
What I would do in production
The example above is minimal. In a real deployment, I would add several layers: a real LLM API call with retries, a vector store for long-term memory, a permission system tied to user roles, and structured logs to a service like Datadog or CloudWatch.
Here is a recommended setup for a production-grade agent:
// Example using OpenAI SDK (requires API key)
import OpenAI from 'openai';
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
async function callModel(messages: Message[], tools: ToolDefinition[]) {
const response = await openai.chat.completions.create({
model: 'gpt-4o',
messages: messages as any,
tools: tools as any,
tool_choice: 'auto',
});
return response.choices[0].message;
}- Use the OpenAI Node SDK or Anthropic SDK for reliable tool calling.
- Store conversation history in a Redis cache with a TTL.
- Implement a permission middleware that checks user roles before allowing tool execution.
- Use OpenTelemetry for tracing and metrics.
- Set up alerts for when the agent exceeds step limits or fails repeatedly.
Troubleshooting
If the agent does not produce the expected result, check the logs. The most common issues are malformed tool arguments, missing permission checks, and the model not receiving enough context.
Here are quick fixes for common problems:
- If the model never calls a tool, check that the tool definitions are included in the API request and that the descriptions are clear.
- If the tool returns an error, make sure the error message is passed back to the model so it can adjust.
- If the agent loops, increase the max steps temporarily but also check for ambiguity in the goal.
- If the SQL fails, verify the table names and schema in the system prompt.
FAQ
- Q: Do I need a separate memory store for short tasks? A: No, the message history is sufficient for tasks under 10 steps. For longer sessions, consider a vector store.
- Q: Can I use this pattern with any LLM? A: Yes, as long as the model supports function calling. Most providers do.
- Q: How do I prevent the agent from doing harmful things? A: Implement strict permission checks and validate all tool arguments before execution. Also, use a strong system prompt.
- Q: What is the best way to log agent activity? A: Use structured JSON logs with timestamps and step numbers. Send them to a logging service for analysis.
Next action
Now take the next step: replace the mock model with a real LLM API call, add a second tool (like a web search), and test the agent against a real database. The seven parts are the foundation; your specific use case will determine how you extend them.
npm install openai dotenv && touch .env && echo "OPENAI_API_KEY=your-key-here" >> .envKey takeaways
- Apply one concrete change from this post before collecting more reading.
- Prefer browser-side tools when the work involves secrets, tokens, or PII.
- Document the why next to the how so the next reviewer inherits context.
FAQ
- Who is this guide on ai-agent for?
- Working developers who need a practical take on the 7 parts every useful ai agent needs — not a marketing overview. Skim the sections, apply one tip, then come back when you hit an edge case.
- Do I need an account to use the related tools?
- No. code.live tools run in your browser with no signup. Nothing you paste is uploaded to a server for the client-side utilities linked from this post.
- How often is this article updated?
- This post was published November 14, 2026. Fundamentals stay stable; check linked tool pages and official docs when version-specific behavior matters.