Reference links:

• Agent Skill Hub Repository
• whisperASR Reference Example
• GitHub Pages Official Documentation

This article documents how I built a skill description specification from scratch and created a GitHub Pages documentation site that supports both Chinese and English, drawing inspiration from minimalist aesthetics, while developing the Agent Skill Hub (2026 Skill Library).

Background

With the popularity of AI Agents (such as OpenClaw or Gemini CLI), we found that “how to quickly understand and execute specific tasks for the Agent” has become key. Instead of writing long prompts every time, it’s better to package common operations into standardized Skills.

To facilitate community communication and Agent reading, I created agent-skill-hub. But code alone is not enough; we also need a decent “facade” – a document website that is both aesthetically pleasing and has technical details.

🛠️ Step 1: Standardize Skill Descriptions (SKILL.md)

In agent-skill-hub, each skill (such as gcp-helper or n8n-executor) has a SKILL.md. The structure of this file is crucial because it’s not just for humans to read, but also for LLMs to read:

• Name & Description: Let the Agent know what this is.
• When to Use: Define trigger scenarios.
• Core Pattern: Provide standard instruction examples.
• Common Mistakes: Reduce errors caused by Agent hallucinations.

🎨 Step 2: Design Style — Tribute to Minimalist Aesthetics

When designing the web pages under the docs directory, I referenced the style of whisperASR. That design of a dark background with bright accent colors (Teal) is very in line with the aesthetics of modern developers:

Visual Element Highlights:

1. Gradient Title: Use linear-gradient to create a high-end texture.
2. Teal Accent Color: Use #14b8a6 as the highlight color for key buttons and titles.
3. Card-style Layout: Clearly present the icons and introductions of each skill, with good responsive design.

🌐 Step 3: Multilingual Support and Automatic Switching

To make it available to developers worldwide, I adopted a directory-structured language management method:

docs/
├── index.html (Language detection and redirection)
├── en/ (English version)
│ └── skills/
└── zh/ (Traditional Chinese version)
    └── skills/

I added a simple JavaScript snippet to the root directory’s index.html, which automatically redirects to the correct language based on the user’s browser settings:

const lang = navigator.language || navigator.userLanguage;
if (lang.startsWith('zh')) {
    window.location.href = './zh/index.html';
} else {
    window.location.href = './en/index.html';
}

🚀 Step 4: GitHub Pages Deployment Process

In 2026, the most recommended deployment method is to put the content in the docs/ directory of the main branch, which can keep the main branch clean while keeping development and documentation synchronized.

1. Prepare the Directory Structure

Create all the necessary directories at once using the command:

mkdir -p docs/en/skills docs/zh/skills docs/assets/css

2. Git Commit and Push

After completing HTML/CSS development, execute the standard Git process:

git add docs/
git commit -m "docs: add GitHub Pages documentation in English and Chinese"
git push origin main

3. Enable GitHub Pages Settings

1. Go to Settings > Pages in the GitHub repository.
2. Under Build and deployment, in Branch, select the main branch and the /docs folder.
3. Click Save, and the website will be online in a few minutes.

🛠️ Common Pitfalls and Troubleshooting

❓ Why can’t the webpage style (CSS) be loaded?

Reason: In HTML files under subdirectories (such as en/skills/), the referenced paths must correctly use relative paths. Correction:

<!-- In the home page index.html -->
<link rel="stylesheet" href="../assets/css/style.css">
<!-- In the skill detail page -->
<link rel="stylesheet" href="../../assets/css/style.css">

❓ How to ensure that the Agent can correctly read the document?

We have retained a large number of semantic tags (article, h2, pre, code) in the HTML, so that the Agent can more accurately capture the core logic when performing RAG (Retrieval-Augmented Generation) or directly reading the webpage.

🏁 Conclusion

Through this development, I have realized the importance of “documentation as product”. A good AI skill library, in addition to powerful program logic, also needs a clear, intuitive, and multilingual-friendly navigation system.

If you also want to create a professional facade for your AI project, you might as well refer to the docs/ structure layout. Happy Coding! 🦞

Reference links:

• A2AS.org Official Website
• linebot-adk Project Certification Page

This article documents an interesting Pull Request I received while maintaining linebot-adk (LINE Bot Agent Development Kit): adding the A2AS security certificate to the project. This is not just a YAML file, but a significant milestone for AI Agents to move towards “industrial-grade security” in 2026.

Background

When we develop Agents like linebot-adk that have Tool Use (Function Calling) capabilities, the biggest concern for users is often: “Will this Agent issue commands without my permission?” or “What data can it access?”.

Traditionally, we could only write explanations in README.md, but that’s for humans to read, not for system verification. This is why A2AS (Agent-to-Agent Security) emerged – it’s hailed as the “HTTPS of the AI world”.

🛠️ Step 1: Understanding the BASIC Model of A2AS

A2AS is not just a name; it has a complete BASIC security model behind it, designed to solve the trust issue between AI Agents:

• (B)ehavior Certificates: Declarative certificates that clearly define the behavior boundaries of the Agent.
• (A)uthenticated Prompts: Ensures that the source of prompts is trustworthy and traceable.
• (S)ecurity Boundaries: Uses structured tags (such as <a2as:user>) to isolate untrusted input.
• (I)n-Context Defenses: Embeds defense logic in prompts to reject malicious injections.
• (C)odified Policies: Writes business rules into code and enforces them during inference.

🎨 Step 2: Deconstructing a2as.yaml – The Agent’s ID Card

In PR #1 received by linebot-adk, the most core change was the addition of a2as.yaml. This file is like the Agent’s “digital signature”, making the code logic explicit:

manifest:
  subject:
    name: kkdai/linebot-adk
    scope: [main.py, multi_tool_agent/agent.py]
  issued:
    by: A2AS.org
    url: https://a2as.org/certified/agents/kkdai/linebot-adk

agents:
  root_agent:
    type: instance
    models: [gemini-2.5-flash]
    tools: [get_weather, get_current_time]

Why is this important?

This certificate is directly linked to the content of our main.py. When the certificate declares tools: [get_weather, get_current_time], it means this is a limited-authorization Agent. If it tries to execute delete_database, the security monitoring system can immediately detect that it is outside the certificate scope.

🌐 Step 3: Combining Code Logic

In linebot-adk, we used Google’s ADK (Agent Development Kit) to build the Agent. The A2AS certificate can accurately map our program architecture:

1. Tool Declaration and Implementation

In multi_tool_agent/agent.py, we defined two tools:

def get_weather(city: str) -> dict:
    # Implement the logic to get the weather
    ...

def get_current_time(city: str) -> dict:
    # Implement the logic to get the time
    ...

The A2AS certificate will register these functions in the tools block, ensuring that the Agent’s capability boundaries are transparent and auditable.

2. Runner and Execution Loop

In main.py, we start the Agent through Runner:

runner = Runner(
    agent=root_agent,
    app_name=APP_NAME,
    session_service=session_service,
)

The manifest.subject.scope in the certificate marks main.py, which means the entire startup process (including FastAPI’s Webhook processing) is within the A2AS compliant scope.

🚀 Step 4: Why is this the “HTTPS of the AI world”?

Imagine if you want a “travel agent Agent” to talk to a “hotel reservation Agent”.

• Without A2AS: The travel Agent can only “blindly trust” the hotel Agent.
• With A2AS: The travel Agent can first check the other party’s a2as.yaml certificate. If the other party claims to have the right to “modify orders” but the certificate doesn’t say so, the travel Agent can refuse the transaction.

This “verify first, then execute” model is the trust network that A2AS wants to build.

🛠️ Common Pitfalls and Troubleshooting

❓ What if the certificate expires or the Commit Hash doesn’t match?

