Agent Specification Engineering

Agent demos are fluent because the happy path is easy to hide. Production systems expose the missing decisions: ambiguous goals, excessive tool authority, stale context, invalid state, duplicate effects after timeout, unbounded delegation, unverifiable completion, and failures that no prompt can safely resolve.

Agent Specification Engineering presents a rigorous alternative to prompt-only development. Its central thesis is simple: models should interpret and propose inside an execution architecture whose contracts, schemas, policy, state, budgets, typed tools, domain services, approvals, and evidence define what can actually happen.

You will learn how to:

• Translate prompts into explicit behavioral contracts.
• Distinguish goals, outputs, outcomes, completion, and business success.
• Design typed tool contracts for reads, reversible writes, and irreversible effects.
• Separate workflow state, authoritative domain state, temporary context, and governed memory.
• Enforce least privilege, tenant scope, delegation, approvals, and separation of duties.
• Compile specifications into runtime artifacts and bind them safely to models and frameworks.
• Classify timeouts, unknown outcomes, retries, reconciliation, compensation, and replay.
• Test structural, semantic, policy, state, failure, adversarial, and stochastic behavior.
• Evaluate observable paths and effects rather than final answers alone.
• Build guardrails, audit trails, incident controls, release tuples, and governance.

The book includes AgentSpec 0.1 as a concrete executable specification language, along with a JSON Schema and EBNF, five complete specifications, and a dependency-free Python 3.12 reference engine with offline tests.

Four production case studies cover:

• Customer-support triage.
• A sandboxed software-engineering agent.
• Financial operations with deterministic thresholds and two-person control.
• Bounded multi-agent incident response.

Eight appendices provide language and schema references, threat and production checklists, evaluation scorecards, discussion notes for all 126 exercises, a 115-term glossary, and annotated further reading.

This book is for staff and principal engineers, AI and platform engineers, software architects, security and reliability practitioners, technical leads, and engineering managers responsible for systems that call tools or affect real data.

It assumes familiarity with APIs, schemas, testing, and distributed-system basics. It does not require formal-methods expertise or allegiance to any particular AI framework.

Unlike a prompt cookbook, the book treats model behavior as one component in a system of independently reviewable boundaries.

Unlike a framework manual, it separates portable purpose and contract semantics from provider-specific binding.

Unlike a governance-only overview, it provides executable artifacts, failure simulations, tests, diagrams, and release gates.

Agent Specification Engineering extends the language-design ideas introduced in Geison Flores’s AI DSL Development. The earlier book asks how to design a domain-specific language; this one asks what an executable agent specification must say about authority, state, tools, effects, evidence, failure, and operations.

If an AI system must remain reliable after the demo—when identity changes, dependencies fail, requests are duplicated, evidence conflicts, and models are wrong—this book gives your team the vocabulary and engineering method required to build the boundary.