My journey developing an AI-powered coding assistant for HNG Internship Stage 3

During my participation in the HNG Internship’s third backend stage, I received an assignment to develop an AI-powered agent with Telex.im integration through the A2A protocol. The goal wasn’t to build another standard database application—the challenge was creating an intelligent system that provides real value to developers. My solution: Code Helper Agent—an intelligent assistant capable of examining source code, identifying errors, recommending enhancements, and spotting security risks across numerous programming languages. In this article, I’ll share my complete development process, from conception through production deployment, highlighting every obstacle encountered and the strategies I used to overcome them. Technology Choices: • Mastra Framework (agent architecture) • Google Gemini AI (intelligent analysis) • Express.js (backend server) • Telex.im (platform connectivity) • Railway (cloud hosting) Project Links: GitHub Repository : https://github.com/Habeeboss/code-helper-mastra-telex

Live Application : code-helper-mastra-telex-production.up.railway.app https://code-helper-mastra-telex-production.up.railway.app/a2a/agent/codeHelper

Phase 1: Conceptualization and Architecture Selecting the Project The assignment provided creative freedom: develop any functional AI agent. Several concepts crossed my mind: • Deadline Reminder System - Notifies users about upcoming tasks • Conversation Digest Tool - Condenses chat discussions • Code Analysis Helper - Reviews and debugs source code The Code Analysis Helper won because: • It addresses a genuine daily challenge for developers • It effectively demonstrates AI capabilities • Its utility is immediately apparent and quantifiable • Supporting multiple languages highlights its adaptability Establishing Core Features I outlined essential functionality versus optional enhancements: Critical Requirements: • Source code interpretation and breakdown • Error identification • Compatibility with various programming languages • Professional markdown output • Telex.im connectivity via A2A protocol Additional Features: • Security flaw detection • Performance enhancement recommendations • Industry standard practice suggestions

Phase 2: Project Foundation Bootstrap Process bash mkdir code-helper-mastra-telex cd code-helper-mastra-telex npm init -y Dependency Management My first significant hurdle appeared during package installation. Challenge #1: Mastra Installation Issues The official documentation lacked clarity on exact package requirements. My initial attempt: bash npm install @mastra/core Failure Message: npm ERR! code ERESOLVE npm ERR! ERESOLVE unable to resolve dependency tree Resolution: After examining the Mastra repository and documentation carefully, I discovered:

1. Node.js version 20 or higher was mandatory (I had version 16)
2. Initial installation required the legacy peer dependencies flag bash # Upgrade Node.js nvm install 22.17.0 nvm use 22.17.0

Install with appropriate configuration

npm install @mastra/core@^0.23.3 –legacy-peer-deps This approach eliminated the dependency conflicts. Organizing the Codebase I structured the project for maintainability: src/ ├── agents/ │ └── codeHelper.js # Agent implementation ├── config/ │ └── gemini.js # AI setup ├── routes/ │ └── a2aRoutes.js # API endpoints ├── mastra/ │ └── index.js # Framework instance └── main.js # Application entry Rationale for this organization: • Clear separation - Each module has distinct responsibilities • Easy maintenance - Locating and modifying code is straightforward • Growth potential - Adding new features or agents is simple

Phase 3: Developing the Mastra Agent Grasping Mastra Fundamentals Mastra provides a framework for constructing intelligent systems, built around these core ideas: • Agent - The intelligent entity with defined behavior and instructions • Tools - Callable functions the agent can utilize • Workflows - Multi-stage automated processes Agent Construction Challenge #2: Agent Configuration Problems My first implementation attempt: javascript const codeHelperAgent = new Agent({ name: “code_helper”, model: “gemini-2.5-flash”, instructions: “You are a code helper...” }); Error Encountered: Error: Agent requires a valid model instance The problem? Mastra needs a model object, not a string identifier. Resolution: Proper Gemini AI integration was necessary: javascript import { Agent } from “@mastra/core”; import { getGeminiModel } from “../config/gemini.js”;

