Deterministic code around probabilistic models.
Over 120 building blocks of AI agents in nine areas, each with its classic equivalent in software engineering.
The principle
An AI agent is not a single model, but a software system that embeds a probabilistic model inside a controlled execution loop.
The language model is the central probabilistic decision component in the system. The code around it is built to be as deterministic as possible: it frames that unpredictability, feeds it context, validates its proposals, and catches failures. This code is the harness.
The model proposes, a scorer evaluates, the code decides.
Control Flow & Triggers
Event & Time Triggers
Run agents not just interactively in chat, but on a schedule or in response to background system events.
Agent Loop
Call the model in a loop until the goal is reached.
Termination Condition
Stop when a final answer is produced or hard limits (steps, time, budget) are reached.
Prompt Chaining
Fixed sequence where the output of step 1 is the input to step 2.
Plan-and-Execute
Have the model produce a structured work plan before code executes it step by step.
Evaluator–Optimizer (Reflection)
Draft → critique → revise in a targeted loop until a quality criterion is met.
Routing
Have the model classify the request; code dispatches it to the matching execution path.
Tool Dispatch
Map the tool name in a model response to the actual function in code.
Hooks / Middleware
Code that runs automatically before/after every model or tool call (logging, validation, transformation).
Workflow Graph
Enforce allowed states and transitions explicitly in code.
Parallelization
Launch multiple model or tool calls concurrently and merge their results.
Speculative Execution
Preload likely data or run guardrails in parallel while the model is still generating.
Orchestrator–Worker
One model decomposes the overall task; specialized workers process the sub-tasks.
Streaming & Events
Forward tokens and intermediate steps continuously instead of blocking until completion.
Human-in-the-Loop
Require a human to confirm before critical steps proceed.
Interrupts & Cancellation
Cleanly abort a running loop when the user stops it or supplies new information.
Time-Travel / Replay
Rewind to an earlier checkpoint, adjust context, and re-run from that point.
Clarifying Questions on Ambiguity
Pause when a request is ambiguous and ask the user instead of guessing (e.g. via an ask_user tool). Code detects this and pauses the loop.
Tool Choice (Forced Call)
Set tool_choice to auto, required, or a specific tool, e.g. to force a structured final response on the last step.
Context, Memory & Tool Interfaces
System Prompt
Anchor ground rules, role, and boundaries at the very top of the context.
Prompt Templates
Assemble prompts at runtime from fixed building blocks and variables.
Few-Shot Examples
Demonstrate desired behavior and output format via examples in the prompt.
Tool Definitions
Name, description, and parameter schema for every tool (the model sees only this — unclear docs lead to bad calls).
Deterministic Tools over Model Knowledge
Offload arithmetic, date logic, sorting, or code execution to tools instead of letting the model guess.
Tool Output Preparation
Truncate, filter, or summarize oversized tool outputs before they blow up the context window.
Short-Term Memory
Carry message history and intermediate steps through the current run.
Context Scoping (Isolation)
Show each step only the exact slice of data it needs.
Context Compaction
Trim or summarize older history when the context window fills up.
Long-Term Memory
Persist knowledge across sessions.
Background Memory Extraction
Extract key facts asynchronously after a conversation and write them to a database.
RAG
Retrieve relevant documents from a knowledge base before or during a run.
Dynamic Tool Loading (Tool-RAG)
When hundreds of tools exist, load only the tool descriptions relevant to the current step into context.
Multimodal Preprocessing
Convert PDFs, images, or audio into text, tables, or chunks before calling the model.
Prompt Caching
Avoid reprocessing an unchanged prompt prefix on every step (saves latency and cost).
Context Ordering
Put critical instructions at the beginning or end; information buried in the middle of very long contexts is easier to miss. Keep stable parts at the front so prompt caching hits.
Chunking & Indexing
Split documents meaningfully (by section, with overlap and metadata such as source and date). Poor chunks produce poor RAG, no matter how strong the model is.
Hybrid Search & Query Rewriting
Combine keyword search (e.g. BM25) and vector search because embeddings struggle with exact strings like part numbers. Let the model rewrite or decompose search queries.
Instruction Modules (Skills)
Load specialized instructions only when needed instead of stuffing everything into the system prompt. Keeps context lean.
External Working Memory (Notes & Task Lists)
Let the agent write plans, progress, and findings to files or a task list. Survives context compaction and very long runs.
Input & Output Validation (Validation & Guardrails)
Input Guardrails
Catch invalid, dangerous, or sensitive inputs before calling the model.
Constrained Decoding
Exclude invalid tokens during generation itself.
Structured Outputs
Enforce a typed data object instead of free-form text.
Parsing & Validation
Parse model responses, check types and value ranges, and catch errors cleanly.
Output Guardrails
Check the response for content and format rules before passing it on.
Grounding & Citations
Require the model to back claims with source IDs; code deterministically verifies that the source and quote exist.
Deterministic Recalculation
Recompute totals, percentages, or dates mentioned in text using deterministic code.
Logprobs / Confidence Check
Inspect token probabilities. Caveat: not available from every provider and not a reliable hallucination detector (models are often confidently wrong).
LLM-as-Judge
A second model evaluates the response (caveat: itself probabilistic!).
Retry with Feedback
Feed the validation error back to the model so it can self-correct.
Multi-Sampling & Voting
Generate multiple responses and pick the most frequent or highest-scoring one.
Fallback
Switch to a backup model or fixed response when retries are exhausted.
Stop-Reason Handling
Inspect why generation stopped (finished, tool call, max tokens, refusal). Continue or reject truncated responses and handle refusals explicitly instead of treating them as normal answers.
Guardrails are not just if/else. if/else describes the control flow; in practice guardrails are also implemented via policy engines, permission services, schema validators, sandboxes, or dedicated classifier models.
Security & Isolation
Prompt Injection Defense
Mark untrusted external data in the prompt. Important: unlike SQL prepared statements, LLMs have no guaranteed separation between code and data. Real protection comes from hard restrictions on tool permissions in the harness.
Tool Argument Validation
Check not only whether a tool is allowed, but also what arguments it is called with (e.g. file paths, amount limits, recipient domains).
Output Encoding
Treat model output as untrusted input before rendering it as HTML/Markdown in a browser or interpolating it into queries.
Tenant Isolation in Memory
Strictly enforce in database/RAG code that User A's memory and documents never enter User B's context.
Identity Propagation (On-Behalf-Of)
Execute data and tool calls with the exact permissions of the authenticated user.
Tool Permissions
Define which tools and actions are allowed in a given state.
Approval Before Irreversible Actions
Never send, delete, pay, or publish without explicit human approval.
Reversible PII Masking
Replace sensitive data with placeholders before calling the model and restore it afterward.
Secrets Handling
Never place passwords or API keys into the model context; inject them only inside tool code.
Sandbox
Isolate code execution and file access from the host system.
Egress Filter (DLP)
Prevent a hijacked model from exfiltrating data via external links, webhooks, or images.
Budgets & Rate Limits
Enforce hard caps on cost and call counts per run and per tenant.
Audit Trail
Record tamper-evident logs of who triggered which write or irreversible action and when.
Autonomy Levels
Set per task: read_only, suggest, act_with_approval, or autonomous. Choose the level based on action risk, not trust in the model.
Trust Verification for Tools & MCP Servers
Third-party tool servers can return manipulated tool descriptions or results. Use vetted sources, pin versions, and monitor tool descriptions for changes.
Data Privacy & Retention
Define which data lands in logs, traces, checkpoints, and vector indexes, how long it is kept, and how it is completely deleted on request.
Regulatory Classification
Depending on the use case, regulations such as the EU AI Act impose obligations (transparency, documentation, human oversight). Clarify the risk category early.
Red Teaming
Deliberately attempt to trick the agent into misbehaving (injection, privilege escalation, data exfiltration) before attackers do. Turn findings into permanent eval cases.
Reliability, Operations & Lifecycle
Prompt Versioning
Version prompts like code so evals, metrics, and rollbacks map to an exact revision.
Model Version Pinning
Pin dated model snapshots so provider updates do not silently alter behavior.
Sampling Parameters
temperature and top_p control variance (note: even temperature=0 is not guaranteed deterministic).
Model Cascading / Tiering
Try a small, fast model first; escalate to a larger model only when needed.
Timeouts
Cleanly abort hanging model or tool calls.
Circuit Breaker & Backoff
Wait with backoff on API outages or rate limits, or fail over to a secondary provider.
Idempotent Tools
Ensure a retried tool call does not cause duplicate side effects.
Compensation Logic (Rollback)
If step 4 aborts, undo the side effects of steps 1–3.
Checkpointing
Resume long-running workflows from the last completed step after a crash.
Response Cache
Avoid paying twice for identical requests.
Semantic Caching
Cache similarly phrased questions via vector similarity. Caution: requires very high thresholds + fact checking, otherwise "by June 30" and "by September 30" may collide.
Logging & Tracing
Reconstruct what the agent did, when, how long it took, and why.
Cost Tracking
Track token usage (input, output, cache, reasoning) and cost per run.
Evals
Measure statistically across realistic test cases whether a change degrades quality.
Shadow Mode / Canary
Test new prompts or models in the background against real traffic.
Feedback Data for Training
Collect successful and corrected runs. The harness itself never mutates model weights — a separate training pipeline (e.g. fine-tuning) uses this data to train future models.
Durable Execution
Guarantee that a run continues across crashes, deployments, or multi-day waits. Builds on top of checkpoints.
Reasoning Budget
On reasoning models, configure how much thinking budget a step gets: high for hard planning, low for routine steps. Costs tokens and latency.
Batch Processing
Process non-urgent workloads via provider batch APIs at lower cost.
Online Quality Monitoring & Drift
Evals check before release; in production, sample and score live runs to catch quality drift or new request patterns early.
Global Kill Switch
Immediately disable an agent or specific tenants/tools centrally without redeploying.
Multi-Agent Coordination
Sub-Agent
Delegate a sub-task to an agent with its own isolated context.
Handoff (Context Transfer)
Hand over conversation and responsibility completely to a specialist agent.
Message Passing
Let agents exchange results asynchronously via messages.
Tool / Agent Protocols (MCP, A2A)
Standardize how tools and agents connect without bespoke glue code.
Ping-Pong / Deadlock Protection
Prevent agents from passing tasks back and forth in an infinite loop.
Least-Privilege Delegation to Sub-Agents
Grant sub-agents only the permissions required for their sub-task, never more than the caller holds.
Typed Handoffs
Pass results between agents or phases as validated schemas rather than free text. Errors surface at the boundary, not three steps later. Checks structure, not factual truth.
Scoring as an Intermediate Layer (Scoring & Thresholds)
Scoring bridges the gap between fuzzy model outputs and deterministic code: a soft question like "is this good enough?" becomes a number, and ordinary code decides via if score > threshold. Even at the single-token level, language models work this way: the network deterministically assigns scores (logits) to every token, and only sampling from that distribution is probabilistic.
Token Scoring (Logits → Softmax)
The network scores every candidate token; temperature, top_k, and top_p shape the distribution before sampling. Constrained decoding and logprobs checks operate right here.
Similarity Scoring (Embeddings)
Express similarity between a query and a document, tool description, or cache entry as a number. Foundation for RAG, Tool-RAG, and semantic caching.
Reranking
A second, more precise model re-orders coarse RAG hits so only the top k enter the context.
Classifier Scores
Probability per category (injection, toxicity, topic routing); code blocks or routes above a threshold.
Rubric-Based Judge Scores
An LLM-as-Judge assigns points against explicit criteria instead of vague impressions. Still probabilistic, so audit a sample against human ratings.
Best-of-N Selection
Generate N candidate answers, score them, and return the best. Costs N times the tokens.
Confidence-Based Escalation
On a low score, escalate to a stronger model (cascading) or to a human (human-in-the-loop).
Threshold Calibration
Derive thresholds from evals on real examples rather than guessing. Every threshold trades false positives against false negatives — guessing just moves fuzziness into an arbitrary number.
Reward Model (Training)
AI labs use reward models to score outputs and shift weights toward higher scores (e.g. RLHF). Only relevant inside your own harness if you fine-tune models yourself.
Reward-Hacking Protection
Models sometimes optimize for the score rather than the task (deleting or weakening tests, hardcoding outputs, hiding errors with type: ignore, sweet-talking a judge). Defenses: read-only scorers (ProtectedPaths), diff checks on test/config files, held-out tests, multiple independent signals (tests, typecheckers, linters), isolated judge, specific feedback instead of a raw number, bounded retries, human review before merge.
Pairwise Comparison
Have a judge decide "is A or B better?" instead of assigning absolute 1–10 scores. Usually more stable.
Judge Bias Control
Judges often favor longer answers, the first option shown, or outputs from their own model family. Randomize order, account for length, and use a different model family as judge.
Where scoring already appears elsewhere in this taxonomy: RAG and Tool-RAG (similarity), routing and input guardrails (classifiers), LLM-as-Judge, multi-sampling & voting, logprobs checks, model cascading, semantic caching, and evals (pass rate as release gate).
Multi-Model Operation (Model-Agnostic Architecture)
Models from different labs react differently to the same prompt, prefer different formats, and have different strengths — partly because each lab trains its models inside its own harness environment. Principle: shared safety core, model-specific edges, evals as the referee. A harness built on the lowest common denominator wastes model capabilities; a harness coupled to a single model creates lock-in.
Model-Agnostic Safety Core
Tool permissions, sandboxes, egress filters, approvals, tenant isolation, and budgets never depend on the model. A weaker model may produce worse answers, but cannot cause harm.
Provider Adapter
Thin layer translating the canonical internal format into each provider's API format (tool calls, structured outputs, caching, system prompt handling). The rest of the codebase only knows the canonical format.
Per-Model Prompt Profiles
Maintain system prompts, few-shot examples, and tool descriptions as versioned variants per model when needed. What works best for Model A can confuse Model B.
Native Features over Polyfills
Use native tool calling, structured schemas, and prompt caching rather than emulating them with prompt tricks. Plays to the strengths the model was trained on.
Capability Matrix
Declare in code what each model supports (tools, vision, etc.). The router filters candidates accordingly.
Graceful Degradation
When a model lacks a feature, fall back to a supported alternative (e.g. Pydantic validation + retry) instead of crashing.
Cross-Model Evals
Run the exact same eval suite with real project tasks against every candidate model. Shows which model performs best with this harness and whether a prompt tweak for A regresses B.
Task-Based Model Routing
Pick the best model per task based on evals: fast model for routine steps, frontier model for complex reasoning, specialized model for code or vision.
Related building blocks in this taxonomy: model version pinning, shadow mode / canary during model migrations, portable tool protocols (MCP), unified logging & tracing for model comparisons, model cascading, fallback, and circuit breakers with provider failover.
Human–Agent Interface (UX & Transparency)
The user interface is also deterministic code — and often the place that determines whether approvals, corrections, and trust actually work in practice.
Progress Transparency
Surface the current step and tool calls via events so humans can intervene early rather than only at the end.
Preview Before Execution
Show planned changes (code diff, email draft, payment details) before executing them. That is what makes human approval meaningful rather than rubber-stamping.
Communicating Uncertainty
Let the agent ask clarifying questions (ask_user) or flag assumptions instead of presenting guesses with false confidence.
Undo / Rollback
Provide a clear way for users to revert agent actions (technically backed by compensation logic or version control).
Feedback Capture
Capture thumbs up/down, edits, and cancellations to feed evals, online monitoring, and the data flywheel.
Start a project or scale further?
Tell us where you stand and where you want to go. We support you along the way and will get back to you personally.
info@appamass.com