interface:
  display_name: "AWS AgentCore"
  short_description: "Build and deploy AWS AgentCore agents with CLI-first, docs-verified workflow boundaries"
  default_prompt: "Use $aws-agentcore to build, test, migrate, or deploy an AWS Bedrock AgentCore agent. Prefer the recommended @aws/agentcore CLI for new projects, distinguish code-based agents from preview harness workflows, and verify commands against current local CLI help before proposing automation."
dependencies:
  tools:
    - type: "mcp"
      value: "agentcore-mcp-server"
      description: "Optional AgentCore MCP server for docs, runtime, memory, and gateway workflows when available; do not assume it exists in every environment"
policy:
  allow_implicit_invocation: true

# AgentCore Gateway Integration Guide

> Version note: AgentCore tooling is evolving. Verify exact CLI syntax against the installed toolkit and current official AWS docs before production use. Do not paste secrets into commands or files.

## What people get wrong

The naive story is:

> Gateway exposes tools, so once I create a gateway I’m done.

Wrong.

Official AWS docs imply at least five separate concerns:

1. **inbound authentication** — who is allowed to call the gateway
2. **outbound authentication** — how the gateway authenticates to downstream tools
3. **target modeling** — Lambda, OpenAPI/API, Smithy/AWS-service style targets, or MCP servers
4. **policy enforcement** — Cedar-based controls over who can call what
5. **tool discovery** — including optional semantic search
6. **MCP session behavior** — session IDs, per-user scoping, timeout, streaming, and downstream target session state
7. **interactive MCP flows** — elicitation, sampling, progress notifications, and logging notifications

If you only think “endpoint + tool,” you are missing the real security model.

## Officially grounded gateway shape

AWS docs describe Gateway as:

- a managed MCP-compatible gateway
- a way to connect APIs, Lambda functions, existing services, and pre-existing MCP servers
- a service that handles both **ingress auth** and **egress auth**
- a policy-enforced surface where Cedar-based policies gate tool calls
- a stateful MCP gateway for clients and downstream MCP targets when sessions are enabled
- a streaming and interactive channel for MCP targets that use elicitation, sampling, progress, or logging messages

That is the key insight:

> Gateway is not just transport. It is identity + auth + policy + discovery + session governance.

## Non-negotiable design rules

### 1. Split inbound auth from outbound auth

Do not collapse them mentally.

- **Inbound auth** answers: who may invoke the gateway?
- **Outbound auth** answers: how does the gateway authenticate to the target system?

If you confuse those, you will either overgrant downstream access or break end-user delegation.

### 2. Do not hardcode raw secrets into examples unless there is no alternative

Official docs emphasize managed auth paths and Gateway/Identity capabilities.

So prefer:

- managed credential storage
- OAuth / JWT-based inbound flows
- clearly scoped outbound credentials

Do **not** normalize:

- pasting API keys into chat
- embedding bearer tokens in code samples casually
- pretending headers alone are a security model

### 3. Policy is first-class, not optional cleanup

Official AWS policy docs show:

- Gateway traffic can be mediated by a **policy engine**
- policies use **Cedar**
- policies control which principals can perform which actions on which resources, with conditions

If the skill recommends Gateway without also asking “what is the policy boundary?”, the skill is incomplete.

### 4. Semantic search is useful, but it changes governance

Gateway docs mention semantic tool selection / search to reduce prompt size and scale tool discovery.

That is powerful, but it also means:

- tool metadata quality matters more
- broad catalogs can cause accidental reach
- policy boundaries matter even more

Do not recommend semantic search as pure upside.

### 5. Gateway target type changes the failure mode

Different targets mean different risks:

- **Lambda** → IAM, payload schema, side effects
- **OpenAPI / API** → credential placement, scope creep, request shaping
- **Smithy / AWS service models** → AWS auth/permissions and service blast radius
- **MCP servers** → remote tool governance, protocol trust, capability sprawl

