Learn Agentic Engineering

A system is agentic when a model decides which action to take next based on what it observed, inside a loop with a termination condition — everything else is a program with an LLM in it.

Every agent is the same loop — observe, reason, choose an action, run a tool, fold the result into state, check for completion — and every production problem lives in one of those boxes.

Six recurring system types — assistants, RAG, tool-calling systems, process automation, multi-agent systems, and the evaluation/observability layer that makes the others shippable.

Conversational, support, research, coding and internal assistants share one shape and differ on four axes — knowledge, tools, risk and latency — which decide the architecture.

Agents orchestrating APIs, databases, documents and humans replace glue work — but side effects demand idempotency, audit trails, and often a workflow engine instead of an agent.

Escalate plain code → LLM call → structured output → tool calling → RAG → workflow → agent → multi-agent one rung at a time, and stop at the first rung that solves the problem.

One model, one loop, a small set of tools, a hard step limit — the default architecture until measurements prove it insufficient.

An agent whose knowledge lives outside the model: retrieval is either a tool the agent chooses to call or a step that always runs before the model sees the question.

One coordinating agent delegates sub-tasks to specialised worker agents with isolated contexts — buying tool partitioning and parallelism at the price of coordination overhead and a single bottleneck.

A typed state object moved through a fixed graph of steps with deterministic and conditional edges, capped retries, and checkpoints — the most debuggable way to use LLMs on a task whose shape you already know.

Classify the intent once with a cheap model, then dispatch to a specialised handler — plain code, a single LLM call, a workflow, or an agent — so that each request pays only for the machinery it needs.

A side-by-side of single agent, agent + RAG, router, workflow, supervisor, and multi-agent on complexity, latency, cost, reliability, and debuggability — and the handful of questions that decide between them.

The model emits a structured request to call a function; your application executes it and feeds the result back — the model never runs anything itself.

The name, description and JSON schema of a tool are the only documentation the model ever reads — write them like an API contract, not a comment.

Constrain the model to emit JSON that matches a schema, then parse it into typed objects — the right abstraction when you need data, not actions.

Model-generated arguments are untrusted input from a probabilistic source — validate types, ranges, allow-lists and paths before execution, and feed violations back as re-prompts.

Classify tool failures as retryable or not, retry with exponential backoff and jitter under a timeout, and surface the rest to the model as observations it can reason about.

In an at-least-once world, a tool with side effects must be safe to call twice with the same arguments — idempotency keys make retries and re-runs harmless.

Run independent tool calls concurrently and dependent ones in order — a dependency graph, a fan-out limit, and deterministic result ordering keep it fast and debuggable.

Give each tool the narrowest scope that does the job, separate reads from writes, act with the user's delegated authority, and gate destructive actions behind confirmation, sandboxes and audit logs.

Retrieval-Augmented Generation fetches relevant passages at query time and puts them in the prompt so the model answers from evidence instead of from memory.

Turning raw files into clean, well-bounded, well-labelled chunks is where most RAG quality is won or lost.

An embedding model maps text to a vector so that semantically similar texts land close together; retrieval becomes nearest-neighbour search.

Where embeddings live: a plain database with a vector column, a dedicated vector store, or a search engine — and the ANN indexes that make nearest-neighbour search fast.

Dense vectors capture meaning; BM25 captures exact terms; hybrid retrieval fuses both so neither paraphrases nor identifiers are missed.

Restricting retrieval by tenant, permission, recency, or type is done with metadata filters — and where the filter runs decides both correctness and recall.

A reranker re-scores a small candidate set with a more expensive model so the few chunks that reach the LLM are the right ones — it fixes precision, not recall.

Turning ranked chunks into a prompt: order, deduplicate, fit the token budget, and instruct the model to answer only from what it was given — or to say it cannot.

A citation is a verifiable pointer from a claim to a retrieved span; the system, not the model, must check that it points at real text.

Measure retrieval and generation separately: recall@k, precision, MRR for the retriever; faithfulness and answer correctness for the generator — on a golden set you built from real queries.

The context window is the only input the model has; assembling it deliberately from instructions, request, history, retrieved knowledge, tool results, memory and state is the real program you are writing.

Decide what earns a place in the window, then shrink it: summarise history, truncate tool output, and extract facts instead of pasting raw dumps.

Models attend unevenly across the window: content at the start and end is used reliably, content in the middle is often ignored — so order the context on purpose.

Give every context section a token budget, measure real usage with the tokenizer, do the cost arithmetic before launch, and use sliding windows so history has a fixed size.

Build the context fresh at every step from state, retrieval and tool results; keep the stable prefix byte-identical for caching; and prefer code over templates once logic appears.

Agents have three storage horizons — the context window, short-term session state, and long-term persistent memory — and long-term memory splits into semantic facts, episodic events and procedural know-how.

A memory system is a write path (extract → dedupe → store) plus a read path (retrieve → rank → inject) over a store chosen for the access pattern — key-value, vector or graph — always scoped per user.

More memory is not automatically better: pollution, poor retrieval, summarisation drift, missing expiry, privacy exposure and no user control each turn a helpful feature into a liability.

Four ways to turn a goal into actions — direct execution, plan-then-execute, replanning, and the ReAct loop — each with a different profile of token cost, latency and robustness to surprises.

Explicit planning pays off on long-horizon tasks with dependencies or parallelisable subtasks; on simple tasks it only adds latency and cost — so decide with a rubric, evaluate plan quality, and enforce step budgets.

