Agent Action Contract v1

Pre-action control for AI agents

Agents propose tool calls. AANA checks evidence, authorization, and risk, then only allows execution when the route is accept.

AANA is a pre-action control layer for AI agents: agents propose actions, AANA checks evidence/auth/risk, and tools execute only when the route is accept.

Try AANA in 2 minutes Static tool-call demo Agent Action Contract View the code

Production-candidate as an audit/control/verification/correction layer. Not yet proven as a raw agent-performance engine.

Start here

What reviewers should understand in the first minute.

AANA is not trying to replace the base agent. It sits between the agent and the tool: agent proposes, AANA checks, the tool executes only when the route is accept.

Try the gate Paste a tool call and verify blocked tools do not execute. Read the standard Seven fields, route semantics, examples, and JSON schema. Wrap an agent Examples for Python, FastAPI, MCP, OpenAI Agents, and middleware. Check the evidence Diagnostic results, limitations, and reproducible validation commands.

Watch first

Start with the story: why better answers can still drift.

Before the charts and papers, these short videos show the core tension: an AI system can get more capable while losing track of the constraints that make its answers worth trusting.

Plain English

Think of it as an obstacle course for AI answers.

A direct answer can sound confident and useful while quietly breaking a budget, inventing evidence, ignoring a safety limit, or guessing when it should ask a question. AANA makes those hidden failures easier to test.

The question

Can the answer do the job?

Capability asks whether the response is useful enough to be tempting.

The catch

Did it keep the promises?

Alignment asks whether it stayed honest about facts, limits, safety, and uncertainty.

The signal

Where did they split apart?

The gap score surfaces the polished answers that quietly lose the plot.

A playful obstacle course representing AI answers passing through constraint checks.

Why it matters

Real-world prompts often come with invisible tripwires.

1

Pressure rises.

Users ask for faster, cheaper, more certain, or more persuasive answers.

2

Constraints get dropped.

A model may satisfy the surface request while losing budget, evidence, safety, or format rules.

3

AANA measures the gap.

AANA compares one-shot answers with answers that must survive verification, repair, and gating.

Where AANA fits

It is strongest when failures can be checked, not waved away.

AANA is less about telling a model to "be more careful" and more about giving the system a correction path: detect the broken constraint, ground the answer, repair it if possible, or refuse, ask, and defer when repair would be fake.

Planning assistants

Budgets, schedules, and logistics

Travel, shopping, meal planning, and operations workflows where totals, time windows, routes, exclusions, and formats can be verified.

Grounded research

Facts, citations, and uncertainty

Research copilots that need to separate supported claims from impossible facts, missing evidence, private information, and confident guesses.

Safety-critical advice

Forbidden ingredients and hard limits

Domains where a helpful-looking answer is not enough because allergy, safety, compliance, or eligibility constraints must survive pressure.

Workflow agents

Actions with preconditions

Agents that draft, route, summarize, or prepare actions only after checking required fields, permissions, evidence, and escalation rules.

Evaluation labs

Capability versus constraint loss

Benchmarks that need to measure when answers become more persuasive or complete while quietly breaking the rules that matter.

Not a fit

Pure taste or vague preference

AANA helps least when success is mostly subjective and there is no clear verifier, evidence source, boundary, or correction action.

Start building guide Copy integration recipes Read application playbook Use adapter template View scenario pack Read demo results

Why this is different

Make the pre-action decision visible.

Frontier LLMs and multimodal models already use alignment training, safety policies, tool use, retrieval, and hidden refusal behavior. AANA makes the verification loop explicit so teams can inspect what evidence was checked, what failed, and why an answer or action was accepted, revised, refused, or deferred. The goal is to wrap capable base agents with a control layer, not replace them as the raw task engine.

SOTA LLM or multimodal model Powerful generator with mostly internal alignment behavior
Prompt Model weights, policies, tools, and hidden checks Answer or refusal
  • Strong average behavior from training and product guardrails.
  • Domain constraints often live in prompts, hidden policies, or middleware.
  • Downstream teams may not see which evidence or verifier changed the decision.
AANA-style architecture Generator plus explicit verifiers, evidence, correction policy, and gate
Request Generator Evidence Verifier stack Revise, retrieve, ask, refuse, defer, or accept Audited gate
  • Environment-specific facts and policies become runtime evidence.
  • Verifier calibration, escalation, and audit records are first-class concerns.
  • The system can correct or route uncertainty instead of silently trusting a polished answer.
Local facts

Base models do not know your environment.

