skills.rest
amplitude
amplitudeOFFICIAL
Explore all skills by this author →
WebsiteGitHub

investigate-ai-session

Diagnoses root causes of AI agent session failures using conversations and execution traces.

Updated Apr 3, 2026
Search Tags:#debugging#root cause analysis#ai agent#amplitude#agent analytics#execution trace#session investigation
One-click install
npx skills add https://github.com/amplitude/amplitude-copilot-plugin --skill investigate-ai-session-amplitude
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: investigate-ai-session
Source: https://github.com/amplitude/amplitude-copilot-plugin/tree/main/skills/plugins/amplitude/investigate-ai-session
Command: npx skills add https://github.com/amplitude/amplitude-copilot-plugin --skill investigate-ai-session-amplitude

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When an AI agent fails, gives wrong answers, or frustrates users, teams struggle to pinpoint why. This Skill performs root cause analysis on specific AI agent sessions or failure patterns by combining session metadata, full conversation transcripts, and span-level execution traces from Amplitude Agent Analytics. ## Core Features & Use Cases - Session Deep-Dives: Retrieves detailed session enrichment data, conversation transcripts, and execution traces for up to 5 sessions in parallel. - Failure Classification: Categorizes failures as tool errors, LLM failures, orchestration issues, user confusion, or data/context problems. - Pattern Detection: Groups failing sessions by agent, topic, or tool to determine whether an issue is one-off or systemic. - Use Case: A user reports that the Chart Agent keeps timing out. The Skill queries recent failed sessions, traces the spans to find a tool timeout after 30 seconds, confirms the pattern across sessions, and recommends adding retry logic with exponential backoff. ## Quick Start Ask the assistant to investigate why session abc-123 failed and identify the root cause using Amplitude Agent Analytics.

Frequently Asked Questions about investigate-ai-session

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

FAQPage Schema
How do I investigate why an AI agent session failed?▼

Provide the session ID and the Skill retrieves detailed session data, the full conversation transcript, and the span-level execution trace in parallel. It then classifies the failure type, checks whether it is systemic, and presents a root cause analysis with recommended fixes.

How to find the root cause of AI agent tool errors?▼

Query sessions filtered by tool name and failure flags, then deep-dive into representative sessions to inspect span status, latency, and error details. Aggregating spans by tool name reveals whether error rates correlate with the failing sessions.

Does this require Amplitude Agent Analytics instrumentation?▼

Yes, the Skill only works when Amplitude Agent Analytics is instrumented in the project. Span-level analysis additionally requires OpenTelemetry-compatible tracing in the AI agent; without it, only session and conversation data are available.

What if the session ID is not found?▼

The session may belong to a different project or fall outside the data retention window. Confirm the correct project and verify the session ID with the user before retrying the investigation.

How many sessions can be investigated at once?▼

The Skill deep-dives into at most 3-5 representative sessions per investigation. For larger failure sets, it first groups sessions by agent or topic to find the common pattern, then examines a few examples in detail.

Related Skills

Explore More Data & Analytics Skills→
coval-aicoval-ai
2

optimize-trace-observability

Add missing STT, LLM, TTS, and tool spans to OpenTelemetry traces.

Official
Advanced
RobinNorbergRobinNorberg
5

ultraqa

Automate end-to-end QA cycles across tests, builds, lint, and typecheck.

Community
Advanced
astronomerastronomer
419

debugging-dags

Diagnose Airflow DAG failures and identify root causes across pipelines.

Official
Basic
personamanagmentlayerpersonamanagmentlayer
41

ml-expert

Provide machine learning guidance and code for model training and MLOps.

Official
Advanced