	In Browser
	StumbleUpon
	del.icio.us
	Google
	Google Buzz
	reddit
	LinkedIn

	Facebook
	Twitter
	Linkedin
	E-Mail

Generative AI > Google Gemini API > GST Compliance Agent

GST Compliance Agent

Author: Venkata Sudhakar

GST compliance is a monthly obligation for every registered business in India. ShopMax India processes hundreds of B2B invoices each month - and a single error in HSN code, tax rate, or GSTIN format can trigger notices from the GST portal. A GST Compliance Agent validates invoices before they are filed, calculates CGST/SGST/IGST correctly, and flags any discrepancy that could cause a mismatch in GSTR-1 or GSTR-3B.

This tutorial builds a GST Compliance Agent using Google ADK and Gemini 2.0 Flash. The agent validates GSTIN format, looks up the correct GST rate for an HSN code, calculates the tax breakdown, and flags interstate vs intrastate supply correctly.

The below example shows the GST Compliance Agent validating an invoice for a B2B supply from Mumbai to Hyderabad.

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai.types import Content, Part
import re

# HSN code to GST rate mapping (sample)
HSN_RATES = {
    "8471": 18,  # Computers and peripherals
    "8473": 18,  # Computer parts and accessories
    "8517": 18,  # Phones and networking equipment
    "8528": 28,  # Monitors and displays
    "8504": 18,  # UPS and power supplies
    "9999": 18,  # Miscellaneous IT services
}

def validate_gstin(gstin: str) -> dict:
    """Validate GSTIN format and extract state code."""
    pattern = r"^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z]{1}[1-9A-Z]{1}Z[0-9A-Z]{1}$"
    valid = bool(re.match(pattern, gstin))
    state_codes = {
        "27": "Maharashtra", "36": "Telangana", "29": "Karnataka",
        "07": "Delhi", "33": "Tamil Nadu", "09": "Uttar Pradesh"
    }
    state_code = gstin[:2] if valid else None
    return {
        "gstin": gstin,
        "valid": valid,
        "state_code": state_code,
        "state": state_codes.get(state_code, "Unknown") if state_code else None,
        "error": None if valid else "Invalid GSTIN format"
    }

def calculate_gst(hsn_code: str, taxable_value: float,
                  supplier_state: str, recipient_state: str) -> dict:
    """Calculate GST breakdown for a line item."""
    if hsn_code not in HSN_RATES:
        return {"error": "HSN code not found: " + hsn_code}
    rate = HSN_RATES[hsn_code]
    is_interstate = supplier_state != recipient_state
    if is_interstate:
        igst = round(taxable_value * rate / 100, 2)
        cgst = sgst = 0
        supply_type = "Interstate - IGST applies"
    else:
        cgst = sgst = round(taxable_value * rate / 2 / 100, 2)
        igst = 0
        supply_type = "Intrastate - CGST + SGST applies"
    total_tax = igst + cgst + sgst
    return {
        "hsn_code": hsn_code,
        "gst_rate_pct": rate,
        "taxable_value": taxable_value,
        "supply_type": supply_type,
        "cgst": cgst,
        "sgst": sgst,
        "igst": igst,
        "total_tax": total_tax,
        "invoice_value": round(taxable_value + total_tax, 2)
    }

gstin_tool = FunctionTool(func=validate_gstin)
gst_tool = FunctionTool(func=calculate_gst)

gst_agent = Agent(
    model="gemini-2.0-flash",
    name="gst_compliance_agent",
    instruction="""
        You are a GST Compliance Agent for ShopMax India.
        When given invoice details:
        1. Validate the supplier and recipient GSTINs
        2. Calculate GST for each line item using HSN code
        3. Produce a compliance report:
           - GSTIN validation results
           - Line-item tax breakdown (CGST/SGST or IGST)
           - Total taxable value, total tax, and invoice value
           - Supply type (interstate/intrastate)
           - Any compliance issues or discrepancies flagged
        Use Indian GST terminology. Be precise with amounts.
    """,
    tools=[gstin_tool, gst_tool]
)

session_service = InMemorySessionService()
runner = Runner(agent=gst_agent, app_name="gst_check", session_service=session_service)

session = session_service.create_session(app_name="gst_check", user_id="accounts")
prompt = """
    Validate this invoice for GST compliance:
    Supplier GSTIN: 27AABCS1429B1ZB (ShopMax India, Maharashtra)
    Recipient GSTIN: 36BBBCS9999C1ZD (Hyderabad Tech Pvt Ltd, Telangana)
    Line Items:
    1. Dell Laptop (HSN 8471) - Rs 55,000 x 5 units = Rs 2,75,000
    2. LG Monitor (HSN 8528) - Rs 12,000 x 5 units = Rs 60,000
    3. Networking Switch (HSN 8517) - Rs 8,500 x 2 units = Rs 17,000
"""
message = Content(role="user", parts=[Part(text=prompt)])
for event in runner.run(user_id="accounts", session_id=session.id, new_message=message):
    if event.is_final_response():
        print(event.content.parts[0].text)

It gives the following output,

GST COMPLIANCE REPORT
======================
Supply Type: INTERSTATE (Maharashtra to Telangana) - IGST applies

GSTIN Validation
  Supplier: 27AABCS1429B1ZB - VALID (Maharashtra)
  Recipient: 36BBBCS9999C1ZD - VALID (Telangana)

Line Item Breakdown
Item                HSN   Rate  Taxable Value   IGST       Invoice Value
Dell Laptop (x5)    8471  18%   Rs 2,75,000    Rs 49,500  Rs 3,24,500
LG Monitor (x5)     8528  28%   Rs   60,000    Rs 16,800  Rs   76,800
Network Switch (x2) 8517  18%   Rs   17,000    Rs  3,060  Rs   20,060

Summary
  Total Taxable Value : Rs 3,52,000
  Total IGST          : Rs 69,360
  Total Invoice Value : Rs 4,21,360

Compliance Status: PASS
  No discrepancies found. Invoice is ready for GSTR-1 filing.
  Note: HSN 8528 (Monitors) attracts 28% - verify this is
  correctly communicated to the customer.

The GST Compliance Agent can be integrated into your billing system to validate every invoice before it is sent. Extend it to cross-check invoices against purchase orders, flag mismatches in GSTR-2A reconciliation, and generate GSTR-1 JSON output ready for portal upload. For businesses with high transaction volumes, run it as a batch agent at month-end before the filing deadline.

Send your comments, suggestions or queries regarding this site to [email protected].