const codeHelperAgent = new Agent({ name: “code_helper_telex”, instructions: ` You are a specialized coding assistant designed to help developers by:

• Analyzing and explaining code functionality
• Identifying and resolving bugs
• Enhancing code performance
• Detecting security vulnerabilities

Deliver responses using clean markdown formatting. Utilize bullet lists, code segments, and organized headers. `, model: “gemini-2.5-flash” }); Refining Agent Instructions Crafting effective instructions required multiple iterations: First Draft (Overly Broad): You are a helpful assistant that analyzes code. Second Draft (Too Restrictive):

1. First, explain the code
2. Then, list all bugs
3. Finally, suggest improvements Final Version (Optimal Balance): You are an expert code assistant...

CORE FUNCTIONALITY:

• Analyze code in multiple languages
• Identify bugs and issues
• Suggest improvements

RESPONSE FORMAT:

• Clean markdown
• Bullet points for lists
• Code blocks with language tags Important Discovery: Provide clear direction while maintaining flexibility. Establish guidelines without excessive constraints.

Phase 4: Gemini AI Integration Initial Configuration Challenge #3: Authentication Setup My first configuration: javascript import { GoogleGenerativeAI } from “@google/generative-ai”;

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY); Error Message: Error: GEMINI_API_KEY is not defined Resolution: Proper environment configuration was essential:

1. Generated .env file
2. Added it to .gitignore
3. Created .env.example as a template bash # .env GEMINI_API_KEY=your_actual_key_here PORT=4040 NODE_ENV=development javascript // config/gemini.js import { GoogleGenerativeAI } from “@google/generative-ai”; import dotenv from “dotenv”;

dotenv.config();

if (!process.env.GEMINI_API_KEY) { throw new Error(“GEMINI_API_KEY is required”); }

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);

export const getGeminiModel = (model = “gemini-2.5-flash”) => { return genAI.getGenerativeModel({ model }); }; Bridging Mastra and Gemini Challenge #4: Method Customization The Mastra Agent class includes a generate() method that needed customization for direct Gemini usage. Initial Unsuccessful Approach: javascript codeHelperAgent.model = geminiModel; Successful Implementation: javascript const originalGenerate = codeHelperAgent.generate;

codeHelperAgent.generate = async (prompt) => { try { const gemini = getGeminiModel(“gemini-2.5-flash”); const result = await gemini.generateContent(prompt); return result.response.text(); } catch (error) { console.error(“Gemini error:”, error); if (originalGenerate) { return originalGenerate.call(codeHelperAgent, prompt); } throw error; } }; Why This Approach Works: • Maintains the original method as a backup • Enables custom Gemini integration • Preserves comprehensive error handling

Phase 5: Express Server Development Route Configuration javascript import express from “express”; import { CodeHelperService } from “../agents/codeHelper.js”;

const router = express.Router();

router.post(“/a2a/agent/codeHelper”, async (req, res) => { try { const { message, text } = req.body; const result = await CodeHelperService.processMessage(message || text);

res.json({
response: result.text,
timestamp: new Date().toISOString()
});

} catch (error) { console.error(“Error:”, error); res.status(500).json({ response: “Service temporarily unavailable” }); } }); Challenge #5: Output Formatting Problems Initial responses appeared like this: Code Explanation\n• This is a function\n• It does something The escape sequences \n were visible in Telex! Root Issue: JavaScript string escaping behavior Resolution: I developed a text sanitization function: javascript cleanResponse(text) { if (!text || typeof text !== ‘string’) return text;

return text .replace(/\n/g, ‘\n’) // Correct newlines .replace(/`/g, ‘`’) // Correct backticks .replace(/*/g, ‘’) // Correct asterisks .replace(/#/g, ‘#’) // Correct headers .replace(/*/g, ‘’) // Correct underscores .replace(/\n\s*\n\s*\n/g, ‘\n\n’) // Eliminate excessive newlines .trim(); }

