DEV Community: AWS

Build a Full-Stack Music Station with OpenRouter, Amazon Bedrock, and Nuxt

Erik Hanchett — Wed, 26 Aug 2026 00:48:03 +0000

Have you ever been coding and then gotten into that flow state? You know where hours pass by , and it feels to you it's only ben a few minutes? Me too. One thing that really helps me get into that state is music. So I create my own music Lo-Fi server called compile and chill.

As a part of this project, I created three radio stations. Each station can generate a 16:9 scene with Amazon Bedrock, compose an instrumental loop with ElevenLabs, and turn an illustration into a six-second video through OpenRouter. Generated files live in private Amazon S3 storage and return to the browser through the Nuxt server.

I also added a Stream Deck API interface!

This tutorial shows how to build this radio station from start to finish.

The complete source code is available in the Compile & Chill repository.

Watch the full video on YouTube.

Prerequisites

You need the following tools for the complete build:

Node.js 22.19 or newer. The locked Nuxt 4.5.2 release requires Node 22.19+, 24.11+, or 26+.
npm 10 or newer.
An AWS account and a configured AWS Command Line Interface (AWS CLI) profile.
The AWS Serverless Application Model (AWS SAM) CLI for the private storage stack.
Access to Stability AI Stable Image Ultra through Amazon Bedrock in us-west-2.
An ElevenLabs API key for music generation.
An OpenRouter API key for animated scenes.

The provider credentials are optional. Without them, the UI, bundled scene, station switching, player, and Focus Block timer still work.

The identity running the app needs bedrock:InvokeModel plus bucket-scoped permissions for s3:GetObject, s3:PutObject, s3:DeleteObject, s3:DeleteObjectVersion, and s3:ListBucketVersions. Use a role or profile scoped to the station bucket rather than an administrator identity.

For this project I included infrastructure as code with SAM to help setup the AWS parts. It's also included in the repo.

Steps

1. Run the station without credentials

Pull down the repo and get started!

git clone https://github.com/ErikCH/compile-and-chill.git
cd compile-and-chill
npm ci
cp .env.example .env
npm run dev

Open http://127.0.0.1:8231. You should see the station UI with the bundled placeholder scene.

The environment file separates each feature:

ELEVENLABS_API_KEY=
BEDROCK_IMAGE_REGION=us-west-2
BEDROCK_IMAGE_MODEL_ID=stability.stable-image-ultra-v1:1
AWS_PROFILE=default
STATION_S3_BUCKET=
STATION_S3_REGION=us-west-2
OPENROUTER_API_KEY=
STATION_BIND_HOST=127.0.0.1
NUXT_CONTROL_TOKEN=

Do not add NUXT_PUBLIC_ to these names. Nuxt exposes public runtime configuration to browser code.

Keep STATION_BIND_HOST on loopback unless you need remote control. For Stream Deck access from another machine, bind to a private VPN interface address, never 0.0.0.0 or a public IP, and set a long random NUXT_CONTROL_TOKEN. The server refuses a non-loopback binding without that token.

2. Put provider calls behind Nuxt server routes

The browser should call your application. Compile & Chill keeps provider credentials in Nuxt runtimeConfig and places provider code under server/api/ and server/utils/.

The relevant section of nuxt.config.ts looks like this:

export default defineNuxtConfig({
  runtimeConfig: {
    elevenLabsApiKey: process.env.ELEVENLABS_API_KEY || '',
    imageGenerationRegion: process.env.BEDROCK_IMAGE_REGION || 'us-west-2',
    imageGenerationModel:
      process.env.BEDROCK_IMAGE_MODEL_ID || 'stability.stable-image-ultra-v1:1',
    stationStorageBucket: process.env.STATION_S3_BUCKET || '',
    stationStorageRegion: process.env.STATION_S3_REGION || 'us-west-2',
    openRouterApiKey: process.env.OPENROUTER_API_KEY || '',
  },
})

This boundary gives you one place to validate requests, clamp paid parameters, redact signed URLs, and translate provider errors into useful HTTP responses.

You can inspect the complete routes in server/api.

3. Generate a scene with Amazon Bedrock

Authenticate with your AWS profile first. This example uses AWS IAM Identity Center:

aws sso login --profile your-profile

Add the profile and model settings to .env:

AWS_PROFILE=your-profile
BEDROCK_IMAGE_REGION=us-west-2
BEDROCK_IMAGE_MODEL_ID=stability.stable-image-ultra-v1:1

The image route validates the station mode, visual style, developer presentation, and optional seed. It then calls generateStationScene() in server/utils/station-generation.ts.

The provider payload is small:

const payload = {
  prompt: buildScenePrompt(mode, direction, {
    visualStyle,
    developer,
    diversitySeed: seed,
  }),
  // Shortened here. The source contains the complete negative prompt.
  negative_prompt: [
    'logos, readable text, watermark, rear view, motion blur, extra fingers',
    visualStyle === 'illustrated'
      ? 'photograph, live action, photorealistic skin, 3D render'
      : 'cartoon, anime, cel shading, flat illustration',
  ].join(', '),
  mode: 'text-to-image',
  aspect_ratio: '16:9',
  output_format: 'png',
  seed,
}

const response = await client.send(
  new InvokeModelCommand({
    modelId: config.imageGenerationModel,
    contentType: 'application/json',
    accept: 'application/json',
    body: JSON.stringify(payload),
  }),
)

The server normalizes the seed before constructing the payload. This matters because Number(undefined) becomes NaN, and JSON serializes NaN as null. Stable Image Ultra expects an integer.

The prompt also ties visual style to output type. Static scenes use a realistic style. Animated scenes use a clearly illustrated 2D style so the source is visibly non-photorealistic. I added that distinction after a provider's person-likeness classifier refused one of the illustrated anchors.

Checkpoint: restart the app, open Visual settings, choose Realistic static, and generate one scene. If the model is unavailable in the configured region, the route returns the provider error and model ID instead of silently switching models.

4. Add looping music with ElevenLabs

The UI sends a 60-second duration, and the server should reject or normalize nonnumeric input before applying its 10-to-60-second bounds. This hardened version avoids sending null to the provider if another client calls the route with an invalid value:

const requestedDuration = Number(input.durationSeconds ?? 60)
const durationSeconds = Number.isFinite(requestedDuration)
  ? Math.min(60, Math.max(10, requestedDuration))
  : 60

const response = await fetch(
  'https://api.elevenlabs.io/v1/music?output_format=mp3_44100_128',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'xi-api-key': config.elevenLabsApiKey,
    },
    body: JSON.stringify({
      prompt: buildMusicPrompt(input.mode, input.direction),
      music_length_ms: durationSeconds * 1000,
      model_id: 'music_v2',
      generation_mode: 'loop',
      force_instrumental: true,
      sign_with_c2pa: true,
    }),
  },
)

generation_mode: 'loop' is one part of making the repeat sound natural. The prompt also asks for no intro pickup, ending cadence, or fade-out. A track written like a normal song sounds broken when it jumps from the ending back to the first beat.

Compile & Chill keeps one generated track per station mode. Switching from Deep Work to Rainy Debug and back reuses the existing track instead of making another paid request.

Checkpoint: add ELEVENLABS_API_KEY to .env, restart the server, and generate one 60-second track. Switch modes and confirm that returning to the original mode reuses its audio.

5. Deploy the private media library

The repository includes an AWS SAM template managed by AWS CloudFormation. Validate and deploy it:

sam validate \
  --template-file infra/compile-and-chill-private-station.yaml \
  --region us-west-2

sam deploy \
  --region us-west-2 \
  --stack-name compile-and-chill-private-station \
  --template-file infra/compile-and-chill-private-station.yaml \
  --no-confirm-changeset \
  --no-fail-on-empty-changeset

Read the media bucket output:

aws cloudformation describe-stacks \
  --region us-west-2 \
  --stack-name compile-and-chill-private-station \
  --query "Stacks[0].Outputs[?OutputKey=='StationMediaBucketName'].OutputValue" \
  --output text

Copy that value into .env:

STATION_S3_BUCKET=YOUR_STACK_OUTPUT
STATION_S3_REGION=us-west-2

The stack creates two versioned buckets. One stores generated station media. The other stores AWS CloudTrail data-event logs encrypted with AWS Key Management Service (AWS KMS). An Amazon CloudWatch alarm watches delete requests against the media bucket.

The application assigns each browser profile a random station ID in an HttpOnly, SameSite cookie. Objects use this layout:

stations/<station-id>/manifest.json
stations/<station-id>/<mode>/scene.png
stations/<station-id>/<mode>/scene.mp4
stations/<station-id>/<mode>/music.mp3

The browser receives same-origin URLs such as /api/library/assets/deepWork/scene. The route reads the matching S3 object into server memory and returns it. The current implementation is a proxy, not a streaming pass-through, so account for memory when increasing the 50 MiB video limit.

The storage implementation is in server/utils/station-library.ts.

Checkpoint: regenerate a scene or track, reload the page in the same browser profile, and confirm that the media returns. Open a private browsing window and confirm that it starts with a separate station.

6. Turn one illustration into a seamless video loop

Animated mode generates a fresh illustrated anchor with Amazon Bedrock, saves it to S3, and creates a 300-second presigned read URL. OpenRouter needs that temporary URL because its video provider must download the input image.

The trick is to submit the same anchor as both frame constraints:

body: JSON.stringify({
  model: modelId,
  duration: 6,
  resolution: '720p',
  aspect_ratio: '16:9',
  generate_audio: false,
  prompt: [
    'Animate this 2D cartoon illustration of a fictional character.',
    'Use a locked-off camera and keep the illustrated composition unchanged.',
    'The provided illustration is both the first and last frame.',
    'Allow only tiny two-hand typing motion and one gentle blink.',
    'No zoom, pan, cut, identity change, new objects, or geometry changes.',
    'Create a silent seamless six-second ambient loop.',
  ].join(' '),
  frame_images: [
    {
      type: 'image_url',
      image_url: { url: sourceUrl },
      frame_type: 'first_frame',
    },
    {
      type: 'image_url',
      image_url: { url: sourceUrl },
      frame_type: 'last_frame',
    },
  ],
})

The model can move away from the anchor, but the matching frame constraints request a return to the same composition at the end. The prompt limits movement to a small typing motion and one blink, with no camera movement, reframing, cuts, new objects, or identity changes.

The app discovers compatible video models at runtime. A candidate must support six seconds, 720p, first_frame, and last_frame. It prefers Seedance 2.0 Fast, then checks a short fallback list.

The fallback policy is intentionally narrow:

HTTP 402 stops because credits are unavailable.
HTTP 429 stops because the account is rate limited.
An input-image moderation refusal may try the next compatible model because no video job was created.
Other failures stop rather than risk submitting and billing a duplicate job.

See the complete policy in server/utils/openrouter-video.ts.

Video generation takes minutes rather than seconds, and provider timing and prices change. Treat the request as a paid background job even if the first version runs inside one long HTTP request.

7. Report real progress during a long request

A spinner cannot tell the user whether a three-minute provider job is moving or stuck. Compile & Chill keeps a process-local job registry with six phases:

creating anchor
preparing source
submitting video
rendering loop
downloading loop
saving privately

The browser creates a job ID, starts the generation request, and polls the Nuxt status endpoint every 750 milliseconds. Nuxt polls the provider every 15 seconds, up to 48 times. These are separate loops.

The registry also rejects a second active job for the same station with HTTP 409. That protects the user from duplicate clicks, but it is not a distributed queue. A process restart loses status, and multiple Nuxt instances would each have their own registry. For a multi-instance deployment, move job state and concurrency control to a shared data store and worker queue.

8. Validate the build

Run the same checks used for the source project:

npm test
npm run typecheck
npm run build

The current repository has 26 passing tests plus a clean type check and production build.

Then test one provider at a time:

Start with no credentials and verify the UI.
Add Amazon Bedrock and generate one static scene.
Add ElevenLabs and generate one track.
Deploy the storage stack and verify reload persistence.
Add OpenRouter last, acknowledge the paid operation, and generate one animated loop.

This order keeps failures small. If the video path fails, you already know that image generation, storage, and browser identity work independently.

Cleanup

The cleanup steps remove data permanently. Download anything you want to keep before continuing. The buckets and KMS key use retention policies, so they can remain after stack deletion and may continue to incur charges.

First, use Delete saved station inside each browser profile whose generated media should be removed. This purges object versions and delete markers under that profile's station prefix.

Before deleting the stack, record the retained resource names:

MEDIA_BUCKET=$(aws cloudformation describe-stacks \
  --region us-west-2 \
  --stack-name compile-and-chill-private-station \
  --query "Stacks[0].Outputs[?OutputKey=='StationMediaBucketName'].OutputValue" \
  --output text)

AUDIT_BUCKET=$(aws cloudformation describe-stacks \
  --region us-west-2 \
  --stack-name compile-and-chill-private-station \
  --query "Stacks[0].Outputs[?OutputKey=='CloudTrailLogBucketName'].OutputValue" \
  --output text)

KMS_KEY_ID=$(aws kms describe-key \
  --region us-west-2 \
  --key-id alias/compile-and-chill-cloudtrail \
  --query KeyMetadata.KeyId \
  --output text)

Delete the non-retained stack resources:

sam delete \
  --stack-name compile-and-chill-private-station \
  --region us-west-2

The media bucket, audit bucket, and KMS key are retained by design. Empty all versions and delete markers from both versioned buckets in the S3 console, then delete the buckets:

aws s3api delete-bucket --bucket "$MEDIA_BUCKET" --region us-west-2
aws s3api delete-bucket --bucket "$AUDIT_BUCKET" --region us-west-2

Schedule the retained KMS key for deletion after confirming that you no longer need the encrypted audit logs:

aws kms schedule-key-deletion \
  --region us-west-2 \
  --key-id "$KMS_KEY_ID" \
  --pending-window-in-days 7

KMS key deletion has a waiting period. After deletion, data encrypted only by that key cannot be recovered.

For local cleanup:

rm -rf node_modules .nuxt .output
rm .env

Finale

This has been a very fun project. Let me know if you try it out!

You can explore every route, prompt, infrastructure resource, and test in the Compile & Chill source code. For another Nuxt project that keeps AI actions behind explicit user approval, read How to Build an AI Agent That Asks Permission First. Leave a comment on what you think! Thank!

Observability for AI Agents with OpenTelemetry

Elizabeth Fuentes L — Mon, 24 Aug 2026 23:32:49 +0000

AI agent observability means capturing your agent's reasoning cycles, tool calls, and token usage as metrics, traces, and logs. In this guide I build it in three layers with OpenTelemetry (OTEL), then take the same agent to production on Amazon Bedrock AgentCore.

