This content originally appeared on DEV Community and was authored by ibrahimabdulquadri101
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.
- 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.
- 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],
// ...
});
`
- 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.
- 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!
This content originally appeared on DEV Community and was authored by ibrahimabdulquadri101
ibrahimabdulquadri101 | Sciencx (2025-11-01T21:34:00+00:00) From Casual to Corporate: Building a Formalizer Agent with Mastra and Telex.im. Retrieved from https://www.scien.cx/2025/11/01/from-casual-to-corporate-building-a-formalizer-agent-with-mastra-and-telex-im/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.