One gateway pattern does not fit all four.

### 6. MCP sessions change state and audit assumptions

Current release notes describe Gateway MCP sessions with a unique `Mcp-Session-Id`, per-authenticated-user scoping, configurable timeouts, and downstream MCP target session state.

Design implications:

- decide whether stateful sessions are required or whether stateless tool calls are safer
- set session timeout intentionally instead of inheriting defaults blindly
- bind audit logs to principal + session ID + target tool
- test what happens when downstream MCP target sessions expire or request user input
- do not reuse session IDs across users, tenants, or unrelated workflows

### 7. Streaming, elicitation, sampling, progress, and logs are not harmless extras

Newer Gateway docs/release notes describe:

- response streaming via SSE for multiple JSON-RPC messages
- elicitation pass-through for user input during tool execution
- sampling messages where MCP servers request LLM completions from the client
- progress notifications and structured logging notifications

These features increase capability and risk:

- elicitation needs UI/user-consent handling and phishing-resistant prompts
- sampling can create unexpected model-call cost and data exposure
- progress/log streams can leak sensitive tool inputs or downstream identifiers
- streaming clients must handle partial, failed, or reordered events safely

## Minimal safe implementation flow

1. Identify target type
2. Define inbound auth path
3. Define outbound auth path
4. Define Cedar policy boundary
5. Add one target only
6. Decide whether MCP sessions/streaming/elicitation/sampling are allowed
7. Verify tool schema and least-privilege behavior
8. Add semantic search only if tool catalog size justifies it

## High-risk assumptions to kill

- “Gateway automatically makes this secure”
- “Cognito exists, so auth is solved”
- “If the agent can see a tool, it should be allowed to use it”
- “Semantic search will pick the right tool”
- “OpenAPI import means safe invocation”
- “MCP server connected means MCP server trusted”

Those are lazy assumptions.

## Safe command/code verification targets

Verify against current docs and local tooling before use:

- `agentcore gateway ...`
- gateway create / target create / inspect flows
- inbound authorization requirements
- outbound authorization setup
- policy engine wiring and mode
- MCP session timeout and `Mcp-Session-Id` behavior
- SSE/streaming, elicitation, sampling, progress, and logging behavior when using MCP targets

## When to push back

Push back if the user asks for:

- one gateway with broad access to everything
- raw secret injection into headers as the default pattern
- no policy layer
- no per-target review
- semantic search over sensitive tools without policy constraints

That is not “faster.” It is reckless.

# Getting Started with AgentCore

> Version note: AgentCore tooling is evolving. Verify exact CLI syntax against the installed toolkit and current official AWS docs before production use. Do not paste secrets into commands or files.

## First: classify the path

Do not blur these together:

1. **New project** — use the recommended npm CLI `@aws/agentcore`
2. **Existing code-based agent** — adapt/configure what exists; do not scaffold over it
3. **Import/migration from Amazon Bedrock Agents** — use the import flow if the goal is migration, not greenfield creation
4. **Managed harness** — a config-based path that current AWS docs describe as preview
5. **Direct code deployment** — current release notes include Node.js direct code deployment as well as Python-oriented paths; do not imply container-only or Python-only deployment.
6. **Resource import / operational CLI work** — current release notes mention resource import, bash command execution in runtime/local containers, BYO Dockerfile, and Memory streaming. Verify exact installed CLI help before giving commands.

If you pick the wrong path, your advice becomes cargo cult.

## Prerequisites

- Node.js **20 or later**
- npm
- AWS credentials configured through AWS CLI, environment variables, or a named profile
- Python **3.10 or later** for agent code
- Node.js runtime support exists for direct code deployment; verify the installed CLI/runtime path before assuming Python-only project structure
- IAM permissions to call AgentCore APIs and assume the CDK bootstrap roles used during deployment

Install the current recommended CLI for new projects:

```bash
npm install -g @aws/agentcore
```