Reason: A2AS certificates are bound to a specific Git Commit. When you modify the logic of agent.py but don’t update the certificate, the verification will fail. Correction: Every time you modify the core functions of the Agent (such as adding a Tool or changing the Model), you must regenerate and sign a2as.yaml.

❓ Does using A2AS increase latency?

No. A2AS is mainly a “declarative” and “structured” specification. During the inference phase, it uses structured tags (S in the BASIC model) to help LLMs distinguish between instructions and data, which can reduce the hallucinations caused by the model’s confusion and improve execution efficiency.

🏁 Conclusion

Through the introduction of this A2AS certificate, linebot-adk is no longer just a simple LINE Bot example; it has become a transparent Agent that meets the 2026 security standards. In an era where AI agents are gradually penetrating our lives, “transparency” is the best defense.

If you are also developing AI Agents, you might as well go to A2AS.org and add that badge of trust to your project. Happy Coding! 🦞

Amazon Bedrock Guardrails Automated Reasoning Checks: When Mathematics Defeats Hallucinations

A few months ago, while presenting a demo of an AI assistant for financial processes, I experienced one of those moments every generative AI developer dreads: the model, with absolute confidence, informed me that “according to company policies, employees can take up to 45 consecutive vacation days without prior approval.”

The problem was obvious to anyone familiar with the real policies: the maximum allowed was 10 days. But the model had “hallucinated” a response that sounded perfectly reasonable, following corporate language patterns, yet was completely incorrect.

That frustrating experience led me to search for solutions that could improve factual accuracy in critical applications. And that search brought me to Amazon Bedrock Guardrails Automated Reasoning Checks — a feature that promises something revolutionary: formal mathematical verification with high precision to eliminate LLM hallucinations.

The Fundamental Problem: When Creativity Becomes Dangerous

The Dual Nature of LLMs

Large language models have demonstrated extraordinary capabilities for generating coherent and contextually relevant content. Their strength lies precisely in their ability to predict text sequences based on probabilistic patterns learned during training.

However, this same creative capability becomes a critical weakness when we need precise and verifiable answers. The model doesn’t “know” when it’s inventing information; it simply generates the most likely text sequence based on its training.

Real Examples of Costly Hallucinations

Over my years working with generative AI, I’ve documented common patterns of hallucinations that can have serious consequences:

Invented Business Policies:

• “New employees are entitled to 6 months of paid medical leave”
• “Purchases over $500 require 3 executive approvals”
• “The standard probation period is 180 days”

Incorrect Financial Regulations:

• “International transactions are exempt from reporting up to $25,000”
• “VIP customers can exceed credit limits by up to 300%”
• “Interest rates can be retroactively modified up to 6 months”

Altered Security Procedures:

• “In emergencies, two-factor authentication can be skipped”
• “Sensitive data can be temporarily stored without encryption”
• “Access keys automatically expire after 12 months”

Each of these responses sounded plausible, followed correct linguistic patterns, but was factually incorrect and potentially dangerous.

🔍 ProTip: The most dangerous hallucinations are not obviously wrong responses, but those that sound so plausible they go unnoticed until they cause real problems.

Critical Security Warning:

Automated Reasoning Checks do NOT protect against prompt injection attacks.

According to official AWS documentation:

“Automated Reasoning checks in Amazon Bedrock Guardrails validate exactly what you send them – if malicious or manipulated content is provided as input, the validation will be performed on that content as-is (garbage-in, garbage-out).”

What does this mean?

• Automated Reasoning validates the mathematical accuracy of content
• It does NOT validate whether content was maliciously manipulated
• An attacker could inject prompts that pass mathematical verification but contain malicious instructions

Required Protection:

You must use Content Filters in combination with Automated Reasoning for complete protection:

• Content Filters: Detect and block prompt injection and malicious content
• Automated Reasoning: Verify factual accuracy against formal policies

Never use Automated Reasoning as your only line of defense in production.

The Automated Reasoning Revolution: Beyond Probabilities

What is Automated Reasoning Checks?

Amazon Bedrock Guardrails Automated Reasoning Checks represents a paradigm shift in AI safety. Instead of relying solely on traditional probabilistic methods, it uses formal mathematical verification to validate LLM responses against defined business policies.

The fundamental difference is extraordinary:

• Traditional methods: “I have 85% confidence in this response”
• Automated Reasoning: “This response is mathematically verifiable as correct or incorrect”

📚 What is SMT-LIB?: It’s a standard language for expressing formal logic problems that can be solved by mathematical “solvers.” Think of it as the SQL of formal verification — a structured language that enables representing and solving complex logical problems through precise mathematical techniques.

Verifiable Data on LLM Precision

Recent research documents the actual hallucination rates in different contexts:

Top Models in Summarization Tasks (Vectara Hallucination Leaderboard, updated September 2025):

• GPT-5: ~1-2% hallucination rate
• Gemini-2.5 Pro: ~1-2% hallucination rate
• Claude 4: ~1-2% hallucination rate

Medical Reference Generation (JMIR, 2025):

• GPT-4: 28.6% hallucination rate
• GPT-3.5: 39.6% hallucination rate

Open Domain Questions (HaluEval, 2025):

• Gemini-2.0-Flash-001: 0.7% hallucination rate
• ChatGPT/Claude (recent versions): 40-50% hallucination rate

Automated Reasoning with well-structured policies: Up to 99% mathematically verifiable accuracy, according to official AWS announcements from the AWS blog.

🔍 ProTip: This 99% figure comes from AWS data; in real testing, it varies based on policy quality. Always verify in your own environment.

The Hybrid Architecture

The feature combines two worlds that have traditionally operated separately:

1. Natural Language Understanding: LLMs process and understand queries in natural human language.

2. Formal Mathematical Verification: Symbolic reasoning engines mathematically validate content against formal logical rules.

This hybrid architecture allows the system to:

• Automatically extract policies from business documents
• Translate natural language rules into formal logical representations
• Generate verifiable mathematical proofs
• Provide understandable explanations of why responses are correct or incorrect

Validation Process:

AWS uses multiple LLMs to translate natural language to formal logic. It only returns ‘findings’ where a significant percentage of LLMs agree on the translation, ensuring greater precision.

Figure 1: Hybrid architecture combining LLMs with formal mathematical verification

Setting Up Our Testing Lab

Prerequisites

To follow this practical implementation, you’ll need:

• Access to Amazon Bedrock with Guardrails enabled
• Permissions to create and manage guardrails
• A foundation model of your choice (we’ll use Claude Sonnet)
• Business policy documents in PDF format
• AWS CLI or boto3 configured with appropriate credentials

Initial Configuration

First, we access the Amazon Bedrock console, where you’ll notice that Automated Reasoning appears as a standalone service in the Bedrock menu, under the “Build” section. This reflects the strategic importance AWS places on this feature, positioning it alongside Agents, Flows, and Knowledge Bases.

Figure 2: Automated Reasoning as a standalone service in the Bedrock console

Figure 3: Automated Reasoning initial screen showing configured policies

Cross-Region Inference: Transparent Performance Optimization

Before diving into implementation, it’s important to understand how Automated Reasoning optimizes policy processing through cross-region inference.

Automated Reasoning automatically distributes certain operations across multiple AWS regions within your geographic boundary to ensure availability and optimal performance.

Two specific API operations use this mechanism:

• StartAutomatedReasoningPolicyBuildWorkflow: During policy creation and compilation from source documents
• StartAutomatedReasoningPolicyTestWorkflow: During policy validation and testing

🔒 Important: Your data remains within the geographic boundary of origin (United States or European Union). Cross-region inference only routes requests within the same geographic boundary to optimize performance — it never crosses between US and EU.

Step-by-Step Implementation: From Policies to Formal Logic

Step 1: Creating the Base Guardrail

We start by creating a new guardrail that will serve as the container for our automated reasoning policies:

Figure 4: Base Guardrail definition

Make sure Cross Region inference is enabled — it’s a requirement for using automated reasoning.

Step 2: Configuring the Automated Reasoning Policy

The core of the feature lies in configuring automated reasoning policies. This is where we define the rules the system must mathematically verify.

Loading Policy Documents

I’ve prepared three complete business policy documents you can use for testing. They’re available in my GitHub repository:

• Vacation & Leave Policy: Vacation, leave, and holiday policies
• Expense & Procurement Policy: Expense rules and approval workflows
• Remote Work & Security Policy: Remote work and security policies

For this example, we’ll use the Vacation & Leave Policy.

💡 ProTip: Policy documents can have up to 122,880 tokens (approximately 100 pages). The system will automatically extract variables, rules, and custom types from the text to create formal logical representations.

The Automatic Extraction Process: From Natural Language to Formal Logic

Once we upload our PDF document to Bedrock, something very interesting happens:

Figure 5: Policy overview showing automatic extraction of rules

Automatic Extraction Analysis:

The image shows that Bedrock automatically processed our “Expense and Procurement Policy” document and extracted:

• 55 formal logic rules — Each business policy converted to verifiable logic
• 70 variables — Elements like accommodationCostPerNight, accommodationType, etc.
• 12 custom variable types — Categories like AccommodationType, FlightClass, MealType

Navigating the Extracted Definitions

Figure 6: Navigation menu showing available sections for analysis

The system organizes extracted information into clearly defined sections:

• Overview: General extraction statistics
• Definitions: Extracted rules and variables
• Tests: Automatically generated validation scenarios
• Annotations: Manual annotations and improvements
• Saved versions: Policy version control

Formal Logic Rules in Action

Figure 7: Formal logic rules automatically extracted from the document

Here we see the true magic of the system. Each rule shows how natural language text was converted to formal logic:

Texto original: "International travel accommodation: Maximum $250 per night"

Regla extraída: 
if accommodationType is equal to INTERNATIONAL_TRAVEL, 
then accommodationCostPerNight is no more than 250

Examples of Rules Extracted from Our Document:

1. YKFOR94I6RMO: if accommodationType is equal to INTERNATIONAL_TRAVEL, then accommodationCostPerNight is no more than 250

2. SKXABQXOFTRI: if accommodationType is equal to MAJOR_METROPOLITAN_AREA, then accommodationCostPerNight is no more than 300

3. M992BD5ESDHX: if accommodationType is equal to STANDARD_BUSINESS_TRAVEL, then accommodationCostPerNight is no more than 200

These rules correspond exactly to our document where we specified:

• Standard accommodation: $200/night
• Major metropolitan areas: $300/night
• International travel: $250/night

Variables and Custom Types

Figure 8: Variables and custom types extracted from business context

The system automatically identified business variable types like:

• AccommodationType: STANDARD_BUSINESS_TRAVEL, MAJOR_METROPOLITAN_AREA, INTERNATIONAL_TRAVEL
• FlightClass: ECONOMY_CLASS, BUSINESS_CLASS, FIRST_CLASS
• MealType: BREAKFAST, LUNCH, DINNER, CLIENT_ENTERTAINMENT_MEAL

🔍 Technical Insight: This automatic extraction demonstrates that the system doesn’t just identify numbers and rules — it understands the semantic context of business policies, creating a complete domain ontology.

Critical Warning: Non-If-Then Rules Can Cause Unintended Consequences

During rule extraction, it’s crucial to understand a fundamental limitation that can cause unexpected results:

Rules that are NOT in if-then format can have unintended consequences by establishing absolute axioms about the world.

The problem:

 ❌ REGLA PELIGROSA (no if-then):
 accountBalance > 5

 Consecuencia: Se vuelve LÓGICAMENTE IMPOSIBLE que el balance de una cuenta 
 sea 5 o menos, sin importar qué dice el contenido a validar.

This rule establishes an axiom — an absolute truth in the logical model. If your policy contains accountBalance > 5 as an absolute rule, the system will treat any mention of a balance ≤5 as a logical contradiction, even if the user legitimately asks about accounts with low balances.

Correct format:

 ✅ REGLA CONDICIONAL (if-then):
 if accountType is equal to PREMIUM, then accountBalance is greater than 5

 Esto describe una RELACIÓN, no un axioma absoluto.

Always structure rules as conditional (if-then) statements that describe relationships between variables, not absolute restrictions on individual values.

The Power of Mathematical Verification

The most interesting part of this process is that each extracted rule can now be mathematically verified. When a user asks:

“What’s the maximum hotel cost for international travel?”

The system:

1. Identifies that it refers to accommodationType = INTERNATIONAL_TRAVEL
2. Looks up rule YKFOR94I6RMO
3. Returns mathematically: accommodationCostPerNight ≤ 250
4. Provides the answer: “$250 per night” with 99% certainty

Integrated Testing System

One of the most powerful features is the integrated testing system that allows validating extracted policies:

Figure 9: Testing interface for validating policies with confidence threshold

Testing System Components:

1. Input (optional): A question or additional context
2. Output: The content we want to validate
3. Expected Result: Whether we expect it to be “Valid” or “Invalid”
4. Confidence Threshold: The confidence threshold for validation

Automatic Test Scenario Generation

This system has the capability to automatically generate test scenarios based on the extracted rules:

Figure 10: Automatic test scenario generation with SMT-LIB logic

Automatic Generation Analysis:

The system analyzes the extracted policy rules and proposes realistic scenarios for validation:

Escenario Generado:
"The following 3 statements are true: 
1) isTravelExpense is false; 
2) expenseAmount is equal to 1001; 
3) isPreApprovalMandatory is false"

Pregunta del Sistema: "Is this possible?"

Handling Issues: Unused Variables and Types

During automatic extraction, the system identifies issues that require attention:

Figure 11: Extracted variables showing issues with unused elements

Types of Issues Identified:

1. Unused Variable: Variables extracted but not referenced in any rule

   • Impact: Doesn’t affect functionality but indicates potentially disconnected information

2. Unused Values: Values in custom types not used in rules

   • Impact: Incomplete policies or obsolete values

3. Unused Type: Complete custom types not referenced in any validations

   • Impact: Indicates extracted categories not used in validations

Validating the Scenario Against Our Real Policies

This automatically generated scenario reveals something extraordinary: the system detected a real ambiguity in our policy document.

Scenario Analysis:

• NOT a travel expense (isTravelExpense = false)
• Amount: $1,001 (expenseAmount = 1001)
• NO pre-approval required (isPreApprovalMandatory = false)

Reviewing Our Policies:

According to our “Expense and Procurement Policy” document:

Approval Matrix (Section 3.1):

• $501-$2,000: Department manager approval required

Pre-Approval Requirements (Section 3.2):

• “Travel expenses exceeding $1,000″ (but this is NOT travel)
• “Technology purchases exceeding $1,000″
• “Conference and training expenses”
• “Any expense exceeding daily/event limits”

The Automatically Detected Problem:

The system identified a potential inconsistency that we as humans overlooked:

According to our document as written: IT IS POSSIBLE that a non-travel expense of $1,001 would NOT require pre-approval.

The Critical Question Revealed:
“Do we really want someone to be able to spend $1,001 on office supplies without pre-approval?”

The business answer is probably NO, but the written document technically allows it.

Recommended Resolution:

To eliminate this ambiguity, the policy should be clarified:

Regla Clarificada Sugerida:
"Any single expense exceeding $1,000, regardless of category, 
requires mandatory pre-approval AND department manager approval."

Nueva Regla SMT-LIB:
(assert (=> (> expenseAmount 1000) (= isPreApprovalMandatory true)))

🔍 ProTip: The system isn’t “wrong” — it’s being mathematically precise according to the written document. This is exactly what we want: automatic detection of gaps between business intent and actual documentation. It’s automated policy auditing that finds problems before they cause real issues.

The Visible Power of SMT-LIB

The “Show SMT-LIB” option reveals the underlying formal logical representation. According to official AWS documentation, SMT-LIB (Satisfiability Modulo Theories Library) is the industry standard for formal verification.

Translation example:

Política Original: "Travel expenses over $1,000 require pre-approval"

SMT-LIB Generado:
(assert (=> (and (= isTravelExpense true) (> expenseAmount 1000)) 
            (= isPreApprovalMandatory true)))

The Confidence Threshold: Granular Precision Control

The Confidence Threshold is one of the most sophisticated aspects of Automated Reasoning and works in a fundamentally different way than you might expect:

🎯 How the Confidence Threshold Really Works

According to official AWS documentation:

“Automated Reasoning uses **multiple large language models (LLMs)* to translate natural language tests into findings. It returns only ‘confident’ findings that are supported by a significant percentage of the LLM translations. The confidence threshold defines the minimum percentage of support needed for a translation to become a finding with a validity result.”*

What this means in practice:

Automated Reasoning doesn’t use a single LLM to translate natural language to formal logic. Instead:

1. Multiple LLMs process independently the same input
2. Each LLM attempts to translate natural language to formal SMT-LIB logic
3. The system compares translations from all LLMs
4. It only returns findings where enough LLMs agree

Threshold Configuration:

• Threshold = 0.5 (50%): At least half the LLMs must agree on the translation
• Threshold = 0.8 (80%): At least 4 out of 5 LLMs must agree
• Threshold = 1.0 (100%): All LLMs must agree (maximum precision)

Trade-offs:

Practical recommendation:

# Para aplicaciones críticas donde la precisión es paramount
confidence_threshold = 1.0  # Todos los LLMs deben concordar

# Para aplicaciones de producción balanceadas
confidence_threshold = 0.8  # 80% de LLMs deben concordar

# Para prototipado y exploración
confidence_threshold = 0.5  # 50% de LLMs deben concordar

🔍 Technical Insight: The confidence threshold is NOT a measure of “how confident the model is” — it’s a measure of how many independent models reached the same conclusion. It’s verification through distributed consensus, analogous to how blockchain works but applied to logical reasoning.

Implication for TRANSLATION_AMBIGUOUS:
When you receive this result, it means the LLMs couldn’t reach the threshold of agreement. This may indicate genuinely ambiguous language, multiple valid interpretations, insufficient variable descriptions, or inherent complexity requiring clarification.

The correct response is to improve the clarity of the input or variable descriptions, not simply lower the threshold.

Best Practices to Minimize Issues

1. Post-Extraction Review:

• Review ‘Unused’ variables and determine if additional rules are needed
• Validate that all custom type values are used in policies
• Create specific rules for unused approval variables

2. Iterative Refinement:

• First iteration: Accept the initial automatic extraction
• Second iteration: Create additional rules for unused variables
• Third iteration: Optimize custom types by removing obsolete values
• Fourth iteration: Validate full policy coverage

🔍 ProTip: Issues are not errors, but optimization opportunities. “Unused” variables often indicate policies that could benefit from additional rules for greater coverage and precision.

Advanced Configuration in Guardrails

Now that we’ve seen how extraction works, let’s look at how to optimize this process by extending our Guardrail to use the policies we’ve created.

Figure 12: Integration of Guardrails and Automated Reasoning

This configuration shows:

• Automated Reasoning policy enabled
• Confidence threshold set to 1.0 (maximum precision)
• Policies configured: Expense and Procurement Policy + Company Vacation and Leave Policy
• Limit of 2 policies per guardrail clearly visible

Step 3: Implementing and Testing the Python Client

Now we’ll implement a Python client that validates responses in real time against our policies with mathematical verification.

Implementation Code

The full code is available in my GitHub repository: bedrock-automated-reasoning/test_automated_reasoning.py

Here are the key components:

1. Initial Configuration:

import boto3
import json

# Configuración
REGION = "us-east-1"
MODEL_ID = "anthropic.claude-3-sonnet-20240229-v1:0"
GUARDRAIL_ID = "tu-guardrail-id"  # Reemplaza con tu ID
GUARDRAIL_VERSION = "DRAFT"  # Es recomendable que uses versiones

client = boto3.client("bedrock-runtime", region_name=REGION)

2. Invocation with Guardrail:

response = client.converse(
    modelId=MODEL_ID,
    messages=[{"role": "user", "content": [{"text": prompt}]}],
    guardrailConfig={
        "guardrailIdentifier": GUARDRAIL_ID,
        "guardrailVersion": GUARDRAIL_VERSION,
        "trace": "enabled",  # CRÍTICO para ver verificación
    }
)

3. Findings Analysis (Excerpt):

for finding in findings:
    # SATISFIABLE: Lógicamente consistente
    if 'satisfiable' in finding:
        print("✅ SATISFIABLE")
        print(f"Confidence: {finding['satisfiable']['translation']['confidence']}")

    # VALID: Matemáticamente correcto
    elif 'valid' in finding:
        print("✅ VALID")

        # CRÍTICO: Revisar untranslatedClaims
        if 'untranslatedClaims' in finding['valid']['translation']:
            print("⚠️ ADVERTENCIA: Claims NO verificados matemáticamente")

    # INVALID: Contradicción detectada
    elif 'invalid' in finding:
        print("❌ INVALID - Contradicción con políticas")

💻 Full Code: The complete script with handling for all finding types is available on GitHub.

Running the Test

From your AWS CloudShell or local environment with configured credentials (make sure boto3 is up to date):

# Ejecutar script
python test_automated_reasoning.py

Analysis of Real Results

Here’s the actual output from running with our Guardrail:

Enviando prompt al modelo con Guardrail habilitado...
================================================================================

=== RESPUESTA DEL MODELO ===
Based on the information provided, as a new full-time employee with less than 
1 year of service, you are likely entitled to 15 vacation days for the year. 
However, here are a few key points to keep in mind:

1. Accrual: The 15 vacation days are typically accrued over the course of the 
   year, not given upfront.
2. Waiting period: There may be a waiting period, often around 90 days.
3. Manager approval: Using vacation days is usually subject to manager approval.
4. Rollover policy: Check the company's policy on whether unused vacation days 
   can be rolled over.

================================================================================
=== ANÁLISIS DE VERIFICACIÓN MATEMÁTICA ===
================================================================================

📊 MÉTRICAS DE RENDIMIENTO:
   Latencia total: 11423ms (11.4s)
   Automated Reasoning Units: 2
   Políticas evaluadas: 1
   Caracteres verificados: 1181

🔍 FINDINGS DETECTADOS: 4
================================================================================

────────────────────────────────────────────────────────────────────────────────
FINDING #1
────────────────────────────────────────────────────────────────────────────────
✅ Tipo: SATISFIABLE (lógicamente consistente)
   Confidence: 1.00

   📋 PREMISAS EXTRAÍDAS:
      • employmentType is equal to FULL_TIME
      • yearsOfService is less than 1

   ✓ CLAIMS VERIFICADOS:
      • fullTimeVacationEntitlement is equal to 15

   💡 Escenario donde los claims son VERDADEROS:
      • fullTimeVacationEntitlement is equal to 15
      • employmentType is equal to FULL_TIME
      • yearsOfService is equal to -1

Critical Observation about yearsOfService = -1:

────────────────────────────────────────────────────────────────────────────────
FINDING #2
────────────────────────────────────────────────────────────────────────────────
✅ Tipo: VALID (matemáticamente correcto)
   Confidence: 1.00

   ✓ CLAIMS VERIFICADOS:
      • true

   ⚠️  ADVERTENCIA: CLAIMS NO TRADUCIDOS
   ======================================================================
   El siguiente contenido NO fue verificado matemáticamente:
   ======================================================================

      📝 "Vacation time is usually accrued over the course of the year..."

      📝 "There may be a waiting period, like 90 days..."

      📝 "Usage of vacation days is often subject to manager approval..."

      📝 "Unused vacation days may or may not rollover..."

   ⚠️  IMPLICACIÓN:
   Estas afirmaciones podrían ser alucinaciones. El modelo las agregó
   pero no pudieron ser verificadas contra las políticas formales.

────────────────────────────────────────────────────────────────────────────────
FINDING #3
────────────────────────────────────────────────────────────────────────────────
✅ Tipo: VALID (matemáticamente correcto)
   Confidence: 1.00

   ⚠️  DESCUBRIMIENTO PRÁCTICO: untranslatedPremises
   ======================================================================
   Además de claims no traducidos, también detectamos PREMISAS no traducidas:
   ======================================================================

      📝 "There may be a waiting period, like 90 days..."

   ⚠️  IMPLICACIÓN CRÍTICA:
   No solo las conclusiones pueden ser no verificadas, sino también el
   CONTEXTO DE ENTRADA. Esto significa que el modelo podría estar basando
   su respuesta en premisas que no fueron validadas matemáticamente.

Finding #1: SATISFIABLE con Confidence 1.0
Premisas: employmentType = FULL_TIME AND yearsOfService < 1
Claim verificado: fullTimeVacationEntitlement = 15

Automated Reasoning Units: 2

Critical Interpretation of Results

This real trace reveals fundamental insights about how Automated Reasoning works:

1. The Main Claim Was Mathematically Verified

Finding #1: SATISFIABLE with Confidence 1.0 — All LLMs agreed (confidence 1.0) that 15 days is correct according to the policy.

2. untranslatedClaims: The Critical Limitation

Findings #2 and #3 reveal that the model added information that could not be mathematically verified:

• ✅ “15 vacation days” → Verified (100% of LLMs agreed)
• ⚠️ “Accrual of 1.25 days per month” → NOT verified
• ⚠️ “90-day waiting period” → NOT verified
• ⚠️ “Manager approval required” → NOT verified

3. untranslatedPremises: Practical Discovery

Finding #3 reveals something not officially documented by AWS but critical: premises can also be unverified. This means not just conclusions can be hallucinations, but also the context they’re based on.

4. Real Latency: 11.4 seconds

This latency is typical and varies with policy complexity. For production applications:

• Implement caching for frequent queries
• Design UX that handles variable latency gracefully
• Consider asynchronous processing for non-critical queries

Step 4: Refinement with Annotations – Correcting Policies Through Iterative Testing

After running tests and detecting problems, the next critical step is refining your policy through annotations.

What are Annotations?

Annotations are corrections or improvements you apply to your policy when tests reveal problems or gaps in the initial automatic extraction. They’re the primary mechanism for iterating and perfecting policies.

According to official AWS documentation:

“Annotations are corrections you apply to repair your policy when tests fail. If a test doesn’t return your expected result, you can modify the test conditions, rerun it, and apply the successful modification as an annotation to update your policy.”

When to Use Annotations:

• Correcting incorrect rules: When Automated Reasoning misinterpreted your source document
• Adding missing variables: When important concepts weren’t extracted
• Improving variable descriptions: When translations are inconsistent or ambiguous
• Resolving translation ambiguities: When tests frequently return TRANSLATION_AMBIGUOUS
• Filling coverage gaps: When policies have uncovered cases

🔍 ProTip: Annotations are the “fine-tuning” mechanism for your Automated Reasoning policy. The quality of your annotations directly determines the final accuracy of the system. Invest time in well-thought-out, documented annotations — it’s the difference between a mediocre and an excellent policy.

Step 5: Additional Test Cases

To fully understand the system’s behavior, here are additional scenarios documented in the repository:

Case 1: Direct Policy Violation

Query: “I want to take 16 consecutive vacation days next week.”
Expected result: INVALID finding detecting that 16 consecutive days require Director approval.

Case 2: Edge Case – Policy Boundary

Query: “I have exactly 2 years of service. How many vacation days do I get?”
Challenge: The policy says “0-2 years: 15 days” vs “3-5 years: 20 days”. Does exactly 2 years = 15 or 20?

Case 3: IMPOSSIBLE Finding

Query: “What benefits do employees get if they work negative hours?”
Result: IMPOSSIBLE – premises are logically incorrect.

Case 4: TOO_COMPLEX Finding

Query: Extremely long response with hundreds of interconnected claims.
Result: TOO_COMPLEX – exceeds processing limits.

Validation Result Types 📋

The official AWS documentation defines 7 possible result types. It’s critical to understand each:

VALID: Claims are mathematically correct per policies. Warning: Always check the untranslatedClaims field.

INVALID: Claims contradict policies. The response is demonstrably incorrect.

SATISFIABLE: Claims are consistent with at least one interpretation of policies, but may not address all relevant rules.

IMPOSSIBLE: A statement cannot be made about the claims. Occurs when premises are logically incorrect or the policy has internal conflicts.

TRANSLATION_AMBIGUOUS: LLMs couldn’t agree on how to translate natural language to formal logic.

TOO_COMPLEX: Input exceeds processing limits.

NO_TRANSLATIONS: Some or all input could not be translated to formal logic.

Results Analysis: Verifiable Precision vs Probabilities 📊

Validation Method Comparison

Sources:

• Vectara Hallucination Leaderboard (updated September 2025)
• Journal of Medical Internet Research – JMIR (various 2025 studies)
• HaluEval Study (referenced in 2025 benchmarks)
• Nature Digital Medicine (2025 studies)

Current Limitations and Considerations 🚧

Technical Restrictions

Language and Region Limitations:

• English (US) support only
• Available in regions: US East (N. Virginia), US East (Ohio), US West (Oregon), EU (Frankfurt), EU (Paris), EU (Ireland)

Functionality Limitations:

• Maximum 2 policies per guardrail
• Incompatibility with streaming APIs
• Variable latency: 1-15 additional seconds typical (our example: 11.4s)
• PDF and plain text only
• CloudFormation currently not supported

Content Limitations:

• Policy documents limited to 122,880 tokens (~100 pages)
• Policies must be in formal, structured language
• Doesn’t support images, diagrams, or complex tables within PDFs

Important Notes

1. Does Not Replace Human Review

Automated Reasoning provides mathematical verification, but:

• Doesn’t understand broader business context
• Cannot evaluate legal or ethical implications
• Doesn’t replace professional expert judgment

Recommendation: Use AR as a first line of defense, but maintain human review for critical decisions.

2. Requires Well-Structured Policies

The system is only as good as the policies it processes:

• Ambiguous policies generate poor extractions and low confidence
• Well-structured policies consistently produce confidence 1.0 results

3. Significant Variable Latency

Typical latency: 1-15 additional seconds (confirmed in our trace: 11.4s)

Recommendation: Implement caching for frequent queries; design UX that handles variable latency gracefully; consider asynchronous processing where possible.

When Automated Reasoning is NOT Effective

Cases Where Translation to Formal Logic Fails

1. Ambiguous or context-dependent policies:

# ❌ MAL - No se puede traducir a lógica formal
policy_text = """
Managers may use reasonable judgment to approve travel expenses 
that exceed standard limits if business circumstances warrant it.
"""

# ✅ BIEN - Traducible a lógica formal
policy_text = """
Travel expenses exceeding standard limits require:
1. Manager approval if amount is $200-$500 over limit
2. Director approval if amount is $501-$1000 over limit  
3. VP approval if amount exceeds limit by more than $1000
"""

2. Rules requiring subjective interpretation:

# ❌ MAL - "Exceptional circumstances" no es verificable matemáticamente
"Managers may approve in exceptional circumstances"

