🤖strands-agent

You are building an AI agent using the Strands Agents SDK deployed on Amazon Bedrock AgentCore.

First: Clarify Language

Before writing any code, ask the user:

TypeScript or Python? (TypeScript is recommended for new projects — it has strong typing, good DX, and first-class Strands support. Python is fully supported too.)

Default to TypeScript if the user doesn't have a preference.

Process

1. Clarify the agent's purpose — one sentence. If it needs "and", consider multiple agents.
2. Clarify language preference (TS preferred, Python supported)
3. Identify the tools the agent needs (keep to 3-5 for a PoC)
4. Decide on memory needs: no memory, STM only, or STM+LTM
5. Scaffold the project using the patterns in references/
6. Include observability setup (OTel tracing is built in — just configure the endpoint)
7. Include an eval scaffold using Strands Evals (even for TS agents, evals are Python)
8. Include deployment instructions using the AgentCore CLI

Quick PoC Path: AgentCore CLI

For the fastest path to a working deployed agent, use the AgentCore Starter Toolkit CLI. It handles configuration, deployment, memory provisioning, and invocation.

# Install the toolkit
pip install bedrock-agentcore-starter-toolkit

# Configure your agent
agentcore configure --entrypoint agent.py --name my-agent

# Deploy to AWS (uses CodeBuild, no Docker needed)
agentcore deploy

# Invoke it
agentcore invoke '{"prompt": "Hello!"}'

# Check status
agentcore status

# Tear down when done
agentcore destroy --force

See references/agentcore-cli.md for the full CLI reference.

TypeScript Project Setup

mkdir my-agent && cd my-agent
npm init -y
npm pkg set type=module
npm install @strands-agents/sdk
npm install --save-dev @types/node typescript

See references/typescript-patterns.md for complete TypeScript agent patterns.

Python Project Setup

mkdir my-agent && cd my-agent
python -m venv .venv && source .venv/bin/activate
pip install strands-agents bedrock-agentcore

See references/python-patterns.md for complete Python agent patterns.

Observability & Tracing

Strands has OpenTelemetry built in. Every agent invocation, model call, and tool execution emits OTel spans automatically. You just configure where to send them.

• AgentCore deployed agents: OTel is enabled by default → CloudWatch Logs, X-Ray traces, GenAI dashboard
• Local development: Set OTEL_EXPORTER_OTLP_ENDPOINT to route to Jaeger, Grafana, Langfuse, etc.
• Disable: agentcore configure --disable-otel

See references/agentcore-integrations.md for full setup, third-party backends, and trace attribute configuration.

Evaluation with Strands Evals

Ship evals from day one. Strands Evals provides LLM-as-a-Judge evaluation with 9+ built-in evaluators:

• OutputEvaluator: Custom rubric-based quality scoring
• TrajectoryEvaluator: Did the agent use the right tools in the right order?
• HelpfulnessEvaluator: 7-point helpfulness scale
• FaithfulnessEvaluator: Is the response grounded in context? (anti-hallucination)
• HarmfulnessEvaluator: Safety check
• ToolSelectionAccuracyEvaluator / ToolParameterAccuracyEvaluator: Tool-level correctness
• GoalSuccessRateEvaluator: Did the user achieve their goal across a full session?
• ActorSimulator: Simulates realistic multi-turn users for conversation testing

pip install strands-agents-evals

Evals are Python-only. Even for TypeScript agents, write your eval suite in Python.

See references/agentcore-integrations.md for eval code patterns, trace-based evaluation, multi-turn simulation, and auto-generated test cases.

Memory Decision Guide

Memory is opt-in. Start without it, add when you need it.

Gotchas

• AgentCore CLI is Python-only for deployment — even if your agent is TypeScript, the agentcore CLI itself is a Python tool. Your TS agent runs in a container.
• TypeScript agents need containerized deployment — use --deployment-type container when configuring TS agents with the AgentCore CLI
• Default model is Claude Sonnet — Strands defaults to global.anthropic.claude-sonnet-4-5-20250929-v1:0 via Bedrock. You need model access enabled in your AWS account.
• AWS credentials required — Strands uses Bedrock by default. Ensure AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY are set, or use IAM roles.
• Tool count matters — more tools = more reasoning steps = slower + more expensive. Keep PoCs to 3-5 tools.
• Zod is included — @strands-agents/sdk bundles Zod for TypeScript tool input validation. No separate install needed.
• Memory provisioning takes time — STM: ~30-90s, LTM: ~120-180s. The CLI waits for ACTIVE status.
• agentcore destroy deletes everything — including memory resources. Use --dry-run first.
• Session lifecycle — idle timeout defaults to 900s (15min). Set --idle-timeout and --max-lifetime during configure if you need longer sessions.
• VPC config is immutable — once deployed with VPC settings, you can't change them. Create a new agent config instead.
• OTel is on by default in AgentCore — traces go to CloudWatch/X-Ray. Disable with --disable-otel if you don't want it.
• Strands Evals is Python-only — even for TypeScript agents, write evals in Python. The eval framework uses the same Bedrock models as your agent.
• Evals cost money — each LLM-as-a-Judge evaluation invokes a model. Use callback_handler=None in eval task functions to suppress console output.
• Memory batching requires close() — if using batch_size > 1, you MUST use a with block or call close() or buffered messages are lost.

Output

When scaffolding a new agent project, generate:

1. Complete project structure with all files
2. Agent entrypoint with at least one custom tool
3. Observability setup (OTel endpoint config, env vars)
4. Eval scaffold (evals/ directory with at least one test case using Strands Evals — Python, even for TS agents)
5. README with setup, deployment, observability, and eval instructions
6. .gitignore appropriate for the language
7. Deployment commands (local dev + AgentCore cloud)