Building a Production-Ready AI Agent

Luvie — Mon, 03 Nov 2025 21:01:45 +0000

Building a Production-Ready AI Agent in Pure Java: The License Compatibility Checker for Telex.imIntroduction: From Idea to Integration 🚀As part of the HNG Stage 3 Backend task, I designed and built a specialized AI agent for the Telex.im platform. My goal was to create something genuinely useful for developers: a License Compatibility Checker Agent. This agent goes beyond simple Q&A, offering on-demand license compatibility checks, detailed information, and proactive educational content—all built from scratch in Java 17+ without relying on external frameworks like Spring.This post walks through the architectural choices, the core logic (including the "clock system"), and the successful integration with the Telex A2A (Agent-to-Agent) protocol.🏗️ Architectural Design: Layered JavaTo meet the requirements for clean, maintainable, and testable code, I chose a simple Layered Architecture inspired by the classic Model-View-Controller (MVC) pattern, substituting the "View" with a dedicated formatting layer.LayerFilesPurposeMainLicenseCompatibilityAgent.javaServer setup, thread pooling, and endpoint registration (using com.sun.net.httpserver).Controllers*Controller.javaHandles HTTP requests (e.g., /v1/message, /health). Translates HTTP into service calls.Services*Service.javaContains all business logic (caching, API calls, scheduling, compatibility matrix).Utilities*Utils.java, LicenseExtractor.javaShared helpers: HTTP client, JSON parsing, NLP for query extraction, and Markdown formatting.Models*Info.javaSimple POJOs for data transfer (e.g., LicenseInfo, CompatibilityResult).Key Design Principle: Separation of ConcernsThe use of distinct classes like MessageProcessor and LicenseExtractor ensured that the agent could handle incoming JSON-RPC messages, extract complex natural language queries, fetch data from the LicenseService, and format the final Markdown response without any single class becoming bloated.💡 Core Functionality & Logic1. Data Source and Caching StrategyThe agent uses the GitHub Licenses API (https://api.github.com/licenses) as its primary, free data source.Caching: To adhere to best practices and conserve API bandwidth, the LicenseService implements an in-memory HashMap cache. When a license detail is requested (e.g., for MIT), it is fetched once from GitHub and stored. All subsequent requests for MIT are served instantly from the cache.2. The "Clock System" (Daily Posts) ⏰A core requirement was creating an agent that is both reactive (responds to users) and proactive (posts automatically).SchedulerService.java: This service uses a standard Java ScheduledExecutorService to execute a task every 24 hours.Proactive Content: The scheduled task calls the LicenseService to determine the "License of the Day" based on the day of the year (ensuring a different license is selected daily) and posts the result to a specified channel via an internal messaging mechanism.3. Compatibility LogicThe heart of the agent is in the LicenseService, which defines a pre-computed compatibility matrix based on established open-source license guidelines (e.g., GPL's Copyleft requirements). This simple logic ensures accurate and fast results for queries like: "Can I use MIT with GPL-3.0?"🔗 Integration with Telex.im (A2A Protocol)Integration was handled via three main public HTTP endpoints, ensuring full compliance with the Agent-to-Agent (A2A) JSON-RPC 2.0 standard.1. Agent Card Discovery (/.well-known/agent-card)This is the handshake for Telex. The AgentCardController serves a static agent-card.json file that clearly lists the agent's capabilities (license-compatibility-check, daily-license-insights) and skills.2. Message Handling (/v1/message)This is the main interaction point. The MessageController is responsible for:Receiving the JSON-RPC request.Extracting the user's plain text message.Calling the MessageProcessor to determine the intent (compatibility check, info request, or list request).Returning a valid JSON-RPC result object with the final Markdown-formatted response.3. Health Check (/health)A simple endpoint used by the platform for monitoring, ensuring the server is up and responsive.

Building My First RESTful API: Backend Wizards Stage 0 Journey 🚀

Luvie — Sun, 19 Oct 2025 08:47:47 +0000

Building My First RESTful API: Backend Wizards Stage 0 Journey 🚀

A complete walkthrough of building a dynamic profile endpoint with Java and Spring Boot

📋 Table of Contents

The Challenge
Why Java and Spring Boot?
Architecture Overview
Implementation Journey
Key Learnings
Challenges Faced
Testing & Deployment
Conclusion

🎯 The Challenge {#the-challenge}

Backend Wizards Stage 0 presented an interesting task: build a RESTful API endpoint that combines static user profile data with dynamic external API integration. The requirements were clear:

Endpoint: GET /me
Response: JSON with user info, timestamp, and cat fact
External API: Fetch fresh cat facts from catfact.ninja
Dynamic Data: New timestamp and cat fact on every request
Error Handling: Graceful fallbacks for API failures

Here's what the response should look like:

{
  "status": "success",
  "user": {
    "email": "developer@example.com",
    "name": "John Developer",
    "stack": "Java/Spring Boot"
  },
  "timestamp": "2025-10-18T12:34:56.789Z",
  "fact": "Cats can rotate their ears 180 degrees."
}

🤔 Why Java and Spring Boot? {#tech-stack}

While I could have chosen any language, I opted for Java with Spring Boot for several reasons:

Advantages:

✅ Industry Standard - Widely used in enterprise applications

✅ Spring Boot Magic - Auto-configuration saves tons of boilerplate

✅ Strong Typing - Catches errors at compile time

✅ Excellent Ecosystem - Mature libraries and tools

✅ RestTemplate - Built-in HTTP client with timeout support

✅ Easy Deployment - Single JAR file, runs anywhere

Tech Stack:

Java 17 - Latest LTS version
Spring Boot 3.2.0 - Web framework
Maven - Dependency management
RestTemplate - HTTP client
Jackson - JSON serialization
SLF4J - Logging

🏗️ Architecture Overview {#architecture}

I followed a clean MVC architecture with clear separation of concerns:

┌─────────────────────────────────────┐
│     ProfileController               │  ← HTTP Layer
│  (Handles REST requests/responses)  │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│       ProfileService                │  ← Business Logic
│  (Fetches cat facts, builds model)  │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│      External Cat Facts API         │  ← External Integration
│     (https://catfact.ninja/fact)    │
└─────────────────────────────────────┘

Layer Breakdown:

1. Controller Layer (ProfileController.java)

Handles HTTP requests
Returns proper status codes
Manages error responses

2. Service Layer (ProfileService.java)

Business logic
External API calls
Data transformation

3. DTO Layer (Data Transfer Objects)

ProfileResponse - Main response structure
UserInfo - User profile data
CatFactResponse - External API response

💻 Implementation Journey {#implementation}

Step 1: Setting Up the Project

Created a Spring Boot project with Maven:

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.0</version>
</parent>

Step 2: Building the Main Application

@SpringBootApplication
public class ProfileApplication {
    public static void main(String[] args) {
        SpringApplication.run(ProfileApplication.class, args);
    }
}

Simple and clean! Spring Boot handles all the heavy lifting.

Step 3: Creating the REST Controller

@RestController
public class ProfileController {

    @Autowired
    private ProfileService profileService;

    @GetMapping(value = "/me", produces = MediaType.APPLICATION_JSON_VALUE)
    public ResponseEntity<?> getProfile() {
        try {
            ProfileResponse response = profileService.getProfileWithCatFact();
            return ResponseEntity.ok(response);
        } catch (Exception e) {
            // Error handling
            Map<String, Object> errorResponse = new HashMap<>();
            errorResponse.put("status", "error");
            errorResponse.put("timestamp", Instant.now().toString());
            return ResponseEntity.status(503).body(errorResponse);
        }
    }
}

Key Points:

@RestController - Combines @Controller and @ResponseBody
@GetMapping - Maps HTTP GET requests
ResponseEntity - Full control over HTTP response
Error handling with proper status codes

Step 4: Implementing the Service Layer

The most interesting part - integrating with the external API:

@Service
public class ProfileService {

    private final RestTemplate restTemplate;

    public ProfileService(RestTemplateBuilder builder) {
        this.restTemplate = builder
            .setConnectTimeout(Duration.ofSeconds(5))
            .setReadTimeout(Duration.ofSeconds(5))
            .build();
    }

    public ProfileResponse getProfileWithCatFact() {
        String catFact = fetchCatFact();
        UserInfo userInfo = new UserInfo(email, name, stack);

        return new ProfileResponse(
            "success",
            userInfo,
            Instant.now().toString(),  // ISO 8601 timestamp
            catFact
        );
    }

    private String fetchCatFact() {
        CatFactResponse response = restTemplate.getForObject(
            "https://catfact.ninja/fact",
            CatFactResponse.class
        );
        return response.getFact();
    }
}

Critical Implementation Details:

Timeout Configuration: 5-second timeout prevents hanging
ISO 8601 Timestamps: Instant.now().toString() automatically formats
RestTemplate: Spring's HTTP client with automatic JSON mapping
Constructor Injection: Best practice for dependency injection

Step 5: Creating DTOs

Clean data transfer objects for type safety:


java
public class ProfileResponse {
    @JsonProperty("status")
    private String status;

    @JsonProperty("user")
    private UserInfo user;

    @JsonProperty("timestamp")
    private String timestamp;

    @JsonProperty("fact")
    private String fact;

    // Constructors, getters

Forem: Luvie

Building a Production-Ready AI Agent

Building My First RESTful API: Backend Wizards Stage 0 Journey 🚀

Building My First RESTful API: Backend Wizards Stage 0 Journey 🚀

📋 Table of Contents

🎯 The Challenge {#the-challenge}

🤔 Why Java and Spring Boot? {#tech-stack}

Advantages:

Tech Stack:

🏗️ Architecture Overview {#architecture}

Layer Breakdown:

💻 Implementation Journey {#implementation}

Step 1: Setting Up the Project

Step 2: Building the Main Application

Step 3: Creating the REST Controller

Step 4: Implementing the Service Layer

Step 5: Creating DTOs