Refund eligibility, file scope, CI status, jurisdiction, calendar state, and access rights need deployment-specific evidence.

Visible gates

Hidden alignment is hard to govern.

AANA exposes adapter, verifier, action, violation, and audit metadata so teams can review what happened.

Consequence-aware

More checking is worth it when false accepts are costly.

The loop adds latency and infrastructure, so it fits consequential actions better than casual low-stakes chat.

What AANA adds

AANA standardizes the decision before execution.

Prompt guardrails, classifiers, LLM judges, and framework middleware can all help, but they often leave the action decision implicit, provider-hidden, or tied to one runtime. AANA makes that decision a typed contract and a consistent audit surface.

Agent Action Contract Tool name, category, authorization, evidence, risk, arguments, and route
Agent proposes AANA checks Accept, revise, retrieve, ask, defer, or refuse Execute only on accept Audit-safe log
  • Wrapped tools do not execute unless AANA returns accept with no hard blockers.
  • Missing evidence, missing authorization, and unknown tools become explicit routes instead of hidden assumptions.
  • CLI, SDK, FastAPI, MCP, and middleware surfaces return the same decision shape.
Read the full explainer Architecture notes

How it works

Generate. Verify. Repair. Gate. Score.

The project is not claiming perfect AI alignment. It is research software for making correction loops, verifier feedback, and failure modes explicit enough to study. Domain adapters make the pattern reusable: name the constraints, attach verifiers, define repair actions, then gate the final answer.

Task A request arrives with goals, facts, boundaries, and tradeoffs.
Generator The model takes its first shot.
Verifier Verifier checks look for broken facts, risky impacts, task drift, and false confidence.
Corrector The system repairs, asks, refuses, defers, or lets the answer through.
Results The trail stays visible: records, tables, and charts show what changed.

Current signal

In the pilot run, correction loops held the line far better than direct answers.

In the published 120-case comparison, direct answers passed 45.8% of the constraint checks. The strongest tool-structured AANA run reached 98.3% while lifting the capability score from 0.662 to 0.922. Treat this as a research signal, not a certified benchmark.

A first six-scenario application demo now tests the same idea on travel, meals, research, privacy, workflow readiness, and feasibility. Under high pressure, AANA-style correction raised model-judged alignment from 0.7600 to 0.8383 and pass rate from 0.5000 to 0.8333, while exposing a travel-planning failure that needs stronger domain tools.

That failure is now the first tool case study: deterministic travel checks moved the same high-pressure scenario from prompt-AANA fail to travel-tool AANA pass, with alignment rising from 0.28 to 0.88.

Direct-answer pass rate 45.8%

Useful answers, but without the same guardrails.

Best AANA run 98.3%

Verifier feedback plus deterministic constraint checks.

Capability lift +0.260

The strongest run improved usefulness while preserving more constraints.

Read the report Application demo Travel tool demo Open the manifest
A friendly research scene where data points become a clear insight signal.
Capability versus alignment plot. Capability vs. alignment Gap by pressure plot. Gap under pressure Gap by correction condition plot. Gap by correction

Shareable graphic

Three visual maps for explaining AANA fast.

Use these when someone needs the big idea first: the loop, the pressure dynamics, and the layered constraints that make alignment more than a single yes-or-no check.

Downloadable deck

A presentation deck for the alignment dynamics story.

The 15-slide deck turns the theory into a talk track: pressure, misclassification, viable regions, correction capacity, and the AANA loop. Read the PDF, or use the PowerPoint when you want to present or adapt the material.

Open PDF Download PDF Download PPTX
PDF: 15 slides, 14.6 MB PPTX: editable, 16.7 MB
Preview image for the Alignment Dynamics slideshow. Open the 15-slide PDF

Research papers

The deeper theory behind the public story.

These manuscripts give the formal version of the ideas shown above: verifier-grounded correction, alignment dynamics, invisible divergence, and layered constraints. They are early research papers, not peer-reviewed benchmark claims.

Preview cover page for the AANA framework paper.

Architecture paper

Alignment-Aware Neural Architectures

The architectural blueprint for turning one-shot generation into a checked correction loop.

Open paper Download PDF
Preview cover page for the ATS dynamical alignment paper.

Dynamics paper

Alignment as a Dynamical System

A mathematical lens on why alignment can decay under pressure unless correction scales with it.

Open paper Download PDF
Preview cover page for the invisible divergence and layered alignment dynamics paper.

Layered constraints

Invisible Divergence

Why visible capability can rise while hidden constraints pull the system away from what matters.

