Building a QR & Barcode Generator Agent for Telex.im: A Complete Integration Journey

Introduction

As part of the HNG Stage 3 Backend Task, I built an AI agent that generates QR codes and barcodes, fully integrated with Telex.im using the A2A protocol. This post walks through the entire development process, challenges faced, and lessons learned.

The Problem

In today’s digital world, QR codes and barcodes are everywhere — from restaurant menus to inventory management. However, generating these codes often requires switching between different tools or websites. I wanted to create a seamless solution that users could access directly through Telex.im conversations.

Solution Architecture

Tech Stack Choice

- **Python**: For robust backend development
- **FastAPI**: Fast, modern web framework with automatic API documentation
- **qrcode & python-barcode**: Specialized libraries for code generation
- **Pydantic**: Data validation and serialization
- **A2A Protocol**: For Telex.im integration

Architecture Design

I followed SOLID principles with a clean MVC architecture:

src/
├── controllers/          # Handle HTTP requests
├── services/            # Business logic
├── models/              # Data models
├── utils/               # Utilities & integrations
└── main.py              # FastAPI application

Implementation Journey

1. Core Functionality Development

**QR Code Service:**
class QRService:
    def generate_qr(self, text: str, size: int = 10) -> str:
        qr = qrcode.QRCode(version=size, box_size=10, border=5)
        qr.add_data(text)
        qr.make(fit=True)
        # Generate and return base64 image

**Barcode Service:**
class BarcodeService:
    def generate_barcode(self, text: str, format_type: str = "code128") -> str:
        barcode_class = barcode.get_barcode_class(format_type)
        code = barcode_class(text, writer=ImageWriter())
        # Generate and return base64 image

2. Telex.im Integration Challenges

**Challenge 1: A2A Protocol Compliance**
The A2A protocol requires specific JSON response formats. I had to ensure responses matched exactly:

{
    "text": "QR code generated successfully!",
    "type": "image",
    "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

**Challenge 2: Message Parsing**
Telex sends messages in various formats. I created a robust parser:

class MessageParser:
    def parse_command(self, message: str) -> dict:
        # Handle "qr size:15 Hello World"
        # Handle "barcode format:ean13 123456789"
        # Extract parameters and text

**Challenge 3: Error Handling**
Invalid inputs needed graceful handling without breaking the conversation flow:

try:
    result = self.qr_service.generate_qr(text, size)
    return {"text": "QR generated!", "type": "image", "image": result}
except Exception as e:
    return {"text": f"Error: {str(e)}", "type": "text"}

3. Deployment & Testing

**Local Testing:**

python -m src.main
curl -X POST "http://localhost:8000/" -H "Content-Type: application/json" -d '{"text": "qr Hello World"}'

Production Deployment

Used Vercel for seamless deployment with the following configuration:

{
  "functions": {
    "api/index.js": {
      "runtime": "python3.9"
    }
  },
  "routes": [
    { "src": "/(.*)", "dest": "/api/index.js" }
  ]
}

Try It Out

The agent is live on Telex.im! Join the platform at [telex.im](https://telex.im) and try these commands:
- `qr https://telex-barcode-generation.vercel.app`
- `barcode 1234567890`
- `qr size:20 Hello HNG!`

**Links:**
- [GitHub Repository](https://github.com/tulbadex/telex-barcode-generation)
- [Live Demo](https://telex-barcode-generation.vercel.app)
- [Telex.im Platform](https://telex.im)