agents-debug

Name: agents-debug
Author: aws

587installs190forks

How to install agents-debug?

aws/agent-toolkit-for-aws/agents-debug

$npx -y skills add aws/agent-toolkit-for-aws --skill agents-debug

Installs into the current project.

Summary

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

Files · 1

View on GitHub

SKILL.md

1	# debug
2
3	Diagnose why your AgentCore agent or environment isn't working correctly.
4
5	## When to use
6
7	- Your agent is returning wrong answers or errors
8	- Tool calls are failing or timing out
9	- Agent works locally but fails after deploying
10	- Logs aren't showing up in CloudWatch
11	- The AgentCore CLI isn't working or environment seems broken
12	- `agentcore` command not found or prerequisites are missing
13
14	Do NOT use for:
15
16	- Deploy failures (CDK errors, IAM during deploy) → use `agents-deploy`
17	- Scaffolding a new project → use `agents-get-started`
18	- Measuring quality or setting up monitoring → use `agents-optimize`
19
20	## Input
21
22	`$ARGUMENTS` is optional:
23
24	```
25	/agents-debug # interactive — describe what's wrong
26	/agents-debug traces # read and explain recent traces
27	/agents-debug logs # search recent logs for errors
28	/agents-debug memory # diagnose memory recall issues specifically
29	/agents-debug doctor # check environment prerequisites
30	```
31
32	## Process
33
34	### Step 0: Determine problem type
35
36	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.
37
38	If the issue is about agent behavior (wrong answers, errors, timeouts, tool failures), continue with Step 1 below.
39
40	### Step 1: Verify CLI version
41
42	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.
43
44	### Step 2: Understand the symptom
45
46	Ask (or infer from context):
47
48	> "What's happening?
49	>
50	> 1. The agent returns an error message
51	> 2. The agent returns a wrong or unhelpful answer
52	> 3. A specific tool call is failing
53	> 4. Memory isn't working (agent doesn't remember things)
54	> 5. The agent is slow or timing out
55	> 6. I want to understand what the agent did in a specific session"
56
57	### Step 3: Read traces and logs automatically
58
59	Don't ask the developer to paste logs — read them directly.
60
61	```bash
62	# List recent traces
63	agentcore traces list --runtime <AgentName> --since 1h
64
65	# Get the most recent trace ID
66	agentcore traces list --runtime <AgentName> --since 1h --limit 1
67
68	# Download and read the trace
69	agentcore traces get <traceId> --runtime <AgentName>
70
71	# Search logs for errors
72	agentcore logs --runtime <AgentName> --since 1h --level error
73
74	# Search logs for a specific pattern
75	agentcore logs --runtime <AgentName> --since 2h --query "timeout"
76	agentcore logs --runtime <AgentName> --since 2h --query "model access"
77	```
78
79	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.
80
81	Read `agentcore/agentcore.json` to get the agent name if not provided.
82
83	### Step 4: Diagnose by symptom
84
85	---
86
87	## Symptom: "model access denied" or model error
88
89	Most common cause: The model isn't enabled in the Bedrock console for your region.
90
91	Fix:
92
93	1. Go to AWS Console → Amazon Bedrock → Model access
94	2. Enable the model your agent uses
95	3. Wait 1–2 minutes for access to propagate
96
97	Second cause: The execution role is missing `bedrock:InvokeModel`.
98
99	Check:
100
101	```bash
102	aws iam simulate-principal-policy \
103	--policy-source-arn $(agentcore status --json \| jq -r '.runtimes[0].executionRoleArn') \
104	--action-names bedrock:InvokeModel \
105	--resource-arns "arn:aws:bedrock:::foundation-model/"
106	```
107
108	Third cause: Cross-region inference profile requires model access in all regions.
109
110	Model IDs starting with a geographic prefix are cross-region inference profiles that route requests within that

People who liked this also viewed

6 picks

Type

agents-debug

587installs190forks

View on GitHub

How to install agents-debug?

aws/agent-toolkit-for-aws/agents-debug

$npx -y skills add aws/agent-toolkit-for-aws --skill agents-debug

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# debug
2
3	Diagnose why your AgentCore agent or environment isn't working correctly.
4
5	## When to use
6
7	- Your agent is returning wrong answers or errors
8	- Tool calls are failing or timing out
9	- Agent works locally but fails after deploying
10	- Logs aren't showing up in CloudWatch
11	- The AgentCore CLI isn't working or environment seems broken
12	- `agentcore` command not found or prerequisites are missing
13
14	Do NOT use for:
15
16	- Deploy failures (CDK errors, IAM during deploy) → use `agents-deploy`
17	- Scaffolding a new project → use `agents-get-started`
18	- Measuring quality or setting up monitoring → use `agents-optimize`
19
20	## Input
21
22	`$ARGUMENTS` is optional:
23
24	```
25	/agents-debug # interactive — describe what's wrong
26	/agents-debug traces # read and explain recent traces
27	/agents-debug logs # search recent logs for errors
28	/agents-debug memory # diagnose memory recall issues specifically
29	/agents-debug doctor # check environment prerequisites
30	```
31
32	## Process
33
34	### Step 0: Determine problem type
35
36	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.
37
38	If the issue is about agent behavior (wrong answers, errors, timeouts, tool failures), continue with Step 1 below.
39
40	### Step 1: Verify CLI version
41
42	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.
43
44	### Step 2: Understand the symptom
45
46	Ask (or infer from context):
47
48	> "What's happening?
49	>
50	> 1. The agent returns an error message
51	> 2. The agent returns a wrong or unhelpful answer
52	> 3. A specific tool call is failing
53	> 4. Memory isn't working (agent doesn't remember things)
54	> 5. The agent is slow or timing out
55	> 6. I want to understand what the agent did in a specific session"
56
57	### Step 3: Read traces and logs automatically
58
59	Don't ask the developer to paste logs — read them directly.
60
61	```bash
62	# List recent traces
63	agentcore traces list --runtime <AgentName> --since 1h
64
65	# Get the most recent trace ID
66	agentcore traces list --runtime <AgentName> --since 1h --limit 1
67
68	# Download and read the trace
69	agentcore traces get <traceId> --runtime <AgentName>
70
71	# Search logs for errors
72	agentcore logs --runtime <AgentName> --since 1h --level error
73
74	# Search logs for a specific pattern
75	agentcore logs --runtime <AgentName> --since 2h --query "timeout"
76	agentcore logs --runtime <AgentName> --since 2h --query "model access"
77	```
78
79	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.
80
81	Read `agentcore/agentcore.json` to get the agent name if not provided.
82
83	### Step 4: Diagnose by symptom
84
85	---
86
87	## Symptom: "model access denied" or model error
88
89	Most common cause: The model isn't enabled in the Bedrock console for your region.
90
91	Fix:
92
93	1. Go to AWS Console → Amazon Bedrock → Model access
94	2. Enable the model your agent uses
95	3. Wait 1–2 minutes for access to propagate
96
97	Second cause: The execution role is missing `bedrock:InvokeModel`.
98
99	Check:
100
101	```bash
102	aws iam simulate-principal-policy \
103	--policy-source-arn $(agentcore status --json \| jq -r '.runtimes[0].executionRoleArn') \
104	--action-names bedrock:InvokeModel \
105	--resource-arns "arn:aws:bedrock:::foundation-model/"
106	```
107
108	Third cause: Cross-region inference profile requires model access in all regions.
109
110	Model IDs starting with a geographic prefix are cross-region inference profiles that route requests within that

People who liked this also viewed

6 picks

Type