Your AI agent is in production. A user asks it a question, and it takes thirty seconds, calls five tools, and gives an answer you can't explain. What did it actually do? Which tools did it call? How many times did it "think" before answering? If you can't answer that, you're running agents blind. Traditional monitoring won't help you here: CPU, RAM, and uptime watch the machine, not the reasoning.

In this post I make a travel-booking agent's normal behavior visible. No injected failures, no chaos experiments. A real agent doing its job, seen through four increasingly capable lenses:

Agent metrics: what the run cost, with zero extra configuration
OpenTelemetry traces: the path the agent took, step by step
Custom trace attributes: your business context, on the same trace
Production: the same visibility in Amazon CloudWatch via Amazon Bedrock AgentCore

Everything comes from a runnable sample repository: observability-for-agents-sample-for-aws. Each demo is keyed to a specific section of the Strands Agents observability documentation.

A note on the stack. The demos use Strands Agents, an open-source SDK that emits OpenTelemetry natively. Metrics, hierarchical traces, and span attributes are general agent-observability concepts. The same patterns carry over to other agent frameworks, and Strands is model-agnostic: works with any LLM provider (Amazon Bedrock, Anthropic, local models via Ollama, or others).

What agent are we observing?

All four demos instrument the same travel agent: it searches real sandbox flight fares (Duffel API), checks real weather (Open-Meteo), and books flights into a local SQLite ledger. The only thing that changes, demo to demo, is how much of the agent's internal behavior becomes visible, and where that visibility lives:

Layer 1 / What metrics do you get with zero configuration in Strands?

Every Strands agent run already carries its own metrics: reasoning cycle count, token usage, and per-tool call counts and timings, exposed through result.metrics.get_summary(). No extra install, no exporter, no setup. Every AI agent run has a shape, and that shape is captured before you configure anything.

Compare two lenses on the same run. First, traditional logging:

DEBUG | strands.tools.executors._executor | tool_use=<...name': 'search_flights'...> | streaming
DEBUG | strands.tools.executors._executor | tool_use=<...name': 'get_weather'...> | streaming
DEBUG | strands.tools.executors._executor | tool_use=<...name': 'book_flight'...> | streaming
John Doe's flight from JFK to MIA has been successfully booked ... booking reference BK-JSFPJ5 ...

Useful for "did this run". Useless for "how much did it cost". Now the built-in metrics, one method call:

result = agent("Book a one-way flight from JFK to MIA...")
print(result.metrics.get_summary())

{
  "total_cycles": 3,
  "total_duration_s": 5.13,
  "accumulated_usage": {"inputTokens": 2520, "outputTokens": 209, "totalTokens": 2729},
  "tool_usage": {
    "search_flights": {"call_count": 1, "success_count": 1, "average_time_s": 0.721},
    "get_weather":     {"call_count": 1, "success_count": 1, "average_time_s": 1.434},
    "book_flight":     {"call_count": 1, "success_count": 1, "average_time_s": 0.006}
  }
}

This is real output from an agent run, and every field answers a question a log line can't:

total_cycles: 3. An agent is not a single function call, it's a loop: the model calls a tool, thinks again with the result, calls another. Three cycles here. If this number is ever ten for a basic question, something's wrong, and now you can see it.
accumulated_usage. 2,729 tokens for the whole booking. Notice input is roughly ten times output; that's typical for agents, because every tool result gets fed back into the model. This is the number that tells you how heavy each request really is.
tool_usage. Three tools, three completely different performance profiles: search_flights at 0.7 s (a real API call), get_weather at 1.4 s (another API), book_flight at 6 milliseconds (a local write). Without this breakdown, "the agent is slow" is a mystery. With it, it's a diagnosis.

One more habit worth building from day one: the demo also queries the booking database directly, so you can cross-check what the agent said ("booked!") against what actually persisted. In this run, the agent's claim and the ground truth agreed.

Honest caveat: in Strands 1.47.0, accumulated_metrics.latencyMs reads 0 for some LLM providers. It ships as a TODO in the provider streaming code (I verified this by reading the installed SDK source). Token counts and per-tool timings are accurate everywhere; treat the top-level latencyMs as not-yet-implemented.

Layer 2 - How do you trace an AI agent with OpenTelemetry?

Metrics are a flat snapshot, traces are the path. A trace records the full hierarchy of one request: which reasoning cycle called which model invocation, which invocation triggered which tool, in what order, with timestamps. In Strands, turning on OpenTelemetry tracing is two lines:

from strands.telemetry import StrandsTelemetry

strands_telemetry = StrandsTelemetry()
strands_telemetry.setup_console_exporter()   # print the span tree to stdout
# strands_telemetry.setup_otlp_exporter()    # or send it to a collector (Jaeger, CloudWatch, ...)

StrandsTelemetry wires up the OpenTelemetry SDK and registers it as the global tracer provider. Every Agent(...) call after this is automatically instrumented; there is no manual span-wrapping of your own agent loop. Run the same travel query, and the console prints the documented span hierarchy:

invoke_agent Strands Agents      # the whole run (top-level span)
  execute_event_loop_cycle       # one reasoning cycle
    chat                         # the model invocation for that cycle
    execute_tool search_flights  # one span per tool call
    execute_tool get_weather
    execute_tool book_flight

Each span carries attributes. The invoke_agent span holds the totals (gen_ai.usage.total_tokens: 2725, gen_ai.request.model), and each execute_tool span holds that one call's gen_ai.tool.name, gen_ai.tool.call.id, tool.status, and the formatted tool result. That's enough to answer "did book_flight fail, and what did it return?" from the trace alone, without re-running anything.

And because this is standard OpenTelemetry, the console exporter is interchangeable with any OTEL backend. Want a visual UI locally? One Docker command starts Jaeger, one environment variable points the exporter at it, and the agent code doesn't change.

Layer 3 — How do you add business context to agent traces?

Out of the box, spans carry technical attributes: tool name, token counts, status. None of those answer "was this a high-value booking?". That context is yours to add, and the Strands traces guide documents two mechanisms. The demo uses both.

Static context. Agent-level trace_attributes attach metadata (session ID, user ID, tags) to every span the agent produces:

agent = Agent(
    tools=[search_flights, get_weather, book_flight],
    trace_attributes={"session.id": "demo-03-custom-trace-attributes"},
)

Dynamic context. A hook tags the active span at the exact moment a business rule fires. An AfterToolCallEvent callback runs right after each tool call finishes; at that moment, the currently open span is that tool's execute_tool span, so trace.get_current_span() reaches it directly:

from opentelemetry import trace
from strands.hooks import AfterToolCallEvent, HookProvider, HookRegistry

VIP_THRESHOLD = 50.0  # low on purpose, so sandbox fares cross it

class TagVipBookings(HookProvider):
    def __init__(self, threshold: float):
        self.threshold = threshold

    def register_hooks(self, registry: HookRegistry, **kwargs) -> None:
        registry.add_callback(AfterToolCallEvent, self._tag_if_vip)

    def _tag_if_vip(self, event: AfterToolCallEvent) -> None:
        if event.tool_use.get("name") != "book_flight":
            return
        amount = float(event.tool_use.get("input", {}).get("amount", 0))
        span = trace.get_current_span()
        span.set_attribute("business.booking_amount_usd", amount)
        span.set_attribute("business.vip_booking", amount >= self.threshold)

Run the agent, find the execute_tool book_flight span, and the custom attributes sit right alongside the SDK's own:

{
  "name": "execute_tool book_flight",
  "attributes": {
    "gen_ai.tool.name": "book_flight",
    "gen_ai.tool.status": "success",
    "business.booking_amount_usd": 88.73,
    "business.vip_booking": true
  }
}

The detail that matters: this lives on the trace, not in the conversation. The model never sees it. Trace attributes are OpenTelemetry span metadata, entirely separate from the message list, so they add exactly zero tokens to the agent's context. But six months from now, "show me every VIP booking this quarter" is a search on your traces.

Production — where does agent observability live when you deploy?

Everything so far lived in your terminal. That's fine while you're developing, but your agent isn't going to run in your terminal, and you won't be there watching console output. The payoff of building on an open standard: everything we made (metrics, traces, attributes) is OpenTelemetry data, and OTEL data is portable. Swap the exporter, and the agent code doesn't change.

Demo 04 deploys the same travel agent to Amazon Bedrock AgentCore Runtime. The production architecture:

The agent runs on AgentCore Runtime (the code change is one decorator: @app.entrypoint).
The three tools become AWS Lambda functions served through an AgentCore Gateway (a Model Context Protocol endpoint with IAM auth).
book_flight writes to Amazon DynamoDB instead of SQLite. Same tool, same booking, real storage.
One added dependency, aws-opentelemetry-distro (the AWS Distro for OpenTelemetry), ships the OTEL data to CloudWatch. The Runtime runs your agent under its auto-instrumentation automatically.
One-time account setup: turn on CloudWatch Transaction Search. Without it, traces don't appear in the console (official guide).

After invoking the deployed agent, open CloudWatch GenAI Observability and you get three views:

Agents View: every AgentCore agent in your account, with invocations, latency, and error rates.
Sessions View: every conversation. Remember the session.id from Layer 3? This is where it pays off: it's how you go from "something went wrong" to "here's the exact conversation".
Traces View: the same span tree you learned to read in your terminal (invoke_agent → cycles → chat + execute_tool), now rendered as a visual timeline, with every attribute searchable, including business.vip_booking.

The repo ships the deployment two ways: an AWS CDK stack (cdk deploy, and cdk destroy tears down everything, DynamoDB table included) and a step-by-step boto3 notebook if you want to see every API call.

Frequently asked questions

What's the difference between logs, metrics, and traces for an AI agent?
Logs are timestamped text records of what happened ("tool X was called"). Metrics are measurements of those events (how many times, how long, how many tokens). Traces are the hierarchical timeline connecting them. A log tells you that something happened, a metric tells you how much it cost, a trace shows you the path.

Do I need OpenTelemetry for basic agent metrics?
No. In Strands, result.metrics.get_summary() is part of the base SDK: no [otel] extra, no exporter, no collector. OpenTelemetry comes in when you want traces (Layer 2 onward).

Do I need a collector to see traces?
No. setup_console_exporter() prints the full span tree to your terminal. Use setup_otlp_exporter() when you want a real backend: Jaeger locally, or CloudWatch in production.

Do custom trace attributes cost extra tokens?
No. They're OpenTelemetry span metadata, entirely separate from the message list the model sees. The model never reads them.

Does this only work with Strands Agents or AWS?
No. An agent loop, hooks, metrics, and OpenTelemetry tracing are general agent-observability concepts. The demos use Strands because these primitives are built in, and Strands is model-agnostic: works with any LLM provider with no change to the agent code. The same patterns carry over to other agent frameworks.

How does Strands' built-in observability compare to manual instrumentation?
Strands emits OpenTelemetry spans natively with no manual wrapping. In frameworks without native OTEL support, you'd instrument each tool call and reasoning cycle yourself using the OpenTelemetry SDK directly. The data structure is identical — only the setup differs.

Wrap-up: three layers, one standard

Agent observability, as built here, is three layers:

Metrics tell you what your agent did and how efficiently: cycles, tokens, tool timings. Free with the SDK.
Traces show you the path it took: every decision, in order, with full context. Two lines to turn on.
Trace attributes add your context to that path, so you can search it by what matters to your business. A dictionary and a hook.

You build all three once, they travel on OpenTelemetry, and a managed runtime takes them to production with minimal configuration.

One deliberate boundary: this post is about observability, seeing what an agent already does. It is not about resilience or chaos testing (injecting failures and recovering from them); that's a different, related story. And once you can see what your agent does, the natural next step is to validate it. Evaluation builds on exactly this data. You can't validate what you can't see.

Try it yourself

The travel agent, all four demos (each self-contained, with a script and a Jupyter notebook), and both production deployment paths are in the sample repository:

→ observability-for-agents-sample-for-aws

You need Python 3.10+, uv, an API key for your LLM provider (the demos support multiple providers), and a free Duffel sandbox token. Demo 01 runs in under a minute:

git clone https://github.com/elizabethfuentes12/observability-for-agents-sample-for-aws.git
cd observability-for-agents-sample-for-aws/01-agent-metrics
uv venv && source .venv/bin/activate
uv pip install -r requirements.txt
cp .env.example .env   # fill in your LLM provider API key and DUFFEL_API_KEY
uv run python test_agent_metrics.py

Clone it, run it, and stop running your agents blind. Which of your agents would surprise you most if you could see every cycle? Tell me in the comments.

References: Strands Agents observability docs · OpenTelemetry · AgentCore Observability · CloudWatch GenAI Observability

Gracias!

🇻🇪 Dev.to Linkedin GitHub Twitter Instagram Youtube

Elizabeth Fuentes LFollow

I help developers build production-ready AI applications through hands-on tutorials and open-source projects.

Amazon DynamoDB Vector Search. No Separate Vector Store

Elizabeth Fuentes L — Fri, 21 Aug 2026 22:40:38 +0000

📦 Clone and ⭐ stop-ai-agents-losing-memory-sample-for-aws

Part 1 of this post showed how keyword search misses semantic questions and measured two vector backends: FAISS and Amazon S3 Vectors (managed), on the same traveler memories. Both found the answer. The difference was deployment: local vs cloud-managed.

This part adds a third vector backend: Amazon DynamoDB Vector Search, generally available since 2025. The question and the memories are identical. Only the backend changes.

stored:   dietary_notes: "Vegetarian; severe shellfish allergy — strictly no
          crustaceans or mollusks."

asked:    "What should I avoid eating when I go out for dinner on this trip?"

DynamoDB Vector Search: top hit (score 0.231)  answer found: True

What is Amazon DynamoDB Vector Search?

It is a vector index added to an existing DynamoDB table. Not a separate service. You define a VectorIndexes block when you create (or update) the table, and DynamoDB stores the embeddings as a List attribute on each item. Queries use the SearchVectors API.

The key difference from S3 Vectors: the vectors live in the same table as your operational data. If your agent already reads user preferences or travel records from DynamoDB, you can add a vector index to that same table and query by meaning without provisioning another service.

	Amazon S3 Vectors	Amazon DynamoDB Vector Search
Where vectors live	Dedicated vector bucket	Inside a DynamoDB table
Operational data collocated	No	Yes
Query latency	~100–200 ms	Single-digit ms
Billing model	Per-query + storage	On-demand (PAY_PER_REQUEST)
Accuracy	✅ same (same embeddings)	✅ same (same embeddings)
Survives restart	Yes	Yes
Infrastructure to manage	None	None
Best for	Dedicated vector memory, no operational data to manage	Agents that already use DynamoDB, or want one service for data + embeddings

Both are valid choices. S3 Vectors is purpose-built for dedicated vector workloads and the right fit when you want memory completely separate from your operational data. DynamoDB Vector Search is the right fit when your agent data is already in DynamoDB and you want one service for both.

