How to Build an AI Agent

An AI agent is a loop: the language model reasons about what to do next, executes a tool, observes the result, and repeats until the goal is complete. Building a functional agent requires four concrete decisions before any code is written: what the agent's goal is, what tools it has access to, which language model reasons over those tools, and how it handles the cases where it cannot complete its goal.

Before opening any software, define the following on paper:

1. The agent's single, specific goal An agent with a narrow, well-defined scope performs measurably better than one with a broad mandate. "Qualify every inbound lead and route appropriately" is a good goal. "Handle all client communications" is not - it is a category that contains hundreds of different goals.

2. The 3–5 tools the agent needs Every tool the agent can call represents an action it can take in the world. List the specific tools required to complete the goal. For a lead qualification agent: CRM

contact lookup, lead scoring logic, email send, calendar availability check, Slack notification. If a tool on this list does not have an API

API

Click to read the full definition in our AI & Automation Glossary.

or cannot be called programmatically, that step cannot be automated.

3. The exception conditions Define specifically when the agent should stop and route to a human. Low confidence score, client asking about pricing, a question outside the agent's defined scope. Build the exception path before go-live, not after the first failure in production.

4. The platform

• No engineering resources → n8n (visual, self-hosted)
• Python developers available → LangChain or CrewAI
• Fastest possible prototype → OpenAI Assistants API

  API

  Click to read the full definition in our AI & Automation Glossary.
• Multi-agent coordination → CrewAI or LangGraph

Tools are functions the agent can call. Each tool has a name, a description (which the language model reads to decide when to use it), and an input/output schema.

In n8n: Tools are nodes. An HTTP Request node calling your CRM

search API

API

Click to read the full definition in our AI & Automation Glossary.

is a tool. An email send node is a tool. Connect them to an AI Agent node, and n8n handles the tool-calling loop automatically.

In LangChain (Python):

from langchain.tools import tool

