agents-debug

Files (2)

• SKILL.md
• doctor.md · references/

SKILL.md (first lines)

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

```bash
# 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:

```bash
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.

From aws/agent-toolkit-for-aws, Apache-2.0.

More from aws/agent-toolkit-for-aws