Use the Python `bedrock-agentcore-starter-toolkit` only for legacy Python-based workflows or migration-era examples.

## Current local CLI surface to assume only after verification

Verified locally in this environment:

- `agentcore create`
- `agentcore dev`
- `agentcore deploy`
- `agentcore invoke`
- `agentcore status`
- `agentcore destroy`
- `agentcore stop-session`
- `agentcore configure`
- `agentcore identity`
- `agentcore gateway`
- `agentcore memory`
- `agentcore obs`
- `agentcore policy`
- `agentcore eval`

Do not promise undocumented or unverified commands just because a README or blog post mentioned them.

## New project path

Use `agentcore create` only when the user actually wants a new project.

```bash
agentcore create --non-interactive --project-name MyAgent
```

Useful flags verified locally:

- `--template basic|production`
- `--agent-framework Strands|LangChain_LangGraph|GoogleADK|OpenAIAgents|AutoGen|CrewAI`
- `--model-provider Bedrock|OpenAI|Anthropic|Gemini`
- `--iac CDK|Terraform`
- `--memory STM_ONLY|STM_AND_LTM|NO_MEMORY`
- `--venv` / `--no-venv`

Key assumption many people miss:

- For non-Bedrock providers, official harness docs say you need an **API key ARN**, not just “some secret somewhere”.
- If the project needs shared prompts, skills, datasets, or intermediate artifacts, check whether runtime/harness filesystem mounts with S3 Files or EFS are appropriate before inventing custom download/sync code.

## Existing code-based agent path

If the agent already exists, do **not** run `agentcore create` on top of it.

Start by inspecting configuration:

```bash
agentcore configure --help
```

Current official docs say project configuration lives under:

- `agentcore/agentcore.json`
- `agentcore/aws-targets.json`

So stop assuming old one-file layouts are the only truth.

## Import / migration path

If the user is migrating an existing Amazon Bedrock Agent, treat that as a separate path.

Local CLI help currently shows import under `create`:

```bash
agentcore create import --help
```

Starter-toolkit docs and Context7 also reference `import-agent` style flows. That mismatch means you must verify the installed CLI before giving automation steps.

## Local development loop

Run the dev server:

```bash
agentcore dev
```

Useful verified flags:

- `--port`
- `--env KEY=VALUE`

Then test locally:

```bash
agentcore invoke --dev '{"prompt":"Hello"}'
```

Useful verified flags:

- `--agent`
- `--session-id`
- `--bearer-token`
- `--local`
- `--dev`
- `--port`
- `--user-id`
- `--headers`

## Harness-specific cautions

Official AWS docs describe:

- a **code-based agent** path
- a **managed harness** path

These are not the same thing. Current AWS docs describe the harness as preview. Do not casually recommend harness-only features as if they are universal AgentCore behavior.

Also:

- harness skills are **filesystem paths inside the runtime environment**
- `--skill-path` references a path; it does **not** upload the skill for you
- some harness docs mention `agentcore invoke --exec` shell access, but installed CLIs may not expose that surface the same way yet
- release notes now include attached filesystems for runtime and harness sessions; mount paths become part of the runtime contract and must be reviewed for data perimeter, retention, and path-collision risk
- Agent Inspector can make local `agentcore dev` workflows more observable, but do not assume it is available unless the installed CLI exposes it

## Security-critical realities

- SigV4 authentication does **not** give per-user identity propagation into downstream tool calls the way the OAuth bearer-token path can.
- OBO token exchange exists for user-scoped protected resource access. Prefer it over copying user tokens into tool configs when the use case is on-behalf-of access.
- Gateway security is not “create gateway and done”; policy design is a separate concern.
- Custom observability requires more than default metrics; official docs call out ADOT and CloudWatch prerequisites for richer traces.
- Payments are preview and introduce wallet, spending-limit, transaction authorization, and audit requirements. Do not include payments in a production path without explicit preview-risk handling.

