/agents-debug

name: agents-debug
description: >
  Use when your agent or environment is broken — wrong answers, errors,
  timeouts, tool failures, or CLI issues. Reads traces and logs to
  diagnose root causes. Also checks prerequisites when the CLI itself
  isn't working. Triggers on: "agent not working", "wrong answer",
  "agent error", "tool call failing", "debug agent", "check logs",
  "read traces", "broken", "500 error", "424 error", "model access
  denied", "command not found", "stuck in DELETING", "maxVms exceeded",
  "cold start diagnosis", "cold start slow", "agentcore create error",
  "create failed", "exit code 7", "connection refused local dev".
  Not for deploy failures — use agents-deploy. Not for performance
  tuning without errors — use agents-optimize. Not for VPC
  configuration — use agents-build. Not for observability setup or
  missing logs — use agents-optimize.
allowed-tools: Read Grep Glob Bash
metadata:
  type: skill
  version: "1.0.0"
  author: aws-agentcore
  requires-cli: ">=0.9.0"

debug

Diagnose why your AgentCore agent or environment isn't working correctly.

When to use

• Your agent is returning wrong answers or errors
• Tool calls are failing or timing out
• Agent works locally but fails after deploying
• Logs aren't showing up in CloudWatch
• The AgentCore CLI isn't working or environment seems broken
• `agentcore` command not found or prerequisites are missing

Do NOT use for:

• Deploy failures (CDK errors, IAM during deploy) → use `agents-deploy`
• Scaffolding a new project → use `agents-get-started`
• Measuring quality or setting up monitoring → use `agents-optimize`

Input

`$ARGUMENTS` is optional:

/agents-debug                      # interactive — describe what's wrong
/agents-debug traces               # read and explain recent traces
/agents-debug logs                 # search recent logs for errors
/agents-debug memory               # diagnose memory recall issues specifically
/agents-debug doctor               # check environment prerequisites

Process

Step 0: Determine problem type

If the developer's issue is about the CLI itself (command not found, prerequisites, environment setup), load [`references/doctor.md`](references/doctor.md) and follow its diagnostic checklist.

If the issue is about agent behavior (wrong answers, errors, timeouts, tool failures), continue with Step 1 below.

Step 1: Verify CLI version

Run `agentcore --version`. This skill requires v0.9.0 or later. If the version is older, tell the developer to run `agentcore update` before proceeding.

Step 2: Understand the symptom

Ask (or infer from context):

> "What's happening? > > 1. The agent returns an error message > 2. The agent returns a wrong or unhelpful answer > 3. A specific tool call is failing > 4. Memory isn't working (agent doesn't remember things) > 5. The agent is slow or timing out > 6. I want to understand what the agent did in a specific session"

Step 3: Read traces and logs automatically

Don't ask the developer to paste logs — read them directly.

# List recent traces
agentcore traces list --runtime <AgentName> --since 1h

# Get the most recent trace ID
agentcore traces list --runtime <AgentName> --since 1h --limit 1

# Download and read the trace
agentcore traces get <traceId> --runtime <AgentName>

# Search logs for errors
agentcore logs --runtime <AgentName> --since 1h --level error

# Search logs for a specific pattern
agentcore logs --runtime <AgentName> --since 2h --query "timeout"
agentcore logs --runtime <AgentName> --since 2h --query "model access"

**Important:** CloudWatch put-to-get latency is **~10 seconds end-to-end** — that's the delay from when a span is emitted to when it's readable by `agentcore traces get` or `agentcore run eval`. There is **no separate "trace ingested but eval not ready yet" window**; the same ingestion step unlocks both paths. Older skills and docs said 30–60s for traces and 2–5 minutes for evals — both are stale. If you just invoked the agent, wait ~15 seconds and both trace reads and evals will work.

Read `agentcore/agentcore.json` to get the agent name if not provided.

Step 4: Diagnose by symptom

---

Symptom: "model access denied" or model error

**Most common cause:** The model isn't enabled in the Bedrock console for your region.

Fix:

1. Go to AWS Console → Amazon Bedrock → Model access 2. Enable the model your agent uses 3. Wait 1–2 minutes for access to propagate

**Second cause:** The execution role is missing `bedrock:InvokeModel`.

Check:

aws iam simulate-principal-policy \
  --policy-source-arn $(agentcore status --json | jq -r '.runtimes[0].executionRoleArn') \
  --action-names bedrock:InvokeModel \
  --resource-arns "arn:aws:bedrock:*::foundation-model/*"

**Third cause:** Cross-region inference profile requires model access in all regions.

Model IDs starting with a geographic prefix are cross-region inference profiles that route requests within that geography:

| Prefix | Geography | Example destination regions | |---|---|---| | `us.` | United States | us-east-1, us-east-2, us-west-2 | | `eu.` | Europe | eu-central-1, eu-west-1, eu-west-2, eu-west-3 | | `apac.` | Asia Pacific | ap-northeast-1, ap-southeast-1, ap-southeast-2, ap-south-1 | | `global.` | All commercial regions worldwide | All supported regions |

The AgentCore CLI scaffolds `global.` by default (e.g., `global.anthropic.claude-sonnet-4-5-20250929-v1:0`). All prefixes require model access enabled in every destination region the profile covers. For `us.` profiles, enable in all US regions; for `eu.`, all EU regions; for `global.`, all supported regions. Not all models support all prefixes — `global.` is currently available for select models only. Use `global.` for maximum throughput when available, or a geographic prefix when data residency requirements constrain where inference can run. Check the Bedrock inference profiles docs for current model × prefix availability.