Meridian: stateful agentic AI with Aurora, MCP and AgentCore
Meridian is a sample travel concierge that stores its state in Amazon Aurora
PostgreSQL. You learn how an agent application grows in five phases: from SQL
queries to Model Context Protocol (MCP) tools, hybrid retrieval, a governed
agent on Amazon Bedrock AgentCore, and a Strands Graph workflow in its own
AgentCore Runtime that resumes after its session stops. Every screen shows the SQL, tool calls, authorization
decisions and stored records behind each answer.
Stateful agentic AI workflows on Amazon Aurora PostgreSQL with MCP, Amazon Bedrock AgentCore, Strands Agents, pgvector and row-level security
2026-10-27
星數
4
工具
—
可用率
—
The data is sample travel packages and one fictional traveler, Jordan Morgan.
Holds and confirmations change rows in Meridian's own database only. There is
no supplier, airline or payment integration.
What it demonstrates
Each phase adds one capability and keeps the earlier ones.
A Strands Graph in its own AgentCore Runtime, Aurora snapshots, worker leases and idempotent holds
Each phase folder has a short guide with a sample prompt and the evidence to
inspect. The sample keeps three kinds of state in Aurora or AgentCore:
Traveler context: profile, preferences and conversation history in Aurora. The agent session is in AgentCore Memory.
Workflow progress: Strands Graph snapshots in the Aurora table workflow_snapshots, appended after every node.
Business results: holds and bookings in Aurora. One idempotent SQL function handles each action, so a retried request returns the first result.
Architecture
Browser (React, Vite)
└─ FastAPI backend ──────────────── Aurora PostgreSQL (RDS Data API)
│ Phases 1-3: SQL, MCP servers, Bedrock embeddings and rerank
│ Phase 5: invokes MeridianWorkflow, relays its result,
│ holds the stop-session control
│
├─ AgentCore Runtime (MeridianConcierge, Strands agent)
│ ├─ AgentCore Memory
│ └─ AgentCore Gateway (MCP; Cognito access token in jwt mode)
│ ├─ request interceptor: pins travelerId to the token's claim
│ ├─ Cedar policy engine (ENFORCE)
│ ├─ SemanticTripSearchLambda ─── Aurora (pgvector search)
│ └─ MeridianHolds Lambda ─────── Aurora (hold and confirm functions)
│
└─ AgentCore Runtime (MeridianWorkflow, Strands Graph)
├─ runs as the Aurora login meridian_workflow
├─ saves workflow_snapshots after every node
└─ places its hold through the same Gateway and Cedar policies
Every hold and confirmation goes through the Gateway. Cedar checks each tool
call before a Lambda runs: the traveler must confirm, a hold lasts at most 12
hours for at most 6 travelers, and the total must fit the saved budget. Aurora
RLS limits each query to one traveler. Read
STATEFUL_ARCHITECTURE.md for the
state design and meridian/README.md for the API, schema
and configuration.
Models on Amazon Bedrock: Claude Sonnet 5.5 for the agents, through its global
cross-Region inference profile, Cohere Embed v4 for embeddings and Cohere
Rerank 3.5 for reranking. BEDROCK_MODEL_ID changes the backend's Strands
agents and reply polish; the managed Concierge runtime's model is set in
meridian/meridian_agentcore/agentcore/agentcore.template.json.
Prerequisites
Python 3.13 and Node.js 22.12 or later
An AWS account with credentials (aws login, aws sso login or aws configure)
Amazon Bedrock access to Claude Sonnet 5.5, Cohere Embed v4 and Cohere Rerank 3.5
An Aurora PostgreSQL cluster with the RDS Data API enabled and a Secrets Manager secret for the database user. OPERATIONS.md shows how to create one with the included CDK app.
For Phase 4, the Concierge chat and all holds: AgentCore resources, deployed with the AgentCore CLI (npm install -g @aws/agentcore). See the deployment runbook.
Quick start
These steps run the backend and frontend on your machine against Aurora in your
account. Resources in your account incur charges while they exist.
1. Configure and prepare the database
cd meridian
python3.13 -m venv venv
source venv/bin/activate
python -m pip install --require-hashes -r requirements.txt
cp .env.example .env
In .env, set AWS_DEFAULT_REGION, AURORA_CLUSTER_ARN, AURORA_SECRET_ARN
and AURORA_DATABASE. For a new, empty database, run:
Phase 5 runs in the MeridianWorkflow AgentCore Runtime, not in this process.
The backend invokes it through AGENTCORE_WORKFLOW_RUNTIME_ARN, which
python scripts/sync_agentcore_env.py --write sets after you deploy. The
Runtime connects to Aurora as the meridian_workflow login created by
scripts/provision_workflow_login.py. See the
deployment runbook. Check the
backend:
curl http://127.0.0.1:8013/api/health
The response should include "checkpoint_backend": "Aurora workflow_snapshots",
"checkpoint_durable": true and "workflow_runtime_configured": true. Local requests need no API token. Read the
governance boundary before you expose
the API to a network.
3. Start the frontend
In a second terminal, from the repository root:
cd meridian/frontend
npm ci
export VITE_API_ORIGIN=http://127.0.0.1:8013
npm run dev -- --host 127.0.0.1 --port 5176 --strictPort
Open http://127.0.0.1:5176/showcase. The header shows Meridian live when
/api/health reports healthy and the catalog and traveler profile reads work.
Without AgentCore resources, the catalog, Phases 1 to 3, System evidence and
Solution briefing work. The Concierge chat, Phases 4 and 5 and all holds report
that AgentCore is not configured.
Try the reference app
The showcase has five views along the top of the page.
Concierge: browse trips for Jordan and ask, for example,
Find Tokyo trips that fit my saved preferences. Open a trip, then use
Request 12-hour hold and Confirm this trip for Jordan.
Capability ladder: pick a phase and run its suggested prompts. Open the
activity trace under a reply to see the SQL, tool calls, retrieval scores and
policy decisions. Turn on Use traveler context for Phase 4.
Recovery desk: run the Phase 5 prompt
My JFK-to-Tokyo flight was canceled. Rework the trip, then check duration availability for the best three options.
The workflow pauses after a saved step, with a snapshot in Aurora. Select
Continue at recovery desk, choose Stop runtime session on the
continuity rail, then select Resume and request hold. The next resume
starts a new microVM on the same session and continues on the same thread.
System evidence: read what Aurora recorded: snapshots, leases,
session stops, authorization decisions and the hold.
Solution briefing: the architecture, phases, Gateway tools and Cedar
policies. It calls no service.
The full prompt list for each phase is in meridian/README.md.
OPERATIONS.md has
scripts that stop a worker or discard a response on purpose.
The AgentCore configuration is stored as templates with placeholders.
python scripts/render_agentcore_config.py fills in your account, Region and
resource IDs. See the AgentCore project README.
Each guide ends with teardown steps.
Tests
# Backend (from meridian/, virtual environment active)
PYTHON_DOTENV_DISABLED=1 python -m pytest -m "not database"
# Frontend (from meridian/frontend/)
npm ci && npm run lint && npm run typecheck && npm run test:run
On every pull request CI runs ruff, the backend unit tests and pip-audit; the
frontend lint, typecheck, unit tests, build, npm audit and Playwright
accessibility tests; a backend container build with a network-less MCP import
check; the AgentCore CDK build, tests, format check and audit; and the web
infrastructure tests and audit. See application-ci.yml.
The unit tests block network access and ignore meridian/.env. Tests marked
database write snapshots, journeys and holds to a live Aurora database. Run
python -m pytest -m database only against a disposable database. See the
dependency notes for the open audit finding.
Callers sign in with Amazon Cognito. In jwt mode the backend, both Runtimes
and the Gateway each verify the access token and take the traveler from its
traveler_id claim, never from a request body or a tool argument. Aurora
row-level security is the last check. MERIDIAN_AGENTCORE_AUTH selects the
mode: jwt carries the token through every hop, and iam (the default when
the variable is unset) signs the AgentCore hops with AWS credentials. Local
development keeps an open loopback mode and a shared API token path; a jwt
release refuses both. Review networking, monitoring, availability and data
protection before any production use. To report a security issue, see
CONTRIBUTING.
License
This library is licensed under the MIT-0 License. See the LICENSE file.
S
Sample Stateful Agentic Ai Workflows Aurora MCP Agentcore
aws-samples·4 顆星·
Stateful agentic AI workflows on Amazon Aurora PostgreSQL with MCP, Amazon Bedrock AgentCore, Strands Agents, pgvector and row-level security
Sample Stateful Agentic Ai Workflows Aurora MCP Agentcore 上次檢查是什麼時候?
上次檢查時間:2026-10-27。 Stateful agentic AI workflows on Amazon Aurora PostgreSQL with MCP, Amazon Bedrock AgentCore, Strands Agents, pgvector and row-level security