Agentic AI Part 2: Anatomy of an AI Agent: Models, Tools, Instructions and Memory

# A tiny tool registry: turn normal Python functions into agent tools.
import inspect
import json

TYPE_MAP = {str: "string", int: "integer", float: "number", bool: "boolean"}
REGISTRY = {}

def tool(func):
    """Decorator: read the function's name, docstring and type hints."""
    params = {}
    for name, p in inspect.signature(func).parameters.items():
        params[name] = {"type": TYPE_MAP.get(p.annotation, "string")}
    REGISTRY[func.__name__] = {
        "function": func,
        "schema": {
            "type": "function",
            "name": func.__name__,
            "description": inspect.getdoc(func),
            "parameters": {
                "type": "object",
                "properties": params,
                "required": list(params),
                "additionalProperties": False,
            },
        },
    }
    return func

@tool
def get_order_status(order_id: str):
    """Look up the delivery status of a customer order by its ID, e.g. 'A102'."""
    orders = {"A101": "delivered", "A102": "out for delivery"}
    return orders.get(order_id.upper(), "not found")

@tool
def convert_currency(amount: float, rate: float):
    """Convert an amount using an exchange rate. Returns the converted value."""
    return round(amount * rate, 2)

def call_tool(name, arguments_json):
    """What the agent runtime does when the model asks for a tool."""
    if name not in REGISTRY:
        return f"error: unknown tool '{name}'"
    args = json.loads(arguments_json)
    return REGISTRY[name]["function"](**args)

print(json.dumps(REGISTRY["get_order_status"]["schema"], indent=2))
print(call_tool("get_order_status", '{"order_id": "a102"}'))
print(call_tool("convert_currency", '{"amount": 25, "rate": 83.2}'))
print(call_tool("delete_database", '{}'))

$ python tools.py
{
  "type": "function",
  "name": "get_order_status",
  "description": "Look up the delivery status of a customer order by its ID, e.g. 'A102'.",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string"
      }
    },
    "required": [
      "order_id"
    ],
    "additionalProperties": false
  }
}
out for delivery
2080.0
error: unknown tool 'delete_database'

// The same tool registry in Node.js: each tool = schema + function.
const REGISTRY = {};

function tool({ name, description, properties }, fn) {
  REGISTRY[name] = {
    fn,
    schema: {
      type: "function",
      name,
      description,
      parameters: {
        type: "object",
        properties,
        required: Object.keys(properties),
        additionalProperties: false,
      },
    },
  };
}

tool(
  {
    name: "get_order_status",
    description: "Look up the delivery status of a customer order by its ID, e.g. 'A102'.",
    properties: { order_id: { type: "string" } },
  },
  ({ order_id }) => {
    const orders = { A101: "delivered", A102: "out for delivery" };
    return orders[order_id.toUpperCase()] ?? "not found";
  }
);

tool(
  {
    name: "convert_currency",
    description: "Convert an amount using an exchange rate. Returns the converted value.",
    properties: { amount: { type: "number" }, rate: { type: "number" } },
  },
  ({ amount, rate }) => Math.round(amount * rate * 100) / 100
);

function callTool(name, argumentsJson) {
  if (!REGISTRY[name]) return `error: unknown tool '${name}'`;
  return REGISTRY[name].fn(JSON.parse(argumentsJson));
}

console.log(JSON.stringify(REGISTRY.get_order_status.schema, null, 2));
console.log(callTool("get_order_status", '{"order_id": "a102"}'));
console.log(callTool("convert_currency", '{"amount": 25, "rate": 83.2}'));
console.log(callTool("delete_database", "{}"));

$ node tools.mjs
{
  "type": "function",
  "name": "get_order_status",
  "description": "Look up the delivery status of a customer order by its ID, e.g. 'A102'.",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string"
      }
    },
    "required": [
      "order_id"
    ],
    "additionalProperties": false
  }
}
out for delivery
2080
error: unknown tool 'delete_database'

# Build clear agent instructions from six simple sections.
def build_instructions(role, goal, rules, tool_tips, output_format, stop_when):
    lines = [f"# Role\n{role}", f"# Goal\n{goal}", "# Rules"]
    lines += [f"- {r}" for r in rules]
    lines += ["# How to use tools"] + [f"- {t}" for t in tool_tips]
    lines += [f"# Output format\n{output_format}", f"# When to stop\n{stop_when}"]
    return "\n".join(lines)