The Model Context Protocol standardises how an AI application discovers and calls external capabilities, turning N × M bespoke integrations into N + M.

An MCP server exposes tools (model-invoked actions), resources (application-read data) and prompts (user-selected templates); knowing which is which decides who controls the call.

A session runs initialise → capability negotiation → listing → invocation over a transport such as stdio or streamable HTTP, with auth and error handling at each step.

Direct API code is tightest and fastest, function calling adds model-driven invocation, MCP adds discovery and reuse across applications — each wins in a different N × M regime.

Multiple agents with distinct roles can be arranged as supervisor, pipeline, hierarchy or swarm; a role buys separate context, tools and evals, at the price of coordination.

One orchestrator agent decomposes work, delegates to specialist agents, and merges results — simple to reason about, but the orchestrator is the bottleneck and the single point of failure.

Agents arranged as fixed stages with typed hand-offs (Research → Analyze → Write → Review) trade flexibility for per-stage evaluation, replaceability and predictable cost.

Manager → team leads → workers scales a supervisor to many parallel sub-tasks, but each level compresses information and multiplies latency and cost.

Peer agents hand a conversation and its context to whichever agent has the right capability, with no central controller — flexible for routing-heavy dialogues, risky without hop limits.

Multi-agent systems stack latency, compound errors, cost coordination tokens and are harder to evaluate; the first question is always whether one agent or deterministic code can do the job reliably.

Agents coordinate through discovery, capability descriptions, task delegation and hand-off, choosing between shared state and message passing; A2A-style protocols cover agent↔agent the way MCP covers agent↔tool.

Between an agent proposing an action and executing it sits a risk assessment that routes high-impact actions to a human for approval — the architectural control that makes autonomous systems deployable.

Classify actions by reversibility and blast radius, preview them with dry-runs, design approval UIs that show what will actually happen, and audit every decision.

Human-in-the-loop blocks on approval; human-on-the-loop monitors and intervenes; both need escalation paths, SLAs and a defined fallback when nobody answers.

Model self-reported confidence is poorly calibrated; route to humans using external signals — evaluator scores, retrieval similarity, validation results — with thresholds set on eval data, not by feel.

Evals are the test suite for systems whose output is a distribution, not a value: a fixed dataset, repeatable runs, evaluators that score traces, and a comparison against the last version.

A catalogue of agent metrics — outcome, trajectory, retrieval, efficiency and safety — with a precise definition and computation for each, so a number means the same thing across versions.

A golden dataset is the versioned set of inputs and expected outcomes every eval runs against; its coverage, hard cases and hygiene determine whether the numbers mean anything.

Using a model to score outputs scales evaluation to criteria code cannot express, but the judge has biases of its own and is only trustworthy after calibration against human labels.

Most of what matters about an agent run can be checked by code — schemas, tool calls, trajectory shape, budgets — and those checks are exact, free and never flaky; use them before reaching for a judge.

Offline evals gate changes in CI; online evaluation samples production traces, runs A/B or shadow comparisons and closes the feedback loop — and both need enough samples to separate signal from noise.

A trace is a tree of spans — one per LLM call, tool call and state change — that records what the agent saw, decided, spent and how long it took; it is the primary artefact for both debugging and evaluation.

When an agent misbehaves, the trace is the evidence: walk it to the first bad decision, reconstruct the context the model saw at that step, compare tool arguments to the schema, then replay with a fix — a loop, not a guess.

Structured logs, RED metrics plus agent-specific ones (steps, tokens, cost per task), alerts on loops and cost anomalies, and dashboards — with PII redacted before anything leaves the process.

An agent that reads untrusted text and can call tools is a confused deputy by construction; security is layered checks in code around the model, not a paragraph in the prompt.

Direct prompt injection is a user supplying text that overrides the developer’s instructions; it cannot be fully prevented by prompting because instructions and data share one channel.

Indirect injection is when content the agent reads (a web page, document, email or tool result) carries instructions; it is the dominant real-world attack against tool-using agents.

The damage from a compromised or confused agent flows through its tools: destructive writes, data leaving via URLs, emails and files, and runaway call volumes.

An agent should act as the user, with the user’s scoped credentials, and every tool must check authorisation in code; the prompt is not an access control list.

Guardrails are cheap checks in code before and after the model: classifiers, allow and deny lists, schema validation, PII detection; they reduce risk but cannot enforce policy on their own.

Secrets must never enter the model’s context, traces or logs, and every byte returned by a tool must be treated as untrusted data and labelled before it re-enters the loop.

Production agents fail in a small number of recurring ways; each has a known mitigation, and a reliable system is one that has a planned response for all seven before launch.

Each of the seven production failure scenarios has a characteristic signal in traces and metrics and a concrete runbook; knowing both turns a 3 a.m. page into a ten-minute fix.

An agent loop must be bounded by hard limits on steps, tokens, cost and wall-clock time, with loop detection and a graceful degradation path, all enforced in code outside the model.

Provider fallback chains keep the product up, prompt caching and result caching cut cost and latency, and routing by difficulty sends each request to the cheapest model that can handle it.

Agent frameworks package prompt templates, tool registries, loops, state graphs, memory and tracing; the abstraction saves boilerplate and costs visibility, and the right choice depends on which you need more.

An LLM SDK plus ordinary application code covers most production agent systems; a tool-calling loop with a step limit is about forty lines, and you own every one of them.