AAT — Adaptive API Toolkit

Model your API as a graph once. Get long-chain integration tests, layer × environment matrices, CI-ready runs, and an MCP server for AI coding tools — all from the same YAML.

AAT describes an API as a graph of operations: what each one takes and returns, which must run before which, and which undoes which. From that graph it runs multi-step test plans that wire data between steps, check every response, clean up after themselves, and leave an archive of every request and decision. LLMs are optional and authoring-time only: aat prompt can draft a plan, and the MCP server teaches AI tools your API. Execution never calls an LLM.

aat-sandbox init shop && cd shop     # after installing: see Install
aat-sandbox serve &
aat run plan full-lifecycle

Start Here

• Shop example — watch AAT drive a realistic API in a minute, offline: an order through every state, a layer matrix, two regions, negative tests
• Petstore Quickstart — go from an OpenAPI spec to a passing, self-cleaning test in five minutes
• MCP Server — give Claude Code or another MCP client your graph and the tools to write and run tests
• Share your API with integrators — package part of the project your tests use, so your integrators' AI tools learn the API from it

Install with Homebrew, a release archive, Docker, or go install, or build from source: see Install.

Getting Started

Guide	Time	What you get
Install	2 minutes	aat and aat-sandbox from a release, Homebrew, Docker, or source
Shop example	1 minute	A complete project running against the offline sandbox
Petstore Quickstart	5 minutes	Your first graph, templates, and plan, scaffolded from the Petstore spec
Petstore Walkthrough	15 minutes	Every file of a small working project, explained
Tutorial	45 minutes	A project built by hand: environments, plans, workflows, recipes, layers

Documentation Map

Core Guides

Progressive reading order — each builds on the previous.

Document	What you'll learn
Project Setup	The aat-project.yaml manifest, directory layout, and auto-discovery rules
API Graphs	Nodes, inputs, outputs, ordering, and the operation model your tests build on
Templates	HTTP request/response YAML files, placeholders, extraction, and conditional blocks
Lua Transforms	Post-processing responses with inline Lua scripts
Environments	Base URLs, auth, secrets, headers, multiple environments, and per-host overrides
Plans and Recipes	Recipes (compact format), full plans, steps, values, assertions, and layers
Workflows	Reusable plan templates, addons, slots, and composition
Value Resolution	How AAT resolves step inputs: literals, references, pools, selections, and expressions
Domain Knowledge	Concepts, custom types, and value pools for test data

Running

Document	What you'll learn
Running Tests	aat run plan, aat run batch, output modes, exit codes, retries, and cleanup
Matrix Testing	Layer groups, cartesian product batches, duplicate detection, and the test matrix
Local Development	Auto-discovered .aat-overrides.yaml for routing traffic to localhost
CI/CD Integration	Exit codes, --json output, --quiet mode, and pipeline examples
Checkpoints	Stopping after a step and handing live state to another tool
Archives	What each run records, redaction, export and import, and pruning
Web UI	Browsing runs, batches, and traces in the embedded web viewer
Visualizers	Custom HTML renderers for API response data in the web UI
Validation	All aat validate subcommands and the errors they report

AI and Integration

Document	What you'll learn
MCP Server	IDE AI integration: transports, tools, resources, and personas
Share Your API with Integrators	Packaging part of your test project as a kit that integrators' AI tools learn the API from
AI Assistant Primer	Structural reference for AI coding assistants working with AAT projects
Scaffolding from OpenAPI	What aat generate writes from a spec, and what to add by hand
Generating API Docs	Markdown documentation from the graph with aat docs generate
LLM-Assisted Planning	aat prompt, interactive confirmation, plan saving, and trace debugging

Examples

Document	What you'll learn
Examples	The example projects and what each one shows
Shop example	The offline quick start: slots and addons, a layer matrix with dedup, us/eu environments, negative tests, checkpoints, and MCP configuration
Petstore Walkthrough	A line-by-line tour of a working example: graph, templates, workflows, recipes, and how they compose
Airline case study	The 74-operation project AAT was built for, and the features that scale relies on

Concepts Glossary

Alphabetical definitions of key AAT terms. Each links to the doc that covers it in depth.

Addon

A workflow fragment that extends a base workflow by splicing steps at a declared insertion point. -> workflows.md

Archive

The JSON record every run writes: each request and response, how each input was resolved, assertion results, and cleanup. -> archives.md

Assertion

A post-step validation check that verifies response values meet expected conditions. -> plans.md

Checkpoint

A run stopped after a named step with --stop-after, skipping cleanup and exporting its state (base URLs, headers, and outputs, with credentials redacted unless requested) with --dump-state. -> checkpoints.md

Cleanup Step

A teardown step that runs after the plan completes, even on failure, to release resources. -> plans.md

Domain Knowledge

A YAML file declaring business concepts, custom types, and value pools for test data. -> domain.md

Element Field

A named, typed field declared on an array output that describes the structure of each element for selection strategies. -> graphs.md

Environment

Runtime configuration that provides base URLs, auth credentials, static headers, secret references, and LLM settings. -> environments.md

Expression

A dynamic value placeholder like {{today + 7 days}} or {{env.API_KEY}} evaluated at execution time. -> value-flow.md

Graph

A YAML model of your API's operations — nodes with typed inputs and outputs, ordering rules, and error detection. -> graphs.md

Layer

A YAML overlay that provides alternate test data for a plan without duplicating the entire plan structure. -> plans.md

Layer Group

A set of mutually exclusive layers combined via --layer-group to produce a cartesian product of batch permutations, with automatic duplicate detection. -> batch-layers.md

Manifest

The aat-project.yaml file that marks a project root and declares paths to all project artifacts. -> project-setup.md

MCP Server

aat mcp serve: exposes the graph, workflows, and tools to validate and run plans to AI coding assistants over the Model Context Protocol. -> mcp-server.md

Node

One API operation in the graph, with a name, adapter reference, typed inputs, and typed outputs. -> graphs.md

Override

An environment entry that routes matching nodes (such as payment*) to another base URL, auth, or headers. -> environments.md

Plan

A concrete, ready-to-run test specification with ordered steps, input values, assertions, and cleanup. -> plans.md

Recipe

A compact plan format that names a workflow and provides only the value overrides, letting AAT fill in the rest. -> plans.md

Selection

Choosing one element from an array output using a strategy like first, min, max, or match. -> value-flow.md

Slot

A choice point in a base workflow where one of several named workflow fragments can be inserted. -> workflows.md

Step

One operation in a plan, mapped to a graph node, with resolved input values and optional assertions. -> plans.md

Template

A YAML file defining the HTTP request shape and response extraction rules for a single graph node. -> templates.md

Value Pool

A curated list of valid values for a domain type in the domain file, used by aat prompt, aat docs generate, and the MCP tools; runs never read it (a pool default on an input is what varies run data). -> domain.md

Visualizer

A standalone HTML plugin that renders API response data in the web UI, turning complex reference-based JSON into readable visual displays. -> visualizers.md

Workflow

A reusable plan skeleton with steps, slots, and composition rules; recipes name one and state only what differs, whether you, an AI assistant through the MCP server, or aat prompt wrote them. -> workflows.md