ask_cloud_assist |
The primary interface for Google Cloud Platform assistance. Use this tool to interact with the GCA Root Agent for general troubleshooting, log analysis, or broad cloud inquiries. It acts as the central orchestration agent that directs user requests to expert sub-agents or handles them directly using general-purpose tools. Capabilities:
- General Inquiries: Answers broad questions about Google Cloud services, concepts, and documentation.
- Estate Queries: Retrieves current resource state and inventory (e.g., "List my active VMs," "Show me the config for this pod").
- Directives: Executes specific, low-complexity directives or status checks.
- Triage & Routing: Handles complex or ambiguous intents (e.g., "Something is wrong with my app") to identify the problem scope before potentially handing off to specialized agents.
- Secure Execution: Orchestrates mutative actions (e.g., "Restart this VM", "Scale this cluster") using a secure Human-in-the-Loop (HITL) workflow. It verifies user consent before executing
gcloud commands.
Usage Guidelines:
- Default Choice: Select this tool when the user's intent is broad, ambiguous, exploratory, purely informational, or involves planning.
- Triage: Use this tool for initial issue reporting where the specific domain is not yet clear.
- Direct Execution: Use this tool when the user requests a specific, intended change to their environment (e.g., "Restart instance X", "Scale this cluster", "Update the firewall rule").
- Exclusions:
- If the user explicitly asks to design, architect, or deploy infrastructure, use
design_infra.
- If the user explicitly asks for deep root cause analysis, debugging, or remediation of a known failure, use
investigate_issue.
- If the user explicitly asks about costs, billing, or idle resources, use
optimize_costs.
Session Management:
- This tool returns a
contextId in its output.
- To continue a conversation (multi-turn), you MUST include this
contextId.
- Omit
contextId to start a new, independent task.
|
investigate_issue |
The Investigation Orchestrator Agent is the Principal Troubleshooting & Diagnostics Agent for Google Cloud. It acts as a specialized "SRE in a box" capable of navigating complex infrastructure, application code, and observability data to resolve incidents. Core Features & Architecture:
- Advanced Reasoning & Interactive Investigations: Uses sophisticated planning algorithms to execute parallelized hypothesis evaluation, allowing it to check multiple failure scenarios simultaneously rather than sequentially.
- Quick vs. Deep Investigation Strategy:
- Express Mode: For rapid insights, log/metric anomaly detection, and real-time status checks.
- Deep Research Mode: For complex Root Cause Analysis (RCA). It leverages domain expertise by integrating with specialized Database & Analytics Agents via the Cloud Assist Planner Agent.
- Diagnostic Runbooks: Can automatically select and execute pre-defined diagnostic playbooks for standardized troubleshooting.
- Trace-Based Topology: Generates dynamic architecture maps derived from real traffic traces, not just static configuration.
- Source Code Insights: Analyzes application logic to find root causes within the code itself (e.g., connection pools, queries).
- AI-Powered Explanation: Provides plain-language explanations for obscure error logs and metric anomalies.
When to route to this agent:
- User requests Root Cause Analysis (RCA) or help with an outage/crash.
- User asks to analyze logs, metrics, or traces for anomalies.
- User needs to understand dependencies or reason about topology graph.
- User asks about source code issues causing infrastructure failures.
- User wants to run specific diagnostics or health checks.
Detailed Capabilities & Skills:
Deep Research & Root Cause Analysis (RCA): Initiates a comprehensive, multi-step investigation using advanced reasoning and planning. It executes parallelized hypothesis evaluation, leveraging domain-specific agents (Database, Analytics) to find definitive root causes. Use this for complex, open-ended problems.
- Examples: "My application latency has spiked to 5s, find the root cause.", "Investigate why the chatter-service is throwing 503 errors during the load test.", "Why are the pods on ClusterABC unschedulable?", "Analyze the bottlenecks in my checkout flow.", "Perform a deep analysis of the database lock contention."
Diagnostic Runbooks & Playbooks: Executes deterministic diagnostic runbooks and standard operating procedures (SOPs). This skill integrates with the Cloud Assist Planner Agent to run validated checks for known issues and common failure modes.
- Examples: "Run the connectivity diagnostic for the frontend service.", "Execute the standard health check runbook.", "Check for known configuration issues using the diagnostic playbook.", "Is there a runbook to verify network reachability?"
Express Diagnostics & Anomaly Detection: Performs rapid 'Quick Checks' and automated anomaly detection on logs and metrics. Use this to instantly identify outliers, spikes, or error patterns without waiting for a full investigation.
- Examples: "Detect any metric anomalies for the checkout-service.", "Show me the traffic level and latency for the chatter-frontend service.", "Are there any outliers in the CPU usage?", "What are the top errors for the store-processing service right now?", "Scan the logs for recent error spikes."
AI-Powered Log & Error Reasoning: Uses AI to reason about and interpret complex error logs, stack traces, and metric patterns. Beyond simple explanation, it deduces the technical meaning and potential impact of observability data.
- Examples: "Analyze this stack trace and explain why the crash is happening.", "Reason about this 'Connection Reset' error in the context of high load.", "Interpret this obscure database error code.", "Why am I seeing this specific error log repeatedly?"
Trace-Based Topology Graph: Generates a dynamic topology graph derived from real application traces (OneGraph). It visualizes and reasons actual traffic paths and dependencies, overlaying latency and error signals on the graph nodes.
- Examples: "Show me the trace-based topology for the payment service.", "Visualize the actual traffic flow between microservices.", "Map out the dependencies based on recent request traces.", "Generate a graph showing where the latency is introduced in the stack."
Source Code Insights: Deeply analyzes application source code and configuration files (via DevConnect). It connects infrastructure symptoms to specific lines of code, identifying issues like bad queries, aggressive timeouts, or logic bugs.
- Examples: "Analyze the source code for inefficient database queries.", "Did a recent commit change the connection pool settings?", "Check the app logic for potential race conditions.", "Review the configuration files in the repo for errors."
Root Cause Resolution & Remediation: Synthesizes investigation findings to identify the definitive root cause and generates a corresponding actionable remediation plan (e.g., CLI commands, code patches) to resolve the issue.
- Examples: "Find the root cause of the database timeout and generate a plan to fix it.", "Identify why the instance is crashing and create a gcloud command to resize it.", "Determine the cause of the connection errors and suggest code changes.", "What is the recommended fix for this error?"
Multi-Turn Interactive Troubleshooting: Supports stateful, multi-turn interactivity. Allows the user to guide the investigation, ask follow-up questions, refine the scope, and iterate on findings in a conversational manner.
- Examples: "That didn't fix it, what should we check next?", "Can you look at the database logs instead?", "Let's focus on the frontend service now.", "Go deeper into that second hypothesis."
Session Management:
- This tool returns a
contextId in its output.
- To continue a conversation (multi-turn), you MUST include this
contextId.
|
