cianfhoghlaim/cianchosaint / .agents/skills/google-adk
google-adk
Verifiedname: google-adk description: Expert assistance for building AI agents with Google's Agent Development Kit. Use when users need multi-agent coordination via the Multi-Agent Workflow Engine + NodeRunner, Native Inter-Agent Routing (v2.1+), the A2A Protocol for cross-agent communication, neuro-symbolic OWL truth-anchoring, or production deployment to Agent Engine. Cianfhoghlaim-specific: agent chain is OCR → BAML → embedding → Graphiti → RAGAS.
Google ADK - Agent Development Kit
Version: >=2.9.0,<3 | Last Updated: 2026-09-26
Overview
Google's Agent Development Kit (ADK) is a framework for building production AI agents with first-class multi-agent coordination:
- Multi-Agent Workflow Engine + NodeRunner — explicit workflow graph with deterministic orchestration
- Native Inter-Agent Routing (v2.1+) — agents route to other agents based on request content, with fallback chains
- A2A Protocol — agent-to-agent communication via the open
protocol (
/.well-known/agent.jsonAgent Cards, JSON-RPC 2.0 over SSE) - Workflow Primitives —
SequentialAgent,LoopAgent(withTerminationStrategy),ParallelAgent(fan-out / gather), Coordinator Pattern - Neuro-Symbolic Truth Anchoring — OWL knowledge graph enforces hard constraints on LLM outputs (e.g. compliance, regulatory)
- Production deployment —
make deployto Agent Engine (managed), withmake register-gemini-enterprise, always-on Cloud Trace, optional GCS / BigQuery / Cloud Logging - Google AI Integration — Gemini Live API, Firecrawl integration via TypeScript adapters
Documentation: https://cloud.google.com/agent-development-kit
When to Use This Skill
Activate when users need:
- "Build a multi-agent system with explicit workflow control"
- "Create Google AI agents"
- "Coordinate multiple agents with the A2A Protocol"
- "Anchor an LLM's output to an OWL knowledge graph"
- "Deploy agents to Google Agent Engine"
- "Wire Gemini Live API into a voice agent"
- "Integrate Firecrawl scraping into an agent"
Core Concepts
Agent
The basic unit. Created via Agent(...) with a model, system
prompt, tools, and (optionally) a sub-agent list.
from google.adk.agents import Agent
agent = Agent(
name="curriculum_extractor",
model="gemini-2.5-pro",
system_prompt="Extract curriculum areas and learning outcomes.",
tools=[pdf_extractor, schema_validator],
)
Multi-Agent Coordination (v2.1+)
The Multi-Agent Workflow Engine + NodeRunner provides
explicit, deterministic orchestration. There are 4
workflow primitives:
1. SequentialAgent
A → B → C. The output of A is the input of B, etc.
from google.adk.agents import SequentialAgent
pipeline = SequentialAgent(
name="ocr_to_kg_pipeline",
sub_agents=[
ocr_agent, # step 1: PDF → text
baml_extractor, # step 2: text → typed BAML class
embedder, # step 3: text → vector embedding
kg_writer, # step 4: embedding + metadata → Graphiti
],
)
2. LoopAgent (with TerminationStrategy)
A → B → A → B → ... until a termination strategy is met. The canonical use case is draft-critique-refine:
from google.adk.agents import LoopAgent, TerminationStrategy
loop = LoopAgent(
name="draft_critique_refine",
sub_agents=[draft_writer, critic],
termination=TerminationStrategy(
# Stop when the critic returns "approved"
stop_on=lambda critic_output: "approved" in critic_output,
max_iterations=5, # safety cap
),
)
3. ParallelAgent (fan-out / gather)
Run N agents in parallel, gather their outputs.
from google.adk.agents import ParallelAgent
parallel = ParallelAgent(
name="multi_perspective_analyzer",
sub_agents=[
linguistic_analyzer, # runs in parallel
cultural_analyzer, # runs in parallel
historical_analyzer, # runs in parallel
],
# The outputs are gathered into a list and passed to the
# downstream agent.
)
4. Coordinator Pattern (TripPlanner)
A "root" agent that has a fleet of sub-agents and routes to
them based on the request. The canonical example is TripPlanner
— a coordinator with flights, hotels, and activities
sub-agents:
coordinator = Agent(
name="trip_planner",
model="gemini-2.5-pro",
system_prompt="You are a trip planner. Route to the right sub-agent.",
sub_agents=[flights_agent, hotels_agent, activities_agent],
)
In v2.1+, the routing is native — the coordinator's model makes the routing decision automatically, no manual routing logic required.
A2A Protocol (Agent-to-Agent)
For cross-agent communication across processes (or even across
vendors), use the A2A Protocol. The wire
format is JSON-RPC 2.0 over SSE, with a discovery endpoint
(/.well-known/agent.json).
Server side (your agent)
from google.adk.a2a import A2AServer
server = A2AServer(
agent=my_agent,
agent_card_url="https://my-agent.example.com/.well-known/agent.json",
port=8080,
)
server.serve()
Client side (another agent calling yours)
from google.adk.a2a import A2AClient
client = A2AClient("https://my-agent.example.com")
result = client.call("extract_curriculum", {"pdf_url": "..."})
The agent card (at /.well-known/agent.json) advertises the
capabilities, input/output schema, and version.
Neuro-Symbolic Truth Anchoring
For compliance-critical agents (e.g. medical, legal, financial), ADK supports an OWL knowledge graph as a hard constraint on the LLM output. The LLM proposes, the OWL engine disposes.
from google.adk.symbolic import OWLTruthAnchor
# Load the OWL ontology
anchor = OWLTruthAnchor.from_file("compliance.owl")
# Wrap any agent with the truth anchor
anchored_agent = anchor.wrap(
agent=my_compliance_agent,
# If the agent output violates the OWL ontology,
# reject it and ask the agent to retry.
reject_and_retry=True,
)
Canonical Cianfhoghlaim use case: the Mionnscríbhinn (Irish-language
land deed) Compliance Agent. The LLM proposes extracted
entities, the OWL ontology (which encodes the 19th-century
Irish land-tenure model) validates, and any output that
violates the ontology is rejected.
Production Deployment
The canonical deployment is Google Agent Engine (managed):
# Build and push the container
make deploy
# Or directly
gcloud run deploy my-agent \
--image gcr.io/PROJECT/my-agent \
--region us-central1 \
--set-env-vars GOOGLE_API_KEY=...
make deploy (in the Cianfhoghlaim saoi/ project layout) builds,
pushes, and deploys in one step. After deployment, the agent
endpoint is available at the Agent Engine URL.
Register with Gemini Enterprise
make register-gemini-enterprise
This makes the agent discoverable in the Gemini Enterprise console (for users with a Google Workspace license).
Observability
Agent Engine automatically enables:
- Cloud Trace (always on) — every agent invocation is traced with full input / output / tool calls
- GCS export (optional) —
GOOGLE_CLOUD_STORAGE_BUCKET=... - BigQuery export (optional) — for SQL analytics on agent traffic
- Cloud Logging (optional) —
GOOGLE_CLOUD_LOGGING=true
Tools
Any Python function can be a tool:
from google.adk.tools import tool
@tool
async def get_weather(city: str) -> dict:
"""Get the current weather for a city."""
response = await fetch(f"https://api.weather.com/{city}")
return response.json()
The function's signature + docstring are auto-extracted into the agent's tool schema. The LLM decides when to call the tool.
Multimodal (Gemini Vision)
agent = Agent(
name="receipt_extractor",
model="gemini-2.5-pro", # vision-capable
system_prompt="Extract line items from this receipt image.",
tools=[receipt_validator],
)
Pass images / PDFs as parts in the request; Gemini handles
the rest.
Gemini Live API (voice / streaming)
from google.adk.live import LiveAgent
agent = LiveAgent(
name="voice_assistant",
model="gemini-2.5-flash-live",
voice="en-US-Neural2-A",
)
Use the Live API for real-time voice conversations, low-latency chat, or streaming audio. The ADK handles the WebSocket / audio encoding for you.
Firecrawl Integration (TypeScript)
For agents that need to scrape web pages, use the Firecrawl adapter (TypeScript):
import { Agent, firecrawl } from "@google/adk";
const agent = new Agent({
name: "scraper",
model: "gemini-2.5-pro",
tools: [
firecrawl({
apiKey: process.env.FIRECRAWL_API_KEY,
}),
],
});
The firecrawl tool can scrape, crawl, and extract structured
data from any URL.
Cianfhoghlaim agent chain (Cianfhoghlaim-specific)
The Cianfhoghlaim ingestion pipeline is a 5-stage SequentialAgent:
from google.adk.agents import SequentialAgent
pipeline = SequentialAgent(
name="ingestion",
sub_agents=[
ocr_agent, # PDF → text (Docling, PaddleOCR, ColPali)
baml_extractor, # text → typed BAML class
embedder, # text → vector (BGE-M3 or BGE-large-en)
graphiti_agent, # vector + metadata → Graphiti episode
ragas_evaluator, # run 6 deterministic evals
],
)
This is wired up via the cianfhoghlaim-curriculum-extraction
Dagster asset, which runs the pipeline against incoming NCCA
PDFs.
Memory and Context
from google.adk.memory import InMemoryMemory
memory = InMemoryMemory()
agent = Agent(
name="tutor",
model="gemini-2.5-pro",
memory=memory,
system_prompt="You are a tutor. Remember the student's progress.",
)
For production, use a persistent memory store (Vertex AI Memory Bank or a custom backend).
Cianfhoghlaim integration notes
- LLM backend: LiteLLM gateway (project gateway; LiteLLM routes to Gemini, OpenAI, Anthropic, etc.)
- Tracing: Langfuse (project tracing) — every agent invocation is traced
- Memory: Graphiti (bi-temporal knowledge graph) + Cognee (the primary KG) for long-term context
- Eval: RAGAS (project eval) for end-to-end agent quality
- Related skills:
.agents/skills/agno/,.agents/skills/pydantic-ai/,.agents/skills/baml/,.agents/skills/litellm/,.agents/skills/langfuse/,.agents/skills/ragas/
Resources
- ADK docs: https://cloud.google.com/agent-development-kit
- A2A Protocol: https://a2a.dev/
- Agent Engine: https://cloud.google.com/agent-engine
- Gemini Live API: https://ai.google.dev/gemini-api/docs/live
- Cianfhoghlaim agent chain:
cianfhoghlaim-curriculum-extractionDagster asset - Cianfhoghlaim examples:
cianfhoghlaim/saoi/(the canonical Cianfhoghlaim ADK project layout)
Framework comparison (when to use this vs Pydantic AI / Agno)
| Use case | Google ADK | Pydantic AI | Agno |
|---|---|---|---|
| Gemini Live API / voice | ✅ first-class | ⚠️ via OpenAI | ⚠️ via OpenAI |
| A2A Protocol | ✅ built-in | ⚠️ via adapter | ✅ built-in |
| AgentOS / managed deploy | ✅ Agent Engine | ⚠️ self-host | ✅ AgentOS |
| Neuro-symbolic OWL | ✅ Truth Anchoring | ❌ | ❌ |
| MCP server | ✅ built-in | ✅ via adapter | ✅ via adapter |
| Workflow primitives (Sequential/Loop/Parallel) | ✅ first-class | ⚠️ via DBOS | ✅ first-class |
| Type-safe I/O (Pydantic) | ✅ | ✅ first-class | ✅ |
| Multi-model support (OpenAI, Anthropic, Gemini) | ⚠️ Gemini-first | ✅ any | ✅ any |
| AG-UI SSE integration | ⚠️ via adapter | ✅ first-class | ✅ first-class |
Rule of thumb: use Google ADK for Gemini-heavy workflows (Live API, A2A, Agent Engine); use Pydantic AI for type-safe I/O with Pydantic models (the Cianfhoghlaim standard); use Agno for multi-agent teams with Z.ai GLM-4.6 (cost-effective).
Cianfhoghlaim LiteLLM wire-up (Agent 63 — 2026-06-29)
Historical drift (RESOLVED 2026-08-15): the 32 LlmAgent(model=config.model_name) constructors historically hardcoded "gemini-2.0-flash", BYPASSING the Cianfhoghlaim minimax 7-tier LiteLLM fallback alias (Agent 06 P0-#1 drift finding). As of 2026-08-15-centralized-model-schema-registry-and-deployment-control-panel-v1, all 32 sites now resolve through the unified MODEL_REGISTRY (meaisinfhoghlaim.models.MU_REGISTRY.resolve("text_llm", "default")), so the default flows through the LiteLLM alias without further code changes.
For new agent code, prefer the LiteLlm model wrapper (ADK 1.5+) to make the LiteLLM routing explicit:
from google.adk.models.lite_llm import LiteLlm
from collections.abc import Callable
def _minimax_model() -> LiteLlm:
"""Resolve the Cianfhoghlaim `minimax` 7-tier LiteLLM alias at agent-construction time."""
return LiteLlm(
model="minimax", # Cianfhoghlaim canonical alias
api_base=os.getenv("LITELLM_API_BASE", "https://litellm.cianfhoghlaim.ie"),
)
```python
from google.adk.models.lite_llm import LiteLlm
from collections.abc import Callable
def _minimax_model() -> LiteLlm:
"""Resolve the Cianfhoghlaim `minimax` 7-tier LiteLLM alias at agent-construction time."""
return LiteLlm(
model="minimax", # Cianfhoghlaim canonical alias
api_base=os.getenv("LITELLM_API_BASE", "https://litellm.cianfhoghlaim.ie"),
)
# In each LlmAgent constructor:
agent = LlmAgent(
name="celtic_education_research_planner",
model=LiteLlm(model="minimax", api_base="https://litellm.cianfhoghlaim.ie"),
description="...",
instruction="...",
)
Bump: google-adk>=1.0.0 → >=1.5.0 (for the LiteLlm class).
Email triage surface (2026-06-29)
A new oideachais ADK agent email_triage (on port 7778) exercises
the new email-inbox pipeline with 4 read-only tools
(classify_email_thread, summarise_thread,
link_thread_to_research, find_loose_threads). The agent itself
is the agent-platform sub-agent's scope, but the ADK framework
patterns (SequentialAgent, LoopAgent, citation_callbacks, A2A
Protocol) are reused as-is — see
.agents/skills/cianfhoghlaim-email-triage/SKILL.md
for the full BAML + Dagster + marimo + cognify wiring.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |