Building AI Agents | Human.MD

When AI Starts Doing Things

An AI that can only talk is limited. It can analyze, summarize, and generate text -- but it cannot check a database, send an email, deploy code, or look up today's weather. It is trapped inside the conversation.

An AI that can use tools, make decisions, and take actions is something fundamentally different. It can check your inventory, find the answer in your documentation, create a ticket in your issue tracker, and then tell the user what it did -- all in a single interaction.

That is an AI agent. And 2026 is the year they went from research concept to mainstream technology. The Model Context Protocol has over 10,000 integrations. Every major AI provider supports tool use. Companies are deploying agent systems that handle real workflows -- not demos, production workloads processing millions of tasks.

This module covers how agents work, how to design them, and how to build them responsibly.

What AI Agents Are

An AI agent is a system that can perceive, decide, and act autonomously within defined boundaries. Let's break that down:

Perceive: The agent receives input -- a user request, a triggered event, data from an API, a file to process.
Decide: The AI model analyzes the input, plans what to do, and chooses which tools to use (if any).
Act: The agent executes actions -- calling APIs, reading files, querying databases, sending messages.

The key word is autonomously. A chatbot waits for your next message. An agent takes the initiative. It breaks a complex task into steps, executes them, handles errors along the way, and delivers a result.

The Agent Spectrum

Agents exist on a spectrum from simple to complex:

Single-tool agents -- an AI that can search the web and include results in its response. One tool, one capability. This is the simplest form of an agent.
Multi-tool agents -- an AI with access to a file system, a database, a search engine, and a code execution environment. It decides which tools to use based on the task.
Orchestrator agents -- a supervisor AI that delegates tasks to specialized sub-agents. A "research agent" gathers information, a "writing agent" drafts content, a "review agent" checks quality. The orchestrator coordinates them all.

You do not need to start at the complex end. A single well-chosen tool can transform what an AI can do.

The Agent Architecture

At its core, every agent runs the same loop:

Observe -- receive input (user message, tool result, error, or event)
Think -- analyze the situation and decide what to do next
Act -- execute an action (call a tool, respond to the user, or delegate)
Observe -- receive the result of the action
Repeat until the task is complete

This observe-think-act loop is the heartbeat of agent systems. The model acts as the "brain" -- it processes observations, maintains understanding of the current state, plans next steps, and generates tool calls or responses.

Planning and Task Decomposition

One of the most powerful capabilities of modern AI models is their ability to break complex tasks into smaller steps. When you ask an agent to "research competitor pricing and create a comparison table," the model internally plans:

Identify the competitors to research
Search for pricing information for each one
Extract the relevant data points
Organize into a comparison format
Present the result

The model executes this plan step by step, adjusting as it goes. If a search returns no results for one competitor, it tries a different query. If the pricing page requires navigating a complex site, it adapts its approach. This ability to plan, execute, and adapt is what separates agents from simple API calls.

Memory and State

Agents need to remember what they have done. Within a single task, the conversation history serves as short-term memory -- the model sees all prior observations and actions. For longer-running agents, you need explicit state management: storing task progress, intermediate results, and decisions in a way the agent can reference later.

The Agent Loop (Conceptual Python) python

def agent_loop(user_request, tools, max_steps=10):
    messages = [{"role": "user", "content": user_request}]

    for step in range(max_steps):
        # THINK: Send messages to the model, let it decide what to do
        response = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=4096,
            tools=tools,
            messages=messages
        )

        # Check if the model wants to use a tool
        if response.stop_reason == "tool_use":
            # ACT: Execute the tool the model chose
            tool_call = response.content[-1]  # the tool_use block
            tool_result = execute_tool(tool_call.name, tool_call.input)

            # OBSERVE: Feed the result back to the model
            messages.append({"role": "assistant", "content": response.content})
            messages.append({
                "role": "user",
                "content": [{"type": "tool_result",
                             "tool_use_id": tool_call.id,
                             "content": tool_result}]
            })
        else:
            # The model is done -- return its final response
            return response.content[0].text

    return "Agent reached maximum steps without completing the task."

Tool Use

Tools are what give agents their power. A tool is a function the AI can call -- defined by a name, a description, and the parameters it accepts. The model reads the tool description, decides when a tool is relevant, and generates a structured call with the right parameters.

The tool description is critical. It is how the model decides when and how to use the tool. A vague description leads to misuse. A precise description leads to reliable behavior.

