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

This post details the development and integration of the 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.

1. 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.

1. 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

The file src/routes/a2a-agent-route.ts serves as the crucial translation layer. It performs 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],

// ...

});

`

1. 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. This is often a subtle issue with how TypeScript imports are compiled into JavaScript modules.

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.

1. 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.

Successful Demo:

Input (Casual Chat)

Output (Formalized Text)

@Formalizer Agent I don't like this project, give me another one fuck you.

I express my significant dissatisfaction with the current project and formally request reassignment to an alternative initiative.

@Formalizer Agent My report is kinda rough. Can you make it sound proper? Cheers!