(This demo uses Strands Agents. The pattern carries over to any agent framework.)

How does the embedding comparison look?

Same question, same Titan V2 embeddings, four backends side by side:

Store	Finds answer	cos_sim	Query latency
Key-value (keyword scan)	No	—	—
FAISS	Yes	0.231	<0.1 ms
Amazon S3 Vectors	Yes	0.231	~195 ms
Amazon DynamoDB Vector Search	Yes	0.231	single-digit ms

All three vector backends return the same top hit with the same score, because they use the same Amazon Titan Text Embeddings V2 model. The embedding call (~510 ms) still dominates end-to-end latency for all of them. What changes is the query after the embedding.

How do you add a vector index to a DynamoDB table?

DynamoDB Vector Search requires on-demand billing (PAY_PER_REQUEST). The vector index is declared when creating the table:

client.create_table(
    TableName="agent-memory-demo-ddb",
    BillingMode="PAY_PER_REQUEST",           # required for vector indexes
    KeySchema=[{"AttributeName": "memory_key", "KeyType": "HASH"}],
    AttributeDefinitions=[{"AttributeName": "memory_key", "AttributeType": "S"}],
    VectorIndexes=[{
        "IndexName": "memory-vector-index",
        "VectorAttribute": {"AttributeName": "embedding"},
        "Dimensions": 1024,
        "DistanceFunction": "COSINE",
        "Projection": {"ProjectionType": "ALL"},
    }],
)

The demo self-provisions the table and index if missing: no console steps, no CDK required.

How do you write and query vectors?

Embeddings are stored as a DynamoDB List attribute alongside the rest of the item:

client.put_item(
    TableName="agent-memory-demo-ddb",
    Item={
        "memory_key":  {"S": "dietary_notes"},
        "text":        {"S": "Vegetarian; severe shellfish allergy..."},
        "embedding":   {"L": [{"N": str(float(f))} for f in vector]},  # 1024 floats
    },
)

Querying uses the SearchVectors API with the same AttributeValue format:

resp = client.search_vectors(
    TableName="agent-memory-demo-ddb",
    IndexName="memory-vector-index",
    SearchVector=[{"N": str(float(f))} for f in question_vector],
    TopK=3,
)

Score note: SearchVectors returns a cosine distance (lower = more similar). The demo converts it to cosine similarity (1.0 − score) so the output is directly comparable to FAISS and S3 Vectors.

Does the index survive a restart?

Yes. It's DynamoDB. A fresh client instantiated after the demo runs still sees every item:

fresh = DynamoDBVectorStore()
fresh.count() == 10   # True — all 10 memories are there

This is the same restart test run in Part 1 for S3 Vectors. Both pass.

How do you run Test 4?

Test 4 runs as part of the existing test_vector_memory.py in the companion repo:

git clone https://github.com/elizabethfuentes12/stop-ai-agents-losing-memory-sample-for-aws
cd stop-ai-agents-losing-memory-sample-for-aws/02-vector-memory-demo
uv venv && uv pip install -r requirements.txt
uv run python test_vector_memory.py

Needs AWS credentials (aws configure) for Titan embeddings (Bedrock), S3 Vectors, and DynamoDB. The demo creates the DynamoDB table and vector index automatically if they don't exist. Requires boto3>=1.43.72 (SearchVectors was added in that release).

When do you pick DynamoDB over S3 Vectors?

You have	Pick
No existing DynamoDB table; memory is the only use case	S3 Vectors — purpose-built for dedicated vector workloads
An existing DynamoDB table with user data	DynamoDB Vector Search — add the index to the same table; one service, one billing model
Need sub-100 ms query latency after the embedding call	DynamoDB Vector Search — single-digit ms vs ~200 ms
High QPS, hybrid search, or advanced filtering	Dedicated vector database (OpenSearch, Qdrant, etc.)

FAQ

Can I add a vector index to an existing DynamoDB table?
Yes. Use update_table with VectorIndexUpdates to add the index to a table that already has data. Existing items without the embedding attribute won't appear in vector queries until you backfill their embeddings and update the items.

Does DynamoDB Vector Search work in all regions?
Check regional availability; the feature is GA but not in every region on launch day.

What's the cost compared to S3 Vectors?
DynamoDB Vector Search uses on-demand billing: you pay for read/write capacity units and storage on the table. S3 Vectors charges per query and per stored vector. For agent memory workloads (infrequent queries, small number of vectors per user) both are low cost; the deciding factor is architecture, not price.

Why does SearchVectors return a distance and not a similarity?
SearchVectors returns cosine distance (1 − cosine_similarity), where 0 means identical and 1 means opposite. The demo converts with 1.0 − score to get cosine similarity for easy comparison with FAISS (which returns inner product of normalized vectors, equivalent to cosine similarity) and S3 Vectors (which also returns 1 − distance).

Resources

Companion repo — demo 02 with the full 4-backend test
Amazon DynamoDB Vector Search — Developer Guide
Amazon DynamoDB Vector Search GA announcement
Amazon S3 Vectors — User Guide
Amazon Titan Text Embeddings V2
Part 1 — FAISS and S3 Vectors

Which surprised you more: the single-digit millisecond DynamoDB latency, or the fact that the cosine similarity score is identical across all four backends? Share in the comments.

Gracias!

🇻🇪 Dev.to Linkedin GitHub Twitter Instagram Youtube

Elizabeth Fuentes LFollow

I help developers build production-ready AI applications through hands-on tutorials and open-source projects.

I Watched My Coding Agent Refuse to Leak a Secret

Jonathan Vogel — Fri, 21 Aug 2026 22:07:05 +0000

A coding agent with AWS access grabs a secret the obvious way and drops the plaintext into its context. AWS Secrets Manager shipped a skill that blocks that and hands the agent a safe path instead. I ran it against a live account in Claude Code and pushed on the edges.

Give a coding agent shell access with AWS credentials, ask it to hit a database and watch what it does. It reaches for the password the obvious way.

$ aws secretsmanager get-secret-value --secret-id agent-toolkit-blog-demo/api-token --query SecretString --output text --region us-east-1
{"username":"demo_user","host":"demo-db.example.internal","password":"FAKE-pw-asdf","token":"FAKE-token-asdf"}

That value is now definitely in the model's context window and conversation history. It could be sitting in a session transcript on disk and end up passing into whatever tool call the agent makes next. You thought you were using Secrets Manager because you wanted to follow best practices and not have a password sitting around.

I'll admit I've done this. I've even pasted secrets straight up into the agent. When you gotta move fast, sometimes you let security take a backseat. Don't be me. Now when you're using agents to build on AWS, you can be fast and secure!

AWS Secrets Manager shipped this nifty feature: a secret safety skill in the aws-core plugin of the Agent Toolkit for AWS. The idea here is simple. An agent should be able to use a secret without ever seeing it. I spent an afternoon running it against a throwaway secret in a real account, then trying to get around it. Here is what happened.

Before I installed the plugin I told Claude Code the secret was a fake throwaway and asked it to fetch the value and reply in chat. It did it without blinking. With the plugin enabled the same prompt died on the spot, and the part I did not expect is that the skill shut it down before the hook even ran.

What the toolkit is, in one screen

If you're doing stuff with AWS using an agent and have not yet set up the Agent Toolkit for AWS, you need to get it set up. Below is some of the "what" around the toolkit:

AWS MCP Server. A managed endpoint your agent talks to for all things AWS. Model training data can be stale, this gives you the capability of running the right AWS CLI commands, searching current AWS docs and logging calls in CloudTrail.
Skills. Task runbooks in markdown, loaded on demand, written by people who ran the workflow and found where agents get stuck. The secret safety skill is one of these.
Plugins. A single install that bundles the MCP Server config and a set of skills. aws-core is the one to start with.

Using the toolkit is free. Skills and doc search work without credentials. API calls need AWS credentials. You pay for any AWS resources your agent deploys.

The demo

I created a throwaway secret with fake values so nothing real was ever at risk.

aws secretsmanager create-secret \
  --name agent-toolkit-blog-demo/api-token \
  --secret-string '{"username":"demo_user","host":"demo-db.example.internal","password":"FAKE-pw-asdf","token":"FAKE-token-asdf"}' \
  --region us-east-1

You already saw the before. get-secret-value hands back the plaintext and it enters the agent's world.

Here's the command to install the toolkit in Claude Code:

/plugin install aws-core@claude-plugins-official

If that comes back with Plugin not found, your local marketplace index is stale. Run /plugin marketplace update claude-plugins-official and install again. If the marketplace is missing rather than stale, update will not help and you need /plugin marketplace add anthropics/claude-plugins-official first.

The skill activates on its own. So does a second piece I will come back to. One thing to know before you try it. Hooks load when the session starts, so restart your agent after installing or the block will not be there yet. Restart, ask the agent to fetch the secret and the request does not run.

The automatic block

A PreToolUse hook sits in front of the agent's tool calls. When the call would fetch a secret value, the hook denies it before it executes and hands the agent a message that points at the safe path.

Direct secret fetching is blocked. Use {{resolve:secretsmanager:secret-id:SecretString:key}} with asm-exec instead. Run /aws-secrets-manager for details.

Worth being precise about which layer does what here. When I asked in plain language, the agent never tried at all. The skill had already told it not to, so it declined on its own and pointed me at the safe path, and the hook never fired. I only saw the message above once I insisted it actually run the command. The skill is the part that changes the agent's mind and the hook is the backstop for when it tries anyway.

I wanted to know how much this actually covers. I tested ten different scenarios to see where the agent might want to reach for a secret and where I might get the skill to trip up when it shouldn't be flagging at all.

STATUS | expected | got   | case
-------+----------+-------+-----------------------------------------
  OK   | deny     | deny  | Bash: aws secretsmanager get-secret-value
  OK   | deny     | deny  | Bash: aws secretsmanager batch-get-secret-value
  OK   | deny     | deny  | use_aws: secretsmanager GetSecretValue
  OK   | deny     | deny  | run_script: boto3 get_secret_value(...)
  OK   | deny     | deny  | Bash: direct SMA daemon curl localhost:2773
  OK   | deny     | deny  | Bash: python3 -c inline boto3 get_secret_value
  OK   | allow    | allow | Bash: asm-exec with {{resolve:...}}
  OK   | allow    | allow | Bash: grep that only mentions get-secret-value
  OK   | allow    | allow | use_aws: secretsmanager CreateSecret (a write, not a fetch)
  OK   | allow    | allow | use_aws: s3 ListBuckets

Results are what I expected, well done agent toolkit. It catches the CLI fetch, the batch fetch, the structured API call, a boto3 call buried in a Python script, a curl straight at the local Secrets Manager Agent daemon and an inline python3 -c one-liner. It does not trip on a grep for the bare string get-secret-value, and it leaves writes and unrelated calls alone. The allowlist for read-only tools is narrower than I assumed though. Search for the full phrase aws secretsmanager get-secret-value and you get denied whether you run it through grep, rg or echo, because the CLI pattern is checked before the allowlist ever applies. I tripped that one myself while grepping my own notes for this post.

What sold me is that both layers push the same direction. The skill has already taught the agent what to do instead, so whether it stops itself or gets stopped by the hook, it does not stall. It rewrites its own command to use the safe path.

Resolve without seeing

The safe path is a dynamic reference and a small wrapper called asm-exec.

asm-exec -- curl -sS \
  -H "Authorization: Bearer {{resolve:secretsmanager:agent-toolkit-blog-demo/api-token:SecretString:token}}" \
  https://api.example.com/data

The command the agent constructs holds a placeholder, not a value. asm-exec scans the arguments, resolves each {{resolve:...}} reference inside its own process, then hands the resolved arguments to the real command. The plaintext never lands in the model's context window or the session transcript.

I pointed it at a local listener that records what it receives, so I could see both sides at once.

Agent-visible command:
  asm-exec -- curl -sS -H 'Authorization: Bearer {{resolve:secretsmanager:agent-toolkit-blog-demo/api-token:SecretString:token}}' http://127.0.0.1:8799/data

Response the agent sees:
  {"authenticated": true, "msg": "token accepted"}

Header the listener actually received:
  Bearer FAKE-token-asdf

The token reached the target. The agent saw a placeholder going in and an API response coming back. It never saw the token.

To be sure I was not fooling myself, I resolved the reference and piped it straight into shasum instead of a command, then compared against the hash of the known fake token.

$ printf %s "FAKE-token-asdf" | shasum -a 256
4953fa5206a3d4a298e6aab9f9c2f74ae50ec2d6f07f374a2df478386674593e  -

$ asm-exec -- sh -c 'printf %s "{{resolve:secretsmanager:agent-toolkit-blog-demo/api-token:SecretString:token}}" | shasum -a 256'
4953fa5206a3d4a298e6aab9f9c2f74ae50ec2d6f07f374a2df478386674593e  -

Same hash. The real value was resolved, used and never printed.

Then the part that closes the loop. I grepped the agent-visible transcript from both runs for the fake values.

-- unguarded path (aws secretsmanager get-secret-value) --
   FAKE-pw-asdf     found
   FAKE-token-asdf  found
-- safe path (asm-exec + {{resolve}}) --
   FAKE-pw-asdf     not found
   FAKE-token-asdf  not found

One path writes your secret into a file on disk. The other runs the exact same task without ever writing it down.

How the pieces fit

One thing I like about the design. asm-exec never shells out to aws secretsmanager get-secret-value itself, so the plaintext is never written to a local process's stdout where something could scrape it.

Where this bites

I've talked about how cool this is but I also promised to go over some rough edges. I want to be clear the skill is useful but it is also a best-effort defense. Even AWS says so in the docs. It stops the common leak but it doesn't mean you should stop thinking about security as high priority in your day-to-day actions.

It reduces exposure, it does not prove a negative. The block covers the fetch shapes I threw at it and more. A determined agent or a creative prompt can still find a path the hook does not model. Treat this as one layer. For real production stuff, you still need to keep IAM least-privilege underneath it, keep CloudTrail on and scope who can read which secret. The skill lowers the odds of a dumb leak. It does not turn the agent into a trusted process.

The safe path still calls GetSecretValue. It is not read-free. asm-exec resolves by calling Secrets Manager, it just does it in its own process instead of handing the value back to the agent. Your identity still needs secretsmanager:GetSecretValue on the secret, and the read still shows up in CloudTrail. When it goes through the MCP endpoint the event lists invokedBy, sourceIPAddress and userAgent all as aws-mcp.amazonaws.com, so you can tell an agent read from one you ran yourself. The difference is where the plaintext lands, not whether the API gets called.

asm-exec times out on slow connections. I got Failed to resolve on a fresh network even with valid creds. The read timeout is 10 seconds. A retry cleared it.

Try it on something you were going to build anyway

