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
| Mode | Behavior |
|---|---|
OBSERVE |
Log decisions only — never blocks tool calls |
MONITOR |
Log decisions with warnings — never blocks |
ENFORCE |
Log decisions AND block denied tool calls |
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.0google-adk >= 0.1.0(for running agents)
Links
License
Apache 2.0 — see LICENSE.
Metadata
Release files for tealtiger-adk 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tealtiger_adk-0.1.0.tar.gz | 12.8 kB | Without provenance | Details for tealtiger_adk-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tealtiger_adk-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for tealtiger_adk-0.1.0-py3-none-any.whl |
Total release size: 21.1 kB
Release files / tealtiger_adk-0.1.0.tar.gz
| Download URL | tealtiger_adk-0.1.0.tar.gz |
|---|---|
| Size | 12.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ed909873ea13e7625bc286e9ad92aa52cf8d62e4adeee2e777f34f15acf51aba
|
|
BLAKE2b-256 checksum How to use checksums |
c5c82056361366e89a0b5960291e3f52e1d487dc3d4b3afdb5ea9ecef5551f7e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Release files / tealtiger_adk-0.1.0-py3-none-any.whl
| Download URL | tealtiger_adk-0.1.0-py3-none-any.whl |
|---|---|
| Size | 8.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
eea24816e0865e064d2f3bce7fe5a0a1a76cd40bd8848008a27800319fbf9877
|
|
BLAKE2b-256 checksum How to use checksums |
bf03a69619e50213067be3092e4c7adede5e62820d4bc9904a4780d4e9c17c59
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Security for tealtiger-adk 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.