DEV Community: Humphery

Building “Exhibit”: An AI-Powered Portfolio Agent with Mastra, A2A, and Telex

Humphery — Mon, 03 Nov 2025 12:52:47 +0000

By Humphery Otuoniyo

As developers, showcasing our work effectively can sometimes be as challenging as building the projects themselves. I recently built Exhibit, an intelligent agent that generates personalized developer portfolios directly from GitHub repositories and a preferred tech stack. In this article, I’ll walk you through the process of building the agent using Mastra, setting up the A2A protocol for agent communication, and integrating it with Telex for a seamless front-end experience.

1. Why Exhibit?

The motivation behind Exhibit was simple: developers often have many repositories on GitHub, but not all of them are portfolio-ready. Manually curating projects and writing polished descriptions can be time-consuming. Exhibit automates this process by:

Fetching GitHub repositories using the user’s username.
Selecting projects that match the user’s tech stack.
Generating a clean, structured portfolio in Markdown format.
Organizing sections such as Introduction, Tech Stack, Projects, and Contact information.

This ensures developers have a professional, ready-to-publish portfolio in minutes.

2. Building the Agent with Mastra

Mastra provides a framework for building intelligent agents that can combine AI models, tools, and memory. Here’s how I defined the Exhibit Agent:

import { Agent } from "@mastra/core/agent";
import { Memory } from "@mastra/memory";
import { LibSQLStore } from "@mastra/libsql";
import { githubRepoTool } from "../tools/exhibit-tool";
import { scorers } from "../scorers/exhibit-scorer";

export const exhibitAgent = new Agent({
  name: "Exhibit Agent",
  instructions: `
    You are Exhibit — an AI that generates a professional portfolio from GitHub repositories...
  `,
  model: "google/gemini-2.5-flash",
  tools: { githubRepoTool },
  scorers: scorers,
  memory: new Memory({
    storage: new LibSQLStore({ url: "file:../mastra.db" }),
  }),
});

Key highlights:

Tools integration: The agent uses githubRepoTool to fetch repositories and metadata.
Custom scoring: I implemented scorers to evaluate the quality, completeness, and appropriateness of tool usage in generating the portfolio.
Memory: Using LibSQLStore ensures the agent remembers previous interactions, improving follow-up portfolio generations.

3. Setting Up the A2A Protocol

A2A (Agent-to-Agent) is Mastra’s protocol for sending structured messages between clients and agents. It follows the JSON-RPC 2.0 specification. Here’s how the A2A route was defined:

import { registerApiRoute } from "@mastra/core/server";

export const a2aAgentRoute = registerApiRoute("/a2a/agent/:agentId", {
  method: "POST",
  handler: async (c) => {
    const mastra = c.get("mastra");
    const agentId = c.req.param("agentId");
    const body = await c.req.json();

    const agent = mastra.getAgent(agentId);
    const messages = body.params?.messages || [];

    const mastraMessages = messages.map(msg =>
      `${msg.role}: ${msg.parts.map(p => p.text || JSON.stringify(p.data)).join("\n")}`
    );

    const response = await agent.generate(mastraMessages);
    return c.json({ jsonrpc: "2.0", id: body.id, result: response });
  },
});

This route:

Receives user messages in JSON-RPC format.
Converts them into the string format expected by agent.generate.
Returns the agent’s response, including artifacts and portfolio text.

With this, any client can communicate with Exhibit securely and reliably.

4. Integrating with Telex

Telex acts as a front-end interface for your agents. It provides a low-code platform to create workflows and connect your A2A agent nodes. For Exhibit:

I defined an A2A node pointing to the deployed agent:

{
  "id": "exhibit_agent",
  "name": "exhibit agent",
  "type": "a2a/mastra-a2a-node",
  "url": "https://rapid-purple-library-8c383acc-5862-46c4-b9ea-3451fc36ac61.mastra.cloud/a2a/agent/exhibitAgent"
}

Created a workflow where users input:

GitHub username
Preferred tech stack

The agent processes this input, fetches repositories, and outputs a ready-to-use Markdown portfolio.

This integration makes it possible to test and deploy Exhibit without building a full front-end from scratch.

5. Testing the Agent

