AWS Builder Center
Predictability, not eloquence. Database rules for AI agents

Predictability, not eloquence. Database rules for AI agents

How we let the database say no to our agent's invalid writes, and turned each constraint violation into an instruction the agent can act on.

The short version

We made agent-generated configurations deterministic by enforcing their rules in PostgreSQL, which rejects any violations. A tool layer translates each rejection into actionable instructions with valid values, allowing the next call to correct them. Invalid configurations never land in a table, and nothing goes live without human approval.

Before that, our configuration agent produced convincing output, but validation revealed invented field names, incorrect units, and inconsistent results across runs. Adding rules to the prompt didn't help, as it grew with every new installation.

In my tests, four of five Bedrock models saved all six expected rows, with costs ranging from $0.0022 for Nova Micro to $0.2061 for Claude Sonnet 4.6. Nova Micro was the best choice, saving all six rows at the lowest cost of the four models that did.

I deliberately kept the prompt minimal, with no domain instructions, to test whether rejections alone could drive convergence to the same valid rows. A sub-cent model matched Claude Sonnet 4.6, and ten additional Nova Micro runs produced identical rows. With raw PostgreSQL errors instead, all ten runs failed to save any rows. In this setup, write-time constraints let a much cheaper model achieve the same result.

Why we needed an agent to write configuration

Take a system that we install separately for each customer, so every installation has its own data sources and its own manual, with its own field names, units and sampling limits. The services in an installation produce signals such as latencies, error counts and queue depths, and the manual and an OpenAPI schema describe them. We built an agent to diagnose incidents from these signals. In one incident it blamed the wrong cause and the incident kept coming back for weeks, because the signal that would have exposed the right one was never collected.

Collecting the right signals meant configuring every source of every installation. People got the configurations right but took far too long, so we built a second agent to write them. That agent was hard to control. It invented field names, wrote latencies in milliseconds for a source that reports seconds, and gave a different configuration on every run of the same manual.

Database constraints and error translation

Our first fix was the system prompt. We added field names, units and exceptions for each installation, and the prompt grew until the model lost track of parts of it. A rejection also ends up in the model's context, but it carries one fact, for the one request that needs it, at the moment the agent gets it wrong, with values read from the catalog. A prompt also gives no determinism, because it informs the model while the database enforces what gets stored. In this demo the system prompt is three sentences of behaviour, with no field names or units, so the rejections carry the whole schema.

Installation docs feed a parser and a catalog. Agent proposals are checked, then rejected or saved.


The manual lists the requests from operations, and the OpenAPI schema describes the source. A parser, plain code, turns them into three catalog tables. Services and fields come from the OpenAPI schema, and each request carries a service, a signal type and a sampling interval. The agent proposes one row per request through a tool, and named foreign keys check every proposal against the catalog.

CONSTRAINT config_field_exists FOREIGN KEY (installation_id, source_field)
REFERENCES source_fields (installation_id, field_name),
CONSTRAINT config_unit_matches_source FOREIGN KEY (installation_id, source_field, unit)
REFERENCES source_fields (installation_id, field_name, unit),
CONSTRAINT config_field_in_service FOREIGN KEY (installation_id, service_id, source_field)
REFERENCES source_fields (installation_id, service_id, field_name),
CONSTRAINT config_sampling_requested FOREIGN KEY (installation_id, request_id, sample_s)
REFERENCES signal_requests (installation_id, request_id, sample_s),

Each constraint has a name that says which mistake it rejects, and the tool layer reads that name when a write fails.  config_field_exists  rejects an invented field. An existing field with the wrong unit fails  config_unit_matches_source , which is the check I care about most, because a wrong unit gives data that is ingested on schedule and off by a constant factor. In my first runs the requests were prose, and a small model saved a sampling interval nobody had asked for. The database accepted it, so I made the request a row.

The agent's database role can insert into a fixed list of columns and nothing else, so every row it inserts gets the default status  draft . Approval needs a different role held by a person.

GRANT INSERT (run_id, installation_id, request_id, service_id, signal_name, signal_type, source_field, unit, sample_s, model_id)
ON collection_configs TO agent_writer;