## Minimum safe workflow

1. Verify CLI help locally
2. Classify new project vs existing agent vs import vs harness
3. Confirm region and feature support
4. Confirm IAM/bootstrap permissions
5. Create or adapt minimally
6. Run `agentcore dev`
7. Test with `agentcore invoke --dev`
8. Only then discuss deploy, Memory, Gateway, Policy, Browser, or Code Interpreter wiring
9. For production agents, add Evaluations / batch evaluation / user simulation / A/B validation before rollout when quality regressions are plausible

# AgentCore Memory Integration Guide

> Version note: AgentCore tooling is evolving. Verify exact CLI syntax against the installed toolkit and current official AWS docs before production use. Do not paste secrets into commands or files.

## What people get wrong

The common bad assumption is:

> “Memory” is just chat history persistence.

That is incomplete.

AgentCore Memory design has at least four separate concerns:

1. **resource lifecycle** — create, wait for `ACTIVE`, inspect, delete
2. **identity model** — `actor_id` and `session_id` are not interchangeable
3. **namespace design** — what gets stored where
4. **metadata filtering** — indexed keys and retrieval filters that change what memories are visible
5. **retention / expiry / deletion** — what survives, for how long, and how you remove it

If you do not model those explicitly, you create memory bugs that look like “the AI is weird.”

## Officially grounded building blocks

AWS docs and Context7 show Memory supports:

- short-term session memory
- long-term strategies such as:
  - session summarization
  - user preference extraction
- semantic / fact extraction
- structured metadata extraction and filtering for long-term memory retrieval

Typical namespace patterns in official examples include:

- `/summaries/{actorId}/{sessionId}/`
- `/preferences/{actorId}/`
- `/facts/{actorId}/`

That pattern is not cosmetic. It is your isolation boundary.

## Non-negotiable design rules

### 1. Keep `actor_id` and `session_id` stable and intentional

- `actor_id` is the user or principal identity dimension
- `session_id` is the conversational/session boundary

If you generate random IDs carelessly on every call, memory will look “broken” because nothing reconnects.

If you reuse the same actor/session pair across unrelated contexts, memory will look “smart” while actually leaking state.

### 2. Design namespaces before writing code

Do not dump everything into one namespace.

Use separate namespaces for:

- per-session summaries
- per-user preferences
- reusable semantic facts

If you cannot explain why a memory belongs in a namespace, you are not ready to store it.

### 3. Retention is a product decision, not just an implementation detail

Official examples show `eventExpiryDuration` and long-term memory strategies.

You need to decide:

- which memories expire
- which are durable
- how deletions work
- what counts as user-requested forgetfulness

If your skill does not surface expiry/deletion, it is not production-ready.

### 4. Metadata schema is an isolation and relevance boundary

Current docs/release notes describe structured metadata filtering for long-term memory. Indexed keys can be declared when creating memory and metadata filters can narrow retrieval/listing.

Do not bolt this on casually:

- decide indexed keys before creation; changing indexed-key strategy later may require new resources or migration
- avoid indexing sensitive values unless the access model and logs are understood
- test retrieval with and without filters for same actor/session, new session, and different actor
- document whether metadata is extracted by LLM strategy, application code, or both

### 5. Wait for resource readiness

Official examples explicitly poll until the memory resource becomes `ACTIVE`.

Do not assume “create returned” means “safe to wire into the agent.”

## Minimal safe implementation flow

1. Create the memory resource
2. Wait until it is `ACTIVE`
3. Decide namespace strategy
4. Decide metadata/index/filter strategy for long-term memory
5. Wire `memory_id`, `actor_id`, and `session_id` into the agent intentionally
6. Test:
   - same actor + same session
   - same actor + new session
   - different actor
   - same actor with restrictive metadata filters
7. Verify expiry/deletion behavior before broad rollout

## Example patterns from official docs

### Create a memory resource with strategies