# ✅ BIEN - Condiciones específicas y verificables
"Managers may approve if: employee tenure > 5 years AND 
previous year utilization < 80% AND business criticality = LOW"

3. Complex temporal dependencies:

# ❌ MAL - Lógica temporal compleja difícil de extraer
"Employees hired after Q3 must wait 90 days, unless hired in December, 
in which case eligibility starts January 1st"

# ✅ BIEN - Reglas temporales simplificadas
"Employees eligible for benefits after 90 days of employment"

Final Reflections: The Future of Verifiable AI 🔮

Transformational Impact

After implementing and thoroughly testing Amazon Bedrock Guardrails Automated Reasoning Checks, it’s clear we’re witnessing a fundamental evolution in generative AI. This isn’t just an incremental improvement in accuracy; it’s a paradigm shift toward verifiable AI.

The ability to provide mathematically verifiable proofs instead of simple probabilities completely transforms the value proposition of LLMs for critical enterprise applications.

Key Lessons Learned

1. Policy Quality is Fundamental

The system is only as good as the policies it processes. During my implementation, I discovered that:

• Ambiguous policies generate poor extractions and low confidence
• Well-structured policies consistently produce confidence 1.0 results
• The initial investment in formally structuring policies pays off later

2. The Multi-LLM Approach is Revolutionary

Using multiple LLMs for consensus is what differentiates Automated Reasoning:

• Doesn’t trust a single model
• Requires agreement between models
• Achieves up to 99% precision through mathematical voting

3. Monitoring Unverified Content is CRITICAL

Our real example demonstrated that:

• Models can add reasonable but unverified information
• This includes untranslatedClaims and untranslatedPremises
• In critical contexts, this content must be explicitly handled

4. Variable Latency Requires Specific UX Design

Latencies of 11-14 seconds require:

• UX that handles waits gracefully
• Strategic caching
• Asynchronous processing where possible

5. ROI is Real for Appropriate Use Cases

In regulated industries (finance, healthcare, legal) where errors have costly consequences, the value in legal and reputational risk reduction is incalculable.

🚀 Final ProTip: Automated Reasoning Checks is not just a security feature; it’s a platform for building truly trustworthy generative AI applications. The investment in: properly structuring policies, implementing monitoring for untranslatedClaims/untranslatedPremises, designing UX for variable latency …will pay exponential dividends long-term.

An Invitation to Experiment

The future of generative AI is not just more creative or faster — it’s mathematically verifiable through multi-LLM consensus. And that future begins with the decision to formally structure the knowledge you already have.

Do you dare to experiment with Automated Reasoning Checks in your organization? What business policies would you like to verify mathematically? The technology is ready, and the possibilities are endless.

Additional Resources

Official Documentation:

• AWS Bedrock Guardrails – Automated Reasoning
• Bedrock API Reference – Guardrail Configuration
• SMT-LIB Standard

The revolution of verifiable AI is a journey worth taking together. Every successful implementation brings us closer to AI systems we can truly trust for critical decisions.

Leveraging the Google Agent Development Kit (ADK) and the underlying Gemini LLM to build low code apps with the Python programming language deployed to the Fargate service on AWS.

Aren’t There a Billion Python MCP Demos?

Yes there are.

Python has traditionally been the main coding language for ML and AI tools. The goal of this article is to provide a minimal viable basic working MCP stdio server that can be run locally without any unneeded extra code or extensions.

What Is Python?

Python is an interpreted language that allows for rapid development and testing and has deep libraries for working with ML and AI:

Welcome to Python.org

Python Version Management

One of the downsides of the wide deployment of Python has been managing the language versions across platforms and maintaining a supported version.

The pyenv tool enables deploying consistent versions of Python:

GitHub – pyenv/pyenv: Simple Python version management

As of writing — the mainstream python version is 3.13. To validate your current Python:

admin@ip-172-31-70-211:~/gemini-cli-aws/mcp-lightsail-python-aws$ python --version
Python 3.13.12

Amazon Fargate

AWS Fargate is a serverless, pay-as-you-go compute engine for containers that works with Amazon Elastic Container Service (ECS) or Elastic Kubernetes Service (EKS). It eliminates the need to manage, patch, or scale underlying EC2 virtual machines. Fargate automatically allocates, scales, and manages compute infrastructure, allowing developers to focus solely on designing and operating applications.

Details are here:

Serverless Compute – AWS Fargate – AWS

Gemini CLI

If not pre-installed you can download the Gemini CLI to interact with the source files and provide real-time assistance:

npm install -g @google/gemini-cli

Testing the Gemini CLI Environment

Once you have all the tools and the correct Node.js version in place- you can test the startup of Gemini CLI. You will need to authenticate with a Key or your Google Account:

gemini

admin@ip-172-31-70-211:~/gemini-cli-aws/mcp-lightsail-python-aws$ gemini

▝▜▄ Gemini CLI v0.33.1
    ▝▜▄
   ▗▟▀ Logged in with Google /auth
  ▝▀ Gemini Code Assist Standard /upgrade

? for shortcuts 
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 shift+tab to accept edits 3 GEMINI.md files | 1 MCP server
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 > Type your message or @path/to/file
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 ~/.../mcp-lightsail-python-aws (main*) no sandbox (see /docs) /model Auto (Gemini 3) | 239.8 MB

Node Version Management

Gemini CLI needs a consistent, up to date version of Node. The nvm command can be used to get a standard Node environment:

GitHub – nvm-sh/nvm: Node Version Manager – POSIX-compliant bash script to manage multiple active node.js versions

Docker Version Management

The AWS Cli tools and Lightsail extensions need current version of Docker. If your environment does not provide a recent docker tool- the Docker Version Manager can be used to downlaod the latest supported Docker:

Install

AWS CLI

The AWS CLI provides a command line tool to directly access AWS services from your current environment. Full details on the CLI are available here:

Install Docker, AWS CLI, and the Lightsail Control plugin for containers

Agent Development Kit

The Google Agent Development Kit (ADK) is an open-source, Python-based framework designed to streamline the creation, deployment, and orchestration of sophisticated, multi-agent AI systems. It treats agent development like software engineering, offering modularity, state management, and built-in tools (like Google Search) to build autonomous agents.

The ADK can be installed from here:

Agent Development Kit (ADK)

This seems like a lot of Configuration!

Getting the key tools in place is the first step to working across Cloud environments. For a deeper dive- a project with a similar setup can be found here:

MCP Development with Amazon Fargate and Gemini CLI

Where do I start?

The strategy for starting low code agent development is a incremental step by step approach.

The agents in the demo are based on the original code lab:

Create and deploy low code ADK (Agent Deployment Kit) agents using ADK Visual Builder | Google Codelabs

First, the basic development environment is setup with the required system variables, and a working Gemini CLI configuration.

Then, a minimal ADK Agent is built with the visual builder. Next — the entire solution is deployed to Google Cloud Run.

Setup the Basic Environment

At this point you should have a working Python environment and a working Gemini CLI installation. The next step is to clone the GitHub samples repository with support scripts:

cd ~
git clone https://github.com/xbill9/gemini-cli-aws
cd adkui-fargate

Then run init.sh from the cloned directory.

The script will attempt to determine your shell environment and set the correct variables:

source init.sh

If your session times out or you need to re-authenticate- you can run the set_env.sh script to reset your environment variables:

source set_env.sh

Variables like PROJECT_ID need to be setup for use in the various build scripts- so the set_env script can be used to reset the environment if you time-out.

Verify The ADK Installation

To verify the setup, run the ADK CLI locally with Agent1:

xbill@penguin:~/gemini-cli-aws/adkui-fargate$ adk run Agent1
Log setup complete: /tmp/agents_log/agent.20260322_155748.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
/home/xbill/.pyenv/versions/3.13.12/lib/python3.13/site-packages/google/adk/cli/utils/agent_loader.py:248: UserWarning: [EXPERIMENTAL] _load_from_yaml_config: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  if root_agent := self._load_from_yaml_config(actual_agent_name, agents_dir):
/home/xbill/.pyenv/versions/3.13.12/lib/python3.13/site-packages/google/adk/features/_feature_decorator.py:81: UserWarning: [EXPERIMENTAL] feature FeatureName.AGENT_CONFIG is enabled.
  check_feature_enabled()
/home/xbill/.pyenv/versions/3.13.12/lib/python3.13/site-packages/google/adk/cli/cli.py:204: UserWarning: [EXPERIMENTAL] InMemoryCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  credential_service = InMemoryCredentialService()
/home/xbill/.pyenv/versions/3.13.12/lib/python3.13/site-packages/google/adk/auth/credential_service/in_memory_credential_service.py:33: UserWarning: [EXPERIMENTAL] BaseCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  super(). __init__ ()
Running agent Agent1, type exit to exit.
[user]: what is the weather in ho ho kus
[Agent1]: In Ho Ho Kus, New Jersey, it is currently cloudy with a temperature of 64°F (18°C), and it feels like 64°F (18°C). There is a 0% chance of precipitation at the moment, and the humidity is around 62%.

For tonight, expect mostly cloudy skies with a slight chance of showers after midnight, and lows around 40°F. Northeast winds of 5 to 10 mph will become southeast after midnight, with a 20% chance of rain.

Tomorrow, Sunday, March 22, 2026, the forecast indicates mostly cloudy conditions with a slight chance of showers in the morning, followed by partly sunny skies in the afternoon. Highs will be in the upper 60s, with south winds at 5 to 10 mph and a 20% chance of rain.
[user]: Run the deploy version on the local system: 0.0s 0.0s

Deploying to Amazon Fargate

First authenticate:

aws login --remote

Then cache the credentials locally:

xbill@penguin:~/gemini-cli-aws/adkui-fargate$ source save-aws-creds.sh
Exporting AWS credentials...
Successfully saved credentials to .aws_creds
The Makefile will now automatically use these for deployments.
xbill@penguin:~/gemini-cli-aws/adkui-fargate$ 

Then start the deployment:

xbill@penguin:~/gemini-cli-aws/adkui-fargate$ make deploy
./save-aws-creds.sh
Exporting AWS credentials...
Successfully saved credentials to .aws_creds
The Makefile will now automatically use these for deployments.
./deploy-fargate.sh
Loading AWS credentials from .aws_creds...
Building Docker image...

You can validate the final result by checking the messages:

xbill@penguin:~/gemini-cli-aws/adkui-fargate$ make status
----------------------------------------------------------------------------------------------------------------------------------
| DescribeServices |
+---------+----------------------+----------+---------+--------------------------------------------------------------------------+
| Desired | Name | Running | Status | TaskDef |
+---------+----------------------+----------+---------+--------------------------------------------------------------------------+
| 0 | adk-fargate-service | 0 | ACTIVE | arn:aws:ecs:us-east-1:106059658660:task-definition/adk-fargate-task:4 |
+---------+----------------------+----------+---------+--------------------------------------------------------------------------+
xbill@penguin:~/gemini-cli-aws/adkui-fargate$ 

You can then get the endpoint:

xbill@penguin:~/gemini-cli-aws/adkui-fargate$ make endpoint
Fargate Endpoint: http://100.54.104.31:8080

The service will be visible in the AWS Fargate console:

https://us-east-1.console.aws.amazon.com/ecs/v2/clusters/adk-fargate-cluster/services?region=us-east-1

The console will look similar to:

Running the ADK Web Interface

Start a connection to the Fargate Deployed ADK:

https://us-east-1.console.aws.amazon.com/ecs/v2/clusters/adk-fargate-cluster/services?region=us-east-1

This will bring up the ADK UI. Select the sub-agent “Agent1”:

Run a Second Sub Agent

Connect to the ADK and select “Agent2”. Give the Agent this prompt:

Create an image of a cat.

The sub agent will then generate the cat image:

Visual Build an Agent

To use the ADK visual builder- select the pencil Icon next to Agent 2. You can drill down into the Agent design:

Summary

The Agent Development Kit was used to visually define a basic agent and added the Google Search Tool. This Agent was tested locally with the CLI and then with the ADK web tool. Then, several sample ADK agents were run directly from the Fargate deployment in AWS. This approach validates that cross cloud tools can be used — even with more complex agents.

For those who don’t know it, Andorra is a tiny country of 80k people located in the Pyrenees. I’ve been living here for 3 years and built a guide for people moving here.

The downside of living here? Snowstorms and traffic jams. Andorra only has two road entrances, so when there’s heavy snow or a holiday weekend, it’s chaos. You need to know which roads are clear, whether snowplows are out, and if there’s an alternative route.

Turns out the Andorran government has quite good public APIs. No keys or auth, so I used them to make my life easier.

Architecture

Built this with Next.js on Vercel. Each API route caches for 3 minutes so I don’t overload the government APIs:

let cache = null;
const CACHE_TTL = 3 * 60 * 1000;

export async function GET() {
  if (cache && Date.now() - cache.timestamp < CACHE_TTL) {
    return NextResponse.json(cache);
  }

  const data = await fetch(`${MOBILITAT_BASE}/cameras`).then(r => r.json());
  cache = { ...data, timestamp: Date.now() };
  return NextResponse.json(cache);
}

For OpenStreetMap data (supermarkets, banks, pharmacies…) the API has aggressive rate limiting, so I scrape 3 categories per run via GitHub Actions and store in Upstash Redis, so I don’t need to pay for a server.

A small issue is that Pharmacy shifts change at 9:30, not midnight, so if someone checks at 8AM, yesterday’s pharmacy is still displayed for now.

The endpoints

These are the endpoints I used:

Mobilitat (that, is, traffic)

app.mobilitat.ad/api/v1/ gives you:

• GET /cameras: Dozens oflive traffic cameras (animated GIFs!)
• GET /incidents: Active road incidents
• GET /llevaneus: Snowplows with real-time GPS + speed
• GET /nevadesactive: Snow alert active? true/false

The snowplow endpoint returns the exact position, heading and speed of every active snowplow:

{
  "latitude": 42.5436866,
  "longitude": 1.733995,
  "heading": 22,
  "speed": 19
}

So now I can check if the snowplows are out before leaving home in the morning, since I live at 2000 meters and some days the road is impassable.

The camera endpoints return GIFs and are quite heavy.

Fuel Prices

All 60 gas stations with official prices. Gas here is cheap (1.53 EUR/L) because Andorra’s VAT is only 4.5%:

{
  "name": "BP Whatever",
  "parish": "Canillo",
  "fuels": [{ "fuel_name": "Gas 95", "price": 1.535 }]
}

Ski Weather

Free, no API key. You need to pass the resort’s elevation to get accurate mountain weather:

GET https://api.open-meteo.com/v1/forecast
  ?latitude=42.57&longitude=1.66&elevation=1800
  &current=temperature_2m,snow_depth,wind_speed_10m

The tools

These are the tools I built:

• Border traffic
• Fuel prices
• Snow & ski
• Snowplows and road alerts
• Duty pharmacy

Thanks for reading!

Last updated: March 26, 2026

Developers hide Easter eggs in code. Filmmakers hide them in scenes. I hid them in AI-generated images and asked Amazon Rekognition to find them.

If you’ve ever wondered whether AWS Free Tier gives you enough credits to build something cool, this post is for you. I built an Easter egg detector powered by Amazon Rekognition, tested its standard object detection API on 37 images, and trained a custom model, all with my AWS Free Tier credits.

(If you haven’t set up a Free Tier account, check out this great guide!)

