Debugging Antigravity AI Agents: A Systematic Diagnosis Guide

import os
from google import genai
from google.genai import types
 
client = genai.Client(api_key=os.getenv("GOOGLE_API_KEY"))
 
# Step 1: Basic connectivity — no tools
response = client.models.generate_content(
    model="gemini-2.5-pro",
    contents="Hello. This is a connectivity test."
)
print("Connectivity:", response.text[:50])
 
# Step 2: Add exactly one tool
def get_current_time() -> str:
    """Returns the current time."""
    from datetime import datetime
    return datetime.now().strftime("%Y-%m-%d %H:%M:%S UTC")
 
response = client.models.generate_content(
    model="gemini-2.5-pro",
    contents="What time is it?",
    config=types.GenerateContentConfig(
        tools=[get_current_time],
        system_instruction="Use the available tools to answer user requests."
    )
)
print("Single tool:", response.candidates[0].content)

import json
import logging
from datetime import datetime
from functools import wraps
 
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)
 
def debug_tool(func):
    """Decorator that logs tool inputs, outputs, and errors."""
    @wraps(func)
    def wrapper(*args, **kwargs):
        call_id = datetime.now().strftime("%H:%M:%S.%f")
        logger.debug(f"[{call_id}] CALL: {func.__name__}, args={args}, kwargs={kwargs}")
        
        try:
            result = func(*args, **kwargs)
            logger.debug(f"[{call_id}] OK: {str(result)[:200]}")
            return result
        except Exception as e:
            logger.error(f"[{call_id}] ERROR: {type(e).__name__}: {e}")
            # Return error as string so the agent can reason about it
            return f"Tool error: {type(e).__name__}: {str(e)}"
    
    return wrapper
 
@debug_tool
def search_database(query: str, limit: int = 10) -> str:
    """Searches the database and returns matching records.
    
    Args:
        query: Search query string
        limit: Maximum number of results to return (default: 10)
    
    Returns:
        JSON string containing matching records, or empty list if none found.
    """
    results = perform_actual_search(query, limit)
    return json.dumps(results, ensure_ascii=False)

class AgentLoopDetector:
    """Detects when an agent is stuck in a repetitive loop."""
    
    def __init__(self, max_repetitions: int = 3, max_steps: int = 20):
        self.call_history: list[tuple[str, str]] = []
        self.step_count = 0
        self.max_repetitions = max_repetitions
        self.max_steps = max_steps
    
    def check(self, tool_name: str, args: dict) -> bool:
        """Records a tool call and returns True if a loop is detected."""
        self.step_count += 1
        
        if self.step_count > self.max_steps:
            print(f"⚠️ Step limit ({self.max_steps}) reached")
            return True
        
        signature = (tool_name, str(sorted(args.items()) if args else []))
        recent = self.call_history[-self.max_repetitions * 2:]
        count = recent.count(signature)
        self.call_history.append(signature)
        
        if count >= self.max_repetitions - 1:
            print(f"⚠️ Loop detected: {tool_name} called {count + 1}x with same args")
            print(f"   Recent calls: {recent[-6:]}")
            return True
        
        return False
 
detector = AgentLoopDetector(max_repetitions=3, max_steps=15)
 
def guarded_tool_call(tool_name: str, args: dict):
    if detector.check(tool_name, args):
        raise RuntimeError(f"Agent loop detected at step {detector.step_count}. Halting.")
    return execute_tool(tool_name, args)

# Without completion criteria — loops happen
bad_system = """
Answer the user's question. Use tools when needed.
"""
 
# With completion criteria — loops become rare
good_system = """
You are a research agent.
 
## Task
Use available tools to collect information and generate an answer.
 
## When to stop using tools
Stop and provide your final answer when any of these conditions are met:
1. You have enough information to fully answer the question
2. You have run the search tool 3 times without finding relevant results
3. You have called the same tool with the same arguments twice
 
## Important rules
- Never run the same search query twice
- If information is incomplete, answer with what you have and state what's missing
- Never end a response with "I couldn't find information" — always suggest a next step
"""

# Vague — agent will misuse this
def search_knowledge_base(query: str) -> str:
    """Search the knowledge base."""
    ...
 
# Clear — agent knows when and how to use this
def search_knowledge_base(query: str, search_type: str = "semantic") -> str:
    """Searches internal documentation and returns relevant articles.
    
    USE THIS TOOL when:
    - The user asks about product specifications, manuals, or FAQs
    - You need past incident reports or troubleshooting history
    
    DO NOT USE THIS TOOL when:
    - Real-time external data is needed (use web_search instead)
    - You need database records (use query_database instead)
    
    Args:
        query: Natural language question or keyword string
        search_type: "semantic" for meaning-based search, "keyword" for exact match
    
    Returns:
        JSON with a list of matching documents. Each entry contains:
        title, content, relevance_score, and last_updated.
        Returns empty list if nothing is found.
    """
    ...