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)

AgentCore CLI Quick Reference

Install: pip install bedrock-agentcore-starter-toolkit

Core Workflow

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

# 2. Deploy
agentcore deploy                    # Cloud (CodeBuild, no Docker)
agentcore deploy --local            # Local (needs Docker/Finch/Podman)
agentcore deploy --local-build      # Build local, deploy to cloud

# 3. Invoke
agentcore invoke '{"prompt": "Hello!"}'
agentcore invoke '{"prompt": "Continue"}' --session-id abc123

# 4. Check status
agentcore status
agentcore status --verbose

# 5. Stop session (save costs)
agentcore stop-session

# 6. Tear down
agentcore destroy --dry-run         # Preview
agentcore destroy --force           # No confirmation

Configure Options

Memory Configuration

Memory is opt-in. Three modes:

# Interactive — prompts for memory setup
agentcore configure --entrypoint agent.py

# Explicitly disable
agentcore configure --entrypoint agent.py --disable-memory

# Non-interactive (STM only by default)
agentcore configure --entrypoint agent.py --non-interactive

Memory Management

agentcore memory create my_memory                    # Create STM
agentcore memory create my_memory --strategies '[{"semanticMemoryStrategy": {"name": "Facts"}}]' --wait  # With LTM
agentcore memory list                                # List all
agentcore memory status <memory-id>                  # Check status
agentcore memory delete <memory-id> --wait           # Delete

Deploy Options

Gateway (MCP Gateway)

agentcore gateway create-mcp-gateway --name MyGateway
agentcore gateway create-mcp-gateway-target --gateway-arn <arn> --gateway-url <url> --role-arn <role>
agentcore gateway list-mcp-gateways
agentcore gateway delete-mcp-gateway --name MyGateway --force

Identity (OAuth / JWT)

# AWS JWT (secretless M2M auth)
agentcore identity setup-aws-jwt --audience https://api.example.com

# Cognito (user auth)
agentcore identity setup-cognito
agentcore identity setup-cognito --auth-flow m2m

# Credential providers
agentcore identity create-credential-provider --name MyProvider --type github --client-id <id> --client-secret <secret>

# Cleanup
agentcore identity cleanup --agent my-agent --force

Useful Patterns

# List configured agents
agentcore configure list

# Set default agent
agentcore configure set-default my-agent

# Deploy with semantic versioning
agentcore deploy --image-tag $(git describe --tags --always)

# Deploy with env vars
agentcore deploy --env API_KEY=abc123 --env DEBUG=true

# Import existing Bedrock Agent to AgentCore
agentcore import-agent

AgentCore Integrations: Observability, Evals, Tracing, Memory

Observability & Distributed Tracing

Strands has OpenTelemetry (OTel) baked in. Traces are emitted automatically for every agent invocation, model call, and tool execution. You just need to tell it where to send them.

Enable Tracing (Python)

Set the OTLP endpoint and Strands starts exporting traces:

# Send to any OTLP-compatible collector (Jaeger, Grafana, etc.)
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# For AgentCore deployed agents, OTEL is enabled by default
# Disable with: agentcore configure --disable-otel

Strands automatically creates spans for:

• Agent invocations (full request lifecycle)
• Model calls (input/output tokens, latency, model ID)
• Tool executions (tool name, input, output, duration)
• Error states and retries

Enable Tracing (TypeScript)

// TypeScript uses the same OTel environment variables
// Set OTEL_EXPORTER_OTLP_ENDPOINT before starting your agent
// Strands TS SDK emits spans automatically

AgentCore Native Observability

When deployed to AgentCore, you get observability out of the box:

• CloudWatch Logs: Agent session transcripts at /aws/bedrock-agentcore/runtimes/<agent-name>
• X-Ray Traces: Distributed traces across agent → model → tool calls
• CloudWatch Metrics: Invocation count, latency, errors (namespace: bedrock-agentcore)
• GenAI Observability Dashboard: Token usage, model latency, cost — linked from agentcore status

# Tail agent logs
aws logs tail /aws/bedrock-agentcore/runtimes/<agent-name>-DEFAULT \
  --region us-east-1 --since 5m --follow

