Initial commit: antigravity-claudekit

skills/ck-google-adk-python/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: ck-google-adk-python
+description: >
+  Builds AI agents using Google Agent Development Kit (ADK) for Python.
+  Activate when user says 'build a Google ADK agent', 'create agent with ADK',
+  'Google Agent Development Kit', 'multi-agent with ADK', or 'ADK tool calling'.
+  Accepts agent goals, tool definitions, and orchestration requirements.
+---
+
+## Overview
+Scaffolds and implements AI agents using Google's Agent Development Kit (ADK) for Python, covering single agents, multi-agent pipelines, tool definitions, and deployment to Vertex AI Agent Engine.
+
+## When to Use
+- Building autonomous agents that use tools to complete tasks
+- Creating multi-agent systems with specialized sub-agents
+- Implementing agents that need Google Cloud service integrations
+- Deploying production agents on Vertex AI Agent Engine
+- Building agents with structured tool calling and state management
+
+## Don't Use When
+- Project uses a different agent framework (LangChain, CrewAI, AutoGen)
+- Simple single-turn LLM calls without tool use (use direct Gemini API)
+- Frontend-only application with no agent orchestration needs
+- Budget constraints prohibit Vertex AI usage (ADK has local dev mode though)
+
+## Steps / Instructions
+
+### 1. Install ADK
+
+```bash
+pip install google-adk
+# For Vertex AI deployment:
+pip install google-adk[vertexai]
+```
+
+### 2. Define a Simple Agent
+
+```python
+# agent.py
+from google.adk.agents import Agent
+from google.adk.tools import FunctionTool
+import os
+
+def get_weather(city: str) -> dict:
+    """Get current weather for a city."""
+    # Replace with real weather API call
+    return {"city": city, "temperature": 22, "condition": "sunny"}
+
+weather_tool = FunctionTool(func=get_weather)
+
+root_agent = Agent(
+    name="weather_agent",
+    model="gemini-1.5-pro",
+    description="Answers weather questions for any city.",
+    instruction="""You help users get weather information.
+    Use the get_weather tool to fetch current conditions.
+    Always confirm the city before reporting.""",
+    tools=[weather_tool],
+)
+```
+
+### 3. Run Locally
+
+```python
+# main.py
+from google.adk.runners import Runner
+from google.adk.sessions import InMemorySessionService
+from google.genai.types import Content, Part
+from agent import root_agent
+
+async def main():
+    session_service = InMemorySessionService()
+    runner = Runner(
+        agent=root_agent,
+        app_name="weather_app",
+        session_service=session_service,
+    )
+
+    session = await session_service.create_session(
+        app_name="weather_app",
+        user_id="user_001",
+    )
+
+    message = Content(parts=[Part(text="What's the weather in Tokyo?")])
+
+    async for event in runner.run_async(
+        user_id="user_001",
+        session_id=session.id,
+        new_message=message,
+    ):
+        if event.is_final_response():
+            print(event.content.parts[0].text)
+
+import asyncio
+asyncio.run(main())
+```
+
+### 4. Multi-Agent Pattern
+
+```python
+from google.adk.agents import Agent
+from google.adk.agents.sequential import SequentialAgent
+
+research_agent = Agent(
+    name="researcher",
+    model="gemini-1.5-pro",
+    instruction="Research the given topic and return key facts.",
+    tools=[search_tool],
+)
+
+writer_agent = Agent(
+    name="writer",
+    model="gemini-1.5-pro",
+    instruction="Write a concise summary based on the research provided.",
+)
+
+pipeline = SequentialAgent(
+    name="research_writer",
+    sub_agents=[research_agent, writer_agent],
+)
+```
+
+### 5. Tool Definition Best Practices
+
+```python
+from typing import Annotated
+from pydantic import Field
+
+def search_database(
+    query: Annotated[str, Field(description="Search query string")],
+    limit: Annotated[int, Field(description="Max results to return", ge=1, le=50)] = 10,
+) -> list[dict]:
+    """Search the product database and return matching items."""
+    # implementation
+    pass
+```
+
+- Use type annotations — ADK generates JSON schema from them
+- Write clear docstrings — used as tool description for the model
+- Return dicts/lists that serialize cleanly to JSON
+- Handle errors gracefully and return error info in the dict
+
+### 6. Session State Management
+
+```python
+from google.adk.sessions import DatabaseSessionService
+
+# Persist sessions across restarts
+session_service = DatabaseSessionService(
+    db_url=os.environ["DATABASE_URL"]
+)
+```
+
+### 7. Deploy to Vertex AI Agent Engine
+
+```python
+from google.adk.deployment import deploy_agent
+
+deploy_agent(
+    agent=root_agent,
+    project=os.environ["GOOGLE_CLOUD_PROJECT"],
+    location="us-central1",
+    staging_bucket=os.environ["GCS_STAGING_BUCKET"],
+)
+```
+
+## Notes
+- Set `GOOGLE_API_KEY` or `GOOGLE_APPLICATION_CREDENTIALS` for authentication
+- Use `adk web` CLI for interactive local testing with a built-in UI
+- ADK auto-traces tool calls — view in Google Cloud Trace
+- Always validate tool inputs; the model may pass unexpected types