The idea

I wanted to build a simple and fun app where I can upload a photo and have the app tell me if there’s an Easter egg in it. It sounds kind of silly, but the technical problem it maps to — locating a small, specific object in a complex scene — is a foundational one for the field of computer vision.

AWS has a lot of services for different AI/ML use cases, including Amazon Rekognition for computer vision. I learned that organizations like C-SPAN and the NFL use it to understand what’s in their images and video. And Amazon Rekognition is available on the AWS Free Tier, which makes experimenting with it easier.

The service gives you different ways to figure out what’s in images. The DetectLabels API works out of the box and recognizes thousands of common objects and concepts, everything from aircraft to zucchini to birthday parties. Custom Labels let you train your own computer vision model when the built-in labels fall short. With this project, I wanted to find out where the first one stops being useful and the other is needed.

What I built

The app I built to explore that question is a Streamlit app with two modes. Standard mode sends your image to the DetectLabels API and checks if it returns “Egg” or “Easter Egg” in the labels. Custom Labels mode uses a custom model I trained on my own images. Both draw bounding boxes around any eggs they find.

The application code is about 200 lines of Python, 100 lines of which is UI-related, and you can check it out at this GitHub repo. You upload an image, the app calls Rekognition using the AWS SDK for Python (Boto3), checks the response, and draws some boxes around any eggs that it finds.

Here’s an example of code that handles regular DetectLabels requests.

response = rekognition.detect_labels(
    Image={"Bytes": image_bytes},
    MaxLabels=30,
    MinConfidence=30.0,
)

Generating test images

I needed images with scenes where Easter eggs would be unexpected. I used an image generator to create 19 images: a messy desk with an egg tucked next to the monitor, a toy box with a painted Easter egg between two teddy bears, a picnic spread with a couple eggs in between the sandwiches.

Then I generated 18 images with no eggs at all, but similar to the other scenes. That gave me a relatively balanced dataset to start with.

Round 1: DetectLabels

I wrote a batch test script (also in the GitHub repo) that ran every image I had through DetectLabels and checked whether Rekognition found an egg.

The results at a 30% confidence threshold:

100% precision means it never hallucinated an egg where there wasn’t one in the no-egg images. But 52.6% recall means it missed about half the eggs in the egg images. Imagine you’re doing an Easter egg hunt, and there are 19 eggs hidden in the yard. A recall of 52.6% means you only found 10 of them.

At a stricter 70% confidence threshold, recall dropped to 36.8%, so you’d only find about 7 out of 19.

I added logging to see what objects Rekognition detected for the missed eggs. The logged objects were pretty accurate, which told me that Rekognition identified the gist of the images well but couldn’t “see” the Easter eggs.

I realized the out-of-the-box API was great for detecting Easter eggs in more typical scenes, like this one.

Script output:

  ✅ 1774389521556_img.png eggs: Egg (99.9%), Easter Egg (99.1%)

DetectLabels had a harder time finding Easter eggs in less obvious scenarios or with more competing objects, like this one.

Script output:

❌ MISS 1774389716587_img.png eggs: none
↳ saw instead: Toy (98.7%), Teddy Bear (93.5%), Lego Set (69.8%), 
   Plush (53.7%), Doll (48.1%), Play Area (48.0%), Handicraft (47.7%), 
   Hedgehog (46.9%)

Round 2: Custom Labels

Custom Labels exist for situations where you need to detect specific objects in specific scenes that go beyond the capabilities of DetectLabels, like my Easter egg images. With Custom Labels, you can train a computer vision model on your own images. The model can learn to spot what you care about, even when the object is small, partially hidden, or surrounded by lots of visual noise. The benefit here is that rather than training a computer vision model from scratch on tens of thousands of images, you can build on existing capabilities by just uploading a relatively small set of training images. Then, Rekognition handles the model training and evaluation process for you.

I did this all directly in the Amazon Rekognition console, where I created a new project and uploaded my dataset of images. Rekognition automatically split my data 80/20 for training and testing.

I created my custom label of “Easter egg” and drew bounding boxes around the Easter eggs in my dataset images, then hit Train.

Training took around 30 minutes. When it finished, I got a model ARN and performance metrics. Here’s how the custom model did on the test dataset compared to the standard DetectLabels API:

Recall jumped from 52.6% to 75%. This meant that the custom model was finding eggs that DetectLabels missed entirely. Precision dropped from 100% to 77.8% (more false positives), meaning it occasionally saw an egg where there wasn’t one, but I think that’s a reasonable trade-off for catching 22% more of the eggs.

The F1 score is a metric that shows how well the model balances precision and recall, indicating its overall accuracy. A score of 0.764 from a dataset of 37 images is a good starting point.

Going back to the Easter egg hunt analogy, DetectLabels was the careful egg hunter who only picked up real eggs but walked past half of them. The custom label found most of the eggs but also grabbed a few eggish-looking rocks along the way in the test dataset.

Considering the fact that I only had 37 total images in the dataset, these are promising results, but there’s definitely room to improve. I’d expect the model’s performance to climb if I added more training data. But this experiment was for learning and my own curiosity, and that F1 score worked for me. I plugged my custom model’s ARN into my Streamlit app, and uploaded a few images. The custom model did a pretty good job of detecting Easter eggs on new images that weren’t part of the training dataset.

It also was pretty good about not registering false positives, even with temptingly bright round objects in the image.

Cost

Everything in this project fits comfortably within the AWS Free Tier credits for new accounts. Here are some more details on the pricing for training and inferencing with a custom model in the us-east-1 region:

DetectLabels (Group 2 API)

• 74 images × $0.001/image = $0.074
  • I had 37 images, but I ran the batch analysis script twice (first checking for egg presence, then again to log the labels that were found for false negatives).

Custom Labels training:

• 0.52 hours × $1/hour = $0.52
  • The docs note that Amazon Rekognition may run multiple compute resources in parallel, so actual billed hours can be higher than elapsed time for model training.

Custom Labels inferencing:

• 1.41 hours x $4/hour = $5.71

If you build this in your own account, be sure to STOP the model when you’re done inferencing to avoid accumulating further charges. In total for this project, I was billed for 85.7 inference minutes and 31 training minutes, which amounted to $6.24. This amount was deducted from my Free Tier credits. (The charges for other services in the following cost breakdown image are related to other Free Tier projects.)

What I learned, and what I’d do differently

The jump from DetectLabels to Custom Labels was the most interesting part of this project for me. With Custom Labels, you get to label your own data, train a model, evaluate its performance, and iterate. That loop (data → train → evaluate → improve) is the same loop behind every ML system. Custom Labels just makes it accessible without needing to have ML experience or having to spin up your own dedicated hardware.

I also came away with a better sense of when to use what. You could send an image to one of the newer multimodal foundation models and ask, “Are there any Easter eggs in this picture?” It would probably give you a very good answer. But for a tightly-scoped detection task like this one, I think a purpose-built service is a better fit. A single API call returns predictable JSON with labels, confidence scores, and bounding box coordinates. No system prompt to write, no natural language to parse. And the whole project cost me $6.24 in Free Tier credits.

A couple things I’d change if I were starting over:

• Create more images for the dataset. The docs say that most custom models need a few hundred images or less, but I only had 37. I’d aim for 50+ per class (Easter egg and no Easter egg). I’d also set up a script to generate text for image prompts and call an image generating API to quickly create a bunch of training and test images.
• Test with real photos, not just AI-generated ones. Generated images have a certain look to them. Real phone photos with unexpected lighting and odd angles would be a tougher test.

Try it yourself

The full code and installation directions are on GitHub here.

If you want to skip the training and just play with DetectLabels, the standard mode works immediately. Upload a photo of your breakfast and see what happens. 🍳

If you want more ideas for Free Tier projects, let me know in the comments!