From Casual to Corporate: Building a Formalizer Agent with Mastra and Telex.im

ibrahimabdulquadri101 — Sat, 01 Nov 2025 21:34:00 +0000

Formalizer Agent, an AI Co-Worker designed for the Telex.im platform. This agent uses the Mastra TypeScript framework to transform informal chat into professional, sophisticated prose, demonstrating a robust implementation of the Agent-to-Agent (A2A) protocol.

The core challenge of Stage 3 was moving beyond basic applications and building a reliable, intelligent service that communicates flawlessly with Telex.im.

I. Defining the Core Logic: The Formalizer Agent

The first step was to define the agent's identity and its singular purpose: linguistic formalization. This is handled in src/agents/formalizer-agent.ts.

The primary instruction set, or System Prompt, was critical to ensuring the agent adhered to strict output constraints, specifically the "no conversational fillers" rule.

Key Design Choices

Model: We selected google/gemini-2.5-flash for its speed and exceptional language manipulation capabilities.
Instructions: The agent was given explicit "CRITICAL RULES" to prevent boilerplate text, ensuring the output is immediately usable.
Name Consistency: The agent was named FormalizerAgent—a name that must be consistently matched across the code, the deployment URL, and the Telex Workflow JSON.

II. The Bridge: A2A Protocol and Mastra Registration

The Telex platform communicates with external agents using the Agent-to-Agent (A2A) protocol, which is based on JSON-RPC 2.0. Our Mastra application needed a bridge to translate this protocol into Mastra's internal messaging format.

The A2A Route Handler (src/routes/a2a-agent-route.ts)

This file serves as the crucial translation layer, performing four essential tasks:

Parsing: It receives the A2A JSON-RPC request and extracts the message and agentId (FormalizerAgent).
Lookup: It uses mastra.getAgent(agentId) to retrieve the correct agent instance.
Execution: It calls the agent's core logic with the user's prompt (agent.generate(mastraMessages)).
Response Formatting: It packages the agent's text output back into the required JSON-RPC 2.0 response structure, complete with history and artifact information.

Agent Registration

The agent must be successfully registered in the main application file, src/mastra/index.ts, so the route handler can find it:

// In src/mastra/index.ts

import { formalizerAgent } from './agents/formalizer-agent';

export const mastra = new Mastra({

// Agent is registered here, making it accessible by its name via the route.

agents: { formalizerAgent },

apiRoutes: [a2aAgentRoute],

// ...

});

III. The Challenge: Debugging the Persistent "Agent Not Found" Error

After initial deployment, testing with Postman and Telex consistently returned a 500 Internal error with the critical detail: "Agent with name FormalizerAgent not found".

What didn't work: Simply checking the code. The file structure and naming appeared correct.
The Diagnosis: The error was not a typo in the URL or the agent definition, but a failure during the build or deployment process where the central Mastra registry was not properly loading the agent.

The Solution (The Key to the Integration)

To eliminate any ambiguity in the registration process, I modified src/mastra/index.ts to use the explicit string name as the key in the agents object:

// The critical fix in src/mastra/index.ts

agents: { 'FormalizerAgent': formalizerAgent },

After implementing this change and executing a final clean build and redeployment, the Mastra server successfully recognized the agent and began processing requests flawlessly. This confirmed that ensuring absolute string-key parity during registration is vital for stable A2A services.

IV. Final Integration and Demonstration

With the backend stable, the final step was configuring the Telex Workflow JSON:

URL: The final A2A endpoint was set: [Your Base URL]/a2a/agent/FormalizerAgent.
Workflow Name: Set to Formalizer Agent.

The agent is now live and can be tested on the Telex platform.
github-url:github.com/ibrahimabdulquadri101/hng13-intern-assesment-stage-3
mastra-website: www.mastra.ai

DEV Community: ibrahimabdulquadri101