agents-debug

Diagnose AgentCore agent failures by reading traces, logs, and environment prerequisites.

1|Updated Aug 1, 2024
One-click install
npx skills add https://github.com/obispobruno/dotfiles --skill agents-debug-obispobruno
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: agents-debug
Source: https://github.com/obispobruno/dotfiles/tree/main/dot_agents/skills/agents-debug
Command: npx skills add https://github.com/obispobruno/dotfiles --skill agents-debug-obispobruno

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? When your AgentCore agent returns wrong answers, throws errors, times out, or the CLI itself stops working, this Skill reads traces and logs directly to find the root cause instead of asking you to paste output manually. ## Core Features & Use Cases - Trace and log analysis: Automatically lists, downloads, and interprets recent traces and CloudWatch logs to pinpoint failing model calls, tool calls, and memory operations. - Symptom-based diagnosis playbooks: Covers model access denied, tool call failures, memory not persisting, 424 errors, maxVms quota exhaustion, streaming disconnects, missing CloudWatch logs, and stuck DELETING runtimes. - Environment doctor: Checks CLI version, Node.js, uv, AWS credentials, Bedrock model access, IAM permissions, and Docker with exact fix commands for each failure. - Use Case: Your deployed agent returns "model access denied" — the Skill checks Bedrock model access, verifies the execution role has bedrock:InvokeModel, and explains cross-region inference profile requirements. ## Quick Start Ask the agent to debug why your AgentCore agent is failing by running the agents-debug skill and describing the symptom.

Frequently Asked Questions about agents-debug

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug an AgentCore agent that returns wrong answers?▼

Read the agent's trace with agentcore traces get to see the model's reasoning, tool calls, and final response. Common causes include vague system prompts, missing tool descriptions, unexpected tool data formats, or an undersized model for the task.

How do I fix model access denied errors in Amazon Bedrock?▼

Enable the model in the AWS Console under Amazon Bedrock Model access and wait 1-2 minutes for propagation. Also verify the execution role has bedrock:InvokeModel, and enable access in every region covered by cross-region inference profiles like us., eu., or global. prefixes.

Why are CloudWatch logs not appearing for my AgentCore runtime?▼

Container builds must wrap the entrypoint with opentelemetry-instrument, the IAM role needs logs and xray permissions, and code must use Python's logging module instead of print. For IaC-deployed runtimes, logs:DescribeLogGroups requires Resource set to wildcard.

Why does InvokeAgentRuntime fail with maxVms limit exceeded at low concurrency?▼

The maxVms quota counts idle environments not yet reclaimed, not just active sessions. Call StopRuntimeSession after each request, reuse session IDs, or lower idleRuntimeSessionTimeout before requesting a quota increase.

Can I use this skill for deploy failures or performance tuning?▼

No. Deploy failures such as CDK or IAM errors belong to the agents-deploy skill, and performance tuning without errors belongs to agents-optimize. This skill covers runtime errors, wrong answers, tool failures, and broken CLI environments only.

Why do local agent invocations fail with connection refused or exit code 7?▼

The agentcore dev server auto-increments ports when defaults are occupied, so a hardcoded port 8080 may miss a server running on 8082. Check the CLI banner or dev logs for the actual bound port, or pin it with agentcore dev --port.