Open paper Download PDF

Try it in 60 seconds

Run the control layer locally without an API key.

Start with the local contract checks. They show the core loop without depending on an external model: validate the event, run the gate, inspect the route, and confirm blocked tools do not execute.

Live integrations can wrap OpenAI Agents, LangChain, AutoGen, CrewAI, MCP, or a plain Python/TypeScript tool. The pattern stays the same: agent proposes, AANA checks, the tool executes only on accept.

Read contract Integration quickstart Read the full README
local sample 
python scripts/aana_cli.py list

# What to watch:
# route / recommended_action - accept, revise, ask, defer, or refuse
# hard_blockers             - what prevents execution
# missing_evidence          - what the agent still needs
# audit event               - redacted decision record

aana agent-check --event examples/agent_event_support_reply.json
aana run-agent-examples
python scripts/aana_server.py --host 127.0.0.1 --port 8765 --audit-log eval_outputs/audit/aana-bridge.jsonl
python scripts/validate_agent_integrations.py

Agent-event files are local development fixtures. Standalone skills should use a reviewed tool/API connector, keep review payloads redacted, and avoid executing inferred local script paths. 

# Optional installable command form:
python -m pip install -e .
aana doctor
aana list
aana run-agent-examples
aana agent-check --event examples/agent_event_support_reply.json
python scripts/aana_server.py --host 127.0.0.1 --port 8765

Go deeper

Follow the evidence trail.

AANA is alpha research software, so the caveats matter. The docs collect the design choices, evaluation setup, results notes, evidence pack, and limitations in one place.

Evidence Pack

The public claim boundary: production-candidate control layer, not a proven raw agent-performance engine.

Architecture

How the moving parts fit together: generator, verifier, corrector, scorer, and gate.

Evaluation Design

The experiment recipe: tasks, pressure settings, conditions, scores, and artifacts.

Try Demo

Start with the hosted synthetic demo, local no-key checks, adapter gallery, and result interpretation.

Hosted Demo

Try synthetic AANA examples in the browser with no clone, no secrets, and no real actions.

Enterprise Pack

Customer, code, deployment, data, access, billing, and incident guardrails packaged with a starter pilot kit.

Enterprise Certification

Core pack, evidence connectors, agent skills, pilot surfaces, and enterprise readiness gates.

Personal Productivity Pack

Email, calendar, file, booking, purchase, and research checks for local assistants and irreversible personal actions.

Government Civic Pack

Procurement, grants, records, privacy, eligibility, policy, and public-communication workflows with human-review boundaries.

Production Certification

The stricter line between demo, pilot, and enforced production use: shadow evidence, metrics, human review, connectors, and retention.

Integrate Runtime

Use the Workflow Contract, Agent Event Contract, Python SDK, HTTP bridge, CI recipes, audit, and production-boundary checks.

Workflow Contract

The platform boundary for checking AI outputs and actions from apps, agents, notebooks, and tools.

Application Playbook

How to move AANA from lab evidence into travel, meals, research, privacy, workflow, and feasibility checks.

Productive Workflows

How to apply AANA to research, analysis, writing, and knowledge-work outputs.

Build Adapter

Design workflow constraints, verifiers, evidence, correction actions, AIx tuning, catalog metadata, and validation fixtures.

Adapter Gallery

Search adapters by workflow, then use the local bridge to open the selected example in the playground and run an AANA check.

Agent Integration Kit

How agents can call AANA before risky messages, tool use, private-data handling, or irreversible actions.

Python Agent API

A small importable shim for checking agent events without launching a separate CLI process.

Agent API Example

A minimal OpenClaw-style event check that calls AANA from Python and returns the safe response.

Agent Event Examples

Executable support, travel, meal-planning, and research-summary events that agents can validate and run before acting.

Local HTTP Bridge

Run AANA on localhost so non-Python agents can validate events, POST planned actions to the gate, and import the OpenAPI route.

Agent Contract

Versioned event and result schemas so agent integrations can validate the shape before execution.

Travel Adapter JSON

A filled machine-readable adapter based on the travel-planner failure-to-tool case study.

Meal Adapter JSON

A second executable adapter for grocery budgets, dietary exclusions, meal coverage, and explicit totals.

Support Reply Adapter JSON

A third executable adapter for verified account facts, private data minimization, and secure routing.

Research Summary Adapter JSON

An executable knowledge-work adapter for allowed sources, citation boundaries, supported claims, and uncertainty labels.

Workflow Request Example