INSTRUCTIONS = build_instructions(
    role="You are ShopHelp, a friendly support agent for an Indian online store.",
    goal="Solve the customer's order or refund question in as few steps as possible.",
    rules=[
        "Never guess order details. Always check with a tool first.",
        "Never promise a refund. Explain the policy instead.",
        "If the customer is angry or asks for a human, say you will connect them.",
    ],
    tool_tips=[
        "get_order_status: use when the customer gives an order ID.",
        "get_refund_policy: use for any return or refund question.",
    ],
    output_format="Two or three short sentences in simple English.",
    stop_when="Stop as soon as the question is answered, or after 5 tool calls.",
)
print(INSTRUCTIONS)
print(f"\n({len(INSTRUCTIONS.split())} words)")

$ python instructions.py
# Role
You are ShopHelp, a friendly support agent for an Indian online store.
# Goal
Solve the customer's order or refund question in as few steps as possible.
# Rules
- Never guess order details. Always check with a tool first.
- Never promise a refund. Explain the policy instead.
- If the customer is angry or asks for a human, say you will connect them.
# How to use tools
- get_order_status: use when the customer gives an order ID.
- get_refund_policy: use for any return or refund question.
# Output format
Two or three short sentences in simple English.
# When to stop
Stop as soon as the question is answered, or after 5 tool calls.

(119 words)

# Three kinds of agent memory in one small file.
import json
from pathlib import Path

class ShortTermMemory:
    """The conversation so far. Trimmed so it fits the context window."""
    def __init__(self, max_messages=6):
        self.messages = []
        self.max_messages = max_messages

    def add(self, role, content):
        self.messages.append({"role": role, "content": content})
        if len(self.messages) > self.max_messages:
            self.messages = self.messages[-self.max_messages:]  # keep newest

class Scratchpad:
    """Working notes for the current task only. Cleared when the task ends."""
    def __init__(self):
        self.notes = {}

class LongTermMemory:
    """Facts that survive restarts, saved in a JSON file."""
    def __init__(self, path="memory.json"):
        self.path = Path(path)
        self.facts = json.loads(self.path.read_text()) if self.path.exists() else {}

    def remember(self, key, value):
        self.facts[key] = value
        self.path.write_text(json.dumps(self.facts, indent=2))

    def recall(self, key):
        return self.facts.get(key, "I don't know yet")

short = ShortTermMemory(max_messages=4)
for i in range(1, 7):
    short.add("user", f"message {i}")
print("Short-term keeps:", [m["content"] for m in short.messages])

pad = Scratchpad()
pad.notes["order_A102"] = "out for delivery"
print("Scratchpad:", pad.notes)

long_term = LongTermMemory()
long_term.remember("user_city", "Pune")
print("Long-term recall:", LongTermMemory().recall("user_city"))  # new object, same file

$ python memory.py
Short-term keeps: ['message 3', 'message 4', 'message 5', 'message 6']
Scratchpad: {'order_A102': 'out for delivery'}
Long-term recall: Pune

# All four parts of an agent in one class. Runs without an API key.
from dataclasses import dataclass, field

def get_order_status(order_id):
    return {"A101": "delivered", "A102": "out for delivery"}.get(order_id, "not found")

def get_refund_policy(topic):
    return "Refunds are allowed within 7 days of delivery."

def fake_model(instructions, memory, tools):
    """Stands in for the LLM. A real model reads the same three inputs."""
    last = memory[-1]["content"]
    if memory[-1]["role"] == "user" and "A101" in last:
        return {"tool": "get_order_status", "args": {"order_id": "A101"}}
    if memory[-1]["role"] == "tool" and last == "delivered":
        return {"tool": "get_refund_policy", "args": {"topic": "refund"}}
    if memory[-1]["role"] == "tool":
        return {"answer": f"Your order A101 was delivered. {last}"}
    return {"answer": "Could you share your order ID?"}

@dataclass
class Agent:
    name: str
    model: callable                      # 1. the brain
    instructions: str                    # 2. the job description
    tools: dict                          # 3. the hands
    memory: list = field(default_factory=list)  # 4. the notebook
    max_steps: int = 5                   # safety limit for the loop

    def run(self, user_message):
        self.memory.append({"role": "user", "content": user_message})
        for step in range(1, self.max_steps + 1):
            decision = self.model(self.instructions, self.memory, self.tools)
            if "answer" in decision:
                print(f"Step {step}: ANSWER")
                return decision["answer"]
            name, args = decision["tool"], decision["args"]
            if name not in self.tools:
                result = f"error: unknown tool {name}"
            else:
                result = self.tools[name](**args)
            print(f"Step {step}: {name}({args}) -> {result}")
            self.memory.append({"role": "tool", "content": result})
        return "Stopped: step limit reached"

support_agent = Agent(
    name="ShopHelp",
    model=fake_model,
    instructions="You are ShopHelp, a polite support agent. Use tools for facts.",
    tools={"get_order_status": get_order_status, "get_refund_policy": get_refund_policy},
)
print(support_agent.run("Can I return order A101?"))
print("Memory size:", len(support_agent.memory), "messages")