To make sure you get the automatic block you saw in the demo above, install the plugin in Claude Code with this command: /plugin install aws-core@claude-plugins-official, then restart your session so the hook loads.

From the Agent Toolkit for AWS site, you'll see this one shot command that works for most agents:

aws configure agent-toolkit

This is the easy way to install the toolkit but it does require AWS CLI 2.35+. This method will auto-detect your agents, install skills, and configure the MCP Server. One catch I hit: it does not install the secret-safety skill you saw here. That one ships with the aws-core plugin (it lives under plugins/aws-core/skills).

Repo and docs below:

Start read-only. Use the aws:CalledViaAWSMCP condition key to keep the agent to reads through the MCP Server so people can get used to it, then open up write access once you trust the pattern. Loosening later is easy. Walking back a broad grant is not.

If you have any feedback on this or general thoughts on the toolkit, drop a comment below. Feel free to connect/reach out on LinkedIn.

3 Ways to Manage Files in CloudShell

Sean Boult — Thu, 20 Aug 2026 16:48:35 +0000

So you've probably had to open CloudShell from time to time to poke at something quickly. Say I wanted to test pulling down an artifact from a private CodeArtifact registry. To do that, I'd need to tweak my ~/.npmrc so npm points at the right registry.

Which raises the question: what's the best way to edit a file once you're in CloudShell? Let's look at a few options.

Using vim

I use Neovim btw (sorry emacs users), so naturally I'm starting with vim.

vim ~/.npmrc

If you're already comfortable with Vim, this is probably the fastest option. You're already in the terminal, you get all the navigation and search you're used to, and there's nothing else to open.

Make your changes, hit ESC, and :wq (write + quit) to save the file.

Using nano

Ah the old classic. I've been using this for decades to edit files on remote boxes.

nano ~/.npmrc

Unlike Vim, there's not much to learn before you can start typing. Nano even shows you the important shortcuts at the bottom of the screen.

Make your changes, hit CTRL+O to write them to disk, and CTRL+X to exit.

If you just need to make a quick edit and get out, nano is hard to beat.

Using edit

Okay, but what if you don't want to use a terminal editor at all?

CloudShell has an edit command that opens the file directly in its built-in editor.

edit ~/.npmrc

Instead of editing inside the terminal, CloudShell opens the file in a familiar graphical editor where you can point, click, type, and save with CMD+S (CTRL+S on Windows/Linux) or the save icon.

If you're used to editing files in VS Code or another graphical editor, this is probably going to feel the most familiar.

No Vim modes. No terminal keybindings to remember.

Which one should you use?

Honestly, whichever gets you back to solving the actual problem fastest.

Editor	Use it when...
vim	You're comfortable with Vim and want to stay in the terminal
nano	You want a simple terminal editor without learning Vim
edit	You'd rather use a familiar graphical editor

So the next time you find yourself debugging something from CloudShell, you've got a few ways to quickly read or edit a file without leaving your browser.

As always, happy coding 😄!

Follow AWS for more articles like this and follow me for all things tech.

AWS Follow

Articles written by current and past AWS Developer Advocates to help people interested in building on AWS. Opinions are each author's own.

Sean BoultFollow

Developer. Hacker. Creator.

How to Build an AI Agent That Asks Permission First (Nuxt + AI SDK 7)

Erik Hanchett — Tue, 18 Aug 2026 18:38:25 +0000

Introduction

I did something stupid. I built a superhero-themed Nuxt app, connected it to an Anthropic model through Amazon Bedrock, and gave it a tool that deletes files from my computer. In fact, if I wasn't careful, it could have deleted all my files!

The first time I tried it, I didn't use any sort of approval mechanism. And as you expected it just deleted things. Then I looked into how my coding agent works, and I learned about tool approvals.

I learned that AI SDK 7 has a tool approval at the model-call level. It works by pausing for an approval, showing an approval window, and then deleting it. I then put Kiro CLI behind the same interface using Agent Client Protocol (ACP).

Watch the full video on YouTube.

Prerequisites

You need:

Node.js 22 or later. AI SDK 7 requires Node.js 22 and uses ECMAScript modules (ESM).
npm 11 or another package manager that works with Nuxt 4.
AWS credentials available through the standard provider chain.
Access to an Amazon Bedrock model in your AWS Region.
The AWS CLI if you want to list the inference profiles available to your account.
An authenticated Kiro CLI installation for the optional ACP section.

Step 1: Create the Nuxt app

Create the project and install the versions used in the recorded demo:

npx nuxi@latest init nuxt-agent-approval
cd nuxt-agent-approval

npm install \
  nuxt@4.5.2 \
  vue@3.5.41 \
  ai@7.0.66 \
  @ai-sdk/vue@4.0.66 \
  @ai-sdk/amazon-bedrock@5.0.57 \
  @aws-sdk/credential-providers@3.1111.0 \
  @nuxt/ui@4.10.0 \
  zod@4.4.3

npm install -D @iconify-json/lucide@1.2.123

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  runtimeConfig: {
    awsRegion: process.env.AWS_REGION ?? 'us-west-2',
    bedrockModelId: process.env.NUXT_BEDROCK_MODEL_ID
  }
})

Add the two Nuxt UI imports:

/* app/assets/css/main.css */
@import "tailwindcss";
@import "@nuxt/ui";

You can compare your setup with the complete companion project.

Step 2: Keep the file tool inside a fixture directory

The video uses two fixture files, old-draft.md and keep-me.md. Create them before adding the tools:

mkdir -p fixtures
printf '# Old draft\n' > fixtures/old-draft.md
printf '# Keep me\n' > fixtures/keep-me.md

The agent can list or remove files in that directory, but it should not accept a path such as ../../package.json.

Approval decides whether a tool runs. It does not decide what the tool can reach after it starts.

// server/utils/file-tools.ts
import { lstat, readdir, realpath, rm } from 'node:fs/promises'
import { resolve, relative, isAbsolute } from 'node:path'
import { tool } from 'ai'
import * as z from 'zod'

function resolveInsideFixtures(inputPath: string): string {
  const root = resolve(process.cwd(), 'fixtures')
  const target = resolve(root, inputPath)
  const rel = relative(root, target)

  if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) {
    throw createError({
      statusCode: 400,
      statusMessage: `Path escapes the fixtures directory: ${inputPath}`
    })
  }

  return target
}

export const listFiles = tool({
  description: 'List the files in the project fixtures directory.',
  inputSchema: z.object({}),
  execute: async () => {
    const entries = await readdir(resolve(process.cwd(), 'fixtures'), {
      withFileTypes: true
    })
    return { files: entries.filter(entry => entry.isFile()).map(entry => entry.name) }
  }
})

export const deleteFile = tool({
  description: 'Permanently delete one file from the fixtures directory.',
  inputSchema: z.object({ path: z.string() }),
  execute: async ({ path }) => {
    const target = resolveInsideFixtures(path)
    const info = await lstat(target).catch(() => null)

    if (!info?.isFile() || info.isSymbolicLink()) {
      return { deleted: false, path, reason: 'Not a regular file' }
    }

    const root = await realpath(resolve(process.cwd(), 'fixtures'))
    const canonicalTarget = await realpath(target)
    const rel = relative(root, canonicalTarget)

    if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) {
      throw createError({
        statusCode: 400,
        statusMessage: 'File resolves outside fixtures'
      })
    }

    await rm(canonicalTarget)
    return { deleted: true, path }
  }
})

The second check happens after realpath(). That catches a path that looked local before resolution but points outside the fixture directory through a symbolic link.

Step 3: Connect the route to Amazon Bedrock

I used Amazon Bedrock, but you can use provider with AI-SDK

Create the provider in server/utils/bedrock.ts:

import { createAmazonBedrock } from '@ai-sdk/amazon-bedrock'
import { fromNodeProviderChain } from '@aws-sdk/credential-providers'

export function useBedrock() {
  const { awsRegion } = useRuntimeConfig()

  return createAmazonBedrock({
    region: awsRegion,
    credentialProvider: fromNodeProviderChain()
  })
}

fromNodeProviderChain() uses the AWS credentials already available to your local environment, including AWS IAM Identity Center sessions, named profiles, environment variables, and instance roles. You do not need to put a long-lived access key in the Nuxt project.

Do not copy a model ID from this post. Available IDs vary by account and AWS Region. List the active Amazon Bedrock inference profiles for your account:

aws bedrock list-inference-profiles \
  --region us-west-2 \
  --query 'inferenceProfileSummaries[?status==`ACTIVE`].inferenceProfileId'

Set one of the returned profile IDs before starting Nuxt:

export AWS_REGION=us-west-2
read -r -p "Inference profile ID: " NUXT_BEDROCK_MODEL_ID
export NUXT_BEDROCK_MODEL_ID
npm run dev

Now add an unguarded chat route. Starting without approval makes the failure visible:

// server/api/chat.post.ts
import {
  streamText,
  stepCountIs,
  convertToModelMessages,
  toUIMessageStream,
  createUIMessageStreamResponse
} from 'ai'
import type { AmazonBedrockProvider } from '@ai-sdk/amazon-bedrock'

type BedrockModelId = Parameters<AmazonBedrockProvider>[0]

export default defineEventHandler(async event => {
  const { messages } = await readBody(event)
  const { bedrockModelId } = useRuntimeConfig()
  const bedrock = useBedrock()

  const result = streamText({
    model: bedrock(bedrockModelId as BedrockModelId),
    instructions:
      'Manage files in the fixture project. List files before deleting. Never guess a filename.',
    messages: await convertToModelMessages(messages),
    tools: { listFiles, deleteFile },
    stopWhen: stepCountIs(5)
  })

  const stream = toUIMessageStream({ stream: result.stream })
  return createUIMessageStreamResponse({ stream })
})

stopWhen is important. AI SDK 7 stops after one step by default. The model can call deleteFile, receive the result, and then stop before it tells the user what happened. Five steps leave room to list, delete, and summarize while keeping the loop bounded.

At this point, delete old-draft.md removes the file as soon as the model selects the tool. That is what happened in the first minute of the video.

Step 4: Add approval to the delete tool

Add one option to the streamText() call (toolApproval):

const result = streamText({
  model: bedrock(bedrockModelId as BedrockModelId),
  instructions:
    'Manage files in the fixture project. List files before deleting. Never guess a filename.',
  messages: await convertToModelMessages(messages),
  tools: { listFiles, deleteFile },
  stopWhen: stepCountIs(5),
  toolApproval: {
    deleteFile: 'user-approval'
  }
})

The option lives on streamText(), not inside the tool definition. The same deleteFile tool might run unattended in a maintenance job and require a person in a customer-facing chat.

AI SDK 7 supports more than a yes-or-no policy. A policy function can approve a call, deny it without asking, or send it to the user. This example uses the direct user-approval status because every delete should stop.

Step 5: Render the approval request in Nuxt

Nuxt UI's chat documentation follows the same AI SDK message-part model. The recorded app uses useChat() from @ai-sdk/vue and the isToolApprovalPending() helper from Nuxt UI:

<script setup lang="ts">
import {
  DefaultChatTransport,
  getToolName,
  isTextUIPart,
  isToolUIPart,
  lastAssistantMessageIsCompleteWithApprovalResponses
} from 'ai'
import { useChat } from '@ai-sdk/vue'
import { isToolApprovalPending } from '@nuxt/ui/utils/ai'

const input = ref('')

const {
  messages,
  status,
  sendMessage,
  addToolApprovalResponse
} = useChat({
  transport: new DefaultChatTransport({ api: '/api/chat' }),
  sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses
})

function onSubmit() {
  if (!input.value.trim()) return
  sendMessage({ text: input.value })
  input.value = ''
}
</script>

sendAutomaticallyWhen resumes the interrupted turn after the user answers. Without it, the approval state changes in the browser but the agent does not continue on its own.

Render tool parts and attach the two decisions while approval is pending:

<template>
  <div v-for="message in messages" :key="message.id">
    <template
      v-for="(part, index) in message.parts"
      :key="`${message.id}-${part.type}-${index}`"
    >
      <div v-if="isToolUIPart(part)" class="tool-card">
        <strong>{{ getToolName(part) }}</strong>

        <pre v-if="part.input">{{ part.input }}</pre>

        <div v-if="isToolApprovalPending(part)">
          <button
            type="button"
            @click="addToolApprovalResponse({
              id: part.approval!.id,
              approved: true
            })"
          >
            Do it
          </button>

          <button
            type="button"
            @click="addToolApprovalResponse({
              id: part.approval!.id,
              approved: false,
              reason: 'The user declined this file deletion.'
            })"
          >
            Nope
          </button>
        </div>
      </div>

      <p v-else-if="isTextUIPart(part)">{{ part.text }}</p>
    </template>
  </div>

  <form @submit.prevent="onSubmit">
    <input v-model="input" placeholder="delete old-draft.md">
    <button :disabled="status !== 'ready'">Send</button>
  </form>
</template>

FYI, An approval button is not useful when the person cannot see which path the agent wants to remove.

The denial reason is also useful. approved: false tells the model it cannot run the tool. The reason gives it enough context to explain what happened rather than trying the same call again.

Run the prompt twice. Deny it once and confirm that old-draft.md remains. Reset the fixtures, repeat the prompt, approve it, and confirm that the file disappears. The model received the same request both times.

Step 6: Put Kiro CLI behind the same Nuxt UI

The video switches the backend for the final demo. Instead of sending the prompt directly to an Anthropic model through Amazon Bedrock, the Nuxt app talks to Kiro CLI over Agent Client Protocol.

ACP gives the app a common way to start an agent session, send a prompt, receive tool events, and answer permission requests. Kiro runs as a separate process and keeps its existing agent tools and Model Context Protocol (MCP) integrations. The Nuxt app remains responsible for the interface and the host tools it exposes.

Install the AI SDK harness packages:

npm install \
  @ai-sdk/harness@1.0.73 \
  @ai-sdk/harness-acp@1.0.11

The Kiro route creates a HarnessAgent instead of calling streamText() directly. The createKiroHarness() ACP preset and createUnsafeLocalSandbox() development adapter come from the companion project, so treat this as the route configuration rather than a standalone file:

import { execFileSync } from 'node:child_process'
import { HarnessAgent } from '@ai-sdk/harness/agent'

const kiroExecutable = execFileSync('which', ['kiro-cli'], {
  encoding: 'utf-8'
}).trim()

const agent = new HarnessAgent({
  harness: createKiroHarness({ port: 4100 }),
  sandbox: createUnsafeLocalSandbox({
    ports: [4100],
    hostBins: [
      { harnessId: 'kiro', name: 'kiro-cli', target: kiroExecutable }
    ]
  }),
  permissionMode: 'allow-reads',
  instructions:
    'Manage files in the fixture project. List files before deleting. Never guess a filename.',
  tools: { listFiles, deleteFile },
  toolApproval: {
    deleteFile: 'user-approval'
  }
})

