Code Examples

Practical, copy-paste ready examples for common Agentle4j use cases.

---

Basic Examples

Simple Chat Completion

import com.paragon.responses.Responder;
import com.paragon.responses.spec.CreateResponsePayload;
import com.paragon.responses.Response;

public class SimpleChatExample {
    public static void main(String[] args) {
        Responder responder = Responder.builder()
            .openRouter()
            .apiKey(System.getenv("OPENROUTER_API_KEY"))
            .build();

        var payload = CreateResponsePayload.builder()
            .model("openai/gpt-4o-mini")
            .addDeveloperMessage("You are a helpful assistant.")
            .addUserMessage("Explain Java streams in 3 sentences.")
            .build();

        Response response = responder.respond(payload).join();
        System.out.println(response.outputText());
    }
}

With Temperature Control

// Creative writing (high temperature)
var creativePayload = CreateResponsePayload.builder()
    .model("openai/gpt-4o")
    .addUserMessage("Write a creative story opening about a space explorer")
    .temperature(1.2)  // More creative/random
    .build();

// Factual response (low temperature)  
var factualPayload = CreateResponsePayload.builder()
    .model("openai/gpt-4o")
    .addUserMessage("What is the formula for calculating compound interest?")
    .temperature(0.1)  // More deterministic
    .build();

Limiting Response Length

var payload = CreateResponsePayload.builder()
    .model("openai/gpt-4o")
    .addUserMessage("Explain quantum computing")
    .maxTokens(150)  // Limit response to ~150 tokens
    .build();

---

Streaming Examples

Basic Streaming with Progress

import java.util.concurrent.atomic.AtomicInteger;

var payload = CreateResponsePayload.builder()
    .model("openai/gpt-4o")
    .addUserMessage("Write a detailed explanation of microservices architecture")
    .streaming()
    .build();

AtomicInteger charCount = new AtomicInteger(0);
long startTime = System.currentTimeMillis();

responder.respond(payload)
    .onTextDelta(delta -> {
        System.out.print(delta);
        System.out.flush();
        charCount.addAndGet(delta.length());
    })
    .onComplete(response -> {
        long elapsed = System.currentTimeMillis() - startTime;
        System.out.println("\n\n--- Stats ---");
        System.out.println("Characters: " + charCount.get());
        System.out.println("Tokens: " + response.usage().totalTokens());
        System.out.println("Time: " + elapsed + "ms");
        System.out.println("Speed: " + (charCount.get() * 1000 / elapsed) + " chars/sec");
    })
    .onError(e -> System.err.println("Error: " + e.getMessage()))
    .start();

Streaming to a File

import java.io.FileWriter;
import java.io.PrintWriter;

var payload = CreateResponsePayload.builder()
    .model("openai/gpt-4o")
    .addUserMessage("Write a comprehensive guide to REST API design")
    .streaming()
    .build();

try (PrintWriter writer = new PrintWriter(new FileWriter("output.md"))) {
    responder.respond(payload)
        .onTextDelta(delta -> {
            writer.print(delta);
            writer.flush();
            System.out.print(delta);  // Also show in console
            System.out.flush();
        })
        .onComplete(r -> {
            System.out.println("\n\n✅ Saved to output.md");
        })
        .start();
}

Streaming with Abort Capability

import java.util.concurrent.atomic.AtomicBoolean;

AtomicBoolean shouldStop = new AtomicBoolean(false);
StringBuilder buffer = new StringBuilder();

var payload = CreateResponsePayload.builder()
    .model("openai/gpt-4o")
    .addUserMessage("Write a very long story")
    .streaming()
    .build();

var stream = responder.respond(payload)
    .onTextDelta(delta -> {
        if (shouldStop.get()) {
            return;  // Stop processing
        }
        buffer.append(delta);
        System.out.print(delta);

        // Auto-stop after 500 characters
        if (buffer.length() > 500) {
            shouldStop.set(true);
            System.out.println("\n\n[Stopped after 500 chars]");
        }
    })
    .start();

---

Structured Output Examples

Simple Data Extraction

public record ProductInfo(
    String name,
    double price,
    String currency,
    boolean inStock
) {}