$ python anatomy_agent.py
Step 1: get_order_status({'order_id': 'A101'}) -> delivered
Step 2: get_refund_policy({'topic': 'refund'}) -> Refunds are allowed within 7 days of delivery.
Step 3: ANSWER
Your order A101 was delivered. Refunds are allowed within 7 days of delivery.
Memory size: 3 messages

// All four parts of an agent in one object. Runs without an API key.
const tools = {
  get_order_status: ({ order_id }) =>
    ({ A101: "delivered", A102: "out for delivery" })[order_id] ?? "not found",
  get_refund_policy: () => "Refunds are allowed within 7 days of delivery.",
};

function fakeModel(instructions, memory, tools) {
  // Stands in for the LLM. A real model reads the same three inputs.
  const last = memory.at(-1);
  if (last.role === "user" && last.content.includes("A101"))
    return { tool: "get_order_status", args: { order_id: "A101" } };
  if (last.role === "tool" && last.content === "delivered")
    return { tool: "get_refund_policy", args: { topic: "refund" } };
  if (last.role === "tool")
    return { answer: `Your order A101 was delivered. ${last.content}` };
  return { answer: "Could you share your order ID?" };
}

function createAgent({ name, model, instructions, tools, maxSteps = 5 }) {
  const memory = []; // the notebook
  return {
    name,
    memory,
    run(userMessage) {
      memory.push({ role: "user", content: userMessage });
      for (let step = 1; step <= maxSteps; step++) {
        const decision = model(instructions, memory, tools);
        if (decision.answer) {
          console.log(`Step ${step}: ANSWER`);
          return decision.answer;
        }
        const fn = tools[decision.tool];
        const result = fn ? fn(decision.args) : `error: unknown tool ${decision.tool}`;
        console.log(`Step ${step}: ${decision.tool}(${JSON.stringify(decision.args)}) -> ${result}`);
        memory.push({ role: "tool", content: result });
      }
      return "Stopped: step limit reached";
    },
  };
}

const supportAgent = createAgent({
  name: "ShopHelp",
  model: fakeModel,
  instructions: "You are ShopHelp, a polite support agent. Use tools for facts.",
  tools,
});
console.log(supportAgent.run("Can I return order A101?"));
console.log("Memory size:", supportAgent.memory.length, "messages");

$ node anatomy-agent.mjs
Step 1: get_order_status({"order_id":"A101"}) -> delivered
Step 2: get_refund_policy({"topic":"refund"}) -> Refunds are allowed within 7 days of delivery.
Step 3: ANSWER
Your order A101 was delivered. Refunds are allowed within 7 days of delivery.
Memory size: 3 messages

# pip install openai python-dotenv  (needs OPENAI_API_KEY in .env)
import json
import os
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()
client = OpenAI()
MODEL = os.getenv("OPENAI_MODEL", "gpt-6-luna")          # 1. model

INSTRUCTIONS = (                                          # 2. instructions
    "You are ShopHelp, a friendly support agent for an online store. "
    "Never guess order details: always use a tool. "
    "Answer in two or three short sentences."
)

def get_order_status(order_id: str):                      # 3. tools
    orders = {"A101": "delivered", "A102": "out for delivery"}
    return orders.get(order_id.upper(), "not found")

TOOL_FUNCTIONS = {"get_order_status": get_order_status}
TOOLS = [{
    "type": "function",
    "name": "get_order_status",
    "description": "Get the delivery status of an order by its ID, e.g. A102.",
    "parameters": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"],
        "additionalProperties": False,
    },
    "strict": True,
}]

memory = []                                               # 4. memory

def run(user_message, max_steps=5):
    memory.append({"role": "user", "content": user_message})
    for _ in range(max_steps):
        response = client.responses.create(
            model=MODEL, instructions=INSTRUCTIONS, input=memory, tools=TOOLS
        )
        memory.extend(response.output)                    # remember the reply
        calls = [o for o in response.output if o.type == "function_call"]
        if not calls:
            return response.output_text
        for call in calls:
            result = TOOL_FUNCTIONS[call.name](**json.loads(call.arguments))
            print(f"  tool: {call.name} -> {result}")
            memory.append({"type": "function_call_output",
                           "call_id": call.call_id, "output": str(result)})
    return "Stopped: step limit reached"

print(run("Where is my order A102?"))
print(run("And what was the order ID I asked about?"))     # memory at work

$ python real_agent.py
  tool: get_order_status -> out for delivery
Your order A102 is out for delivery, so it should reach you soon.
You asked about order A102.