Phase 6: A2A Protocol Implementation Protocol Overview Telex.im uses the A2A (Agent-to-Agent) protocol for communication. Essential specifications: • POST endpoint accepting JSON payloads • Input structure: { “message”: “...” } or { “text”: “...” } • Output structure: { “response”: “...” } Protocol Integration javascript router.post(“/a2a/agent/codeHelper”, async (req, res) => { try { console.log(’ Received Telex A2A request’);

// Support both field names
const { message, text } = req.body;
const userMessage = message || text || '';

if (!userMessage.trim()) {
return res.json({
response: getWelcomeMessage()
});
}

// Process through Mastra agent
const result = await CodeHelperService.processMessage(userMessage);

res.json({
response: result.text
});

} catch (error) { console.error(’ Error:’, error); res.status(500).json({ response: ‘Service temporarily unavailable’ }); } }); Challenge #6: Handling Empty Inputs Occasionally, users activated the agent without submitting code. Resolution: Implemented a greeting for empty submissions: javascript if (!userMessage.trim()) { return res.json({ response: ` Hello! I’m Code Helper

I analyze code and provide:

• Code interpretation
• Bug identification
• Optimization recommendations
• Security evaluation

Share your code to begin! ` }); }

Phase 7: Local Testing Strategy Test Infrastructure bash

System health verification

curl http://localhost:4040/health

Analysis functionality test

curl -X POST http://localhost:4040/a2a/agent/codeHelper
-H “Content-Type: application/json”
-d ‘{“message”: “function test() { console.log(x); }”}’ Challenge #7: JSON Processing Failures Certain requests produced errors: SyntaxError: Unexpected token in JSON Cause: Code containing special characters wasn’t properly escaped Resolution: Added validation middleware: javascript app.use((error, req, res, next) => { if (error instanceof SyntaxError) { return res.status(400).json({ response: “Invalid JSON format” }); } next(); }); Comprehensive Test Suite I developed thorough test scenarios: bash

Scenario 1: Basic syntax

curl -X POST localhost:4040/a2a/agent/codeHelper
-d ‘{“message”: “const x = 5;”}’

Scenario 2: Error detection

curl -X POST localhost:4040/a2a/agent/codeHelper
-d ‘{“message”: “function divide(a, b) { return a / b; }”}’

Scenario 3: Security vulnerability

curl -X POST localhost:4040/a2a/agent/codeHelper
-d ‘{“message”: “const query = SELECT * FROM users WHERE id = ${id};”}’

Scenario 4: Complex multi-line

curl -X POST localhost:4040/a2a/agent/codeHelper
-d ‘{“message”: “function factorial(n) {\n if (n <= 1) return 1;\n return n * factorial(n - 1);\n}”}’

Phase 8: Railway Deployment Platform Selection Rationale Railway was chosen for several advantages: • Seamless GitHub connectivity • Automated deployment pipeline • Adequate free tier for development • Straightforward environment management Deployment Workflow Step 1: Pre-Deployment Configuration Essential files created: json // package.json { “scripts”: { “start”: “node src/main.js”, “dev”: “nodemon src/main.js” }, “engines”: { “node”: “>=18.0.0” } } // Procfile web: node src/main.js Step 2: Repository Publication bash git init git add . git commit -m “Initial commit” git remote add origin https://github.com/Habeeboss/code-helper-mastra-telex.git git push -u origin main Step 3: Railway Configuration

1. Linked GitHub repository
2. Selected target repository
3. Configured environment variables: o GEMINI_API_KEY o PORT (automatically assigned by Railway)
4. Initiated deployment Challenge #8: Port Binding Issues Initial deployment attempt failed: Error: listen EADDRINUSE: address already in use Resolution: Railway dynamically allocates ports. Server configuration updated: javascript const PORT = process.env.PORT || 4040;

app.listen(PORT, ‘0.0.0.0’, () => { console.log(Server running on port ${PORT}); }); Critical adjustment: Binding to 0.0.0.0 rather than localhost for Railway compatibility. Step 4: Domain Generation • Accessed Railway configuration • Generated public domain • Obtained: code-helper-mastra-telex-production.up.railway.app Step 5: Deployment Verification bash curl https://code-helper-mastra-telex-production.up.railway.app/health Deployment successful! 🎉

Phase 9: Telex.im Platform Integration Access Acquisition Via HNG Slack: /telex-invite habeeb@example.com Invitation arrived promptly. Workflow Configuration Development Challenge #9: Understanding Position Values The example workflow contained puzzling coordinates: json “position”: [816, -112] After experimentation, I discovered: • These are simply canvas positioning values • Any positive numbers are acceptable • They control visual node placement in Telex My configuration: json { “active”: true, “category”: “utilities”, “description”: “AI-powered code analysis assistant”, “id”: “code-helper-agent”, “long_description”: “Expert code assistant built with Mastra...”, “name”: “code_helper_agent”, “nodes”: [ { “id”: “code_helper”, “name”: “Code Helper”, “parameters”: {}, “position”: [800, 300], “type”: “a2a/mastra-a2a-node”, “typeVersion”: 1, “url”: “https://code-helper-mastra-telex-production.up.railway.app/a2a/agent/codeHelper” } ], “pinData”: {}, “settings”: { “executionOrder”: “v1” }, “short_description”: “AI-powered code analysis” } Workflow Import Process

1. Authenticated on Telex.im
2. Located Workflows section
3. Selected “Import Workflow”
4. Inserted JSON configuration
5. Saved and enabled Platform Testing Initial interaction: @code_helper_agent analyze this: function test() { console.log(x); } Challenge #10: Response Delays The agent appeared online but remained silent. Investigation Process:
6. Reviewed Railway logs - server operational
7. Direct endpoint testing - functioning correctly
8. Examined Telex logs at: https://api.telex.im/agent-logs/{channel-id}.txt Discovery: Request timeouts occurred due to 8+ second response times. Resolution: Streamlined Gemini prompts for efficiency: javascript // Previous: Verbose, comprehensive prompt const prompt = Analyze this code thoroughly and provide... // 500+ words

// Current: Streamlined, targeted prompt const prompt = `You are a code expert. Analyze: ${code}

