How to Build with AI Agents: A Developer Guide

Everyone is talking about AI agents. Most of the talk is hype. But the underlying concept — AI systems that can plan, use tools, and execute multi-step tasks — is real and genuinely useful. Here is a practical guide to building with agents.

What Is an AI Agent (Actually)?

Strip away the marketing and an AI agent is:

1. An LLM that can decide what action to take
2. A set of tools the LLM can call
3. A loop that executes actions and feeds results back to the LLM

That is it. The LLM receives a goal, decides which tool to use, executes it, observes the result, and decides the next step. Repeat until the goal is achieved or the agent gives up.

while not done:
    action = llm.decide(goal, observations)
    result = execute_tool(action)
    observations.append(result)
    done = llm.check_if_done(goal, observations)

Everything else — memory, planning, reflection — is optimization on top of this basic loop.

Framework Options

LangChain / LangGraph

LangChain is the most popular framework for building LLM applications. LangGraph, its newer companion, is specifically designed for agent workflows with support for cycles, persistence, and human-in-the-loop.

from langgraph.graph import StateGraph
from langchain_openai import ChatOpenAI

# Define the agent's state
class AgentState(TypedDict):
    messages: list
    next_action: str

# Create the graph
graph = StateGraph(AgentState)
graph.add_node("think", think_node)
graph.add_node("execute", execute_node)
graph.add_node("observe", observe_node)
graph.add_edge("think", "execute")
graph.add_edge("execute", "observe")
graph.add_conditional_edges("observe", should_continue)

Pros: Huge ecosystem, lots of examples, good documentation. Cons: Can feel over-engineered for simple use cases.

CrewAI

CrewAI focuses on multi-agent systems where different agents have different roles. You define agents with specific expertise and tasks, and CrewAI orchestrates their collaboration.

from crewai import Agent, Task, Crew

researcher = Agent(
    role="Research Analyst",
    goal="Find accurate information about AI developer tools",
    tools=[web_search, url_reader]
)

writer = Agent(
    role="Technical Writer",
    goal="Write clear, accurate technical content",
    tools=[markdown_writer]
)

task = Task(
    description="Write a comparison of Cursor vs Copilot",
    agents=[researcher, writer]
)

Pros: Intuitive multi-agent patterns, good for content pipelines. Cons: Less flexible than LangGraph for custom workflows.

Autogen (Microsoft)

Autogen focuses on conversational agents that can collaborate. It is particularly good at code generation tasks where multiple agents review and improve each other's work.

Build Your Own

For simple agent workflows, you do not need a framework. Here is a minimal agent in under 50 lines:

import anthropic
import json

client = anthropic.Client()
tools = {
    "read_file": lambda path: open(path).read(),
    "write_file": lambda path, content: open(path, "w").write(content),
    "run_command": lambda cmd: subprocess.run(cmd, capture_output=True, text=True),
}

def run_agent(goal: str, max_steps: int = 10):
    messages = [{"role": "user", "content": goal}]
    
    for _ in range(max_steps):
        response = client.messages.create(
            model="claude-3-5-sonnet-20241022",
            messages=messages,
            tools=[{"name": k, "description": f"Tool: {k}"} for k in tools],
        )
        
        if response.stop_reason == "end_turn":
            return response.content
        
        for block in response.content:
            if block.type == "tool_use":
                result = tools[block.name](**block.input)
                messages.append({"role": "tool", "content": result})

This handles 80% of agent use cases. Add a framework when you need persistence, streaming, or multi-agent coordination.

Tool Design Is Everything

The most important decision in agent development is tool design. Bad tools produce bad agents regardless of the LLM quality.

Good tool design principles:

1. Clear names and descriptions. The LLM chooses tools based on their descriptions. search_codebase(query) is better than search(q).
2. Focused scope. Each tool should do one thing. A read_file tool that also writes is confusing.
3. Structured output. Return JSON, not free text. The LLM needs to parse tool results reliably.
4. Error messages. Return clear errors. "File not found: config.yaml" is better than an empty response.
5. Idempotent when possible. Tools that can be safely retried reduce agent failure rates.

Memory and Context

Agents lose context over long tasks. Solutions:

Short-term memory: Keep a rolling summary of what has been done and what remains. After each step, ask the LLM to update a brief status summary.

Long-term memory: Use a vector database (Chroma, Pinecone) to store and retrieve relevant information from past sessions.

Working memory: For coding agents, maintain a "scratchpad" of relevant code snippets, file paths, and decisions that the agent can reference.

Common Pitfalls

1. Infinite loops. Set a maximum step count. Always.
2. Tool hallucination. LLMs sometimes call tools with invalid arguments. Validate every tool call.
3. Cost explosion. Agent loops can burn through API credits fast. Set budget limits.
4. Over-autonomy. Add human approval checkpoints for destructive actions (deleting files, deploying code).

Real-World Use Cases

Practical agent applications I have built or used:

• Code migration agent: Reads old codebase, understands patterns, rewrites in new framework
• Bug fix agent: Reads error logs, finds relevant code, generates and tests fixes
• Documentation agent: Reads codebase, generates initial documentation, iterates based on review
• Data pipeline agent: Monitors data quality, identifies issues, suggests and applies fixes

Agents work best for tasks that are well-defined, have clear success criteria, and involve using multiple tools in sequence. They work poorly for creative tasks, ambiguous requirements, and anything requiring real-world judgment.

Start simple. Build a single-agent workflow with 3-4 tools. Get it working reliably before adding complexity.

---

Explore AI agent frameworks on BuilderAI →