Once deployed, you can test Exhibit via any HTTP client (like Postman or curl) using JSON-RPC messages:

curl -X POST "https://<your-mastra-domain>/a2a/agent/exhibitAgent" \
-H "Content-Type: application/json" \
-d '{
  "jsonrpc": "2.0",
  "id": "test-1",
  "method": "generate",
  "params": {
    "message": {
      "role": "user",
      "parts": [{"kind": "text", "text": "GitHub username: octocat, tech stack: JavaScript, React"}]
    }
  }
}'

The response will contain the portfolio Markdown text, ready to save or display.

6. What I Learned

Mastra’s flexibility allows for combining AI, tools, and memory efficiently.
A2A protocol simplifies structured communication between agents and clients.
Telex integration enables low-code testing and workflow management.
Automating portfolio generation can save developers hours while ensuring professionalism.

7. Next Steps

Add portfolio customization options, like themes or formats.
Integrate more GitHub analytics (stars, commits) for project selection.
Explore multi-agent workflows to build a complete developer dashboard.

Exhibit is now live and working! This project demonstrates the power of combining AI agents, structured messaging, and low-code workflows to automate developer-focused tasks. Code for the project can be found at my GitHub

Building a String Analyzer Service: From Concept to Deployment

Humphery — Wed, 22 Oct 2025 18:03:07 +0000

By Humphery Otuoniyo

I built a RESTful API service designed to analyze strings and store their computed properties. The project offered a hands-on experience in backend development, from schema design to deployment on Railway, and highlighted the importance of robust data validation and flexible querying.

Project Overview

The service analyzes any submitted string and computes several properties:

Length: Number of characters in the string
Is Palindrome: Boolean indicating whether the string reads the same forwards and backwards (case-insensitive)
Unique Characters: Count of distinct characters
Word Count: Number of words separated by whitespace
SHA-256 Hash: Unique identifier for the string
Character Frequency Map: A dictionary mapping each character to its occurrence count

This allowed the service to not only store strings efficiently but also provide analytical insights for further queries.

API Endpoints

The service exposes five key endpoints, each serving a specific purpose:

1. Create/Analyze String

POST /strings

Users can submit a string in JSON format, and the service computes its properties and stores it:

{
  "value": "string to analyze"
}

Successful responses include the computed properties and the SHA-256 hash. The service handles conflicts and invalid input gracefully, returning appropriate status codes such as 409 Conflict if the string already exists, 400 Bad Request for missing fields, or 422 Unprocessable Entity if the value type is incorrect.

2. Get Specific String

GET /strings/{string_value}

This endpoint retrieves a single string and its properties. If the string does not exist, a 404 Not Found is returned.

3. Get All Strings with Filtering

GET /strings?is_palindrome=true&min_length=5&max_length=20&word_count=2&contains_character=a

The service allows powerful query filtering:

is_palindrome: boolean
min_length and max_length: integers
word_count: exact number of words
contains_character: a single character

Responses include all matching strings, the total count, and a record of the filters applied. Invalid query parameters are rejected with 400 Bad Request.

4. Natural Language Filtering

GET /strings/filter-by-natural-language?query=all%20single%20word%20palindromic%20strings

One of the most interesting features is the ability to parse natural language queries. The service interprets queries like:

"all single word palindromic strings" → word_count=1, is_palindrome=true
"strings longer than 10 characters" → min_length=11
"palindromic strings that contain the first vowel" → is_palindrome=true, contains_character=a

If the query cannot be parsed or results in conflicting filters, the API returns 400 Bad Request or 422 Unprocessable Entity.

5. Delete String

DELETE /strings/{string_value}

Users can remove a specific string from the system. If the string does not exist, a 404 Not Found is returned. Importantly, the endpoint ensures safety by not deleting all data if the parameter is missing.

Development Highlights

Data Validation and Type Safety

Handling numeric filters such as min_length, max_length, and word_count required strict integer validation. Using Number combined with Number.isInteger() ensured that the API rejected decimals, negative numbers, and non-numeric input while accepting valid integers.

Palindrome Detection and Character Analysis

For palindromes, the service ignores case and spaces, providing an accurate boolean flag. Character frequency maps and unique character counts are computed efficiently using simple iteration over the string.