Provide: explanation, issues, improvements. Be concise and use markdown.`; Outcome: Response times reduced to 2-3 seconds.

Phase 10: Monitoring and Validation Log Monitoring Telex provides monitoring at: https://api.telex.im/agent-logs/{channel-id}.txt This revealed: • Usage patterns • Performance metrics • Error frequencies Production Testing I validated various scenarios: Scenario 1: Type Coercion Bug javascript function add(a, b) { return a + b } console.log(add(1, “2”)) Agent Analysis: markdown Issues Detected

• Type mixing: combining number with string
• Absent semicolons
• Missing input validation

Recommendations

• Implement type verification
• Apply parseInt/parseFloat
• Add validation logic Excellent! Scenario 2: SQL Vulnerability javascript const query = SELECT * FROM users WHERE id = ${userId}; Agent Analysis: markdown Security Concerns
• SQL injection vulnerability
• Unparameterized query construction
• Unfiltered user input in SQL

Remediation

• Implement prepared statements
• Use parameterized queries
• Sanitize all inputs Perfect! Scenario 3: Algorithmic Inefficiency javascript function fibonacci(n) { if (n <= 1) return n; return fibonacci(n-1) + fibonacci(n-2); } Agent Analysis: markdown Performance Concerns
• Exponential complexity O(2^n)
• Duplicate computations
• Stack overflow potential for large n

Enhancements

• Apply memoization technique
• Use dynamic programming
• Consider iterative implementation Outstanding!

Phase 11: Obstacle Summary Primary Challenges Obstacle Severity Resolution Duration Framework dependency conflicts High Node.js upgrade, legacy flags 2 hours Output escape characters Medium Text sanitization function 1 hour Port configuration issues High Bind to 0.0.0.0, use env PORT 1.5 hours Slow AI responses Medium Prompt optimization 1 hour Protocol comprehension Low Documentation review, testing 30 mins Key Insights

1. Thorough Documentation Review • Prevented future complications • Reduced error frequency
2. Continuous Testing • Identified issues pre-deployment • Accelerated local debugging
3. Incremental Development • Established working foundation first • Added complexity gradually
4. Production Monitoring • Leveraged logging effectively • Quick issue identification
5. Comprehensive Error Handling • Enhanced user experience • Improved debugging capabilities ________________________________________ Phase 12: Success Factors Mastra Framework Advantages Strengths: • Elegant agent abstraction • Straightforward AI model integration • Quality documentation • Engaged community Appreciated Features: • Intuitive agent creation • Adaptable instruction system • Simple tool extension Example: javascript const agent = new Agent({ name: “my_agent”, instructions: “...”, model: “...” }); Straightforward and logical! Gemini AI Performance Strengths: • Rapid response times (2-3 seconds) • Strong code comprehension • Reliable analysis • Generous free allocation Appreciated Aspects: • Native multi-language capability • Natural markdown output • Contextual awareness Telex A2A Protocol Benefits Strengths: • HTTP-based simplicity • Adaptable message structure • Simple testing process • Robust error management Appreciated Features: • Standard JSON communication • Comprehensive documentation • Useful agent logging

Phase 13: Improvement Opportunities Framework Enhancement Areas Potential Improvements: • More comprehensive documentation • Additional use case examples • Enhanced TypeScript compatibility • More informative error messages Example ambiguity: javascript // Unclear from documentation const agent = new Agent({ model: “gemini” // String or object expected? }); Deployment Challenges Difficulties Encountered: • Environment variable complexity • Unclear port configuration • Cold start delays on free tier Recommendations: • Enhanced hosting platform guides • Mastra deployment templates • Environment configuration checklist

Phase 14: Future Roadmap Planned Features

1. Code Formatting o Automatic code formatting o Configuration suggestions for formatters
2. Enhanced Language Support o Language-specific guidelines o Framework-specific recommendations
3. Conversational Memory o Previous code snippet recall o Follow-up inquiry support o Multi-turn analysis capability
4. Complexity Analysis o Time complexity evaluation o Space complexity assessment o Big O notation reporting
5. Code Generation o Test suite generation o Documentation creation o Refactoring proposals Technical Enhancements
6. Caching System o Cache repeated analyses o Minimize API consumption o Improve response speed
7. Usage Limits o Abuse prevention o Equitable resource distribution o Cost management
8. Usage Analytics o Pattern identification o Popular language tracking o Common issue cataloging

Phase 15: Performance Analysis Current Metrics Indicator Measurement Mean Response Duration 2.8 seconds System Availability 99.2% Request Success Rate 98.7% Supported Languages 10+ Code Examined 5000+ lines Optimization Impact Pre-optimization: • Response duration: 8-12 seconds • Timeout frequency: 15% Post-optimization: • Response duration: 2-4 seconds • Timeout frequency: <1% Contributing Factors: • Streamlined prompts • Enhanced error management • Planned caching implementation

Conclusion Developing the Code Helper Agent presented challenges but delivered substantial learning. Here’s my takeaway: Technical Competencies Acquired • Mastra Framework proficiency • AI integration methodologies • A2A protocol expertise • Production deployment experience • Error handling excellence Core Principles

1. Begin Simply: Establish functionality before adding features
2. Test Comprehensively: Local validation prevents deployment issues
3. Monitor Actively: Logging is invaluable
4. Iterate Rapidly: Incremental improvements accumulate
5. Document Thoroughly: Your future self will appreciate it Upcoming Developments • Implement conversational context • Deploy caching system • Expand language coverage • Introduce code generation • Develop command-line interface Closing Thoughts This project proved that appropriate tooling (Mastra, Gemini, Telex) enables rapid development of sophisticated AI agents. Success requires understanding fundamentals and embracing iteration. I am enthusiastic about this agent’s future evolution!

The HNG Stage 3 assignment challenged me to: • Master new frameworks • Address practical problems • Deploy to production environments • Create comprehensive documentation

Additional Resources • Source Code: code-helper-mastra-telex • Production Instance: Live Application • Mastra Resources: docs.mastra.ai • Telex Platform: telex.im • HNG Program: hng.tech

Author: Habeeb Olakunle Publication Date: November 2, 2025 Topics: #HNG #Mastra #AI #Telex #Backend #JavaScript