tealtiger-adk

Deterministic governance callbacks for Google Agent Development Kit (ADK) — policy enforcement, PII detection, cost tracking, and audit evidence for Gemini-powered agents.

Part of the TealTiger ecosystem — deterministic AI agent governance.

Features

• 🛡️ PII Detection — Block SSN, credit cards, emails, phone numbers, IP addresses in tool arguments
• 🔑 Secret Detection — Prevent API keys (OpenAI, GitHub, AWS, Google, Groq) from leaking through tools
• 💰 Cost Tracking — Per-session budget limits with automatic enforcement
• 🔧 Tool Allowlisting — Restrict which tools agents can call (supports wildcards)
• ❄️ Kill Switch — Instantly freeze/unfreeze an agent's tool access
• 📋 Audit Trail — Complete decision log with correlation IDs, timestamps, and risk scores
• ⚡ Sub-millisecond — Deterministic evaluation, no LLM in the governance path

Installation

pip install tealtiger-adk

Quick Start

from google.adk import Agent
from tealtiger_adk import TealTigerCallback

# Create governance callback
governance = TealTigerCallback(
    policies=[
        {"type": "pii_block", "categories": ["ssn", "credit_card", "email"]},
        {"type": "cost_limit", "max_per_session": 5.00},
        {"type": "tool_allowlist", "allowed": ["google_search", "code_*"]},
        {"type": "secret_detection"},
    ],
    mode="ENFORCE",  # OBSERVE | MONITOR | ENFORCE
)

# Attach to ADK agent
agent = Agent(
    model="gemini-2.0-flash",
    name="research_agent",
    tools=[google_search, code_execution],
    before_tool_callback=governance.before_tool,
    after_tool_callback=governance.after_tool,
)

# Run your agent normally — governance is transparent
response = agent.run("Find the latest AI safety research papers")

# Inspect governance decisions
print(f"Total decisions: {len(governance.decisions)}")
print(f"Denied: {governance.deny_count}")
print(f"Cost tracked: ${governance.total_cost:.4f}")

Governance Modes

Policy Types

PII Detection

{"type": "pii_block", "categories": ["ssn", "credit_card", "email", "phone", "ip_address"]}

Scans tool arguments for PII patterns. In ENFORCE mode, blocks the tool call and returns a governance denial message to the agent.

Cost Limits

{"type": "cost_limit", "max_per_session": 10.00}

Tracks cumulative cost per session. Blocks further tool calls once the budget is exhausted.

Tool Allowlisting

{"type": "tool_allowlist", "allowed": ["google_search", "code_*", "read_file"]}

Only allows tools matching the allowlist. Supports wildcard patterns (code_* matches code_execution, code_review, etc.).

Secret Detection

{"type": "secret_detection"}

Detects API keys and tokens (OpenAI sk-*, GitHub ghp_*, AWS AKIA*, Google AIza*, Groq gsk_*) in tool arguments.

Kill Switch

# Emergency freeze — blocks ALL tool calls regardless of policy
governance.freeze()

# Resume normal governance
governance.unfreeze()

# Check status
print(governance.is_frozen)  # True/False

Decision Audit Trail

Every governance evaluation produces a structured decision:

{
    "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp_ms": 1720000000000.0,
    "action": "DENY",
    "mode": "ENFORCE",
    "tool_name": "send_email",
    "agent_id": "adk-agent-a1b2c3d4",
    "reason_codes": ["PII_DETECTED:ssn"],
    "risk_score": 90,
    "evaluation_time_ms": 0.042,
    "cost_tracked": 0.0,
    "cumulative_cost": 0.008,
}

Integration with TealTiger Ecosystem

tealtiger-adk works standalone, but also integrates with the full TealTiger platform:

from tealtiger_adk import TealTigerCallback

# Stream decisions to your observability stack
def send_to_dashboard(decision):
    # Forward to TealTiger Dashboard, Langfuse, AgentOps, etc.
    requests.post("https://your-dashboard/api/decisions", json=decision)

governance = TealTigerCallback(
    policies=[...],
    mode="ENFORCE",
    on_decision=send_to_dashboard,
)

Requirements

• Python 3.10+
• tealtiger >= 1.1.0
• google-adk >= 0.1.0 (for running agents)

Links

• 📖 TealTiger Documentation
• 🐙 GitHub
• 📦 PyPI
• 🌐 tealtiger.ai

License

Apache 2.0 — see LICENSE.