Official AWS examples show CLI / SDK flows with long-term strategies such as summarization, preferences, and semantic facts. Treat these as design templates, not copy-paste truth for every app.

### Strands integration shape

Official examples show Strands integration using:

- `AgentCoreMemoryConfig`
- `AgentCoreMemorySessionManager`
- optional retrieval configuration for long-term namespaces

That means your real integration surface is not just “turn memory on”; it is:

- resource ID
- actor/session mapping
- retrieval behavior
- metadata extraction and filter behavior

## Adversarial checklist

Before recommending Memory, answer these:

- What is the source of truth for `actor_id`?
- What causes a new `session_id`?
- Which namespace stores preferences vs facts vs summaries?
- Which metadata fields are indexed?
- Who can set or influence metadata values?
- What expires automatically?
- What is the deletion story?
- What happens if two applications share the same memory resource?
- What is the fallback behavior if Memory is unavailable?

If you cannot answer those, your guidance is shallow.

## Safe command/code verification targets

Verify against current docs and local tooling before use:

- `agentcore memory ...`
- memory create/get/list/delete flows
- integration package names and examples
- resource status / readiness checks

## When to push back

Push back if the user says:

- “just remember everything”
- “reuse one memory for all users”
- “we’ll figure out deletion later”
- “generate IDs automatically somehow”

Those are not shortcuts. They are design failures.

# Official sources

Use this reference when grounding current Amazon Bedrock AgentCore behavior.

## Amazon Bedrock AgentCore

- Get started with Amazon Bedrock AgentCore CLI
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-get-started-cli.md
- Available interfaces for using Amazon Bedrock AgentCore
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/develop-agents.html
- AgentCore harness overview
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness.html
- Get started with the harness
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness-get-started.html
- Environment and Skills
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness-environment.html
- Security and access control
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness-security.html
- What is Amazon Bedrock AgentCore
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/what-is-bedrock-agentcore.html
- Runtime getting started
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started.html
- AgentCore Memory
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory.html
- AgentCore Gateway
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway.html
- AgentCore Identity
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity.html
- AgentCore Observability
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html
- AgentCore generated observability data
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-service-provided.html
- Browser tool
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser-tool.html
- Code Interpreter
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/code-interpreter.html
- AgentCore Evaluations
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/evaluations.html
- AgentCore Registry
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/registry.html
- AgentCore Payments
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/payments.html
- AgentCore tools configuration
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness-tools.html
- Runtime file system configurations
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-filesystem-configurations.html
- Runtime custom header passthrough
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-header-allowlist.html
- Gateway MCP sessions
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-sessions.html
- Gateway MCP elicitation
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-mcp-elicitation.html
- Gateway MCP sampling
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-mcp-sampling.html
- Gateway MCP progress notifications
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-mcp-progress.html
- Gateway MCP logging notifications
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-mcp-logging.html
- Long-term memory metadata filtering
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/long-term-memory-metadata.html
- Policy in AgentCore
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy.html
- Create a policy
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy-create-policies.html
- Core concepts for policy
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy-core-concepts.html
- Harness operations
  https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness-operations.html

## Grounded notes from Context7