The complete Kiro route and ACP preset include session creation and approval continuation. When a response comes back from the browser, the route gathers pending approval responses and calls continueStream() against the Kiro session.

My recorded run asked more than once before deleting keep-me.md. Kiro confirmed the target, its permission flow asked to run the tool, and the host deleteFile policy asked for the final approval. It was a little repetitive, but it exposed an important boundary. Kiro's built-in permissions and AI SDK's host-tool approval are separate systems.

The local sandbox in this sample is a development adapter. It limits file API paths to a temporary root, but processes still run as the current operating-system user. Replace it with an isolated sandbox provider before exposing a coding agent to untrusted prompts.

Step 7: Keep approval in its lane

Tool approval is a product DX improvement, it isn't security.

If a person approves the wrong path, the tool still removes the wrong path. If the tool can reach the rest of the filesystem, approval does not narrow that access. Keep the path checks from Step 2, apply authorization inside the tool, validate inputs on the server, and use an isolated runtime for agents that can run commands.

The sample app also keeps its recording controls in development mode. The browser can turn approval off for the first demo, but the built app ignores that flag and requires approval. A client-controlled switch that disables confirmation should not ship.

Cleanup

Stop the Nuxt development server. If you deleted either fixture during the demo, recreate both files before your next run:

printf '# Old draft\n' > fixtures/old-draft.md
printf '# Keep me\n' > fixtures/keep-me.md

This tutorial does not provision AWS resources. Amazon Bedrock requests can still incur charges, so stop sending test prompts when you finish.

If you delete the local project directory, its files and any local session state are removed. Copy anything you want to keep before deleting it. AWS credentials loaded through the provider chain remain in their original profile or identity-center cache; this app does not write them into the project.

Finale

I learned a lot by adding this tool approval process. And even though I normally use Strands Agents, the AI SDK 7 worked really well.

Make sure to leave a comment below if you got this far!

References

Why Can't We Just Use Claude for Everything? Agent Creation vs. Agent Engineering

Matheus Guimaraes — Tue, 18 Aug 2026 16:36:11 +0000

Recently, I was talking to a friend who, much like the rest of the world, has started using AI extensively at work to create agents even though she's not a software developer or from a technical background.

She has been experimenting with Claude a lot, building useful workflows for herself and her team, and getting increasingly excited about what these systems can do.

At some point, our conversation moved onto the work I've been doing around agentic systems: agent architectures, context engineering, memory, orchestration, sub-agents and frameworks such as Strands Agents.

And her reaction was:

Why do you need all of that? I'm already creating agents.

"Great question", I thought to myself.

And what made it particularly interesting was that I'd heard almost the same question from the opposite direction.

After giving a talk about agentic architecture and building harnesses with Strands Agents SDK, a junior developer came up to me and asked:

What's the point of all of this? Why can't we just use Claude for everything?

Two people approaching the subject from completely different directions had arrived at the same question.

And I think that question exposes something important about where we are with agents today. We are using the same word "agent" to describe two very different activities with very different use cases.

The way I see it, there is a big difference between creating agents and engineering agents.

Agent Creation vs. Agent Engineering

Applications such as Claude, ChatGPT, Amazon Quick and others increasingly allow people to create surprisingly sophisticated agentic workflows without building the underlying infrastructure themselves.

There is still a learning curve, though. You need to provide instructions and give the system knowledge and context in a way that produces results that are within expectation (and, hopefully, without hallucinations!). You may also need to learn about tools, set up integrations, schedule work or even create subagents so multiple pieces of functionality can work together.

From the user's perspective, they have created an agent. And indeed they have! But when a software engineer looks at the same system... they see something different.

They see an application providing a highly abstracted, opinionated agent runtime operating as a black box. You have little control over how execution happens, how context is assembled and maintained, how the system scales, or even where memory lives, among other architectural concerns.

As an application user, you are creating an agent inside somebody else's agentic architecture.

And that's not a problem. In fact, this could be exactly what you need!

Developers and software architects make trade-offs between abstraction and control all the time. We don't choose the lowest-level technology simply because it gives us the most control; we use abstractions because they remove decisions we don't want to make and complexity we don't need to own.

The same principle applies here. If Claude gives you everything you need to create an agent, why wouldn't you use it?

As usual with system design, the important thing is understanding the trade-offs. The abstraction works because somebody else has made a set of architectural decisions for you. If those decisions suit your requirements, then awesome. If they don't, you may need to take ownership of some of them yourself.

That's where I find the distinction between Agent Creation and Agent Engineering useful.

For me, three things make that distinction particularly clear.

Is the agent a feature or a component?

This is perhaps my favourite way of thinking about the distinction.

Let's say I create an agent in Claude to research holidays for me. It knows my preferences, researches destinations, compares options and perhaps uses tools to build an itinerary. It could be incredibly sophisticated... but Claude is still the application. I go to Claude, interact through Claude's interface and rely on Claude's infrastructure to make everything work.

My agent is a feature of an application I'm using.

Now imagine I want to offer that same experience through my own travel website. A customer comes to my application and asks for a holiday; somewhere behind the scenes an agent researches flights and hotels, applies their preferences, interacts with booking systems and returns the result.

The capability sounds almost identical, but architecturally something fundamental has changed. The agent is now a component of a system I'm building.

Suddenly I need to decide where it runs, how my application communicates with it, how it scales, how it authenticates against other systems, what happens when it fails, how it fits into traditional application flows, and how I observe what it's doing. The AI is no longer the destination; it's now part of the system I'm responsible for.

That's very clearly Agent Engineering.

The point is really about ownership. If an agent is a feature of Claude or another application, you're limited, quite deliberately, to what that application allows you to do. If your requirements fit inside those boundaries, great. When they don't... you need another abstraction.

Do you need control over the economics?

Another reason you might choose to engineer the agent is cost.

There is a lot of conversation right now about just how many tokens agentic systems can consume, particularly as we build long-running workflows with large context windows, tool calls and multiple agents.

Moving from Agent Creation to Agent Engineering doesn't automatically make any of this cheaper, by the way. Engineering has its own cost, and it would be rather ironic to spend £100,000 in developer time to save £500 in tokens.

What engineering gives you is control.

If you own the harness around your agents, architectural decisions become available that simply aren't exposed when you're operating inside somebody else's application.

You can decide that one task doesn't need the full conversation history, cache an expensive result, retrieve memory only when it's relevant, summarize context between steps, or route simpler tasks to cheaper models.

You can start treating context and tokens as resources that you deliberately engineer.

There's a much larger conversation here around context engineering, but that's a story for another post. For now, the important point is that the abstraction determines which levers are available to you.

If you don't need those levers, there's little value in taking responsibility for them. If the economics of your system mean you do, Agent Engineering gives you that control.

Do you need to own where your data goes?

Then there is a question that tends to become important very quickly in enterprise environments: where does everything actually live?

When I create an agent inside an application, I'm accepting that application's architecture and its mechanisms for handling context, state, memory, integrations and data. Again, that may be completely acceptable.

But what if particular data cannot leave a certain environment? What if I need to know exactly where long-term memory is persisted, control which model receives which information, maintain my own audit trail, or guarantee that certain data never crosses a particular boundary?

Now the black box really matters.

This is partly a compliance question, partly a data ownership question and, yes, partly a vendor lock-in question. The more behaviour, knowledge and state I build around one application's abstractions, the more dependent I become on that platform's capabilities and constraints.

But vendor lock-in isn't, by itself, a reason to engineer everything from scratch. We accept varying degrees of lock-in throughout modern software architecture because managed abstractions can provide enormous value.

The question is simply whether that trade-off is acceptable for the requirements in front of you.

So... Can't We Just Use Claude For Everything?

A useful spreadsheet can eventually become an application, but that doesn't mean the spreadsheet was a mistake. It may have been exactly the right abstraction for the problem at the time, and it may even have helped us understand the problem well enough to know what was worth engineering later.

I think Agent Creation and Agent Engineering should be seen in much the same way: not as levels on a maturity ladder, and certainly not as a journey where every agent should eventually become an engineered one, but as different architectural choices about how much of the underlying system we need to own. We might happily create an agent inside Claude for one task while engineering another from the ground up, perhaps even within the same system.

Sometimes an agent created inside Claude, ChatGPT, Amazon Quick or another application will remain there because it does everything we need. Sometimes our requirements will mean taking ownership of the architecture ourselves and we'll find ourselves reaching for Strands Agents SDK or another agent harness.

And perhaps the next time someone asks me, "Why can't we just use Claude for everything?", my answer will simply be...

You can! For as long as its decisions are compatible with yours.**

Understanding Async Programming

Matheus Guimaraes — Mon, 17 Aug 2026 16:01:25 +0000

Async programming, short for asynchronous programming, is one of those concepts that might sound intimidating at first but becomes surprisingly intuitive once you understand the problem it is trying to solve.

And that problem is mostly waiting.

Modern applications spend a lot of time waiting for things to happen. They wait for APIs to respond, databases to return queries, files to be read or written, and data to travel across a network. Async programming gives us a way to avoid blocking while that happens, allowing other useful work to make progress instead.

In this post, I’ll cover the basic concepts behind async programming rather than focusing on a particular language. The exact implementation differs between languages and runtimes, but the underlying ideas are largely the same. So if you’re new to async, or have used async and await without ever being completely sure what they’re doing, this is a good place to start.

What is Async Programming?

At its core, async programming allows your program to start an operation that may take some time and avoid blocking while it waits for that operation to complete.

This contrasts with synchronous programming, where execution waits for an operation to finish before continuing past that point.

Imagine you’re making an API call, a very common task in modern applications. Your application sends a request across the network and then has to wait for a response. Even if that response takes only a fraction of a second, that's a long time in computer terms.

The important thing is that your application isn't necessarily doing useful computation during all that time. A lot of it is simply waiting for something external to happen.

This is where async programming shines. Rather than blocking an execution resource while waiting for the API call to complete, asynchronous execution can allow other work to make progress and then continue the original operation when its result becomes available.

Async Doesn't Necessarily Mean Faster

One of the most common misconceptions about async programming is that it's about improving performance. A lot of people think that using async makes their code run faster. However...

Async does not necessarily make the operation itself any faster.

Your API call might take exactly the same amount of time to complete whether you call it synchronously or asynchronously. What async changes is what your application can do while it waits. Instead of being blocked by that wait, it can potentially make progress on other work.

When is Async Programming Useful?

There are three main benefits to using async programming:

Improved throughput: Because your application doesn't have to block on one operation before making progress on other work, it can often handle more work over the same period of time. This is particularly valuable in applications such as web servers that may be handling many requests concurrently.
Better resource utilization: Waiting for I/O doesn't necessarily require a thread to sit blocked until the operation completes. With asynchronous I/O, execution resources can potentially be used for other work while the application waits for the database, network, filesystem or another external resource.
Better responsiveness: Async programming can also help applications remain responsive while longer-running operations are taking place. In a user interface, for example, you generally don't want the entire application to freeze while it waits for a network request or file operation to complete.

The common thread between all three is the same: making better use of time that would otherwise be spent waiting.

Sync vs. Async: When to Use Each

Async programming sounds great, but that doesn't mean everything should be asynchronous.

The distinction becomes clearer when we think about I/O-bound and CPU-bound work.

I/O-bound operations spend a significant amount of their time waiting for something outside the CPU: network requests, database calls, file operations and similar tasks. These are often excellent candidates for async programming because there is useful time to reclaim while the application waits.

CPU-bound operations are different. If you're performing a heavy calculation, for example, the CPU is actively doing the work rather than waiting for something else to happen. Making that code asynchronous doesn't suddenly make the computation faster.

CPU-bound work may instead benefit from parallelism, where computation is divided so that multiple pieces of work can execute at the same time, potentially across multiple CPU cores.

Async programming can also introduce additional complexity and some runtime overhead, so there's little benefit in making code asynchronous simply for the sake of it. It is most useful when your application would otherwise spend meaningful time blocked waiting for I/O.

Async Isn't the Same as Parallelism

The distinction between async and parallelism is an important one. Async is primarily about allowing other work to make progress while something is waiting. Parallelism is about performing multiple pieces of work at the same time.

And async doesn't necessarily mean multithreaded either. Different languages and runtimes implement asynchronous execution in different ways, so you shouldn't assume that an async operation means another thread is somewhere doing the work.

This is why async can provide concurrency without necessarily providing parallelism: multiple operations can make progress over the same period of time without their code actually executing at the exact same moment.

How Does Async Work in Code?

The exact mechanics vary between programming languages, but many modern languages provide the familiar async and await keywords to make asynchronous code easier to write and reason about.

At a conceptual level, async identifies code that participates in asynchronous execution, while await marks a point where that code depends on the result of an asynchronous operation.

If that result is already available, execution may simply continue. If it isn't, the function can yield rather than blocking there, allowing other work to make progress. Once the awaited operation completes, execution can continue from that point.

You can think of await as saying: "I need the result of this operation before I can continue from here, but there's no reason to block everything else while I'm waiting for it."

The precise details of what happens underneath, whether that involves an event loop, tasks, promises, futures, state machines or something else, depend on the language and runtime. But you don't need to understand all of those implementation details to understand the basic async mental model.

Ready to Dive Deeper?

If async still feels a little abstract, I also explain the same ideas visually in the companion video below. Sometimes seeing the synchronous and asynchronous flows side by side is what finally makes the concept click.

AI Agent Memory: Add Semantic Search Without a Vector Database

Elizabeth Fuentes L — Thu, 13 Aug 2026 01:31:01 +0000

📦 Clone and ⭐ stop-ai-agents-losing-memory-sample-for-aws

The agent's memory holds the answer. The user asks the question. And retrieval returns nothing.

stored:   dietary_notes: "Vegetarian; severe shellfish allergy — strictly no
          crustaceans or mollusks."

asked:    "What should I avoid eating when I go out for dinner on this trip?"

keyword scan: 4 hits, answer found: False

That's a real run, not a thought experiment. The question names no key and shares no words with the stored note, so the key-value memory from the previous post never finds it. The answer was in the store the whole time.

This is the dividing line for semantic search: do you know the key, or only the intent? When questions stop matching keys, you retrieve by meaning: embed each memory once, embed the question, return the nearest neighbors by cosine similarity. This post measures two things (whether semantic search finds what keyword search misses, and which vector store fits your deployment) using the same embeddings and the same memories in the companion repo.

(Post 2 of a series; the intro maps all the memory types. The code uses Strands Agents, an open source SDK; the pattern carries over to any agent framework.)

Why does key-value memory miss the question?

Because a key-value read is a lookup someone designed in advance, and this question maps to no key. The demo stores 10 memories about a traveler (profile facts, notes, episodes) and asks the dinner question against three stores. The key-value store has exactly two moves, and both fail honestly:

Keyword scan: match question words against keys and values. It returns 4 hits, none of them the allergy note, because "avoid eating at dinner" shares no words with dietary_notes or "shellfish". Answer found: False.
Dump-all fallback: give the model the entire memory and let it read. It works, at a price that grows with every memory you add. For these 10 memories that's 647 characters per question; for hundreds of notes it's thousands of tokens, every single question, forever.

This isn't a bug in key-value memory. Profile lookups ("what's my preferred cabin?") stay exact, instant, and free of embedding costs, which is why the previous post built them that way. The limit only appears when the question is semantic. That's the signal to add a second way in, not to replace the first.

How does semantic search find it?

By comparing meanings instead of words. Every memory is embedded once at write time into a vector (here: Amazon Titan Text Embeddings V2, 1,024 dimensions). At query time, the question is embedded and the store returns the nearest neighbors by cosine similarity:

top hit: "Vegetarian; severe shellfish allergy — strictly no crustaceans
          or mollusks."  (score 0.231)
answer found: True

No shared words between question and note. They're close in meaning, and meaning is what got indexed. Both backends below return this same top hit, because they use the same embeddings; what differs is everything around the query.

FAISS or Amazon S3 Vectors? Same accuracy, different deployment

Both are embedding vector stores. They use the same model (Titan V2), the same algorithm (cosine similarity), and they return the same top hit with the same score. The accuracy is identical this is not a quality trade-off.

Store	Finds the answer	Similarity score
Key-value (keyword scan)	No	— keyword miss
FAISS — Facebook AI Similarity Search, Meta's in-process vector index	Yes	0.231
Amazon S3 Vectors (managed cloud)	Yes	0.231

The difference is deployment. FAISS is an in-process library — zero infrastructure, a pip install, runs local to the process. It provides disk persistence via faiss.write_index / faiss.read_index. In this demo the index is not persisted and is rebuilt from scratch each run. S3 Vectors is a managed AWS service: the index lives in a cloud bucket, reachable from any process with AWS credentials, with no cluster to run or scale.

The demo uses the same AWS credentials for both: Titan embeddings via Bedrock and S3 Vectors via boto3; the same aws configure setup powers both, which is why this requires no extra setup inside a Strands Agents workflow. The demo self-provisions the bucket and index on first run: create_vector_bucket → create_index (1,024 dims, cosine) → put_vectors / query_vectors.

The cost both backends share: embedding the question costs ~510 ms with Titan V2. Index query time (0.09 ms for FAISS, 195 ms for S3 Vectors) is secondary to that. Plan for the embedding call in any latency-sensitive path, regardless of which vector store you pick.

So, do you need a vector database?

It depends on the query pattern. AWS positions S3 Vectors as "ideal for workloads where queries are less frequent", which describes agent memory exactly: an agent queries a user's memories a handful of times per conversation, not thousands of times per second.

	FAISS	Amazon S3 Vectors	Dedicated vector database
Type	In-process library	AWS vector storage	Full database engine
Examples	—	—	OpenSearch, Qdrant, Weaviate, Milvus, pgvector, Chroma
Semantic accuracy	✅ same	✅ same	✅ same
Infrastructure	None — pip install	None — fully managed	Self-hosted or managed
Max vectors	Process memory	Up to 2 billion per index	Depends on deployment
Query latency	~0.09 ms	~100–200 ms	Sub-10 ms at high QPS
Hybrid search	❌	❌	✅ most support it
Best for	Prototype / local agent	Cloud agent, infrequent queries	High QPS, advanced filtering, production search

The decision:

You need	Pick	Why
Facts under known keys (profile, preferences)	Key-value (post 1)	Exact and instant; don't pay ~510 ms of embedding for a lookup
Semantic search, local / prototype	FAISS	Zero infrastructure, pip install, in-process
Semantic search, cloud / infrequent queries	S3 Vectors	Purpose-built AWS vector storage, subsecond latency, up to 2 billion vectors, no infrastructure to manage
High QPS, hybrid search, or advanced filtering	Dedicated vector DB	OpenSearch, Qdrant, Weaviate, Milvus, pgvector, Chroma
Multi-hop questions over relationships	Graph (next post)	Semantic search finds pieces; it can't follow edges between them

What this demo does not cover: FAISS and S3 Vectors are storage backends. They store vectors and retrieve by similarity. Building what to remember (extracting specific facts from conversations, deduplication, structured memory across sessions) is handled by managed memory services like Amazon Bedrock AgentCore Memory. That technique is the topic of a future post in this series.

How does the agent choose between key lookup and semantic search?

From the tool docstrings, on its own. The demo's last test attaches both recall tools to one Strands agent:

@tool
def recall_by_key(key: str) -> str:
    """Recall a memory when the question maps to a known identifier.
    Use when the user asks about a stored field: "my preferred cabin",
    "my home airport"..."""

@tool
def recall_semantic(question: str, top_k: int = 3) -> str:
    """Recall memories by meaning when no key is obvious.
    Use for open questions: "what should I avoid eating on this trip?"..."""

Asked the dinner question, the agent calls recall_semantic; asked "what cabin do I prefer?", it calls recall_by_key. No routing logic, no prompt engineering. The when to use this sentence at the top of each docstring is what the model reads to decide. Write that sentence carelessly and the agent pays embedding latency for profile lookups.

How do you ask an AI coding assistant to build this?

The quality of the semantic search implementation your assistant builds depends on the decisions you name in the prompt. Unnamed, it will default to embedding everything and querying one big index. These five instructions encode what this post measured:

"Add semantic search only for questions that don't map to keys; keep profile facts in key-value state." Otherwise the assistant defaults to embedding every query, including exact lookups that already have a known key.
"Embed each memory once, at write time; only the question gets embedded at query time." Assistants love re-embedding the whole store per query.
"Use one embedding function for storage and queries, and state the model and dimensions." Mixed embedders produce silent garbage similarity scores.
"Give me two recall tools with 'when to use' docstrings: by key, and by meaning." The agent routes per question from those sentences; no router code.
"Make persistence explicit: in-process index for a prototype, managed vector storage for anything that must survive a restart, and prove it with a fresh-client test that still sees every vector."

The companion repo implements and measures all five. Run it to see each decision play out.

How do you run the demo?

git clone https://github.com/elizabethfuentes12/stop-ai-agents-losing-memory-sample-for-aws
cd stop-ai-agents-losing-memory-sample-for-aws/02-vector-memory-demo
uv venv && uv pip install -r requirements.txt
uv run python test_vector_memory.py

Needs AWS credentials (aws configure) for Titan embeddings and S3 Vectors. The demo creates the vector bucket and index automatically if they don't exist. OPENAI_API_KEY is only needed for the agent conversation in the notebook (or swap one line for Amazon Bedrock); the retrieval measurements run without any LLM.

FAQ

Is a vector database the same as AI agent memory?
No. A vector database is one possible backend for one memory type (retrieval by meaning). Agent memory is the whole system: key-value state, vector or graph storage, selection rules, and hygiene. Many production agents need vector retrieval without a vector database.

Can I use a vector database as agent memory?
Yes, for memories you'll query by meaning. But route keyed facts (preferences, settings) to key-value storage first: a direct lookup costs nothing, while every vector query pays the question-embedding call (~510 ms with Titan V2) before the index is even touched.

When do I need something beyond S3 Vectors?
When your query pattern changes. Dedicated vector databases such as OpenSearch, Qdrant, Weaviate, Milvus, pgvector, and Chroma are built for high QPS, hybrid keyword+vector search, aggregations, and advanced filtering. S3 Vectors is purpose-built for infrequent queries: it handles up to 2 billion vectors per index with subsecond latency, which covers agent memory workloads well past prototype scale.

What's the real latency difference between FAISS and S3 Vectors?
Measured on the same memories: 0.09 ms vs 195 ms per query. But embedding the question adds ~510 ms to both, so end-to-end it's ~0.5 s vs ~0.7 s. The index is rarely your bottleneck; the embedding call is.

Why did my semantic search return the wrong memories?
The most common causes: the store and the queries use different embedding models or dimensions, memories were embedded with stale text, or keyed facts polluted the index. Keep one embedder for everything, embed at write time, and keep profile facts out of the vector store.

Resources

Companion repo — demo 02 with the measured tests and notebook
Amazon S3 Vectors — User Guide and limitations
Amazon Titan Text Embeddings V2
FAISS, Meta's similarity search library
Zep: A Temporal Knowledge Graph Architecture for Agent Memory, Rasmussen et al., 2025
From RAG to Memory: Non-Parametric Continual Learning for LLMs (HippoRAG 2), 2025

Gracias!

🇻🇪 Dev.to Linkedin GitHub Twitter Instagram Youtube

Elizabeth Fuentes LFollow

I help developers build production-ready AI applications through hands-on tutorials and open-source projects.

Running Kiro Crew in Docker on Windows

Matheus Guimaraes — Wed, 12 Aug 2026 20:12:47 +0000

I've been playing with Kiro Crew recently, and when I went to get it running on my Windows machine I had a decision to make.

Kiro Crew doesn't currently have a Windows desktop app. You can still run it natively on Windows, but the documented route involves installing and running the Gateway from source.

But then, while looking through the Kiro Crew GitHub repository, I noticed another option that immediately caught my attention: there's an official Docker image!

Docker is already a familiar part of the development workflow for many of us, and a container felt like a nice, clean way to get Kiro Crew running without installing it from source.

So that's the route I took.

It worked, but along the way I ran into an interesting security detail that made the setup slightly less straightforward than simply running a container.

And, as it turns out, that's actually a good thing.

What we're going to do

By the end of this post, we'll have Kiro Crew running in Docker on Windows, with its agent sandbox enabled and without giving the container more privileges than it actually needs.

I'm using Docker Desktop with WSL 2, so you'll want to have those installed before following along.

You can check your WSL installation with:

wsl --version

With that out of the way, let's get Kiro Crew running.

Starting with the official container image

The Kiro Crew team publishes a public container image, so we don't need to build anything ourselves or even authenticate with a container registry. Nice and easy.

Before doing anything else, I created a directory to keep the files for this setup together:

mkdir kiro-crew
cd kiro-crew

Now, at first glance, running Kiro Crew looks like it should be as simple as starting the official image.

And technically, the Gateway itself will run.

But there's another security boundary inside that container that we need to understand before we can start it properly.

Wait... a sandbox inside a container?

This was the interesting part for me.

We're already putting Kiro Crew inside a Docker container, which gives us an isolation boundary between Kiro Crew and our Windows host.

But Kiro Crew adds another boundary of its own.

Agent commands aren't simply executed with access to everything available to the main Kiro Crew process. On Linux, Kiro Crew creates an internal user-namespace sandbox for those commands.

Conceptually, our setup looks something like this:

Windows
└── Docker container
    └── Kiro Crew
        └── Agent sandbox

Why sandbox an agent that's already inside a container?

Because the two boundaries are protecting different things.

The container isolates Kiro Crew from our host. The inner sandbox isolates agent commands from sensitive state available to Kiro Crew itself.

For example, Kiro Crew's sandbox hides credential directories such as ~/.aws and ~/.ssh from agent subprocesses by bind-mounting empty directories over them. So if an agent-executed command tries to access one of those directories, it simply sees an empty directory rather than our AWS credentials or SSH keys.

That means the Gateway can have the credentials it needs to do its job without automatically making those credentials readable by commands executed by an agent.

That's a pretty important distinction when we're giving an AI agent the ability to execute commands.

Where Docker gets in the way

There's one complication.

To create that inner sandbox, Kiro Crew needs Linux system calls including:

unshare(CLONE_NEWUSER)
unshare(CLONE_NEWNS)

Docker's default seccomp security policy blocks those operations.

So if the Kiro Crew container can't create its inner sandbox, it doesn't quietly shrug its shoulders and run agent commands without one.

It fails closed, meaning that when the security mechanism can't be established, access is denied rather than silently falling back to a less secure mode.

The Gateway and dashboard can still run, but agent command execution remains disabled.

I actually really like this design! What initially looks like an extra hurdle in getting the container running is Kiro Crew refusing to silently weaken its security model.

So how do we fix it?

The tempting solution and the better solution

There are a few ways we could approach this.

One option is to simply tell Kiro Crew that we accept running agent commands without the inner sandbox. Kiro Crew provides an environment variable for exactly that:

KIROCREW_ALLOW_UNSANDBOXED=1

We could pass that into our container and Kiro Crew would allow agent execution, leaving Docker itself as our only isolation boundary.

We could also reach for the rather large hammer:

--privileged

That would make the sandbox work, but it does so by granting the container extremely broad privileges and removing many of Docker's normal isolation restrictions.

That's a much bigger security concession than we actually need.

What we really want is much narrower:

Allow the operations Kiro Crew needs to create its sandbox while keeping the rest of Docker's security restrictions in place.

And this is another nice detail about the Kiro Crew implementation: the team already provides a seccomp profile specifically for this!

So we don't have to create one ourselves.

Downloading the Kiro Crew seccomp profile

From the kiro-crew directory we created earlier, download the official Kiro Crew seccomp profile:

curl -fsSL https://raw.githubusercontent.com/kirodotdev/KiroCrew/main/docker/seccomp/kirocrew-seccomp.json \
  -o kirocrew-seccomp.json

You should now have:

kiro-crew/
└── kirocrew-seccomp.json

Having trouble downloading it from WSL?

I happened to be dealing with a DNS issue in my WSL environment when I did this, so curl couldn't resolve GitHub. If you happen to run into the same thing, there's nothing special about downloading the file through curl: you can download kirocrew-seccomp.json directly from the Kiro Crew GitHub repository in your browser and place it in this directory manually, which is what I did.

Now we can start the container using that profile.

Running Kiro Crew

Run:

docker run -d --name kirocrew \
  -p 127.0.0.1:5476:5476 \
  -v kirocrew-home:/home/kirocrew \
  --security-opt seccomp=kirocrew-seccomp.json \
  ghcr.io/kirodotdev/kirocrew:stable

There are a couple of things worth noticing here.

We're only publishing port 5476 on the host's loopback interface, so the dashboard isn't being exposed to the rest of our network.

We're also creating a named Docker volume:

kirocrew-home

Kiro Crew keeps its persistent state under /home/kirocrew, including its configuration and Kiro CLI credentials. That means our state can survive replacing or upgrading the container.

And, most importantly for what we've just discussed, we're passing the Kiro Crew seccomp profile with:

--security-opt seccomp=kirocrew-seccomp.json

The container can now create the inner namespace sandbox while Docker's other default security restrictions remain in place.

Let's open it

At this point I did what I imagine most developers would do.

I opened:

http://localhost:5476

And instead of the Kiro Crew dashboard, I was greeted by a message telling me I was missing a token.

Another security measure!

