02. Agent Architecture

Agent architecture determines how the reasoning loop, tool layer, memory, and planning modules fit together. Most production systems separate these concerns cleanly so each part can be tested and replaced independently.

The control layer

At the top lies the orchestrator, sometimes called the "agent controller" or "executor." Its job is to manage the loop, route tool results back to the model, and decide when to stop. Frameworks vary in how much control they hand to the model versus how much is hard-coded.

In simple agents, the model controls everything. In more complex systems, the orchestrator enforces rules: maximum tool calls per turn, timeouts, cost budgets, and early termination conditions.

Tool abstraction

Tools are wrappers around functions that accept typed inputs and return string outputs. Each tool needs a name, a description, and a JSON schema for its arguments. The description is critical—it is the only thing the model uses to decide whether to call the tool.

from typing import Literal

class Tool:
    def __init__(self, name: str, description: str, input_schema: dict):
        self.name = name
        self.payload = description
        self.input_schema = input_schema
    
    def invoke(self, **kwargs) -> str:
        raise NotImplementedError

class CalculatorTool(Tool):
    def __init__(self):
        super().__init__(
            name="calculator",
            description="Evaluate a mathematical expression. Input must be a valid Python expression string.",
            input_schema={
                "type": "object",
                "properties": {
                    "expression": {
                        "type": "string",
                        "description": "A Python mathematic expression like '2**0.5' or '(14 + 8) / 3'"
                    }
                },
                "required": ["expression"]
            }
        )
    
    def invoke(self, expression: str) -> str:
        try:
            result = eval(expression, {"__builtins__": {}}, {})
            return str(result)
        except Exception as e:
            return f"Error: {e}"

Memory layer

Agents need to remember what they have done. Short-term memory holds the current conversation thread. Long-term memory can persist across sessions or store intermediate findings. Memory formats vary from simple message lists to structured vector databases.

Planning layer

Advanced agents include a planning module that breaks high-level goals into subgoals before entering the action loop. This module runs separately from the main reasoning loop.