String productDescription = """
    The Sony WH-1000XM5 wireless headphones are available for $399.99.
    These premium noise-cancelling headphones are currently in stock.
    """;

var payload = CreateResponsePayload.builder()
    .model("openai/gpt-4o")
    .addUserMessage("Extract product info: " + productDescription)
    .withStructuredOutput(ProductInfo.class)
    .build();

ProductInfo product = responder.respond(payload).join().parsed();
System.out.println("Product: " + product.name());
System.out.println("Price: " + product.currency() + product.price());
System.out.println("In Stock: " + product.inStock());

Sentiment Analysis

public record SentimentAnalysis(
    String sentiment,        // "positive", "negative", "neutral"
    double confidence,       // 0.0 to 1.0
    List<String> keywords,   // Key emotional words
    String summary           // Brief explanation
) {}

String review = """
    I absolutely love this product! It exceeded all my expectations.
    The build quality is fantastic and customer service was helpful.
    Only minor issue is the slightly high price, but worth it!
    """;

var payload = CreateResponsePayload.builder()
    .model("openai/gpt-4o")
    .addDeveloperMessage("Analyze the sentiment of customer reviews.")
    .addUserMessage(review)
    .withStructuredOutput(SentimentAnalysis.class)
    .build();

SentimentAnalysis analysis = responder.respond(payload).join().parsed();
System.out.println("Sentiment: " + analysis.sentiment());
System.out.println("Confidence: " + (analysis.confidence() * 100) + "%");
System.out.println("Keywords: " + String.join(", ", analysis.keywords()));

Code Review Analysis

public record CodeIssue(
    String type,           // "bug", "style", "performance", "security"
    String severity,       // "low", "medium", "high", "critical"
    int lineNumber,
    String description,
    String suggestion
) {}

public record CodeReview(
    int overallScore,      // 1-10
    List<CodeIssue> issues,
    List<String> positives,
    String summary
) {}

String code = """
    public class UserService {
        private String password = "admin123";  // Hardcoded password

        public void deleteUser(int id) {
            String sql = "DELETE FROM users WHERE id = " + id;  // SQL injection
            // execute sql...
        }
    }
    """;

var payload = CreateResponsePayload.builder()
    .model("openai/gpt-4o")
    .addDeveloperMessage("You are a senior code reviewer. Analyze code for issues.")
    .addUserMessage("Review this code:\n```java\n" + code + "\n```")
    .withStructuredOutput(CodeReview.class)
    .build();

CodeReview review = responder.respond(payload).join().parsed();
System.out.println("Score: " + review.overallScore() + "/10");
System.out.println("\nIssues found:");
for (CodeIssue issue : review.issues()) {
    System.out.println("  [" + issue.severity().toUpperCase() + "] " + issue.type());
    System.out.println("  Line " + issue.lineNumber() + ": " + issue.description());
    System.out.println("  Fix: " + issue.suggestion());
    System.out.println();
}

JSON Schema Generation

// Complex nested structures
public record Address(
    String street,
    String city,
    String state,
    String zipCode,
    String country
) {}

public record Company(
    String name,
    String industry,
    int employeeCount,
    Address headquarters,
    List<String> products
) {}

public record MarketAnalysis(
    Company company,
    List<Company> competitors,
    double marketShare,
    List<String> strengths,
    List<String> weaknesses,
    String recommendation
) {}

var payload = CreateResponsePayload.builder()
    .model("openai/gpt-4o")
    .addUserMessage("Provide a market analysis for Apple Inc.")
    .withStructuredOutput(MarketAnalysis.class)
    .build();

MarketAnalysis analysis = responder.respond(payload).join().parsed();

---

Multi-Turn Conversation Examples

Stateful Conversation Manager

import java.util.ArrayList;
import java.util.List;

public class ConversationManager {
    private final Responder responder;
    private final String model;
    private final String systemPrompt;
    private final List<ResponseInputItem> history = new ArrayList<>();

    public ConversationManager(Responder responder, String model, String systemPrompt) {
        this.responder = responder;
        this.model = model;
        this.systemPrompt = systemPrompt;
    }

    public String chat(String userMessage) {
        // Add user message to history
        history.add(new UserMessage(userMessage));

        // Build payload with full history
        var payload = CreateResponsePayload.builder()
            .model(model)
            .addDeveloperMessage(systemPrompt)
            .inputItems(history)
            .build();

        // Get response
        Response response = responder.respond(payload).join();
        String assistantMessage = response.outputText();

        // Add assistant response to history
        history.add(new AssistantMessage(assistantMessage));

        return assistantMessage;
    }

    public void clearHistory() {
        history.clear();
    }

    public int getTurnCount() {
        return history.size() / 2;
    }
}

// Usage
ConversationManager chat = new ConversationManager(
    responder, 
    "openai/gpt-4o-mini",
    "You are a helpful coding tutor."
);

System.out.println(chat.chat("What is a Java interface?"));
System.out.println(chat.chat("Can you show me an example?"));
System.out.println(chat.chat("How is it different from an abstract class?"));

Context Window Management

public class SmartConversation {
    private final Responder responder;
    private final List<ResponseInputItem> history = new ArrayList<>();
    private static final int MAX_HISTORY = 20;  // Keep last 20 messages

    public String chat(String userMessage) {
        history.add(new UserMessage(userMessage));

        // Trim history if too long (keep most recent)
        if (history.size() > MAX_HISTORY) {
            history.subList(0, history.size() - MAX_HISTORY).clear();
        }

        var payload = CreateResponsePayload.builder()
            .model("openai/gpt-4o-mini")
            .inputItems(history)
            .build();

        Response response = responder.respond(payload).join();
        history.add(new AssistantMessage(response.outputText()));

        return response.outputText();
    }
}

---

Batch Processing Examples

Parallel API Calls

import java.util.List;
import java.util.concurrent.CompletableFuture;
import java.util.stream.Collectors;

List<String> topics = List.of(
    "Machine Learning",
    "Blockchain",
    "Quantum Computing",
    "Edge Computing",
    "5G Networks"
);

// Create all requests in parallel
List<CompletableFuture<Response>> futures = topics.stream()
    .map(topic -> {
        var payload = CreateResponsePayload.builder()
            .model("openai/gpt-4o-mini")
            .addUserMessage("Explain " + topic + " in 2 sentences.")
            .build();
        return responder.respond(payload);
    })
    .collect(Collectors.toList());

// Wait for all to complete
CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();

// Process results
for (int i = 0; i < topics.size(); i++) {
    System.out.println("## " + topics.get(i));
    System.out.println(futures.get(i).join().outputText());
    System.out.println();
}

Rate-Limited Batch Processing

import java.util.concurrent.Semaphore;

// Limit to 5 concurrent requests
Semaphore rateLimiter = new Semaphore(5);

List<String> prompts = List.of(/* many prompts */);

List<CompletableFuture<String>> results = prompts.stream()
    .map(prompt -> CompletableFuture.supplyAsync(() -> {
        try {
            rateLimiter.acquire();
            var payload = CreateResponsePayload.builder()
                .model("openai/gpt-4o-mini")
                .addUserMessage(prompt)
                .build();
            return responder.respond(payload).join().outputText();
        } catch (InterruptedException e) {
            throw new RuntimeException(e);
        } finally {
            rateLimiter.release();
        }
    }))
    .collect(Collectors.toList());

---

Error Handling Examples

Comprehensive Error Handling

responder.respond(payload)
    .handle((response, error) -> {
        if (error != null) {
            Throwable cause = error.getCause();

            if (cause instanceof java.net.SocketTimeoutException) {
                System.err.println("Request timed out. Please try again.");
            } else if (cause instanceof java.net.UnknownHostException) {
                System.err.println("Network error. Check your internet connection.");
            } else if (cause.getMessage().contains("401")) {
                System.err.println("Invalid API key. Please check your credentials.");
            } else if (cause.getMessage().contains("429")) {
                System.err.println("Rate limited. Please wait and try again.");
            } else if (cause.getMessage().contains("500")) {
                System.err.println("Server error. The API is temporarily unavailable.");
            } else {
                System.err.println("Unexpected error: " + cause.getMessage());
            }
            return null;
        }

        return response.outputText();
    });

Retry with Exponential Backoff

import java.util.concurrent.TimeUnit;

public Response callWithRetry(Responder responder, CreateResponsePayload payload, int maxRetries) {
    int retries = 0;
    long delay = 1000;  // Start with 1 second

    while (retries < maxRetries) {
        try {
            return responder.respond(payload).join();
        } catch (Exception e) {
            retries++;
            if (retries >= maxRetries) {
                throw e;
            }

            System.out.println("Retry " + retries + " after " + delay + "ms");
            try {
                TimeUnit.MILLISECONDS.sleep(delay);
            } catch (InterruptedException ie) {
                Thread.currentThread().interrupt();
                throw new RuntimeException(ie);
            }

            delay *= 2;  // Exponential backoff
        }
    }

    throw new RuntimeException("Max retries exceeded");
}

---

Real-World Application Examples

AI-Powered REST API Endpoint (Spring Boot)

@RestController
@RequestMapping("/api/ai")
public class AIController {

    private final Responder responder;

    public AIController() {
        this.responder = Responder.builder()
            .openRouter()
            .apiKey(System.getenv("OPENROUTER_API_KEY"))
            .build();
    }

    @PostMapping("/chat")
    public CompletableFuture<Map<String, String>> chat(@RequestBody ChatRequest request) {
        var payload = CreateResponsePayload.builder()
            .model("openai/gpt-4o-mini")
            .addUserMessage(request.message())
            .build();

        return responder.respond(payload)
            .thenApply(response -> Map.of(
                "response", response.outputText(),
                "tokens", String.valueOf(response.usage().totalTokens())
            ));
    }

    @PostMapping("/analyze")
    public CompletableFuture<SentimentAnalysis> analyzeSentiment(@RequestBody TextRequest request) {
        var payload = CreateResponsePayload.builder()
            .model("openai/gpt-4o")
            .addUserMessage("Analyze sentiment: " + request.text())
            .withStructuredOutput(SentimentAnalysis.class)
            .build();

        return responder.respond(payload)
            .thenApply(ParsedResponse::parsed);
    }
}

record ChatRequest(String message) {}
record TextRequest(String text) {}

CLI Tool with Streaming

public class AICli {
    public static void main(String[] args) {
        if (args.length == 0) {
            System.out.println("Usage: ai-cli <prompt>");
            return;
        }

        String prompt = String.join(" ", args);

        Responder responder = Responder.builder()
            .openRouter()
            .apiKey(System.getenv("OPENROUTER_API_KEY"))
            .build();

        var payload = CreateResponsePayload.builder()
            .model("openai/gpt-4o-mini")
            .addUserMessage(prompt)
            .streaming()
            .build();

        responder.respond(payload)
            .onTextDelta(delta -> {
                System.out.print(delta);
                System.out.flush();
            })
            .onComplete(r -> System.out.println())
            .onError(e -> {
                System.err.println("\nError: " + e.getMessage());
                System.exit(1);
            })
            .start();
    }
}

Document Summarizer

public class DocumentSummarizer {
    private final Responder responder;

    public DocumentSummarizer(Responder responder) {
        this.responder = responder;
    }

    public record Summary(
        String title,
        String oneSentence,
        List<String> keyPoints,
        List<String> actionItems,
        String targetAudience
    ) {}

    public Summary summarize(String document) {
        var payload = CreateResponsePayload.builder()
            .model("openai/gpt-4o")
            .addDeveloperMessage("""
                You are a document analysis expert. Summarize documents
                by extracting the most important information.
                """)
            .addUserMessage("Summarize this document:\n\n" + document)
            .withStructuredOutput(Summary.class)
            .build();

        return responder.respond(payload).join().parsed();
    }

    public static void main(String[] args) throws Exception {
        Responder responder = Responder.builder()
            .openRouter()
            .apiKey(System.getenv("OPENROUTER_API_KEY"))
            .build();

        DocumentSummarizer summarizer = new DocumentSummarizer(responder);

        String document = Files.readString(Path.of("document.txt"));
        Summary summary = summarizer.summarize(document);

        System.out.println("# " + summary.title());
        System.out.println("\n" + summary.oneSentence());
        System.out.println("\n## Key Points");
        summary.keyPoints().forEach(p -> System.out.println("- " + p));
        System.out.println("\n## Action Items");
        summary.actionItems().forEach(a -> System.out.println("- [ ] " + a));
    }
}