# Check agent metrics
aws cloudwatch get-metric-statistics \
  --namespace bedrock-agentcore \
  --metric-name Invocations \
  --start-time $(date -v-1d +%Y-%m-%dT%H:%M:%S) \
  --end-time $(date +%Y-%m-%dT%H:%M:%S) \
  --period 3600 --statistics Sum

Third-Party Observability Backends

Strands OTel traces are vendor-neutral. Route them to any backend:

Trace Attributes

Strands enriches spans with GenAI semantic conventions. Opt in to experimental attributes:

# Enable experimental GenAI attributes
export OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental,gen_ai_tool_definitions

This adds:

• gen_ai.system: Model provider
• gen_ai.request.model: Model ID
• gen_ai.usage.input_tokens / gen_ai.usage.output_tokens: Token counts
• gen_ai.conversation.id: Session correlation
• Tool definition schemas in spans

---

Evaluation with Strands Evals

Strands Evals is a dedicated evaluation framework with LLM-as-a-Judge built in. Install separately:

pip install strands-agents-evals

Note: Strands Evals is Python-only as of now. Even if your agent is TypeScript, write your evals in Python.

Built-in Evaluators

Quick Eval Example

from strands import Agent
from strands_evals import Case, Experiment
from strands_evals.evaluators import OutputEvaluator, TrajectoryEvaluator
from strands_evals.extractors import tools_use_extractor

# Define test cases
cases = [
    Case(
        name="order-lookup",
        input="Where is my order #ORD-789?",
        expected_output="Should include order status and tracking info",
        expected_trajectory=["lookup_order"],
    ),
]

# Define evaluators
output_eval = OutputEvaluator(
    rubric="""
    Score 1.0 if the response includes order status and tracking number.
    Score 0.5 if it includes status but no tracking.
    Score 0.0 if it doesn't address the order.
    """,
    include_inputs=True,
)

trajectory_eval = TrajectoryEvaluator(
    rubric="Verify the agent used the lookup_order tool with the correct order ID.",
    include_inputs=True,
)

# Task function — connects your agent to the eval framework
def my_task(case):
    agent = Agent(tools=[lookup_order], callback_handler=None)
    result = agent(case.input)
    trajectory = tools_use_extractor.extract_agent_tools_used_from_messages(agent.messages)
    return {"output": str(result), "trajectory": trajectory}

# Run
experiment = Experiment(cases=cases, evaluators=[output_eval, trajectory_eval])
reports = experiment.run_evaluations(my_task)
reports[0].run_display()

Trace-Based Evaluation (Using OTel Spans)

For deeper analysis, evaluate using captured OTel traces:

from strands_evals.telemetry import StrandsEvalsTelemetry
from strands_evals.mappers import StrandsInMemorySessionMapper
from strands_evals.evaluators import HelpfulnessEvaluator

telemetry = StrandsEvalsTelemetry().setup_in_memory_exporter()

def task_with_traces(case):
    telemetry.in_memory_exporter.clear()
    agent = Agent(
        tools=[lookup_order],
        trace_attributes={
            "gen_ai.conversation.id": case.session_id,
            "session.id": case.session_id,
        },
        callback_handler=None,
    )
    response = agent(case.input)
    spans = telemetry.in_memory_exporter.get_finished_spans()
    session = StrandsInMemorySessionMapper().map_to_session(spans, session_id=case.session_id)
    return {"output": str(response), "trajectory": session}

experiment = Experiment(cases=cases, evaluators=[HelpfulnessEvaluator()])
reports = experiment.run_evaluations(task_with_traces)

Multi-Turn Simulation

Test multi-turn conversations with simulated users:

from strands_evals import Case, ActorSimulator

case = Case(
    input="I need to return a damaged item",
    metadata={"task_description": "Successfully initiate a return"},
)

user_sim = ActorSimulator.from_case_for_user_simulator(case=case, max_turns=10)
agent = Agent(tools=[lookup_order, initiate_return])

user_message = case.input
while user_sim.has_next():
    agent_response = agent(user_message)
    user_result = user_sim.act(str(agent_response))
    user_message = str(user_result.structured_output.message)