Simply being able to reach port 5476 isn't enough to get access to the dashboard. Kiro Crew also requires a bearer token, so someone who can reach the Gateway still needs to authenticate before they can use it.

So, there's one more part of the setup we need to do.

Actually, two.

Authenticating Kiro CLI

Kiro Crew's agent runtime uses kiro-cli, so first we need to authenticate the CLI running inside our container.

We can do that without opening an interactive shell ourselves:

docker exec -it kirocrew kiro-cli login

Follow the authentication flow and log in with the identity you use for Kiro.

Once authentication succeeds, those credentials are stored in the kirocrew-home volume we created earlier, so they survive container upgrades.

But that authenticates the agent runtime.

We still need access to the dashboard.

Getting our dashboard token

Every request to the Kiro Crew dashboard requires a token.

We can mint a temporary login link from the running container:

docker exec kirocrew kirocrew token --ttl 2h

Kiro Crew will print a URL containing the token.

It will look roughly like:

http://localhost:5476/?token=...

Open that URL in your browser and...

We're in!

And with that, we have Kiro Crew running nicely inside Docker on Windows, without having to build it from source and without unnecessarily weakening either of its isolation boundaries.

Now I just need someone to explain why the Solarized theme is green instead of yellow. 😄

References

7 Tips to Make Your AI Agent More Predictable

Salih Guler — Tue, 11 Aug 2026 10:20:35 +0000

After months of building with AI coding tools, I found the difference between generated code that works and generated code that ships comes down to how you communicate with the AI. I have been sharing these lessons in a talk called "It's Dangerous to Code Alone! Take This: Developer's AI Survival Guide" and people keep asking me to write them down. How big is the gap? An MIT study across 100,000+ developers found that AI agents boosted code written by ~180%, while code that actually shipped to production rose by only ~30%.

To demonstrate these tips, I built a link-sharing platform so my teammates can share resources without juggling multiple QR codes. I generated the frontend with Codex GPT 5.6 Sol and Figma MCP, and I am adding an AWS Blocks backend to swap out local mocks with real cloud infrastructure. You can find all the prompts in this repository.

All of these tips are applicable to greenfield projects as well. I can't promise you it is going to have the 42 effect :)

#1 Talk to AI in Clear Prompts

Each model reacts to prompts differently. The clearer you get, the faster you achieve your goal.

You also need to remember that now we don't only have models, we also have effort levels. If you are not mindful about which model you are running with which effort level, you will have a hard time getting the results you want.

Here are some general rules I follow (you can check the BUILD_PROMPT.md and the AWS Blocks skill in the repo for the full picture):

Zero-Shot

Describe what you want. Works for simple, well-defined tasks.

Here is my frontend build prompt. One sentence, clear outcome:

Build "Some Useful Links" — a LinkTree-style web application using
Next.js with SSR enabled. The complete visual design specification
is in `DESIGN_SPEC.md` and reference screenshots are in the
`design-previews/` folder. Implement the design pixel-perfectly.

And for the backend migration to AWS Blocks:

Replace the local JSON mock services in src/lib/services/local/ with
AWS Blocks implementations. The service registry (index.ts) is the
only file that should change in the existing codebase. Frontend must
not be modified.

Both are zero-shot: one clear task, no ambiguity.

Few-Shot

Show examples. Input, output. Input, output. The model picks up the shape. Research shows the format matters more than whether the examples are perfectly correct.

In my BUILD_PROMPT.md, I use this for the service registry pattern. I show the AI what an implementation swap looks like:

// src/lib/services/index.ts
import { LocalAnalyticsStore } from './local/analytics-store.local';
import { LocalLinkStore } from './local/link-store.local';
import { LocalVisitTracker } from './local/visit-tracker.local';

// SWAP POINT: Replace these with cloud implementations
export const analyticsStore = new LocalAnalyticsStore();
export const linkStore = new LocalLinkStore();
export const visitTracker = new LocalVisitTracker();

When I ask the AI to build the AWS Blocks backend, it sees this pattern and knows the target: create a BlocksAnalyticsStore, BlocksLinkStore, and BlocksVisitTracker that implement the same interfaces, then swap them in index.ts. I do not need to explain the concept of dependency injection. The example IS the explanation.

Chain-of-Thought

Force the model to reason step by step before acting. For debugging, architecture decisions, or anything multi-step, this cuts logical errors significantly.

I use this when asking the AI to plan the AWS Blocks migration:

Before writing any code, analyze the existing service interfaces in
src/lib/services/interfaces/. For each interface method, determine:
1. Which AWS Blocks building block maps to it (DistributedTable, KVStore, FileBucket, etc.)
2. What the key schema should be to support the query patterns
3. Whether the method needs authentication (check if the frontend
   calls it from an admin route or a public route)

Write your analysis as a numbered plan. I will review it before you
start implementing.

The AI produces a plan I can review before it writes a single line of code. Without this step, it would just start building and often pick the wrong storage pattern for a given query.

#2 Set Absolute Boundaries

Use words like MUST, NEVER, ALWAYS, and STRICTLY FORBIDDEN. Avoid weak phrasing like "Please try to," "It is preferred," or "Usually we do."

Here is a comparison from my project. The frontend BUILD_PROMPT.md sets boundaries like this:

All backend infrastructure must be local mocks — no cloud dependencies.
The mocks must be documented clearly enough that another AI agent or
developer can swap them for any cloud provider without restructuring.

And the AWS Blocks skill sets boundaries for the backend side:

Backend lives in `aws-blocks/index.ts`. Frontend imports from
'aws-blocks' (workspace package). The `client.js` is auto-generated
— never edit it.

Both are direct, absolute, and leave no room for interpretation.

Prioritize negative boundaries (Guardrails)

Telling the AI what NOT to do is often more effective than listing everything it should do.

Frontend (AGENTS.md):

- Do not add cloud SDKs, deployment configuration, external persistence,
  or source-controlled credentials unless the task explicitly requires them.
- Import services from `@/lib/services`; components and route handlers
  must not import `src/lib/services/local/*` directly.
- Keep unrelated refactors and generated-file churn out of focused changes.

Backend (AWS Blocks skill):

- Adding to an existing project? Scaffold into a temp dir, copy only
  `aws-blocks/` folder, then manually merge workspace config, scripts,
  and dependencies. The scaffolder overwrites root package.json,
  tsconfig.json, vite.config.ts, .gitignore.
- Never edit index.cdk.ts, index.handler.ts, or client.js — these are
  auto-generated.

#3 Give Your AI Persistent Context

You need to steer the agent in the correct direction. AI tools have dedicated files for this purpose:

AGENTS.md
CLAUDE.md
Kiro steering files (.kiro/steering/)
Kiro skills (.kiro/skills/)

Some of these are loaded every session (steering files), giving the AI persistent rules. Others are loaded on demand (skills), giving the AI specialized knowledge only when it needs it. Both keep your context window lean.

Always-loaded: Steering files

For the frontend, I have an AGENTS.md at the root that covers the full Next.js application:

# AGENTS.md

## Project Overview
Some Useful Links is a local-first, multi-page link-sharing application
built with Next.js App Router, React, strict TypeScript, and Tailwind CSS.

## Commands
npm install
npm run dev
npm run validate:links
npm run lint
npm run build

## Architecture
- src/app: App Router pages, layouts, route handlers
- src/components: UI grouped by admin, analytics, layout, links, share
- src/lib/services/interfaces: Backend-neutral service contracts
- src/lib/services/local: Local JSON-backed implementations
- src/lib/services/index.ts: The only provider registration and swap point

I also have two Kiro steering files that enforce cross-cutting rules regardless of the task:

TypeScript rules (.kiro/steering/typescript.md) — enforces strict typing and build validation:

# TypeScript Project Instructions

## Workflows & Validation
- Pre-completion Check: Before completing any task or reporting success,
  you MUST run `npm run build` in the terminal.
- Do not consider a task finished if the build command returns errors. Fix
  the errors first.

## Coding Conventions
- Strict typing is enforced. You are strictly forbidden from using the
  `any` type.
- Always define and apply the exact, correct types and interfaces for all
  variables, function parameters, and return values.
- You are STRICTLY FORBIDDEN from using @ts-ignore.
  If unavoidable, use @ts-expect-error with a detailed comment.

Agent behavior rules (.kiro/steering/agent.md) — controls what the AI can and cannot do on its own:

# Agent Behavior Rules

## File and Folder Boundaries
- DO NOT create any new Markdown files unless explicitly instructed by
  the user.
- STRICTLY FORBIDDEN to auto-generate changelogs or documentation.
- You MUST update the existing README.md if your changes alter the
  project's public API or architecture.

## Technology Boundaries
- You MUST ALWAYS use the Strands Agents library with TypeScript for any
  agent development.
- You are STRICTLY REQUIRED to use Claude Haiku 4.5 from Amazon Bedrock
  for all agent models.
- You MUST ALWAYS use React and Vite with TypeScript for web development.
- NEVER write or generate unit tests unless the user explicitly commands
  it.

## Security Boundaries
- NEVER commit or hardcode sensitive information (client secrets, API
  keys, client IDs, resource IDs).

## Git Boundaries
- Commits MUST stay under 150 lines of source code.
- Every commit: single-sentence summary, blank line, detailed explanation
  (max 20 lines).
- You MUST append `(Kiro)` to the author name using:
  git commit --author="[Git Username] (Kiro) <[User Email]>"

These prevent the common annoyances: AI generating unwanted test files, committing giant diffs, sneaking any types past the compiler, or littering the repo with markdown files nobody asked for.

On-demand: Skills

Steering files are always loaded. But what about capabilities that are only needed sometimes? You do not want to load everything upfront because that wastes context.

A Skill is a reusable, discoverable capability. The AI loads it only when it becomes relevant to the current task. The most important part of a Skill is the name and description. That is how the AI decides whether to use it.

My AWS Blocks skill activates with this frontmatter:

---
name: building-aws-blocks-apps
description: "Builds fullstack TypeScript applications on AWS using"
  @aws-blocks/blocks. Use when working with any Building Block
  (KVStore, DistributedTable, Agent, AuthBasic...), ApiNamespace,
  BlocksStack, or the create-blocks-app CLI.
---

The main SKILL.md is the overview: decision guides, project structure, quick start. Detailed reference lives in separate files:

.kiro/skills/aws-blocks-development/
├── SKILL.md                    # Overview + decision guide (under 200 lines)
├── CORE-ARCHITECTURE.md        # Scope, ApiNamespace, JSON-RPC, CORS
├── TROUBLESHOOTING.md          # Common errors and fixes
└── blocks/
    ├── auth-basic.md           # AuthBasic patterns
    ├── distributed-table.md    # DistributedTable patterns
    ├── api-namespace.md        # ApiNamespace deep dive
    └── ... (20+ block files)

When the AI needs to implement authentication, it loads blocks/auth-basic.md. When it needs to set up a database, it loads blocks/distributed-table.md. It does not carry all 122 KB of reference material in every conversation.

Keep it lean

Keep the root file under 200 lines. My AGENTS.md is 127 lines. The AWS Blocks SKILL.md is the overview (under 200 lines), with detailed reference files loaded on demand.

Use the "Router Pattern": a root file that points to detailed references when needed. The AWS Blocks skill does exactly this with its block reference table.

Separate context from instructions

Project Context tells the AI where it is:

"This is a Next.js 14 App Router project using Tailwind CSS."

Actionable Rules tell the AI what to do:

"Import services from @/lib/services; components must not import src/lib/services/local/* directly."

Keep these separate. Context helps the AI orient itself. Rules constrain its behavior.

#4 Manage Your Context Window

Your AI sees everything in a stack:

System instructions + steering files
Full conversation history (every message)
Tool output (files, terminal, search results)
Your current request

Performance degrades at 25% capacity, not 100%. You do not have the full context window available. The degradation starts much earlier than you think.

Context rot

Long sessions lead to the model "forgetting" earlier decisions, fixing one thing and breaking two others. Hallucinations increase as context fills up and your original constraints stop being followed.

I have seen this firsthand. On the frontend side, I asked my AI to follow the service registry pattern from my AGENTS.md. After 15 turns of unrelated work, it started importing directly from src/lib/services/local/, exactly what I told it not to do.

On the backend side, I had a session where I was building multiple API methods with AWS Blocks. After building the analytics endpoints, I asked it to add authentication. It generated a whole custom auth system instead of using the AuthBasic block that was in the skill file. The context was too full for it to reference back.

Fighting context rot

Start fresh sessions for each new task
Keep steering files under 200 lines
Summarize progress in a file the AI can re-read, do not rely on conversation history
Keep interactions to 5–7 turns per task max

#5 Follow a Spec-Driven Development Process

Vibe coding skips everything we know about building software: planning, analysis, design, testing, maintenance. All of it gone.

Vibe coding works for prototyping and tiny fixes. But for anything beyond that, you need structure.

Spec-Driven Development (SDD) is a methodology where detailed, unambiguous requirements are written and agreed upon before any actual coding begins. The spec is the contract between you and your AI.

Frontend spec (from `BUILD_PROMPT.md`)

<task>
Build "Some Useful Links" — a LinkTree-style web application using Next.js
with SSR enabled. The complete visual design specification is in
`DESIGN_SPEC.md` and reference screenshots are in the `design-previews/`
folder.

All backend infrastructure must be local mocks — no cloud dependencies. The
mocks must be documented clearly enough that another AI agent or developer
can swap them for any cloud provider without restructuring.
</task>

<architecture>
1. Framework: Next.js (App Router) with Server-Side Rendering enabled
2. Styling: Tailwind CSS with a custom theme from the design spec
3. Backend: Local mocks only — no cloud services, no external APIs
</architecture>

Backend spec (from `MIGRATING_TO_CLOUD_PROMPT.md`)

<task>
Replace the local JSON mock services in `src/lib/services/local/` with AWS
Blocks implementations. The existing service interfaces in
`src/lib/services/interfaces/` are the contract. The service registry
(`src/lib/services/index.ts`) is the only file that should change in the
existing codebase.

The frontend, routing, components, and design must remain untouched.
</task>

<architecture>
1. Backend runtime: AWS Blocks (`aws-blocks/index.ts`)
2. API layer: ApiNamespace with methods that mirror the existing service
   interface contracts
3. Auth: AuthBasic for admin routes (analytics dashboard, page management)
4. Data — Link pages: DistributedTable (stores page configurations and
   link entries)
5. Data — Analytics: DistributedTable (stores daily aggregate snapshots
   per page slug and date)
6. Data — Visit events: DistributedTable (stores raw page-view, link-click,
   and share events)
7. Hosting: Blocks Hosting for the Next.js frontend
</architecture>

<acceptance_criteria>
- [ ] All existing frontend functionality works unchanged
- [ ] `npm run dev` starts both frontend and AWS Blocks local server on
      port 3000
