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 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