- Current AWS devguide guidance says the recommended CLI install for new projects is `npm install -g @aws/agentcore`.
- The AgentCore CLI is the Node.js command-line tool for creating, configuring, deploying, and managing agents and uses project JSON config under the `agentcore/` directory, including `agentcore.json` and `aws-targets.json`.
- AgentCore tool configuration can include remote MCP servers, AgentCore Gateway, Browser, Code Interpreter, and inline functions.
- For managed credential rotation and API key storage, prefer AgentCore Gateway and AgentCore Identity over raw authentication headers.
- AgentCore Observability uses CloudWatch metrics for runtime, memory, gateway, built-in tools, and identity resources; custom runtime metrics need instrumentation such as AWS Distro for OpenTelemetry.
- AgentCore offers two distinct paths: code-based agents and the managed harness. Current AWS docs describe the code-based agent path as generally available and the config-based harness path as preview.
- Skills referenced with `--skill-path` must already exist inside the runtime container or session environment. The path reference does not upload the skill for you.
- Gateway creation is not the end of the security model. Official policy docs show Cedar-based policy enforcement is a separate control plane you must design explicitly.
- Harness security docs say SigV4 callers do not get per-user identity propagation into downstream tools. User-scoped token vault and on-behalf-of flows require the OAuth bearer-token path.
- Harness overview docs note regional rollout is ongoing and the currently documented harness availability is limited; do not assume every AgentCore feature is live in every region.
- Official harness docs describe `agentcore invoke --exec` shell access to the session environment, but installed CLI surfaces can drift. Verify the local CLI before promising that workflow.

## Current release-note deltas to account for

The following items were missing or underrepresented in earlier skill guidance and must now be considered before giving implementation advice:

- **Core service map expanded** — current overview docs list Runtime, Harness, Memory, Gateway, Identity, Code Interpreter, Browser, Observability, Payments, Evaluations, Policy, and Registry as AgentCore services/capabilities.
- **Gateway MCP is now stateful and more interactive** — release notes describe MCP sessions, response streaming, elicitation pass-through, sampling messages, progress notifications, and logging notifications. Gateway advice must cover session scope, timeouts, human-in-the-loop prompts, client streaming behavior, and audit/log handling.
- **Runtime and Harness support attached filesystems** — release notes describe Amazon S3 Files and Amazon EFS access point mounts for sharing skills, prompt templates, datasets, and intermediate outputs. Treat mounts as data-perimeter and lifecycle risks, not just convenience.
- **Agent quality loop is first-class** — release notes describe optimization, batch evaluation, user simulation, and A/B testing. Do not treat evaluation as an external afterthought when the user asks for production readiness.
- **Payments are preview** — payment flows add wallet, spending-limit, x402 endpoint, and transaction-governance risks. Keep this separate from GA runtime/gateway guidance.
- **Node.js direct code deployment exists** — do not imply Python/container-only deployment paths.
- **VPC egress and OBO token exchange exist** — Identity, Gateway, and Runtime can reach private resources; user-scoped access can use on-behalf-of token exchange. Verify network and identity boundaries instead of assuming public egress or raw static credentials.
- **Memory supports structured metadata filtering** — namespace design is no longer enough; indexed metadata keys and retrieval filters can materially change isolation and relevance.
- **Observability requires setup** — current docs call out CloudWatch Transaction Search setup, tracing enablement for memory resources, consistent session IDs, distributed tracing, custom attributes, resource usage monitoring, and alerts.
- **AgentCore Registry is in preview** — registry-based discovery and governance can reduce sprawl but introduces approval, publication, semantic-search, and access-control decisions.
- **AgentCore MCP server exists in awslabs/mcp** — coding agents may operate AgentCore resources through a user-configured AWS credential chain. Treat this as live AWS access requiring the user's read-only or explicitly approved profile.

## Starter toolkit caveat

- The Bedrock AgentCore Starter Toolkit repository is still useful for migration and existing Python-based workflows.
- Based on current official AWS devguide evidence, do not present the starter toolkit as the recommended starting point for new projects when the newer `@aws/agentcore` CLI is available.

## Current MCP/documentation refresh (2026-06-02)

Service facts from official docs:
- Current AgentCore docs cover Runtime, Harness, Memory, Gateway, Identity, Code Interpreter, Browser, Observability, Payments, Evaluations, Policy, and Registry as AgentCore services or capabilities.
- Gateway MCP guidance includes sessions, response streaming, elicitation, sampling, progress notifications, and logging notifications; these are tool/session governance concerns, not just integration features.
- AgentCore filesystem, Memory metadata filtering, observability setup, evaluations, registry, payments, VPC egress, and on-behalf-of token exchange materially affect security and production-readiness guidance.