Hashing for Unique Identification

SHA-256 hashing provides a reliable way to identify strings uniquely, which is especially useful for avoiding duplicates and quickly locating records.

Deployment Considerations

Deploying on Railway introduced the common challenge of environment variable handling. Railway sometimes wraps values in quotes, which would break the MongoDB connection. This was handled by sanitizing the MONGO_URI in the connection logic:

let mongoUri = process.env.MONGO_URI;
if (mongoUri.startsWith('"') && mongoUri.endsWith('"')) {
    mongoUri = mongoUri.slice(1, -1);
}

This approach ensured a smooth connection to MongoDB Atlas without manual intervention.

Lessons Learned

Building the String Analyzer Service reinforced several best practices:

Always validate and sanitize input, especially for numeric and string-based filters
Use unique identifiers like hashes to prevent duplicate entries
Implement comprehensive error handling to guide API users
Consider deployment quirks like environment variable formatting early in development

Conclusion

This project demonstrates how a well-structured backend service can provide both analytical functionality and robust, user-friendly endpoints. The combination of computed string properties, filtering capabilities, and natural language interpretation makes it a versatile tool for string analysis. Deploying to Railway and ensuring smooth operation in a cloud environment highlighted real-world considerations that are crucial for any backend engineer.

Github code

Building a Dynamic Profile Endpoint

Humphery — Sat, 18 Oct 2025 20:01:57 +0000

By Otuoniyo Ufuoma-Oghene Humphery

Introduction

As part of the HNG 2025 Backend Wizards program, I recently completed Stage 0, where the task was to build a dynamic profile endpoint. The goal was simple yet powerful: create a RESTful API endpoint that returns my profile information along with a random cat fact fetched from an external API.

This task taught me not just the technicalities of building endpoints, but also how to consume third-party APIs, handle dynamic data, and structure JSON responses professionally.

Task Overview

Requirements:

Create a GET endpoint at /me.
Return JSON with Content-Type: application/json.
Include a dynamic cat fact fetched from Cat Facts API.
JSON response format:

{
  "status": "success",
  "user": {
    "email": "<your email>",
    "name": "<your full name>",
    "stack": "<your backend stack>"
  },
  "timestamp": "<current UTC time in ISO 8601 format>",
  "fact": "<random cat fact from Cat Facts API>"
}

Handle API errors gracefully.
Follow best practices for code structure, environment variables, and logging.

My Work Process

Here’s how I approached this task step by step:

1. Setting Up the Server

I used Node.js and Express for this project. First, I initialized the server and created a simple route handler for /me.

app.get("/me", getUsers);

2. Fetching Dynamic Cat Facts

I implemented a fetchWithTimeout utility to safely fetch data from the Cat Facts API, handling timeouts and network errors:

const catFactJson = await fetchWithTimeout(CAT_API_URL);
const catFact = catFactJson?.fact || "Could not fetch a cat fact right now.";

This ensures the endpoint never crashes, even if the external API is down.

3. Formatting the JSON Response

Next, I structured the JSON response to strictly match the Stage 0 requirements:

res.json({
  status: "success",
  user: {
    email: "humpheryufuoma@gmail.com",
    name: "Otuoniyo Ufuoma-Oghene Humphery",
    stack: "Node.js/Express"
  },
  timestamp: new Date().toISOString(),
  fact: catFact
});

I made sure the timestamp was dynamic and in UTC ISO 8601 format.

4. Environment Variables

For local development, I used .env to store the Cat Facts API URL:

CAT_API_URL=https://catfact.ninja/fact

Note: Railway automatically adds quotes to environment variables, so in production I strip them in code before using the URL.

5. Handling Errors Gracefully

I added error handling to ensure a fallback cat fact is returned if the API fails:

catch (err) {
    res.status(500).json({
        status: "error",
        message: "Failed to fetch cat fact"
    });
}

This guarantees a smooth user experience at all times.

Lessons Learned

Environment variables are crucial for separating config from code, but deployment platforms like Railway may add quirks (like automatic quotes) that you need to handle.
Dynamic data fetching requires proper error handling — always expect the external API to fail occasionally.
JSON schema validation is important; even small typos in field names can break automated checks.
Small tasks teach discipline: Stage 0 reinforced best practices in endpoint design, logging, and clean code.