# Then evaluate the full session with GoalSuccessRateEvaluator

Auto-Generate Test Cases

from strands_evals.generators import ExperimentGenerator
from strands_evals.evaluators import OutputEvaluator

generator = ExperimentGenerator(input_type=str, output_type=str, include_expected_output=True)
experiment = await generator.from_context_async(
    context="A customer service agent for an e-commerce platform",
    task_description="Handle order inquiries, returns, and product questions",
    num_cases=20,
    evaluator=OutputEvaluator,
    num_topics=4,
)
experiment.to_file("generated_evals")

Eval Strategy

---

Memory Integration

See python-patterns.md for the code patterns. Key decisions:

Memory Modes

LTM Strategies

When using STM_AND_LTM, configure strategies for what to extract:

strategies = [
    {"summaryMemoryStrategy": {"name": "SessionSummarizer", "namespaceTemplates": ["/summaries/{actorId}/{sessionId}/"]}},
    {"userPreferenceMemoryStrategy": {"name": "PreferenceLearner", "namespaceTemplates": ["/preferences/{actorId}/"]}},
    {"semanticMemoryStrategy": {"name": "FactExtractor", "namespaceTemplates": ["/facts/{actorId}/"]}},
]

• summaryMemoryStrategy: Summarizes sessions for quick recall
• userPreferenceMemoryStrategy: Extracts user preferences (likes sushi, prefers TypeScript)
• semanticMemoryStrategy: Extracts factual information (user's name, company, role)

Memory with AgentCore CLI

# Interactive — prompts for memory setup
agentcore configure --entrypoint agent.py

# Create memory manually
agentcore memory create my_memory --strategies '[{"semanticMemoryStrategy": {"name": "Facts"}}]' --wait

# Check memory status (must be ACTIVE before use)
agentcore memory status <memory-id>

Memory with Batching (High-Throughput)

For agents with many messages per session, batch memory writes:

from bedrock_agentcore.memory.integrations.strands.config import AgentCoreMemoryConfig
from bedrock_agentcore.memory.integrations.strands.session_manager import AgentCoreMemorySessionManager

config = AgentCoreMemoryConfig(
    memory_id=MEMORY_ID,
    session_id=SESSION_ID,
    actor_id=ACTOR_ID,
    batch_size=10,  # Buffer 10 messages before flushing
)

# MUST use context manager or call close() to flush remaining buffer
with AgentCoreMemorySessionManager(config, region_name="us-east-1") as session_manager:
    agent = Agent(session_manager=session_manager)
    agent("Hello!")
    agent("Tell me about AWS")
# Buffered messages auto-flushed on exit

Strands Agent — Python Patterns

Minimal Agent

from strands import Agent

agent = Agent(
    system_prompt="You are a helpful assistant."
)

response = agent("What can you help me with?")
print(response)

Agent with Custom Tools

from strands import Agent, tool

@tool
def lookup_order(order_id: str) -> str:
    """Look up an order by ID. Returns order status, items, and shipping info."""
    # Replace with your actual data source
    return f"Order {order_id}: shipped, tracking TRK-12345"

agent = Agent(
    system_prompt="You are a customer service agent. Help users check their orders.",
    tools=[lookup_order],
)

response = agent("Where is my order #ORD-789?")
print(response)

AgentCore Deployment Entrypoint

# agent.py — AgentCore-compatible entrypoint
import os
from strands import Agent, tool
from bedrock_agentcore.runtime import BedrockAgentCoreApp

app = BedrockAgentCoreApp()

@tool
def lookup_order(order_id: str) -> str:
    """Look up an order by ID."""
    return f"Order {order_id}: shipped, tracking TRK-12345"

@app.entrypoint
async def invoke(payload, context):
    agent = Agent(
        model="us.anthropic.claude-sonnet-4-5-20250929-v1:0",
        tools=[lookup_order],
    )
    response = await agent.invoke_async(payload.get("prompt", ""))
    return {"response": str(response.message)}

AgentCore with Memory

# agent.py — with AgentCore memory integration
import os
from strands import Agent, tool
from bedrock_agentcore.runtime import BedrockAgentCoreApp
from bedrock_agentcore.memory.integrations.strands.config import AgentCoreMemoryConfig
from bedrock_agentcore.memory.integrations.strands.session_manager import AgentCoreMemorySessionManager

app = BedrockAgentCoreApp()
MEMORY_ID = os.getenv("BEDROCK_AGENTCORE_MEMORY_ID")
REGION = os.getenv("AWS_REGION", "us-east-1")

@app.entrypoint
async def invoke(payload, context):
    session_manager = None
    if MEMORY_ID:
        memory_config = AgentCoreMemoryConfig(
            memory_id=MEMORY_ID,
            session_id=context.session_id,
            actor_id=context.actor_id,
        )
        session_manager = AgentCoreMemorySessionManager(memory_config, REGION)

    agent = Agent(
        model="us.anthropic.claude-sonnet-4-5-20250929-v1:0",
        system_prompt="You are a helpful assistant. Use what you know about the user.",
        session_manager=session_manager,
    )
    response = await agent.invoke_async(payload.get("prompt", ""))
    return {"response": str(response.message)}

Project Structure

my-agent/
├── agent.py              # Agent entrypoint
├── tools/                # Custom tool definitions
│   ├── __init__.py
│   └── lookup_order.py
├── requirements.txt
├── .gitignore
└── README.md

requirements.txt

strands-agents
bedrock-agentcore

Strands Agent — TypeScript Patterns

Minimal Agent (No Tools)

// src/agent.ts
import { Agent } from '@strands-agents/sdk'

const agent = new Agent({
  systemPrompt: 'You are a helpful assistant.',
})

const result = await agent.invoke('What can you help me with?')
console.log(result.lastMessage)

Agent with Custom Tools

// src/agent.ts
import { Agent, tool } from '@strands-agents/sdk'
import z from 'zod'

const lookupOrder = tool({
  name: 'lookup_order',
  description: 'Look up an order by ID. Returns order status, items, and shipping info.',
  inputSchema: z.object({
    orderId: z.string().describe('The order ID to look up'),
  }),
  callback: async (input) => {
    // Replace with your actual data source
    return JSON.stringify({
      orderId: input.orderId,
      status: 'shipped',
      items: ['Widget A', 'Widget B'],
      trackingNumber: 'TRK-12345',
    })
  },
})

const agent = new Agent({
  systemPrompt: 'You are a customer service agent. Help users check their orders.',
  tools: [lookupOrder],
})

const result = await agent.invoke('Where is my order #ORD-789?')
console.log(result.lastMessage)

Agent with Vended Tools (Built-in)

import { Agent } from '@strands-agents/sdk'
import { bash } from '@strands-agents/sdk/vended-tools/bash'

const agent = new Agent({
  tools: [bash],
  systemPrompt: 'You are a DevOps assistant. Help with system tasks.',
})

const result = await agent.invoke('List the files in the current directory')
console.log(result.lastMessage)

Custom Model Configuration

import { Agent } from '@strands-agents/sdk'
import { BedrockModel } from '@strands-agents/sdk'

const model = new BedrockModel({
  modelId: 'anthropic.claude-sonnet-4-20250514-v1:0',
  region: 'us-west-2',
  temperature: 0.3,
})

const agent = new Agent({ model })

Streaming Responses (for Web Servers)

import { Agent } from '@strands-agents/sdk'

const agent = new Agent()

async function handleRequest(prompt: string) {
  for await (const event of agent.stream(prompt)) {
    console.log('Event:', event.type)
    // Forward events to client via SSE, WebSocket, etc.
  }
}

Project Structure

my-agent/
├── src/
│   ├── agent.ts          # Agent definition and entrypoint
│   ├── tools/            # Custom tool definitions
│   │   ├── index.ts
│   │   └── lookup-order.ts
│   └── config.ts         # Model and environment config
├── package.json
├── tsconfig.json
├── .gitignore
└── README.md

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,
    "sourceMap": true
  },
  "include": ["src/**/*"]
}

Running Locally

# Using tsx (recommended for dev)
npx tsx src/agent.ts

# Or compile and run
npx tsc && node dist/agent.js