I. Introduction: The Stateful Challenge
The HNG Stage 3 task required us to build a useful AI agent and integrate it with an agent platform using the Agent-to-Agent (A2A) protocol. I chose to build DevCoach, a Personalized Software Learning Coach.
Unlike a simple Q&A bot, DevCoach's core function is to maintain state: it must track a user's chosen learning topic, course duration, and current day's progress. This required me to go beyond simple prompting and heavily focus on agent memory and A2A compliance.
II. Mastra Agent Design: The Brain and the Memory
As required for TypeScript developers, I used Mastra—the robust agent framework—to build the agent's logic.
Mastra Features Used
Mastra Agent Class: Used to define the core worker with its instructions and model.
Mastra Memory: Crucial for maintaining state (tracking the user's progress across multi-turn sessions).
Mastra Server API Routes: Used to register a custom route handler to accept A2A requests.
A. Implementing Stateful Memory
The key to DevCoach's intelligence is its ability to remember a conversation's context. I leveraged Mastra's Memory capabilities to maintain state, ensuring the learning plan remains sequential and coherent.
// src/mastra/agents/learningCoachAgent.ts (Snippet)
import { Agent } from "@mastra/core/agent";
import { Memory } from "@mastra/memory";
import { openai } from "@ai-sdk/openai";
// Instantiate the memory store
const memory = new Memory(); // This is the feature used!
export const learningCoachAgent = new Agent({
name: "devCoach",
instructions: INSTRUCTIONS,
model: openai("google/gemini-2.5-pro"),
memory: memory, // Injecting the memory instance
});
B. Agent Behavior (The System Prompt)
The instructions mandate that DevCoach must first gather the topic and duration before delivering Day 1's task. This clear, progressive instruction set, combined with Memory, ensures the agent performs its multi-turn, stateful role successfully.
III. Integration: The A2A Protocol Bridge
Integrating with Telex requires a highly specific JSON-RPC 2.0 format over HTTPS (the A2A Protocol). Since Mastra does not automatically output this exact format from a generic route, I adapted a custom route handler to act as the necessary A2A translator.
This custom handler (a2aAgentRoute.ts) performs three critical functions:
JSON-RPC Parsing: It extracts the user's message and the conversation history from the incoming Telex A2A request body.
Mastra Execution: It passes the cleaned messages to the devCoach Mastra agent for processing (agent.generate()).
A2A Response Formatting: It wraps the agent's final text into the complex A2A result payload, including the task status ("state": "completed") and artifacts expected by Telex.
IV. Deployment and Debugging (What Worked & What Didn't)
I chose Railway for its superior CI/CD and stability for Node.js services, which simplified the continuous deployment process.
A. The A2A Endpoint
Upon successful deployment, the endpoint was automatically generated, based on the agent's name (devCoach):
A2A Agent Endpoint:
B. The Crucial Debugging Step (Error Handling)
The initial validation of the A2A connection failed, resulting in a 400 Bad Request error. This occurred because the agent handler either failed to parse the JSON-RPC body or failed a strict validation check on the incoming request format. The fix required stabilizing the request parsing logic within the custom route handler to ensure proper A2A compliance.
A separate, initial error was the missing LLM key: Could not find API key process.env.GOOGLE_GENERATIVE_AI_API_KEY. This was quickly resolved by adding the specific environment variable to the Railway project settings, confirming the integration was correctly configured, but lacking credentials.
V. Conclusion & Submission Links
The DevCoach Learning Agent successfully moved from concept to a stateful, A2A-compliant service. This project validated that the Mastra framework, when paired with a custom A2A route handler, provides a robust pipeline for building sophisticated, multi-turn AI agents.
Telex Integration Details
Telex.im is an AI agent platform like Slack alternative for bootcamps where AI colleagues and human teams can collaborate.
My DevCoach Agent on Telex: You can directly interact with DevCoach on Telex here
DevCoach tracks your progress and provides a personalized, progressive learning experience—a capability that moves beyond simple chat functionality.
Submission Links
Deliverable
Link
Live Agent A2A Endpoint
GitHub Repository
Submission Tweet
Top comments (0)