Mastering A2A: How I Integrated the DevCoach Agent with Telex.im Using Mastra & Memory

#node #javascript

I. Introduction: The Stateful Challenge
The HNG Stage 3 task required us to build a useful AI agent and integrate it with Telex.im 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 focus heavily on agent memory and A2A compliance.

II. Mastra Agent Design: The Brain and the Memory
As required, I used Mastra and TypeScript to build the agent's logic.

A. Implementing Stateful Memory
The key to DevCoach's intelligence is its ability to remember a conversation's context. I used Mastra's Memory capabilities to maintain the user's progress.

// 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 new Memory();

const INSTRUCTIONS = // ... (Your detailed, progressive System Prompt goes here) // CRITICAL: You must use the internal Memory for state persistence: // Key: 'topic', Key: 'maxDays', Key: 'currentDay';

export const learningCoachAgent = new Agent({
name: "devCoach",
instructions: INSTRUCTIONS,
model: openai("google/gemini-2.5-pro"), // Requires GOOGLE_GENERATIVE_AI_API_KEY
memory: memory, // Inject the memory instance for statefulness
});

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 doesn't automatically output this exact format, 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.
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.

A. The A2A Endpoint
Upon successful deployment, the endpoint was automatically generated, based on the agent's name (devCoach):

https://devcoach-agent-production.up.railway.app/a2a/agent/devCoach

B. The Crucial Debugging Step (Error Handling)
The initial deployment failed with a fatal error, teaching a valuable lesson in configuration:

Error: Could not find API key process.env.GOOGLE_GENERATIVE_AI_API_KEY for model id google/gemini-2.5-pro

The Fix: Despite having other API keys set, the agent required the specific GOOGLE_GENERATIVE_AI_API_KEY for the configured model. This was quickly resolved by adding the correct environment variable to the Railway project settings, after which the agent executed flawlessly. This confirmed the integration was perfectly configured; only the LLM credentials were missing.

V. Conclusion & Submission
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 capable of integrating with platforms like Telex.im.

The successful implementation of Mastra Memory allows DevCoach to offer a truly personalized, progressive learning experience—a capability that moves beyond simple chat functionality.

Submission Deliverables
Here are the links to all assets created for the HNG Stage 3 Backend Task: