DEV Community

Name cannot be blank
Name cannot be blank

Posted on

Agent Lagbaja

#agents #showdev #gemini #ai

Building Lagbaja: An AI-Powered Flashcard Generator

A production-ready A2A service that transforms PDFs into intelligent study flashcards

Overview

Lagbaja is an Agent-to-Agent (A2A) compliant backend service that converts PDF documents and text into study flashcards using Google's Gemini AI. It follows JSON-RPC 2.0 protocol, integrates with workflow platforms like Telex, and supports multiple input methods.

The Problem

Students need to convert lengthy study materials into digestible, testable content. Most flashcard tools require manual input and don't intelligently extract key concepts. Lagbaja solves this by:

  • Automatically generating flashcards from PDFs and text using AI
  • Following A2A protocol for seamless agent-to-agent communication
  • Supporting JSON-RPC 2.0 for standardized messaging

Architecture Overview

Lagbaja follows a clean, layered architecture built with Go 1.25.3:

HTTP Server → Handler Layer → Service Layer → External APIs
    ↓             ↓              ↓              ↓
  /a2a        A2AHandler    FlashcardSvc    Gemini AI
  /upload                   PDFService      PDF Parser
  /health
Enter fullscreen mode Exit fullscreen mode

Key Components:

  1. HTTP Server (main.go) - Routing, middleware, graceful shutdown
  2. Handler Layer - JSON-RPC 2.0 and A2A message processing
  3. Service Layer - Business logic for PDF processing and flashcard generation
  4. Models - A2A, JSON-RPC, and domain structures

Key Features

Multiple Input Methods

Lagbaja accepts requests in three ways:

// Text Input
{"message": {"parts": [{"text": "Create flashcards about photosynthesis"}]}}

// PDF URL
{"message": {"parts": [{"text": "https://example.com/notes.pdf"}]}}
Enter fullscreen mode Exit fullscreen mode 
# File Upload
curl -X POST /upload -F "pdf=@notes.pdf"
Enter fullscreen mode Exit fullscreen mode

Protocol Compliance

JSON-RPC 2.0: Standard error codes (-32700 to -32603), proper request/response format

A2A Protocol: Task management, structured artifacts, message history

{
  "result": {
    "status": {"state": "completed"},
    "artifacts": [{"name": "flashcardSet", "parts": [...]}],
    "history": [...]
  }
}
Enter fullscreen mode Exit fullscreen mode

AI Generation

Uses Google Gemini (gemini-1.5-flash) to analyze content and generate 5-10 focused flashcards with questions, answers, and topic categorization.

Technical Decisions

Why Go?

  • Built-in concurrency with goroutines
  • Excellent HTTP and JSON standard library
  • Single binary deployment
  • Fast performance and low memory footprint

Why Gemini over Anthropic?

Primary reason: Anthropic API credit limitations. Gemini's generous free tier enabled continued development and production deployment.

Additional benefits: Simpler API, faster responses, native Google ecosystem integration.

Middleware Design 

// Method enforcement + request logging
mux.Handle("/a2a", loggingMiddleware(methodGuard(handler, "POST")))
Enter fullscreen mode Exit fullscreen mode

Clean separation of concerns keeps handlers focused on business logic.

Testing

Comprehensive test coverage with 11 suites and 23 test cases (100% pass rate):

  • HTTP method validation
  • JSON-RPC protocol compliance
  • Message parsing and validation
  • PDF processing and text extraction
  • Flashcard formatting and generation 
go test ./... -v  # All tests passing
Enter fullscreen mode Exit fullscreen mode

Telex Integration

Lagbaja integrates with Telex workflows via workflow.json:

{
  "category": "education",
  "nodes": [{
    "type": "a2a/mastra-a2a-node",
    "url": "http://lagbaja-production.up.railway.app/a2a",
    "parameters": {
      "model": "gemini-1.5-flash",
      "httpMethod": "POST"
    }
  }]
}
Enter fullscreen mode Exit fullscreen mode

This enables workflow platforms to discover and communicate with Lagbaja automatically.

Deployment

Deployed on Railway with automatic builds:

GEMINI_API_KEY=<key>
PORT=8080
Enter fullscreen mode Exit fullscreen mode

Includes graceful shutdown, health checks, and request timeouts for production reliability.

Usage Example 

curl -X POST https://lagbaja-production.up.railway.app/a2a \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "test",
    "method": "message/send",
    "params": {
      "message": {
        "parts": [{"kind": "text", "text": "Create flashcards about quantum mechanics"}]
      }
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Response: Structured flashcards with questions, answers, and topics in both text and JSON format.

Key Takeaways

  • Protocol Compliance: Following JSON-RPC 2.0 and A2A specs enables seamless integration
  • Testing: Comprehensive tests (23 cases) ensure reliability
  • Pragmatic Choices: Switched to Gemini due to Anthropic credit limits—practical constraints drive good decisions
  • Clean Architecture: Layered design with middleware keeps code maintainable

Future Enhancements

  • Batch PDF processing
  • Custom flashcard templates
  • Anki/Quizlet export formats
  • Caching for repeated requests
  • API authentication

Try It

Live: https://lagbaja-production.up.railway.app/a2a

Code: https://github.com/tobey0x/lagbaja

Quick Start:

git clone https://github.com/tobey0x/lagbaja
cd lagbaja
echo "GEMINI_API_KEY=your-key" > .env
go run main.go
Enter fullscreen mode Exit fullscreen mode

Built with Go 1.25.3 • Google Gemini AI • Deployed on Railway

Top comments (0)