Building an AI Code Helper Agent with Mastra Framework and Telex.im Integration

Habeeb Olakunle — Mon, 03 Nov 2025 07:11:13 +0000

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:

Node.js version 20 or higher was mandatory (I had version 16)
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):

First, explain the code
Then, list all bugs
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:

Generated .env file
Added it to .gitignore
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

Linked GitHub repository
Selected target repository
Configured environment variables: o GEMINI_API_KEY o PORT (automatically assigned by Railway)
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

Authenticated on Telex.im
Located Workflows section
Selected "Import Workflow"
Inserted JSON configuration
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:
Reviewed Railway logs - server operational
Direct endpoint testing - functioning correctly
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

Thorough Documentation Review • Prevented future complications • Reduced error frequency
Continuous Testing • Identified issues pre-deployment • Accelerated local debugging
Incremental Development • Established working foundation first • Added complexity gradually
Production Monitoring • Leveraged logging effectively • Quick issue identification
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

Code Formatting o Automatic code formatting o Configuration suggestions for formatters
Enhanced Language Support o Language-specific guidelines o Framework-specific recommendations
Conversational Memory o Previous code snippet recall o Follow-up inquiry support o Multi-turn analysis capability
Complexity Analysis o Time complexity evaluation o Space complexity assessment o Big O notation reporting
Code Generation o Test suite generation o Documentation creation o Refactoring proposals Technical Enhancements
Caching System o Cache repeated analyses o Minimize API consumption o Improve response speed
Usage Limits o Abuse prevention o Equitable resource distribution o Cost management
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

Begin Simply: Establish functionality before adding features
Test Comprehensively: Local validation prevents deployment issues
Monitor Actively: Logging is invaluable
Iterate Rapidly: Incremental improvements accumulate
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

Forem: Habeeb Olakunle