Sampled live evidence:
- Read-only regional availability sampling reported `isAvailableIn` for Amazon Bedrock AgentCore, Amazon Bedrock, Amazon CloudWatch, and AWS IAM Identity Center in `us-east-1`, `us-west-2`, `eu-west-1`, and `ap-southeast-1`.
- Read-only API sampling surfaced AgentCore operations for Memory, runtime invocation/commands, Browser, Code Interpreter, Evaluations, A/B tests, recommendations, workload access tokens, and payment operations. Some sampled payment operations were visible only in `us-east-1` and `us-west-2`; treat this as sampled availability evidence only.

Review implications:
- Keep AgentCore Gateway, Identity, Memory, Browser, Code Interpreter, Evaluations, Registry, Payments, filesystem, and harness advice in references and re-query docs/tooling before promising exact CLI flags, maturity status, API coverage, or regional support.
- Service/API availability does not prove the user's account quotas, IAM permissions, deployed AgentCore resources, CLI version, or whether preview features are enabled.

## MCP grounding

- Use current AWS documentation tools to find and read the cited AgentCore behavior.
- Use read-only AWS MCP or read-only AWS CLI evidence for live availability and current-state claims when available. Treat that evidence as complementary to documentation, not as proof of the user's account configuration and never as permission to mutate AWS state.

## Grounding rule

Docs explain service behavior. They do not prove the user's installed CLI version, active AWS account, IAM role, Region support, quotas, deployed AgentCore resources, or whether preview-only features are enabled in that account.

# Safety checklist

Use before AgentCore deployment, tool exposure, Memory/Gateway changes, Identity integration, Browser/Code Interpreter enablement, or production recommendations.

## Non-negotiables

- Do not ask for or print AWS credentials, API keys, OAuth client secrets, access tokens, private keys, account IDs, customer data, or tenant identifiers.
- Do not hardcode credentials into MCP headers, agent code, environment files, or reference examples.
- Do not tell users the Python starter toolkit is the preferred new-project path when current official AWS docs recommend the npm CLI `@aws/agentcore`.
- Prefer AgentCore Gateway and AgentCore Identity for managed credential handling where applicable.
- Keep action/tool permissions least-privilege and scoped to the task.
- Confirm logging, metrics, tracing, and CloudWatch visibility before production rollout.
- Confirm CloudWatch Transaction Search / trace destination setup when relying on AgentCore observability.
- Confirm whether the answer relies on code-based agent GA behavior or harness preview behavior.
- Confirm whether the target region supports the specific AgentCore capability being recommended.
- Require explicit approval before deployment, exposing tools, enabling browser/code execution, attaching filesystems, enabling payment flows, or changing memory persistence.

## Component risks

- **Runtime:** wrong entrypoint, broad execution role, public network mode, missing logs, unbounded session lifetime.
- **Memory:** PII retention, namespace leakage, actor/session mixups, metadata-filter bypass, memory poisoning, untested deletion/expiry behavior.
- **Gateway/MCP tools:** overbroad tool access, raw bearer tokens, unsafe OpenAPI targets, excessive scopes, no tool audit trail, unsafe session reuse, ungoverned elicitation/sampling/streaming/log notifications.
- **Identity:** unmanaged secrets, unclear credential provider, missing rotation, broad OAuth scopes, assuming SigV4 preserves end-user identity when official docs say it does not.
- **Environment/skills/filesystems:** assuming `--skill-path` uploads local folders, forgetting ECR/VPC/container prerequisites, overbroad S3 Files/EFS mounts, path collisions, or binding nonexistent in-container paths.
- **Policy:** creating Gateway tools without Cedar policy boundaries or clear principal/resource conditions.
- **Browser:** browsing sensitive sites, recording exposure, egress risk, uncontrolled side effects.
- **Code Interpreter:** data exfiltration, untrusted code, package/network risk, missing sandbox boundaries.
- **Evaluations/optimization:** optimizing against unreviewed production traces, leaking prompt/tool data into eval datasets, promoting A/B winners without guardrail review.
- **Registry:** publishing unreviewed agents/tools/skills, semantic search surfacing sensitive tools, unclear approval workflow.
- **Payments:** preview maturity, wallet custody, spending limits, x402 endpoint trust, transaction auditability, refund/dispute handling.