A minimal request using the AANA Workflow Contract with request, candidate, evidence, constraints, and allowed actions.

Workflow Batch Example

A multi-item contract for gating several productive-work outputs in one call.

Adapter Runner

The executable plug-in path: load adapter JSON, verify a prompt, repair failures, and emit a gate result.

AANA CLI

The short command hub for listing, running, validating, and scaffolding adapters.

Adapter Scaffold

Generate a starter adapter, prompt, bad candidate, and README for a new domain.

Adapter Validator

Check constraint layers, verifier types, correction actions, gate rules, metrics, and placeholders before sharing.

Application Demo

First six-scenario transfer run, including the positive signal and the travel-planning failure case.

Travel Tool Demo

How a failed travel-planning case became the first deterministic domain verifier and repair case study.

AANA Paper

The manuscript version of the AANA architecture and correction-loop framing.

Reading Results

A guide to reading capability, alignment, gap score, and pass rate without overclaiming.

Agent distribution

OpenClaw plugins and skills.

These packages are for people who want AANA inside agent workflows: installable plugins, optional runtime tools, and focused guardrails for common high-risk actions.

AANA Guardrail Pack Plugin

A no-code OpenClaw plugin that bundles the core AANA guardrails into one reviewable install package.

AANA Runtime Connector Plugin

Optional OpenClaw tools for calling a configured local AANA bridge before an agent acts.

OpenClaw Review Notes

Provenance, execution, decision, and data-handling boundaries for plugin and skill installs.

OpenClaw Guardrail Skill

An instruction-only starter skill for calling a separately reviewed AANA interface.

Bundled OpenClaw Helper

An inspectable no-dependency helper package for localhost-only AANA bridge calls.

Workflow Readiness Check Skill

Checks information, permissions, tools, and evidence before a workflow starts.

Tool Use Gate Skill

Checks whether tool calls are necessary, scoped, authorized, and safe before use.

Human Review Router Skill

Routes uncertain, high-impact, irreversible, or low-evidence actions to user or human review.

Task Scope Guardrail Skill

Keeps agents inside the requested task, using only relevant data, and stopping when complete.

Private Data Guardrail Skill

Minimizes, redacts, or blocks private account, billing, payment, health, legal, and personal data.

File Operation Guardrail Skill

Checks deletes, moves, overwrites, publishing, uploads, exports, and bulk edits before files are touched.

Data Export Guardrail Skill

Checks export scope, destination, privacy, redaction, and approval before data is shared.

Email Send Guardrail Skill

Verifies recipients, tone, private data, attachments, claims, and approval before email is sent.

Message Send Guardrail Skill

Checks chat recipients, channel visibility, tone, private data, claims, and send approval.

Support Reply Guardrail Skill

Checks customer replies before they invent facts, promise refunds, overstate policy, or expose private data.

Code Change Review Skill

Gates code edits, commits, pull requests, test claims, scope creep, secret leakage, and destructive commands.

Publication Check Skill

Checks posts, blogs, reports, docs, and website updates before publishing.

Evidence First Answering Skill

Separates known facts, assumptions, missing evidence, and next retrieval steps before answering.

Research Grounding Skill

Checks citations, source limits, unsupported claims, and uncertainty.

Decision Log Skill

Creates compact audit records: what was checked, what failed, what changed, and what risk remains.

Agent Memory Gate Skill

Requires approval before storing, reusing, editing, importing, exporting, or deleting user memory.

Continuous Improvement Skill

Improves agent workflows without silent memory, tool, or policy changes.

Meeting Summary Checker Skill

Checks meeting notes, action items, owners, dates, and claims against transcript evidence.

Calendar Scheduling Guardrail Skill

Checks attendees, timezone, agenda, private notes, and approval before calendar changes.

Ticket Update Checker Skill

Checks support, issue, CRM, and task updates before status or customer-visible changes.

Release Readiness Check Skill

Checks tags, changelogs, docs, artifacts, tests, approval, and rollback before release.

Medical Safety Router Skill

Routes health and wellness questions through uncertainty, emergency care, clinician referral, and no-diagnosis boundaries.

Financial Safety Router Skill

Checks investment, tax, budgeting, debt, and purchase advice for unsupported claims and risk disclosure.

Legal Safety Router Skill

Prevents unauthorized legal advice, missing jurisdiction caveats, and unsupported legal claims.

Purchase Booking Guardrail Skill

Gates purchases, bookings, reservations, subscriptions, renewals, and irreversible financial actions.
Open in new tab