# Agents Debug

Use when your agent or environment is broken, wrong answers, errors, timeouts, tool...

- Repository: https://github.com/aws/agent-toolkit-for-aws (3366 stars)
- Category: Testing
- License: Apache-2.0
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add aws/agent-toolkit-for-aws --skill agents-debug -g -a claude-code -y`
Codex: `npx skills add aws/agent-toolkit-for-aws --skill agents-debug -g -a codex -y`
Cursor: `npx skills add aws/agent-toolkit-for-aws --skill agents-debug -g -a cursor -y`
Gemini CLI: `npx skills add aws/agent-toolkit-for-aws --skill agents-debug -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add aws/agent-toolkit-for-aws`

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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

The rest: https://github.com/aws/agent-toolkit-for-aws/blob/HEAD/plugins/aws-agents/skills/agents-debug/SKILL.md