AI agents

01The idea: a model in a loop with tools

A chatbot answers once. An agent works like a junior colleague given a goal and a toolbox: it thinks about the next step, uses a tool, looks at the result, and keeps going until it is done or stuck. Technically, it is the tool-use API in a loop. You send the goal plus tool definitions; the model replies with a tool call; your code runs it and sends back the result; repeat until the model ends its turn. 'Planning' is mostly the model reasoning between steps, sometimes helped by asking it to write a plan or a to-do list first. The agent's quality depends on four things: the model, the tools you give it, the context it can see, and the guardrails around it. Anthropic's guidance is worth repeating: start with the simplest solution, and add agentic complexity only when it clearly improves results.

• Workflow: your code decides the steps; the LLM fills in parts
• Agent: the LLM decides the steps; your code provides tools and limits
• Most production systems mix both

02A minimal agent loop

Here is the core loop with the Claude Messages API in TypeScript. It keeps calling the model while it asks for tools, runs each requested tool, and returns all results in one user message. Important details: a maximum number of steps so a confused agent cannot loop forever; errors are returned to the model as tool results with is_error set, so it can adapt instead of crashing; and the whole content of each assistant reply is appended to history, not just the text. In real projects you can use the SDK's tool runner helper (which drives this loop for you), the Claude Agent SDK (the Claude Code harness as a library, with built-in file, shell and web tools), or hosted options such as Claude Managed Agents. Other ecosystems offer similar SDKs; the loop underneath is the same.

1const messages: Anthropic.MessageParam[] = [{ role: "user", content: goal }];
2for (let step = 0; step < 20; step++) {
3  const res = await client.messages.create({ model: "claude-opus-5-5", max_tokens: 8000, tools, messages });
4  messages.push({ role: "assistant", content: res.content });
5  if (res.stop_reason !== "tool_use") return res;
6 
7  const results: Anthropic.ToolResultBlockParam[] = [];
8  for (const block of res.content) {
9    if (block.type !== "tool_use") continue;
10    try {
11      const out = await runTool(block.name, block.input, currentUser); // your code, your auth
12      results.push({ type: "tool_result", tool_use_id: block.id, content: JSON.stringify(out) });
13    } catch (e) {
14      results.push({ type: "tool_result", tool_use_id: block.id, content: String(e), is_error: true });
15    }
16  }
17  messages.push({ role: "user", content: results });
18}
19throw new Error("Agent hit the step limit");

03Designing tools the model can use well

Tools are the agent's hands, and most agent failures are tool-design failures. Give each tool one clear job, a name that says what it does, and a description that explains when to use it, what it returns and common pitfalls — as if writing docs for a new teammate. Prefer a few high-level tools ('search_orders' with filters) over dozens of thin wrappers around every endpoint. Return compact, relevant results: an agent that receives a 5 MB JSON dump wastes context and gets confused, so paginate, summarise and include ids for follow-up calls. Make errors helpful ('customer_id not found; use search_customers first'). Make write tools idempotent where possible, and separate read tools from write tools so you can permission them differently. Test tools by watching real transcripts: where the model misuses a tool, the description usually needs work.

04MCP: plugging agents into systems

The Model Context Protocol (MCP) is an open standard, introduced by Anthropic and now supported across many AI tools and providers, for connecting AI applications to tools and data. An MCP server exposes tools (actions), resources (readable data) and prompts (templates) over a standard JSON-RPC protocol, either locally via stdio or remotely over HTTP. Any MCP client — Claude Code, Claude apps, IDEs and other agent hosts — can then use it without custom glue code. That means you write a 'tickets' or 'database' integration once and reuse it across agents. Remote MCP servers use OAuth for authorisation, so the agent acts with a user's delegated, scoped permission. Treat third-party MCP servers like any dependency you install: review what they can access, pin versions, and prefer servers from trusted publishers.

1{
2  "mcpServers": {
3    "tickets": {
4      "command": "node",
5      "args": ["./mcp/tickets-server.js"],
6      "env": { "TICKETS_API_URL": "https://api.example.com" }
7    }
8  }
9}

05Context: the agent's working memory