## Evidence labels

Use `live evidence`, `repo evidence`, `user-provided evidence`, `documentation-based`, or `inference`. Documentation alone never proves the user's live AgentCore deployment.

# Workflow and output contract

Use this reference for full AgentCore implementation, deployment, or production-readiness work.

## Workflow

1. **Classify the path**
   - Existing agent adaptation
   - New project scaffold with the recommended npm CLI
   - Import/migration from an existing Amazon Bedrock Agent
   - Code-based agent versus config-based harness
   - Runtime/local invoke loop
   - Environment/skills path loading
   - Memory integration
   - Gateway/MCP/tool integration
   - Identity/credential flow
   - Observability/instrumentation
   - Browser or Code Interpreter tool usage
   - Evaluations, batch evaluations, user simulation, optimization, or A/B testing
   - Registry publishing/discovery/governance
   - Payments / x402 / wallet-backed agent transactions
   - Runtime or harness filesystem mounts
   - Policy/Cedar controls for Gateway tool access

2. **Verify tooling and docs**
   - Check installed AgentCore CLI/toolkit version when local commands will run.
   - Check whether the user is on a code-based agent path or the harness preview path.
   - For new projects, default to the npm CLI package `@aws/agentcore` unless the user is intentionally staying on an older Python toolkit workflow.
   - Prefer `AwsDocumentationMcpServer` for current official docs, then Context7 or configured AgentCore MCP documentation tools.
   - If AWS docs and starter-toolkit examples disagree, prefer the newer AWS devguide wording and call out the mismatch.
   - Treat bundled commands as examples until verified against local tooling.
   - Confirm region/API support before recommending AgentCore Runtime, Harness, Gateway, Memory, Evaluations, Browser, Code Interpreter, Payments, Registry, or Policy workflows.

3. **Implement minimally**
   - Existing agents: wrap/adapt runtime entrypoint; do not scaffold over code.
   - New projects: prefer non-interactive generation with the recommended CLI only when project creation is requested.
   - Skills: treat `--skill-path` as a container/session filesystem reference, not a skill uploader.
   - Filesystems: treat S3 Files/EFS mounts as data-perimeter resources with explicit path, lifecycle, and tenant-isolation decisions.
   - Memory/Gateway/Identity: create and test resources separately before wiring production flows.
   - Gateway: pair tool onboarding with policy, identity, session, streaming, elicitation, sampling, progress, and logging decisions; do not stop at endpoint creation.
   - Harness: call out preview status and identity propagation caveats if you recommend it.
   - Evaluations: use batch evaluation/user simulation/A-B validation for quality-sensitive production changes.
   - Registry: require publication, approval, access, and discovery governance before recommending broad catalog rollout.
   - Payments: treat as preview; require spending limits, wallet/provider choice, transaction audit, and rollback/disable path.

4. **Validate**
   - Run local invoke/test loop.
   - Confirm IAM role, network mode, environment variables, package dependencies, logs, metrics, tracing prerequisites, and rollback path.
   - Confirm which commands actually exist in the installed CLI before giving automation steps.
   - Confirm CloudWatch Transaction Search or equivalent telemetry destination if the recommendation relies on AgentCore observability.

## Output contract

Return:

1. AgentCore component in scope
2. Evidence level and current unknowns
3. Minimal implementation plan
4. Commands/code to run or verify
5. Security caveats
6. Rollback or cleanup path
7. Feature maturity caveat if the answer touches preview-only harness behavior