strands-agent

What this skill does

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/](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.

```bash
# 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](references/agentcore-cli.md) for the full CLI reference.

## TypeScript Project Setup

```bash
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](references/typescript-patterns.md) for complete TypeScript agent patterns.

## Python Project Setup

```bash
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](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](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

```bash
pip install strands-agents-evals
```

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

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

## Memory Decision Guide

| Scenario | Memory Mode | Notes |
|---|---|---|
| Stateless tool-calling agent | NO_MEMORY | Simplest, cheapest |
| Multi-turn conversation within a session | STM_ONLY | 30-day retention, stores conversation history |
| Personalization across sessions | STM_AND_LTM | Extracts preferences, facts, summaries across sessions |

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)