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.
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 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],
// ...
});
`
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.
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!
More...
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!
More...