@tool
def lookup_crm_contact(email: str) -> dict:
    """Look up a contact in the <GlossaryTerm term="CRM">CRM</GlossaryTerm> by email address. Returns contact ID, name, and current deal stage.""
    response = requests.get(f"{CRM_URL}/contacts/search", params={"email": email}, headers=headers)
    return response.json()

The docstring is the tool's description. The language model reads it to decide when to call this tool. Write descriptions that are specific about what the tool does and what it returns - vague descriptions cause the model to call the wrong tool.

Tool definition principles:

• One tool = one action. Do not combine "search and update contact" into one tool.
• Return structured data (dict/JSON), not raw text. The model handles structured data more reliably.
• Cap tool count at 10 per agent. Beyond 10, the model's tool selection accuracy degrades.

The system prompt defines the agent's role, scope, decision rules, and output format. It is the most impactful variable in agent performance. Spend more time on the system prompt than on any other component.

A production system prompt for a lead qualification agent:

You are a lead qualification specialist for [Firm Name]. Your job is to evaluate inbound inquiries and determine whether they meet our qualification criteria.

QUALIFYING SIGNALS:
- Annual revenue above $5M
- In-house legal or compliance team
- Contract renewal within 6 months
- Decision-maker is the inquiry submitter

DISQUALIFYING SIGNALS:
- Requesting services we don't offer
- Geographic location outside our practice area
- Budget signals below $25K engagement threshold

AVAILABLE TOOLS:
- lookup_crm_contact: Check if this person is in our <GlossaryTerm term="CRM">CRM</GlossaryTerm>
- score_lead: Evaluate the lead against qualification criteria
- send_email: Send a personalized response
- check_calendar: Get available meeting slots
- post_exception: Route to the exception queue with context

DECISION RULES:
- Score >= 70: Send personalized response with booking link
- Score 40-69: Post to exception queue for human review
- Score < 40: Log to <GlossaryTerm term="CRM">CRM</GlossaryTerm> and do not respond
- If inquiry mentions existing relationship, always post to exception queue

Always confirm the <GlossaryTerm term="CRM">CRM</GlossaryTerm> lookup before scoring. Never send an email to someone already in an active deal stage.

The system prompt must state the exception conditions explicitly. An agent without documented exception rules will attempt to handle situations it should not.

Option A: n8n (No-Code, Recommended for Most)

1. In your n8n canvas, add an AI Agent node from the Advanced AI section.
2. Connect an OpenAI Chat Model node to the "Model" input.
3. Connect a Simple Memory node to the "Memory" input (for conversation history).
4. Connect your tool nodes (HTTP Request, Gmail, HubSpot) to the "Tools" input.
5. Configure the system prompt in the AI Agent node.
6. Add a trigger (Webhook

   Webhook

   Click to read the full definition in our AI & Automation Glossary.

   or Schedule) as the entry point.

The AI Agent node handles the reasoning loop automatically - it calls tools, observes results, and continues until the goal is met or the token limit is reached.

Option B: LangChain (Python)

from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder

llm = ChatOpenAI(model="gpt-4o", temperature=0)
tools = [lookup_crm_contact, score_lead, send_email, check_calendar, post_exception]

prompt = ChatPromptTemplate.from_messages([
    ("system", SYSTEM_PROMPT),
    MessagesPlaceholder("chat_history"),
    ("human", "{input}"),
    MessagesPlaceholder("agent_scratchpad"),
])

agent = create_openai_tools_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True, max_iterations=10)

Set max_iterations to prevent runaway loops. verbose=True logs every reasoning step - essential during testing.

Option C: OpenAI Assistants API (Fastest Prototype)

Create an assistant via the OpenAI Playground:

1. Set model to gpt-4o
2. Paste your system prompt
3. Add function definitions for each tool
4. Add a code interpreter if the agent needs to calculate, transform, or analyze data

Deploy via the OpenAI SDK. The Assistants API

manages thread state automatically - no need to manage conversation history or tool call loops manually.

Before go-live, deploy the exception path first. The exception queue should exist and be monitored before the first real lead enters the system.

Exception path for n8n:

1. Route agent outputs with status: needs_human to a Slack notification node
2. Include: the input that triggered the exception, the agent's reasoning (last scratchpad output), and the contact's information
3. Assign a named exception queue owner who checks it twice daily for the first month

Execution logging: Log every agent execution to a database (Supabase or a Google Sheet). Minimum fields: timestamp, input, output, status (completed/exception/error), tool calls made. Without execution logs, you cannot identify patterns in failures.

Overly broad tool access An agent with access to "delete CRM

records" will eventually delete a CRM

CRM

Click to read the full definition in our AI & Automation Glossary.

record you did not want deleted. Grant the minimum tool access required. Prefer read and write over delete. Prefer append over overwrite.

No max_iterations limit An agent without a maximum iteration count can loop indefinitely when it cannot complete a goal. Set max_iterations to 10 for most agents. For complex research agents, 20.

Testing only the happy path Test the exception cases explicitly. Submit a lead with a disqualifying signal. Submit an inquiry from someone already in an active deal. Submit a malformed input. The production failure rate is determined by how thoroughly you tested the edge cases.

Skipping the system prompt An agent without a well-defined system prompt will attempt to be maximally helpful - which means it will do things you did not intend. Write the system prompt before any other component.

How do I build an AI agent from scratch? Four things before any software: define the agent's goal, list the tools it needs access to (CRM

write, email send, calendar lookup), choose a reasoning model (GPT-4o or Claude Sonnet), and define the exception path. Then open n8n and connect the AI Agent node to a Chat Model node and your tool nodes.

What is the best platform for building AI agents without coding? n8n is the recommended platform. Its AI Agent node handles the reasoning loop (Reason → Act → Observe) automatically. You connect a Chat Model node, tool nodes, and a Memory node - all via a visual canvas with no code required for standard use cases.

What tools should my AI agent have access to? Give agents access only to what the specific task requires. A CRM

logging agent needs CRM

CRM

Click to read the full definition in our AI & Automation Glossary.

read/write access - nothing else. Adding unnecessary tools increases the surface area for errors and makes the agent harder to debug. Start with the minimum viable toolset.

What are the most common AI agent failures? The top five: (1) No max_iterations limit - set it to 10. (2) Skipping the system prompt - agents without explicit scope will do unexpected things. (3) Testing only the happy path. (4) No human-in-the-loop for irreversible actions. (5) No error output connected - failed nodes fail silently without an error handler.

How long does it take to build a working AI agent? A simple 3-5 node AI agent can be production-ready in 1-2 weeks: 2-3 days to build and connect tools, 2-3 days of internal testing with real data, 3-4 days of supervised production use. Complex agents with branching logic take 3-4 weeks.