A raw PostgreSQL violation tells a developer what broke and gives the model no valid value to try, so the tool layer maps each constraint to one line that names the parameter to change. In   opsmem/errors.py  ,  classify()  reads the constraint name from the database message,  INSTRUCTIONS  holds its line, and  _LOOKUPS  holds the query that fills  {valid} .

INSTRUCTIONS: dict[str, str] = {
# ...
"config_unit_matches_source": "Wrong unit for this source_field. Valid unit: {valid}.",
# ...
"config_sampling_requested": "Wrong sample_seconds for this request. Valid sample_seconds: {valid}.",
# ...
}

def classify(message: str) -> str:
"""Return the violated rule named in a database message, or ``unknown``."""
for m in _NAME.finditer(message):
name = next(g for g in m.groups() if g is not None)
if name in INSTRUCTIONS:
return name
if name.endswith("signal_name_check"):
return "signal_name_check"
# ...

_LOOKUPS = {
# ...
"config_unit_matches_source": (
"SELECT unit FROM source_fields "
"WHERE installation_id = :installation_id AND field_name = :source_field",
("source_field",),
True,
_first_column,
),
# ...
}

The values come from a read-only SELECT on the catalog tables, run as  agent_writer  for the rejected request, and at most ten are shown.

SYSTEM_PROMPT = (
"Configure one signal per request with propose_config. "
"If a call is rejected, use the valid values in the rejection and call the tool again. "
"Stop only when every request is saved."
)

The tool layer counts rejections per request and rule, and after three it stops the run and moves its saved drafts to  needs_review . If the agent stops with requests still open, the code lists them, at most twice, before a person takes over. Three is my choice for this demo, with no data yet on the right number.

Set up and run it yourself

You end up with the schema and its rules in PostgreSQL 16 in Docker, the agent with its tool, and one run against Amazon Nova Micro in  us-east-1 . Nova Micro is the cheapest model that saved all six rows. You need Python 3.12, uv, Docker and Bedrock access to Nova Micro. Prerequisites and expected outputs are in the  README . To run on Aurora, the  template  creates the database and its secrets. Its  RunnerRole  lists the  permissions the scripts and tests need , which are the Data API, the three secrets and Bedrock.

  1. Install the dependencies and start PostgreSQL in Docker, or deploy Aurora with the  template .
uv sync --group dev --group local
eval "$(scripts/local_db.sh up)"
# or, on Aurora: sam deploy --guided --stack-name agent-tool-errors && source scripts/env.sh
  1. Create the schema and load services, fields and requests.
export AWS_REGION=us-east-1 && uv run scripts/apply_schema.py
  1. Run the unit tests, which cost nothing.
uv run --group dev pytest -q
  1. Run the agent once and read the trace.
uv run scripts/run_writer.py --model us.amazon.nova-micro-v1:0
  1. Remove the database when you are done (last section).

The results of my run

I ran five models locally with  scripts/run_experiment.py , and every number below comes from the  run files  it wrote. The four models that finished saved the same six rows.

request_id
service_id
source_field
signal_type
unit
sample_s
status
R1
media
mst_wr_lat
latency
ms
10
draft
R2
encoding
enc_q_wait
latency
s
10
draft
R3
api
api_p95
latency
s
10
draft
R4
api
api_5xx
count
count
10
draft
R5
classes
cls_create_fail
count
count
60
draft
R6
queue
jq_depth
count
count
10
draft

These are the rows I expected, the configuration an operator would write from the demo manual. Foreign keys guarantee each row has its request's service, type and sampling, and a field of that service in its unit. Choosing between two fields of one service is left to the person who reviews.
I then ran Nova Micro ten more times at temperature 0, with the same input. All ten  runs  made the same 19 tool calls, received the same 13 rejections and saved these same six rows.

Model
Saved
Tool calls
Rejections
Tokens in / out
Cost
Claude Sonnet 4.6
6 of 6
35
29
36,403 / 6,459
$0.2061
Claude Haiku 4.5
6 of 6
33
27
44,904 / 6,148
$0.0756
Amazon Nova 2 Lite
6 of 6
20
14
58,905 / 2,300
$0.0258
Amazon Nova Micro
6 of 6
19
13
51,844 / 2,454
$0.0022
Ministral 3 3B
0 of 6
28
25
15,477 / 2,759
$0.0018