Screenshots / GIFs

Outcome

The final endpoint returns JSON like this:

{
  "status": "success",
  "user": {
    "email": "humpheryufuoma@gmail.com",
    "name": "Otuoniyo Ufuoma-Oghene Humphery",
    "stack": "Node.js/Express"
  },
  "timestamp": "2025-10-18T19:50:29.028Z",
  "fact": "A cat usually has about 12 whiskers on each side of its face."
}

Meets all Stage 0 requirements.
Dynamic timestamp and cat fact.
Graceful error handling.
Ready for deployment on Railway.

Conclusion

Stage 0 of HNG Backend Wizards was packed with learning: working with REST APIs, dynamic data, and deployment quirks.

I’m excited to carry these best practices forward into Stage 1 and beyond, building more complex backend systems that are robust, maintainable, and dynamic.

GitHub Repository

View the code on GitHub

Introduction to Using Supabase with Node.js: Build a Simple Todo App

Humphery — Wed, 24 Sep 2025 08:34:52 +0000

Hey there! 👋 Today, we’re going to have some fun building a simple Todo app using Supabase and Node.js. Don’t worry if you’re a beginner, I’ll explain everything step by step!

What is Supabase?

Supabase is an open-source platform that provides:

A real-time database
Authentication for users
Storage for files
Serverless functions

It helps you build backend features quickly without writing everything from scratch.

Prerequisites

Before we start, make sure you have:

Node.js installed
Basic knowledge of JavaScript
A Supabase account (sign up free at supabase.com)

Step 1: Create a Supabase Project

Go to the Supabase dashboard.
Click “New Project”.
Give it a name, pick a password, and wait for it to create.
Once created, go to Settings → API and copy:

Project URL
Anon key

We’ll need these in our code!

Step 2: Create a Table

We need a table to store our todos.

Go to Database → Tables → New Table
Call it todos and add columns:

Column Name	Type	Notes
id	uuid	Primary key, default `gen_random_uuid()`
task	text	The todo description
inserted_at	timestamptz	Default `now()`

Save the table, and we’re ready to code! 🎉

Note: Here we see the todos table in Supabase with columns id, task, and inserted_at.

Step 3: Setup Node.js Project

Open a terminal and create a folder:

mkdir supabase-todo
cd supabase-todo
npm init -y

Install Supabase JS:

npm install @supabase/supabase-js

Step 4: Write Your First Script

Create a file called index.js and paste this code:

// Import Supabase
const supabase = require('@supabase/supabase-js').createClient;

// Replace with your own URL + anon key
const supabaseUrl = "https://YOUR_PROJECT_URL.supabase.co";
const supabaseKey = "YOUR_ANON_KEY";

const client = supabase(supabaseUrl, supabaseKey);

// Insert a todo
async function addTodo() {
  const { data, error } = await client
    .from('todos')
    .insert([{ task: 'Learn Supabase basics' }]);
  console.log('Insert:', data, error);
}

// Fetch all todos
async function fetchTodos() {
  const { data, error } = await client
    .from('todos')
    .select('*');
  console.log('Todos:', data, error);
}

// Run example
(async () => {
  await addTodo();
  await fetchTodos();
})();

Step 5: Run Your Code

In your terminal, run:

node index.js

If everything works, you’ll see something like this:

[
  {
    "id": "990e6e73-e1fa-4d0b-ab69-be85ebf192e6",
    "task": "Learn Supabase basics",
    "inserted_at": "2025-09-24T08:03:58.157706+00:00"
  }
]
null

The array shows your todos
null means no errors 🎉

Step 6: Next Steps

You can now:

Add more todos with addTodo()
Fetch and display them using fetchTodos()
Later, you can build a web or CLI app around it

Supabase makes it super easy to expand your project. 🚀

Conclusion

Congrats! 🥳 You just built your first Supabase Todo app using Node.js.

Supabase + Node.js is a powerful combo for beginners and pros alike. Now you can explore authentication, storage, or even real-time updates.

Go ahead, play around, and build something amazing!