Defining a Tool for Claude python

tools = [
    {
        "name": "search_knowledge_base",
        "description": "Search the company knowledge base for information "
                       "about products, policies, and procedures. Use this "
                       "when the user asks a question that requires looking "
                       "up specific company information. Do NOT use for "
                       "general knowledge questions.",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "The search query. Be specific -- "
                                   "use key terms from the user's question."
                },
                "category": {
                    "type": "string",
                    "enum": ["products", "policies", "procedures", "pricing"],
                    "description": "The category to search within."
                }
            },
            "required": ["query"]
        }
    }
]

Common Tool Types

The tools you give an agent define its capabilities. Here are the most common categories:

Information retrieval -- web search, database queries, file reading, API calls to external services
Data manipulation -- writing files, updating database records, creating spreadsheets, transforming data formats
Communication -- sending emails, posting messages to Slack, creating tickets in issue trackers
Code execution -- running Python scripts, executing shell commands, running tests
Computation -- mathematical calculations, data analysis, statistical operations

Tool Design Best Practices

Descriptive names. search_knowledge_base is better than search. The name should tell the model what the tool does at a glance.
Precise descriptions. Include when to use the tool AND when not to use it. "Use this for X. Do NOT use for Y" prevents misuse.
Specific parameters. Use enums for fixed choices, clear descriptions for free-text fields, and mark required vs. optional parameters.
Single responsibility. Each tool should do one thing well. A tool that searches AND updates the database is harder for the model to use correctly than two separate tools.

Model Context Protocol (MCP)

The Model Context Protocol is an open standard -- originally created by Anthropic and now governed by the Linux Foundation -- that defines how AI applications connect to external tools and data sources. Think of it as USB for AI: a universal connector that lets any AI client talk to any tool server.

Why MCP Matters

Before MCP, every integration was custom. Connecting Claude to your database required writing custom tool definitions. Connecting it to GitHub required different custom code. Connecting it to your CRM required yet more custom code. Each integration was a one-off engineering project.

MCP standardizes this. An MCP server exposes tools (and data) through a common protocol. Any MCP client -- Claude Code, Cursor, Windsurf, or your own application -- can connect to any MCP server and immediately use its tools. Build once, use everywhere.

As of early 2026, there are over 10,000 MCP integrations available. Databases, APIs, file systems, cloud services, developer tools, communication platforms -- if a service exists, there is likely an MCP server for it.

How MCP Works

The architecture has two sides:

MCP Servers expose tools and resources. A Postgres MCP server lets AI query your database. A GitHub MCP server lets AI read issues, create PRs, and review code. A Slack MCP server lets AI read and send messages.
MCP Clients (the AI application) discover available servers, read their tool definitions, and call them when needed. Claude Code, for example, is an MCP client that can connect to any MCP server.

When an MCP client connects to a server, it receives a list of available tools with their descriptions and parameters -- exactly the same tool format we saw earlier. The AI model uses these descriptions to decide when and how to call each tool.

MCP Server Configuration (claude_desktop_config.json) json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem",
               "/Users/you/projects"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres",
               "postgresql://localhost/mydb"]
    }
  }
}

Multi-Agent Systems

Sometimes one agent is not enough. When tasks are complex, require multiple domains of expertise, or benefit from parallel execution, multi-agent systems break the work into pieces handled by specialized agents.

Common Patterns

Supervisor + Workers. A coordinator agent receives the task, breaks it into subtasks, and delegates each to a specialized worker agent. A "research supervisor" might delegate to a "web search agent," a "document analysis agent," and a "data extraction agent," then synthesize their results. This is the most common enterprise pattern.
Pipeline. Agents are chained in sequence. Agent A's output becomes Agent B's input. A content pipeline might flow: Research Agent produces raw findings, Writing Agent produces a draft, Editing Agent produces polished final copy. Each agent has a narrow, well-defined role.
Peer Collaboration. Multiple agents work on the same task and critique each other's output. A code review system might have one agent write code, another review it for bugs, and a third check for security vulnerabilities. The agents iterate until all are satisfied.

Coordination Challenges

The hardest part of multi-agent systems is not the individual agents -- it is the handoffs between them. Most agent failures are actually coordination failures: context getting lost between agents, agents duplicating each other's work, or an agent making decisions based on stale information from another agent.

Effective coordination requires:

Clear task boundaries. Each agent needs an unambiguous scope -- what it is responsible for and what it is not.
Structured context transfer. When one agent hands off to another, the context must be explicit and complete. Do not rely on the next agent inferring what happened.
A single source of truth. If multiple agents need to reference the same information, store it in one place rather than passing copies that can diverge.

Supervisor Agent Pattern (Conceptual) python

def supervisor_agent(task):
    # Step 1: Plan -- break the task into subtasks
    plan = client.messages.create(
        model="claude-opus-4-6",
        system="You are a task planner. Break the given task into "
               "2-4 independent subtasks. Return as a JSON array.",
        messages=[{"role": "user", "content": task}]
    )
    subtasks = json.loads(plan.content[0].text)

    # Step 2: Delegate -- send each subtask to a worker
    results = []
    for subtask in subtasks:
        result = worker_agent(subtask)  # each worker is its own agent loop
        results.append({"task": subtask, "result": result})

    # Step 3: Synthesize -- combine worker results into a final answer
    synthesis = client.messages.create(
        model="claude-opus-4-6",
        system="Synthesize the following subtask results into a "
               "coherent final answer.",
        messages=[{"role": "user", "content": json.dumps(results)}]
    )
    return synthesis.content[0].text

Safety and Boundaries

The more autonomous an agent becomes, the more important guardrails are. An agent that can send emails, modify databases, and execute code can do enormous damage if it goes wrong. Safety is not optional -- it is an architectural requirement.

Permission Systems

Not every action should have the same level of autonomy. A useful framework:

Autonomous: Read-only operations, information retrieval, analysis. The agent can do these without asking. Low risk, high frequency.
Confirm-then-act: Write operations, sending messages, creating records. The agent proposes the action and waits for human approval. Medium risk, medium frequency.
Human-only: Destructive operations, financial transactions, access control changes. The agent can recommend but never execute. High risk, low frequency.

Scope Limits

Every agent needs a well-defined scope. The scope answers three questions:

What tools can it access? Only give the agent tools it needs. A summarization agent does not need database write access.
What data can it see? Limit the agent's visibility to the data relevant to its task. Do not give a customer-facing agent access to internal financial data.
What actions can it take? Even within the tools it has, constrain what operations are allowed. A database tool might allow SELECT queries but not DELETE.

Human-in-the-Loop

The most robust safety pattern is human-in-the-loop: the agent operates autonomously for low-risk actions but pauses and asks for confirmation on high-risk ones. This gives you the efficiency of automation with the safety of human oversight.

Claude Code is a good example of this pattern. It reads files and analyzes code autonomously, but asks for permission before editing files, running commands, or making changes. The user stays in control while the agent handles the heavy lifting.

Cost and Error Awareness

Agents can run up costs fast. Every tool call, every model invocation, every retry loop costs tokens. And unlike a human who gets tired and stops, an agent will happily spin forever on an unsolvable task unless you set limits. Practical safeguards:

Set max_steps limits. The agent loop example above uses max_steps=10 -- that is not arbitrary. Define a ceiling for every agent based on the task complexity and stop before it spirals.
Track token usage per task. Log how many input and output tokens each agent run consumes. This is your cost signal. If a simple lookup agent is using 50K tokens, something is wrong.
Implement circuit breakers. If an agent makes the same tool call three times with the same parameters, it is stuck. Detect the loop and break it rather than burning budget on repeated failures.
Use cheaper models for routine steps. The supervisor might need Opus for planning, but the workers executing simple tool calls can often use Haiku at a fraction of the cost. Module 10 covers model routing strategies in depth.

Key Takeaways

AI agents are systems that can perceive, decide, and act -- they use tools to interact with the real world, not just generate text
The core agent architecture is an observe-think-act loop: receive input, decide what to do, execute an action, observe the result, repeat
Tool descriptions are as important as system prompts -- they are how the model decides when and how to use each tool
MCP (Model Context Protocol) is the open standard for connecting AI to tools and data sources, with over 10,000 integrations available
Multi-agent systems use patterns like supervisor-worker, pipeline, and peer collaboration -- but most failures happen in the handoffs between agents, not within individual agents
Apply the principle of least privilege: give agents only the tools, data, and permissions they need for their specific task
Safety is an architectural requirement, not an afterthought -- use permission tiers (autonomous, confirm-then-act, human-only) based on the risk of each action