The next map splits those rejections by the rule that fired, for each model.

Heat map of rejections by rule for five models, from 1 to 6 per rule.


The rule that fired most was  config_service_matches_request , with 28 rejections. In 26 of them the model had put the installation id in  service_id . Of the 108 rejections in the five runs, 89 came from composite foreign keys, 11 from the trigger on sampling and 8 from the CHECK on the signal name, and the column grants never fired.

In  raw  mode, where the tool returns the PostgreSQL message untouched, Nova Micro saved none of the six rows in ten runs out of ten. Both modes use the same limit of three rejections of one rule for one request. Every raw run reached it on the check of the signal name. In the  instructive  runs no rule rejected the same request twice, so the text of the rejection is what separates 10 of 10 from 0 of 10.

Bar chart of tool calls and model turns for five models, from 19 to 35 calls.


The Claude models needed more attempts. They sent the six requests as six concurrent calls per turn, so they met each rule once per request. The Nova models sent one call at a time and reused what the rejections of R1 returned on the next requests, which took two to four calls each.

Rows saved by tool call. Four models reach 6 of 6, and Ministral 3 3B saves none.


Both ways ended on the same rows, because the same constraints checked every insert.
Ministral 3 3B was told  Valid unit: s  for R3 and sent  ms  twice more, so the escalation rule stopped it with no row saved. The table shows how Nova Micro got the first request right, and the  raw trace  has every call.

Call
What it changed
Rule that fired
What the rejection gave
1
first guess
 collection_configs_signal_name_check 
the name format
2
name  write_latency_media_volume 
 config_field_exists 
the nine valid fields
3
field  mst_wr_lat 
 config_sampling_supported 
10 to 300 seconds
4
sampling 30
 config_service_matches_request 
service  media 
5
service  media 
 config_sampling_requested 
sampling 10
6
sampling 10
saved as draft

  The same six calls as a sequence. Each rejection comes back from the database with the rule that fired and the valid value, and the sixth call is saved as a draft.  


After call 4 the model read this line, copied from the trace.

REJECTED (config_service_matches_request). Not saved. Wrong service_id for this request. Valid service_id: media.

What it cost

Local runs cost only Bedrock tokens, shown in the results table at list prices for  us-east-1 . Cross-region profiles can cost more. In the project we ran the same schema on Aurora Serverless v2, where  auto-pause  stops compute billing while the instance is paused ( Aurora pricing ,  Bedrock pricing ).

Decisions and trade-offs

Where the rule lives. We also built a validation hook in front of the tool and later removed it, because keeping its copy of the schema's rules in sync took too much maintenance.

A person alone, or the agent alone. People were accurate but could not keep up, and the agent alone was fast and unpredictable, so the agent proposes, a person approves and the database checks everything in between.

Specs as the contract. I built the repository from scratch with Kiro, starting from  specs  of what I wanted to demonstrate. The requirements fix the constraint names and the messages the model reads, so the behaviour in this article is defined before the code. A prototype run also showed that parallel calls could still reach the database after the run had been stopped, so I added a requirement for a lock around each call, with its own test.

Aurora PostgreSQL instead of DynamoDB or Aurora DSQL. The rules need foreign keys into a catalog, check constraints, column grants per role and triggers. DynamoDB condition expressions cannot check a row in another table, and Aurora DSQL, per its  supported SQL , has no triggers.

What I learned

The constraints cannot read meaning, such as a signal name that says one thing while the row collects another. That check stays with the person who approves, who may start to sign without reading.

Since all four models that finished saved identical rows, I start from the cheapest one that converges.

The most fragile part of the design is the translation layer. The tool reads constraint names out of the error text, and on Aurora the Data API does not document the format of its messages. A change in that format would turn every rejection into a generic one, and the raw database message in the trace would show me what to change.

One command removes the local database, or the Aurora stack.

scripts/local_db.sh down
# or, on Aurora: sam delete --stack-name agent-tool-errors --no-prompts

I will present the wider version at re:Invent 2026, in the community session Move Agent Rules Out of the Prompt on November 30 at the Wynn. There the database is one layer, next to Cedar and Dogwood policies that decide which tools an agent may call. The code, schema, manual and tests are in the  repository .
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article