Everything the agent knows during a task lives in its context window: instructions, tool definitions, the history of calls and results. Long tasks fill it up, and quality drops as the context gets noisy. Good harnesses manage context actively. Keep the system prompt focused on goals, constraints and how to verify work. Load tools on demand when there are many (tool search). Clear old, bulky tool results once they are no longer needed (context editing) or summarise earlier history (compaction). Give the agent a scratchpad or memory file for notes that must survive — a plan, decisions, progress. For big tasks, split work across subagents: each explores in its own fresh context and returns only a short result to the main agent. This is how coding agents keep working on large repositories without drowning in file contents.

06Guardrails and human-in-the-loop

An agent can take real actions, so you design limits like you would for a new employee with production access. Least privilege: give only the tools the task needs, with credentials scoped to the user or a narrow service account. Permission tiers: read-only tools run freely; writes need confirmation or run in a sandbox; destructive actions (payments, deletes, emails to customers) always need a human. Budgets: step limits, token or cost budgets, and wall-clock timeouts. Sandboxing: run code and shell commands in isolated containers with no secrets and restricted network. Verification: tell the agent how to check its work — run tests, re-read the result — and check it yourself in code where possible. Audit: log every tool call with inputs, outputs and the identity it acted for.

• Read: allow · Write: confirm or sandbox · Irreversible: human approval
• Step, token and time budgets on every run
• Secrets stay in the tool layer, never in the prompt

07Context engineering for long-running agents

A long agent run is a context-budget problem. Each step adds the model's reasoning, the tool call and its result; after a few dozen steps, much of the window is stale logs. Techniques, roughly in order of use: keep tool outputs small by design (summaries, pagination, ids instead of full objects); clear old tool results the model no longer needs while keeping the fact that the call happened (context editing); periodically compact history into a summary the agent continues from; persist durable state outside the window — a progress file, a task list, a memory store — so a fresh context can resume; and delegate exploration to subagents that return condensed findings. Prompt caching interacts with all of this: cache hits need a stable prefix, so append to history instead of rewriting it, and edit context through the API's supported mechanisms rather than by mutating earlier messages, which can also invalidate the model's preserved reasoning on current models.

08Prompt injection and the lethal trifecta

Security researchers describe a dangerous combination for agents: access to private data, exposure to untrusted content, and the ability to send data out (an email tool, an HTTP request, even rendering an image URL). With all three, a malicious web page or document can instruct the agent to read secrets and exfiltrate them. Since no model is fully immune to injection, break the combination structurally. Remove one leg where possible: no outbound network in the sandbox, or no access to private data while browsing. Apply allow-lists for domains and recipients. Require confirmation for any action that sends data externally. Keep credentials in the tool layer, so the model never sees them, and use per-user scoped tokens so damage is limited to what that user could do. Log and alert on unusual tool sequences, and red-team your agent with injected documents as part of the eval suite.

09Building an MCP server

An MCP server is a small program that declares tools with JSON Schema inputs and handles calls. Official SDKs exist for TypeScript, Python and other languages. Local servers communicate over stdio and inherit the user's machine permissions; remote servers use Streamable HTTP and should implement OAuth so each user grants scoped access. Design tools for agents, not for API completeness: few tools, clear descriptions, compact results. Validate every input and enforce authorisation server-side. Version your server and document breaking changes, because agents depend on tool names and shapes. Check the current MCP specification and SDK docs before building, since the protocol evolves.

1import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
3import { z } from "zod";
4 
5const server = new McpServer({ name: "tickets", version: "1.0.0" });
6 
7server.registerTool(
8  "get_ticket",
9  {
10    description: "Fetch one support ticket by id, including status and last 5 messages.",
11    inputSchema: { id: z.string().describe("Ticket id, e.g. T-1042") },
12  },
13  async ({ id }) => {
14    const t = await fetchTicket(id); // your API, your auth
15    return { content: [{ type: "text", text: JSON.stringify(t) }] };
16  },
17);
18 
19await server.connect(new StdioServerTransport());

10Cost and reliability engineering

Agent cost is tokens per step times steps per task, and both grow quietly. Measure cost and success per completed task, not per request. Levers: prompt caching on the stable prefix (system prompt and tools), which matters a lot because every step resends the history; lower effort or a smaller model for subagents and simple steps; fewer, better tools so the agent needs fewer calls; and task budgets that let the model pace itself instead of being cut off mid-step. For reliability, make tools idempotent and retries safe, checkpoint progress so a crashed run can resume, set wall-clock limits, and handle non-happy stop reasons (max_tokens, refusal, step limit) with a clear outcome rather than silence. Run long tasks as background jobs with status updates, not inside an HTTP request.