- [ ] Admin routes require AuthBasic login
- [ ] Click tracking persists events to DistributedTable
- [ ] `npm run build` completes without TypeScript errors
- [ ] `npm run deploy` deploys the full stack to AWS
</acceptance_criteria>

The AI knows exactly what to build, what the constraints are, and what "done" looks like. No ambiguity on either side.

Writing good specs

Start with Goals and Non-Goals: what are you building? What are you explicitly NOT building?
Define your tech stack and project structure
Add executable commands so the AI knows how to build and run things
Write clear acceptance criteria so everyone knows when the work is done
Set your boundaries: what should the AI always do? What should it ask you first?

#6 Use MCP to Extend AI Beyond Its Knowledge

Model Context Protocol (MCP) is an open standard for connecting AI to the outside world. With MCP, your AI can:

Connect to data sources (local files, databases, APIs)
Run tools (search engines, calculators, linters)
Follow workflows and specialized prompts
Access knowledge that did not exist when it was trained

Right now there is an MCP server for almost everything: GitHub, Slack, databases, documentation, cloud services.

In my project, I used this in two places:

Frontend: I connected Figma MCP so the AI could reference my actual design system when generating components. Instead of describing colors and spacing in text, it pulled the tokens directly from the Figma file.

Backend: AWS Blocks is a new framework. The AI does not know its API surface from training data. Instead of pasting documentation into the chat (wasting context), I added an MCP server that gives the AI access to the AWS Blocks docs and API references on demand. It queries what it needs, when it needs it.

The result: zero hallucinated API calls. The AI uses new ApiNamespace(scope, 'api', (context) => ({...})) because it can look up the actual signature, instead of guessing something like createApi(...).

#7 Know When to Vibe Code and When to Spec

Some tasks deserve a spec. Others work fine as a quick conversation with the AI. Knowing which approach to use is what saves you time.

Use vibe coding when:

Prototyping something
Making smaller changes and tiny fixes
Learning syntax and a new technology
Automating one-off tasks

Use Spec-Driven Development when:

Building production software
Working in a team
Designing complex architecture
Working on brownfield projects (like adding AWS Blocks to an existing Next.js app)

In my project, I vibe coded the initial design exploration with Figma MCP. But the moment I started building the actual app and the backend migration, I switched to specs. The frontend BUILD_PROMPT.md and the backend AWS Blocks skill together gave the AI everything it needed to produce consistent, predictable results.

Wrapping Up

I am currently finishing the AWS Blocks backend for the link-sharing project and deploying it. I will write up that process in the next post.

You can find the full project, including the BUILD_PROMPT.md, AGENTS.md, MIGRATING_TO_CLOUD_PROMPT.md, and the AWS Blocks skill files in this repository.

Stop Your AI Agent Forgetting User Preferences: Key-Value Memory

Elizabeth Fuentes L — Tue, 04 Aug 2026 23:12:24 +0000

Here's a test most AI agents fail. A brand-new user searches flights, books one in business class, and asks: "what do you recommend based on what you know about me?" The agent answers beautifully: business class, non-stop, exactly their taste. Then the process restarts. Same user, same question, and now the answer is generic: the cheapest economy fare. Everything the agent "knew" is gone.

Persistent memory for an AI agent means storing structured facts outside the conversation, in a store that outlives the process. This post builds that for the most common case, user preferences, with the smallest memory that works: a key-value store, measured climbing a durability ladder from process state to local disk to Amazon S3. Everything below runs from the companion repo with live flight data, so the numbers come from real runs, not slideware.

(This is post 1 of a series; the intro post maps all the memory types. The code uses Strands Agents, an open source SDK; the pattern carries over to any agent framework.)

Isn't the conversation history already memory?

Within a session, yes, and that's exactly what fools people. The common claim is "stateless agents forget between turns." That claim is false, and you can prove it in four lines. Agent frameworks keep the conversation history between calls on the same agent instance (in Strands it's agent.messages) and send it to the model on every turn. So an agent with zero memory tooling still "remembers":

User: Book the cheapest business option.
Agent: Your flight from JFK to Paris CDG has been booked... ✅

User (2 turns later): ...what do you recommend based on what you know about me?
Agent: here are some business class options... ✅  ← personalized!

agent.state.get("user_preferences")  → None      ← nothing was learned
len(agent.messages)                  → 12        ← the booking lives ONLY here

That's a real run. The agent personalized turn 3 because "business class" was still sitting in the transcript. Don't let that fool you into thinking it learned something. Three problems hide under that lucky answer:

Nothing structured exists. There is no profile to query, rank offers by, display to the user, or persist. The knowledge is prose inside a transcript.
The transcript gets trimmed. Long sessions need a sliding window or summarization, and the booking scrolls out with the old messages.
The transcript dies with the process. In production, every new request may be a new process. Restart the agent and ask the same question:

[after restart] User: ...what do you recommend based on what you know about me?
[after restart] Agent: I recommend the Iberia flight for $366.85...  ← cheapest economy. Generic.

The research literature calls this cross-session loss memory decay (MemoryOS, Kang et al. 2025). The model isn't broken; models are stateless by design. Memory belongs to the harness you build around them.

So the honest framing is this: the transcript is a context mechanism, not a memory system. A memory system needs structure (facts you can query) and durability (facts that survive the process). Key-value state gives you both.

What does the experiment measure?

One variable. Same model, same three-turn conversation, same live flight data (the Duffel sandbox: real offers, real carriers). The only thing that changes between tests is where memory lives:

Test	Memory wiring	Structured profile	Survives restart
1	none (transcript only)	No	No
2	`agent.state`	Yes	No
3	+ `FileSessionManager`	Yes	Yes (local disk)
4	+ `S3SessionManager`	Yes	Yes (Amazon S3)

The conversation, verbatim in every test:

Turn 1: "Find me flights from JFK to Paris CDG on 2026-09-15, business class."
Turn 2: "Book the cheapest business option." ← the memory moment
Turn 3: "Now I need Paris CDG to Tokyo Haneda — what do you recommend based on what you know about me?"

How does the agent learn preferences without a form?

From actions. Nobody fills in a "preferences" form; the user books a flight, and that action reveals their cabin, their tolerance for stops, their price band, their carrier. The stateful book_flight tool captures all of it as a side effect of doing its job:

from strands import Agent, tool, ToolContext

@tool(context=True)
def book_flight(offer_id: str, tool_context: ToolContext) -> str:
    """Confirm a booking AND learn the user's preferences from their choice."""
    offer = flights_api.get_offer(offer_id)          # the REAL chosen offer

    # First booking ever? state returns None → start an empty profile.
    prefs = tool_context.agent.state.get("user_preferences") or {}

    # The choice reveals the preferences. No form involved:
    prefs["preferred_cabin"] = offer["cabin"]                      # "business"
    prefs["prefers_nonstop"] = all(s["stops"] == 0 for s in offer["slices"])
    prefs["typical_price"]   = {"min": ..., "max": ...}            # price band

    tool_context.agent.state.set("user_preferences", prefs)
    return json.dumps({"status": "CONFIRMED", "preferences_updated": prefs})

Two Strands pieces make this work:

@tool(context=True) injects a ToolContext, which carries a reference to the running agent.
tool_context.agent.state is the key-value store: "key-value storage for stateful information that exists outside of the conversation context" (Strands agent state docs). It is not sent to the model; tools read and write it directly.

And the read path: the next search_flights call loads the profile and ranks real offers with deterministic code, instead of hoping the model re-reads the transcript:

prefs = tool_context.agent.state.get("user_preferences") or {}
offers = flights_api.search_offers(origin, destination, date,
                                   prefs.get("preferred_cabin") or cabin_class)
if prefs:
    offers.sort(key=score_by_profile, reverse=True)   # nonstop +10, in budget +5...

The baseline (Test 1) uses the same tools with the state lines removed: plain @tool, no ToolContext. Identical business logic; no way to remember. That's the whole difference between the failing agent and the learning one.

After Test 2, this profile exists, and it's inspectable, queryable, and persistable:

{
  "preferred_cabin": "business",
  "prefers_nonstop": true,
  "carriers_flown": ["British Airways"],
  "typical_price": {"min": 1382.22, "max": 1382.22}
}

How does persistent memory survive restarts? The durability ladder

agent.state fixed structure, but it lives in the Python process. Restart and it's gone, exactly like the transcript. Durability is a separate decision, and in Strands it's one constructor argument.

Rung 2 → 3: survive a restart (local disk)

from strands.session import FileSessionManager

agent = Agent(
    model=MODEL,
    tools=[search_flights, book_flight],
    session_manager=FileSessionManager(
        session_id="traveler-demo",     # same id = same user
        storage_dir="./sessions",
    ),
)

The demo simulates the restart honestly: agent A books (building the profile), then a brand-new agent instance with the same session_id is created. Measured output:

Session A learned:  {"preferred_cabin": "business", "prefers_nonstop": true, ...}
Session B restored: {"preferred_cabin": "business", "prefers_nonstop": true, ...}
State survived restart: True

Agent B answers turn 3 personalized, without the conversation that taught it. The knowledge moved from the transcript to the store.

Rung 3 → 4: survive in the cloud (Amazon S3)

from strands.session import S3SessionManager

agent = Agent(
    model=MODEL,
    tools=[search_flights, book_flight],
    session_manager=S3SessionManager(
        session_id="traveler-demo",
        bucket="your-sessions-bucket",   # plain JSON objects — no vectors
        prefix="kv-memory-demo",
    ),
)

Same interface, same test, same True, except now the session is plain JSON objects in a bucket. Why this is the production rung: nothing to provision or mount (a durable filesystem on Lambda or Fargate means wiring up EFS: VPC, mount targets, security groups), and any compute instance can restore the session. The state stops being tied to one machine.

Note what this is not: no embeddings, no vector database, no similarity search. Regular S3. A user profile is a fact you know the name of (user_preferences), and key lookup is exact, instant, and free of embedding costs.

What do the measured results show?

From the repo's four-test run (live Duffel + Open-Meteo calls):

Test	Memory wiring	Learned prefs	Survived restart
1 — no memory tools (transcript only)	`agent.messages` only	False	False
2 — `agent.state`	key-value in process	True	—
3 — + `FileSessionManager`	key-value on disk	True	True
4 — + `S3SessionManager`	key-value in S3	True	True

The line that matters is Test 1's restart: the same model that personalized perfectly two turns earlier recommended a $366 economy fare to the same user after one process restart. Memory is wiring, not model.

When is key-value memory the wrong choice?

When the question doesn't name a key. Key-value memory answers questions that map to a known name. Store dietary_notes: "vegetarian, severe shellfish allergy" and ask "what are my dietary notes?": found. Ask "what should I avoid eating at dinner?": no key matches, and the answer sits in the store unreachable. That failure needs retrieval by meaning (vector memory, the next post in this series), and questions that hop across relationships need a graph. The intro post maps all four types.

Also outside this pattern's scope: deciding what's worth storing (selective memory), keeping poisoned content out of the store (hygiene), and remembering why the agent decided (decision traces). Later posts cover each, in the same measured format.

Start here anyway. Profile, preferences, settings, counters: facts with obvious names cover more of production personalization than people expect, with zero retrieval infrastructure.

How do you ask an AI coding assistant to build this?

Most agent code today is written with an AI assistant, and the quality of the memory you get depends on the design decisions you name in the prompt. If you don't name them, the assistant defaults to the transcript, and you ship the Test 1 agent. These five instructions encode everything this post measured; paste them into your assistant and adapt the domain:

"Store user facts in the agent's key-value state, not in the conversation." Name the store (in Strands, agent.state); otherwise the assistant will 'remember' by re-reading the transcript.
"Learn preferences from user actions inside the tools." The booking/purchase/rejection tool writes what the choice reveals. If you don't say this, you get a "save preference" tool the model may never call.
"Read the profile back in code, not in the prompt." Search and recommendation tools load the stored profile and rank deterministically, instead of hoping the model notices.
"Persist state with a session manager keyed by user id." This is the one line that survives the restart. Ask for local files in development and object storage (Amazon S3) in production.
"Prove it: build a test where a brand-new agent instance with the same session id still knows the user." If the assistant can't show that test passing, the memory isn't persistent, whatever the code claims.

That's the whole technique. The demo below is those five instructions, implemented and measured, so you can compare what your assistant produces against a working reference.

How do you run the demo?

git clone https://github.com/elizabethfuentes12/stop-ai-agents-losing-memory-sample-for-aws
cd stop-ai-agents-losing-memory-sample-for-aws/01-key-value-memory-demo
uv venv && uv pip install -r requirements.txt
uv run python test_key_value_memory.py

Needs OPENAI_API_KEY (or swap one line for Amazon Bedrock; the README shows how) and a free Duffel sandbox token for live flight data. Test 4 additionally needs AWS credentials and a bucket name; the demo creates the bucket if it doesn't exist and skips gracefully if not configured. There's an interactive notebook version with the same tests.

FAQ

How do I give an AI agent persistent memory?
Store structured facts outside the conversation (a key-value store your tools write), then persist that store beyond the process: session files on disk for development, objects in cloud storage such as Amazon S3 for production. The conversation transcript alone is not persistent; it dies with the process.

Why does my AI agent forget everything after a restart?
Because the only place the information existed was the conversation history, which lives in process memory. Models are stateless; frameworks keep the transcript between calls but not between processes. Anything worth keeping must be written to an external store during the conversation.

Why not keep the whole conversation in the context window?
Within one session it behaves like memory, since the model re-reads it every turn. But it's unstructured (you can't query or rank by it), it gets trimmed as the conversation grows, you pay to re-process the same tokens every turn, and it's gone on restart. Treat it as a context mechanism, not a memory system.

Do I need a vector database to remember user preferences?
No. Preferences are facts with known names, and key lookup is exact and instant, with no embedding costs. Vector databases earn their keep when questions stop matching keys ("what should I avoid eating?"), which is the next post in this series.

How do AI agents learn user preferences without asking?
From actions. A booking, a purchase, or a rejection carries more reliable signal than a form. Design tools so that doing their job also writes what the action reveals (cabin, price band, carrier) into the agent's state.

Where is the memory actually stored?
In this pattern, three places depending on the durability rung: in-process state (a Python dict, gone on restart), JSON session files on local disk, or plain JSON objects in an Amazon S3 bucket. No vectors and no embeddings at any rung; a profile is a named fact, not a similarity search.

Resources

Companion repo — demo 01 with the runnable script and notebook
Strands Agents: state — agent state vs conversation history, the distinction this post leans on
MemoryOS of AI Agent — Kang et al., 2025: hierarchical memory (+49% F1 on LoCoMo)
Cognitive Memory in Large Language Models — Shan et al., 2025: the memory-tier survey
MemGPT: Towards LLMs as Operating Systems — Packer et al., 2023: the self-managed memory concept