GuviDOc.md

Problem Statement 2
Agentic Honey-Pot for Scam Detection & Intelligence Extraction
1. Introduction
Online scams such as bank fraud, UPI fraud, phishing, and fake offers are becoming increasingly adaptive. Scammers change their tactics based on user responses, making traditional detection systems ineffective.
This challenge requires participants to build an Agentic Honey-Pot — an AI-powered system that detects scam intent and autonomously engages scammers to extract useful intelligence without revealing detection.
2. Objective
Design and deploy an AI-driven honeypot system that can:
Detect scam or fraudulent messages
Activate an autonomous AI Agent
Maintain a believable human-like persona
Handle multi-turn conversations
Extract scam-related intelligence
Return structured results via an API
3. What You Need to Build
Participants must deploy a public REST API that:
Accepts incoming message events
Detects scam intent
Hands control to an AI Agent
Engages scammers autonomously
Extracts actionable intelligence
Returns a structured JSON response
Secures access using an API key

4. API Authentication
x-api-key: YOUR_SECRET_API_KEY
Content-Type: application/json
5. Evaluation Flow
Platform sends a suspected scam message
Your system analyzes the message
If scam intent is detected, the AI Agent is activated
The Agent continues the conversation
Intelligence is extracted and returned
Performance is evaluated
6. API Request Format (Input)
Each API request represents one incoming message in a conversation.
6.1 First Message (Start of Conversation)
This is the initial message sent by a suspected scammer. There is no prior conversation history.
{
“sessionId”: “wertyu-dfghj-ertyui”,
  "message": {
    "sender": "scammer",
    "text": "Your bank account will be blocked today. Verify immediately.",
    "timestamp": 1770005528731
  },
  "conversationHistory": [],
  "metadata": {
    "channel": "SMS",
    "language": "English",
    "locale": "IN"
  }
}
6.2 Second Message (Follow-Up Message)
This request represents a continuation of the same conversation.
Previous messages are now included in conversationHistory.
{
“sessionId”: “wertyu-dfghj-ertyui”,
  "message": {
    "sender": "scammer",
    "text": "Share your UPI ID to avoid account suspension.",
    "timestamp": 1770005528731
  },
  "conversationHistory": [
    {
      "sender": "scammer",
      "text": "Your bank account will be blocked today. Verify immediately.",
      "timestamp": 1770005528731
    },
    {
      "sender": "user",
      "text": "Why will my account be blocked?",
      "timestamp": 1770005528731
    }
  ],
  "metadata": {
    "channel": "SMS",
    "language": "English",
    "locale": "IN"
  }
}
6.3 Request Body Field Explanation
message (Required)
The latest incoming message in the conversation.
Field
Description
sender
scammer or user
text
Message content
timestamp
Epoch time format in ms

conversationHistory (Optional)
All previous messages in the same conversation.
Empty array ([]) for first message
Required for follow-up messages

metadata (Optional but Recommended)
Field
Description
channel
SMS / WhatsApp / Email / Chat
language
Language used
locale
Country or region

7. Agent Behavior Expectations
The AI Agent must:
Handle multi-turn conversations
Adapt responses dynamically
Avoid revealing scam detection
Behave like a real human
Perform self-correction if needed
8. Agent output should be like 
{
  "status": "success",
  "reply": "Why is my account being suspended?"
}
9. Evaluation Criteria
Scam detection accuracy
Quality of agentic engagement
Intelligence extraction
API stability and response time
Ethical behavior
10. Constraints & Ethics
❌ No impersonation of real individuals
❌ No illegal instructions
❌ No harassment
✅ Responsible data handling
11. One-Line Summary
Build an AI-powered agentic honeypot API that detects scam messages, handles multi-turn conversations, and extracts scam intelligence without exposing detection.
12. Mandatory Final Result Callback (Very Important)
Once the system detects scam intent and the AI Agent completes the engagement, participants must send the final extracted intelligence to the GUVI evaluation endpoint.
This is mandatory for evaluation.
Callback Endpoint
POST https://hackathon.guvi.in/api/updateHoneyPotFinalResult
Content-Type: application/json
Payload to Send
Participants must send the following JSON payload to the above endpoint:
{
  "sessionId": "abc123-session-id",
  "scamDetected": true,
  "totalMessagesExchanged": 18,
  "extractedIntelligence": {
    "bankAccounts": ["XXXX-XXXX-XXXX"],
    "upiIds": ["scammer@upi"],
    "phishingLinks": ["http://malicious-link.example"],
    "phoneNumbers": ["+91XXXXXXXXXX"],
    "suspiciousKeywords": ["urgent", "verify now", "account blocked"]
  },
  "agentNotes": "Scammer used urgency tactics and payment redirection"
}
🧠 When Should This Be Sent?
You must send this only after:
Scam intent is confirmed (scamDetected = true)
The AI Agent has completed sufficient engagement
Intelligence extraction is finished
This should be treated as the final step of the conversation lifecycle.

🧩 Field Explanation
Field
Description
sessionId
Unique session ID received from the platform for this conversation
scamDetected
Whether scam intent was confirmed
totalMessagesExchanged
Total number of messages exchanged in the session
extractedIntelligence
All intelligence gathered by the agent
agentNotes
Summary of scammer behavior

⚠️ Important Rules
This callback is mandatory for scoring
If this API call is not made, the solution cannot be evaluated
The platform uses this data to measure:
Engagement depth
Intelligence quality
Agent effectiveness
💻 Example Implementation (Python)
intelligence_dict = {
    "bankAccounts": intelligence.bankAccounts,
    "upiIds": intelligence.upiIds,
    "phishingLinks": intelligence.phishingLinks,
    "phoneNumbers": intelligence.phoneNumbers,
    "suspiciousKeywords": intelligence.suspiciousKeywords
}

payload = {
    "sessionId": session_id,
    "scamDetected": scam_detected,
    "totalMessagesExchanged": total_messages,
    "extractedIntelligence": intelligence_dict,
    "agentNotes": agent_notes
}

response = requests.post(
    "https://hackathon.guvi.in/api/updateHoneyPotFinalResult",
    json=payload,
    timeout=5
)
🧾 Updated One-Line Summary
Build an AI-powered agentic honeypot API that detects scam messages, engages scammers in multi-turn conversations, extracts intelligence, and reports the final result back to the GUVI evaluation endpoint.