Building EduSimplify: An AI Agent for Simplifying Educational Topics using Django, DRF, and Telex A2A Protocol

El-kufahn Muhammad Ahmad — Mon, 03 Nov 2025 16:35:39 +0000

Author: Muhammad Ahmad El-kufahn

GitHub: KhalifahMB/HNG13_Intenship

Live Agent: Live Link to Agent

🌍 Overview

EduSimplify is an AI-powered educational assistant that simplifies complex science topics — especially Physics, Math, and related fields — into clear, easy-to-understand explanations.

Built with Django, Django REST Framework (DRF), and Google Gemini, EduSimplify integrates seamlessly into the Telex.im platform using the Mastra A2A (Agent-to-Agent) Protocol.

The goal is simple:

When a user sends a complex topic like “Explain quantum entanglement,” EduSimplify responds with a concise 2–3 sentence explanation, one real-world example, and a short note or formula.

🧩 Understanding Telex A2A Protocol (in plain English)

Telex’s A2A (Agent-to-Agent) protocol allows external applications (agents) to connect and communicate with Telex channels using the JSON-RPC 2.0 format.

This format ensures that every message follows a consistent structure — each with an id, method, and params.

For example, Telex might send a message to EduSimplify like this:

{
  "jsonrpc": "2.0",
  "id": "001",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "messageId": "12345",
      "parts": [
        { "kind": "text", "text": "Explain Newton's third law" }
      ]
    }
  }
}

Your agent then processes that request, runs the AI model, and sends a structured JSON-RPC response back to Telex with an explanation, artifacts, and history.

🧠 How EduSimplify Works Internally

EduSimplify’s architecture follows a clean modular design:

agents/
├── views.py # Core logic handling A2A JSON-RPC requests
├── serializers.py # DRF validation for JSON-RPC schema
├── models.py # Conversation, Message, Artifact models
├── utils.py # Google Gemini integration

🧩 Request Flow:

Telex sends a JSON-RPC request (e.g., message/send) to your public endpoint.

The A2AAgentView validates the request using DRF serializers.

A unique context_id identifies each conversation.

The user message is stored in the database.

The text is passed to the ask_gemini() helper function.

Gemini generates a simplified explanation.

EduSimplify returns a structured A2A-compliant JSON response with the answer.

⚙️ The Google Gemini Integration

EduSimplify uses the official Google Generative AI Python SDK (google-genai) for calling Gemini models.

import os
from google import genai
from django.conf import settings

def _get_genai_client():
    api_key = getattr(settings, "GEMINI_API_KEY", None) or os.environ.get("GEMINI_API_KEY")
    if not api_key:
        raise RuntimeError("Gemini API key not configured (GEMINI_API_KEY)")
    return genai.Client(api_key=api_key)

def ask_gemini(prompt, model="gemini-2.5-flash"):
    client = _get_genai_client()
    try:
        response = client.models.generate_content(model=model, contents=prompt)
    except Exception as exc:
        raise RuntimeError(f"genai request failed: {exc}") from exc

    text = getattr(response, "text", str(response))
    if not text:
        raise RuntimeError("genai returned empty response")
    return text

This keeps the integration clean, secure, and reusable — ask_gemini() is imported anywhere in your Django app to generate AI content on demand.

🧾 Core View Explained

The main view that powers EduSimplify is A2AAgentView. It receives JSON-RPC data, validates it, extracts user prompts, and responds.

Key Concepts

Message IDs (messageId): Every message (incoming or outgoing) has a unique UUID to track it.

Context IDs: Represent a user’s conversation thread across multiple messages.

Task IDs: Used when Telex runs multiple tasks within one context.

History: Holds both the user’s query and the agent’s reply for Telex display.

Example excerpt:

class A2AAgentView(APIView):
    def post(self, request, *args, **kwargs):
        raw = request.data or {}
        top_serializer = JSONRPCRequestSerializer(data=raw)
        ...
        if method == "message/send":
            pser = MessageParamsSerializer(data=params)
            ...
        user_prompt = last["text"]

        # Call Gemini
        explanation = ask_gemini(
            f"You are EduSimplify... Concept: {user_prompt}\nAnswer:"
        )

        # Respond to Telex
        result = {
            "id": task_id,
            "contextId": conv.context_id,
            "status": {
                "state": "completed",
                "timestamp": datetime.utcnow().isoformat() + "Z",
                "message": {
                    "role": "agent",
                    "parts": [{"kind": "text", "text": explanation}]
                },
            },
            ...
        }
        return Response(make_a2a_success(request_id, result))

Each new request gets a unique messageId to prevent collisions and maintain consistent message threading inside Telex.

🧮 Example: How to Talk to EduSimplify

🔹 Using curl

curl -X POST https://el-kufahn-hng13.up.railway.app/a2a/agent/edusimplify \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "001",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "messageId": "abc123",
        "parts": [
          {"kind": "text", "text": "Explain photosynthesis in simple terms"}
        ]
      }
    }
  }'

✅ Response Example

{
  "jsonrpc": "2.0",
  "id": "001",
  "result": {
    "status": {
      "state": "completed",
      "message": {
        "role": "agent",
        "parts": [
          {
            "kind": "text",
            "text": "Photosynthesis is how plants convert sunlight into energy..."
          }
        ]
      }
    }
  }
}

🔹 Using Postman

Method: POST

URL: https://el-kufahn-hng13.up.railway.app/a2a/agent/edusimplify

Body (raw JSON): same as above.

🔗 Telex Workflow Configuration

To connect EduSimplify to Telex.im, add a workflow JSON like this:

{
  "active": true,
  "category": "education",
  "description": "Simplifies science topics for better understanding.",
  "id": "EduSimplifyAgent_v1",
  "name": "edusimplify_agent",
  "short_description": "Simplify complex topics in simple terms",
  "long_description": "
      EduSimplify helps users understand science topics easily.
      It breaks down complex concepts into short explanations, gives real-world examples,
      and provides simple formulas or notes when applicable.
  ",
  "nodes": [
    {
      "id": "edusimplify_agent",
      "name": "EduSimplify Agent",
      "parameters": {},
      "position": [816, -112],
      "type": "a2a/mastra-a2a-node",
      "typeVersion": 1,
      "url": "https://el-kufahn-hng13.up.railway.app/a2a/agent/edusimplify"
    }
  ],
  "settings": {
    "executionOrder": "v1"
  },
  "pinData": {}
}

💻 Source Code & Setup

All setup details (environment variables, Django configuration, and deployment steps) are explained in the GitHub repository provided at the top.

Interact directly with the deployed agent:

👉 https://el-kufahn-hng13.up.railway.app/a2a/agent/edusimplify

Send it any science concept — from “Explain gravity like I’m 10” to “What is a black hole?” — and get clear, simple answers.

🧭 Conclusion

EduSimplify demonstrates how Django + DRF can be used to build robust, production-ready AI agents that integrate cleanly into Telex.im using the A2A protocol.

By combining Google Gemini’s intelligence with a simple, structured API design, this project shows how AI can transform learning experiences — one simplified concept at a time.

django #ai #education #telex #google-gemini #python

Forem: El-kufahn Muhammad Ahmad